# Top app bar

Source: https://material.spynejs.com/components/app-bar
Part of: Material shell gallery, Google's Material Design 3 for SpyneJS. Index: https://material.spynejs.com/llms.txt

Material's top app bar, at its small size: the app's header. It has two looks, on the page's surface at the top of a page and on a higher surface with a shadow once the page has scrolled under it. Its title is the model's `text.header`, and its links are the app's routes.

## In an app model

The bar’s title is the model’s `text.header`:

```json
{
  "text": {
    "header": "Material shell gallery"
  }
}
```

- The bar’s links are the app’s routes, declared in `src/index.js`. A model does not list them.
- Nothing in a model chooses between the two looks. Scrolling does.

## In a view

The Material channel says when the page leaves its top and when it comes back. The header listens and sets the class `is-scrolled` on itself; the look is styles. A view of your own that changes with scrolling listens to the same action, and does not listen for scrolling itself. A whole view and its trait:

```js
import { SpyneTrait, ViewStream } from 'spyne';

class MyPanelTraits extends SpyneTrait {
  constructor(context) {
    let traitPrefix = 'myPanel$';
    super(context, traitPrefix);
  }

  static myPanel$OnScrollState(e) {
    const { scrolled } = e.payload;
    this.props.el$.toggleClass('is-raised', scrolled);
  }
}

export class MyPanelView extends ViewStream {
  constructor(props = {}) {
    props.traits = [MyPanelTraits];
    props.channels = ['CHANNEL_MATERIAL'];
    super(props);
  }

  addActionListeners() {
    return [['CHANNEL_MATERIAL_SCROLL_EVENT', 'myPanel$OnScrollState']];
  }
}
```

| Action of `CHANNEL_MATERIAL` | Direction | Payload | Means |
| --- | --- | --- | --- |
| `CHANNEL_MATERIAL_SCROLL_EVENT` | out | `{ scrolled }` | `scrolled` is `true` when the page has left its top and `false` when it is back there. Only the change is reported. |

- The listener is a method of a trait, named in `addActionListeners`. What the channel sent is `e.payload`.

## Where it is in the template

| File | What it holds | By name |
| --- | --- | --- |
| `src/app/components/ui-elements/ui-header-view.js` | the header’s view; it listens to the Material channel |  |
| `src/app/traits/ui/ui-header-view-traits.js` | sets `is-scrolled` on the header | `uiHeader$OnScrollState` |
| `src/app/traits/channel/channel-material-traits.js` | turns the window’s scrolling into the one change | `channelMaterial$OnWindowScroll` |
| `src/scss/03-components/material/_app-bar.scss` | the bar’s two looks |  |
| `src/scss/03-components/material/_navigation.scss` | the bar’s links and its two icon buttons |  |

The template is public: https://github.com/spynejs/application-shell-material. An app made from it has these same files.

What it rests on in `@spynejs/grammar`: `op:state-machine-in-channel`, `op:window-event-via-channel`, `op:declare-action-listeners`.

## As the page shows it

The page’s own words, in its own order, read from the page as it is drawn in the light colour scheme. They were written for someone looking at the page: “above”, “below” and “marked” mean the drawn page. A thing the page draws is named here in its place (`Button:`, `Field:`, `Switch:`), and a box that reports what the reader does is as it starts, empty. What depends on the reader’s own window is left out.

The header is Material’s top app bar, at its small size. It has two looks, and whether the page has scrolled decides which.

At the top of a page: on the page’s own surface.

Once the page has scrolled under it: on a higher surface, with a shadow.

These two are drawn from the bar’s own tokens. The bar itself is at the top of the window: on a page long enough to scroll, scroll it and watch the bar change.

### In the app model

```json
{
  "text": {
    "header": "Material shell gallery"
  }
}
```

### What decides the look

The Material channel reports when the page leaves its top and when it comes back (CHANNEL_MATERIAL_SCROLL_EVENT). The header listens, and sets a class on itself: is-scrolled.

Nothing new is proposed here. The bar’s title is the model’s text.header, as in the Shell. Its links are the app’s routes.
