{
  "name": "Material shell gallery",
  "site": "https://material.spynejs.com",
  "about": "Google's Material Design 3 for SpyneJS: the Material template for the SpyneJS Application Shell. An independent implementation, not affiliated with or endorsed by Google.",
  "index": "https://material.spynejs.com/llms.txt",
  "gallery": "gallery-META-2",
  "template": {
    "repository": "https://github.com/spynejs/application-shell-material",
    "start": "npx spyne-cli create-app my-app --template shell --material",
    "needs": "spyne-cli 0.8.0 or later"
  },
  "fields": {
    "name": "the entry’s fixed name; it does not change when a page’s title or address does",
    "kind": "home, section, foundation, component, feature, transition or sample",
    "page": "the page’s address, for a person",
    "markdown": "the same page as Markdown, for a reader that does not run the site",
    "summary": "what the thing is",
    "model": "what an app model writes to ask for it: `says`, an `example`, `keys` (each with its `values` or what it `means`, and its `default`: what leaving it out means), `keysOf` (what the keys are keys of) and `rules`; or `none`, where there is nothing to ask for",
    "styles": "what a template or a style written by hand uses: a `title`, and any of `says`, `code` with its `lang`, a `table` and `notes`",
    "code": "for what is reached in code: the same shape as `styles`",
    "files": "where it is in the template: each `file`, what it `holds`, and `names` that are in it",
    "grammar": "the cards and records of @spynejs/grammar it rests on"
  },
  "entries": [
    {
      "name": "home",
      "kind": "home",
      "title": "Material shell gallery",
      "page": "https://material.spynejs.com/",
      "markdown": "https://material.spynejs.com/index.md",
      "summary": "The gallery of the Material template for the SpyneJS Application Shell: Google's Material Design 3, built on SpyneJS's View, Behavior, Logic pattern. Every component and feature of the template has a page here, and every page says what an app model writes to ask for the thing. An app on the template is started with spyne-cli."
    },
    {
      "name": "foundations",
      "kind": "section",
      "title": "Foundations",
      "page": "https://material.spynejs.com/foundations",
      "markdown": "https://material.spynejs.com/foundations.md",
      "summary": "What every component is made from: colour, type, shape, elevation and motion. The values are Google's Material 3 tokens, read from Google's token package when the app is built, and each is a custom property an app's own styles can read."
    },
    {
      "name": "color",
      "kind": "foundation",
      "title": "Colour",
      "page": "https://material.spynejs.com/foundations/color",
      "markdown": "https://material.spynejs.com/foundations/color.md",
      "summary": "Material's colour roles. Every colour in the template is one of them, in a light and a dark scheme. A style reads a role by its custom property; a model does not choose colours.",
      "model": {
        "none": "Nothing. A model does not choose colours. Every app on the template has the roles, in both schemes, and the visitor changes the scheme with the button in the header."
      },
      "styles": {
        "title": "The custom properties",
        "says": "A role is a custom property named `--md-sys-color-` and then the role. A style of your own reads it with `var()`:",
        "code": ".my-note {\n  background: var(--md-sys-color-secondary-container);\n  color: var(--md-sys-color-on-secondary-container);\n}",
        "lang": "css",
        "notes": [
          "Content on a fill takes the fill’s own `on-` role: `on-primary` on `primary`, `on-surface` on any surface. That pairing is what keeps text readable in both schemes.",
          "The page itself is `surface`. A surface set off from the page takes one of five container roles, from `surface-container-lowest` to `surface-container-highest`, each a step further from the page’s own. Content on any of them is `on-surface`; quieter content is `on-surface-variant`.",
          "Write no colour value by hand. A role changes with the scheme; a typed value does not.",
          "The roles are set on `main#app`, and again for the dark scheme on `main#app[data-theme='dark']`.",
          "The Shell’s older names (`--brand`, `--paper`, `--text-muted` and the rest) still work: each is defined from a role.",
          "Two roles the page does not show: `--md-sys-color-shadow`, the colour of a shadow, and `--md-sys-color-scrim`, the layer behind the open drawer."
        ]
      },
      "files": [
        {
          "file": "src/scss/00-spynejs-design-system/tokens/_material.scss",
          "holds": "reads Google’s tokens (`@material/web`) at build time; the only file that does"
        },
        {
          "file": "src/scss/00-spynejs-design-system/theme/_light.scss",
          "holds": "the light scheme, and every token that does not change with the scheme"
        },
        {
          "file": "src/scss/00-spynejs-design-system/theme/_dark.scss",
          "holds": "the dark scheme: only what differs"
        },
        {
          "file": "src/scss/00-spynejs-design-system/theme/_bridge.scss",
          "holds": "the Shell’s own variable names, each defined from a role"
        }
      ]
    },
    {
      "name": "type",
      "kind": "foundation",
      "title": "Type",
      "page": "https://material.spynejs.com/foundations/type",
      "markdown": "https://material.spynejs.com/foundations/type.md",
      "summary": "Material's type scale: fifteen styles (display, headline, title, body and label, each large, medium and small), each plain and emphasized. The template gives every heading and every kind of text its style; a model does not choose type.",
      "model": {
        "none": "Nothing. A model writes words; the template gives each kind of text its style. A heading takes the emphasized set and running text the plain one, as the table below shows."
      },
      "styles": {
        "title": "The custom properties",
        "says": "A style is five custom properties, named `--md-sys-typescale-`, the style, and one of `font`, `size`, `line-height`, `weight`, `tracking`. The emphasized set has `emphasized-` before the style. Text of your own takes a style by setting all five:",
        "code": ".my-caption {\n  font-family: var(--md-sys-typescale-body-small-font);\n  font-size: var(--md-sys-typescale-body-small-size);\n  line-height: var(--md-sys-typescale-body-small-line-height);\n  font-weight: var(--md-sys-typescale-body-small-weight);\n  letter-spacing: var(--md-sys-typescale-body-small-tracking);\n}",
        "lang": "css",
        "notes": [
          "Use the heading elements (`h1` to `h6`) and `p` as they are: each already has its style.",
          "The typeface is Roboto, served by the app itself. No font is loaded from another site."
        ]
      },
      "files": [
        {
          "file": "src/scss/03-components/material/_type.scss",
          "holds": "which style each heading and each kind of text takes"
        },
        {
          "file": "src/scss/00-spynejs-design-system/tokens/_material.scss",
          "holds": "the styles themselves, read from Google’s tokens"
        },
        {
          "file": "src/scss/00-spynejs-design-system/tokens/_material-typeface.scss",
          "holds": "Roboto, in the weights Material uses"
        }
      ]
    },
    {
      "name": "shape",
      "kind": "foundation",
      "title": "Shape",
      "page": "https://material.spynejs.com/foundations/shape",
      "markdown": "https://material.spynejs.com/foundations/shape.md",
      "summary": "Material's ten corner radii. A component takes its corner from one of them by name; a model does not choose shape, but for a button's `shape` key.",
      "model": {
        "none": "Nothing, with one exception: a button’s `shape` key (`round` or `square`), on the Button page."
      },
      "styles": {
        "title": "The custom properties",
        "says": "A corner is a custom property named `--md-sys-shape-corner-` and then its name:",
        "code": ".my-panel {\n  border-radius: var(--md-sys-shape-corner-medium);\n}",
        "lang": "css"
      },
      "files": [
        {
          "file": "src/scss/00-spynejs-design-system/tokens/_material.scss",
          "holds": "the corners, read from Google’s tokens"
        }
      ]
    },
    {
      "name": "elevation",
      "kind": "foundation",
      "title": "Elevation",
      "page": "https://material.spynejs.com/foundations/elevation",
      "markdown": "https://material.spynejs.com/foundations/elevation.md",
      "summary": "Material's six elevation levels. A level is a height; the template works out the shadow for it when the app is built. A model does not choose elevation.",
      "model": {
        "none": "Nothing. Which level a thing stands at follows from what it is: a section’s surface is an elevated card, the app bar rises once the page has scrolled, a snackbar stands above the page."
      },
      "styles": {
        "title": "In a style",
        "says": "A level’s height is the custom property `--md-sys-elevation-level0` to `--md-sys-elevation-level5`. The height is not a shadow. The shadow for a level comes from a Sass function in the template’s token file, used where a style is written:",
        "code": "@use '../../00-spynejs-design-system/tokens/material';\n\n.my-panel {\n  box-shadow: material.elevation-shadow(2);\n}",
        "lang": "scss",
        "notes": [
          "The path in `@use` is from a file in `src/scss/03-components/material/`; from another folder it changes.",
          "The shadow’s colour is the role `--md-sys-color-shadow`. In the dark scheme a shadow shows much less; that is how Material has it.",
          "A card inside a section is outlined and casts no shadow, so that a card never casts a shadow onto a card."
        ]
      },
      "files": [
        {
          "file": "src/scss/00-spynejs-design-system/tokens/_material.scss",
          "holds": "the levels, and the function that works out a level’s shadow",
          "names": [
            "elevation-shadow"
          ]
        }
      ]
    },
    {
      "name": "motion",
      "kind": "foundation",
      "title": "Motion",
      "page": "https://material.spynejs.com/foundations/motion",
      "markdown": "https://material.spynejs.com/foundations/motion.md",
      "summary": "Material's ten easings and sixteen durations. The template's own moves use them; a model does not choose motion.",
      "model": {
        "none": "Nothing. How a thing moves follows from what it is and from the move being made. The moves between pages are on the Transitions page."
      },
      "styles": {
        "title": "The custom properties",
        "says": "An easing is `--md-sys-motion-easing-` and its name; a duration is `--md-sys-motion-duration-` and its name:",
        "code": ".my-panel {\n  transition: opacity var(--md-sys-motion-duration-short4)\n    var(--md-sys-motion-easing-standard-decelerate);\n}",
        "lang": "css",
        "notes": [
          "Material uses a decelerate easing for what arrives and an accelerate easing for what leaves.",
          "Whatever you make slide, grow or shrink, give it a rule for `@media (prefers-reduced-motion: reduce)`: a fade in its place. A thing that only fades needs none. See the Reduced motion page.",
          "Material’s Expressive set also has springs. CSS has nothing that takes them, so the template does not carry them."
        ]
      },
      "files": [
        {
          "file": "src/scss/00-spynejs-design-system/tokens/_material.scss",
          "holds": "the easings and durations, read from Google’s tokens"
        },
        {
          "file": "src/scss/03-components/material/_motion.scss",
          "holds": "the moves between pages, which use them"
        }
      ]
    },
    {
      "name": "components",
      "kind": "section",
      "title": "Components",
      "page": "https://material.spynejs.com/components",
      "markdown": "https://material.spynejs.com/components.md",
      "summary": "The Material components the template has, one page each: what the thing is, the choices it has, and what an app model writes to ask for it. In the template a component is not something to import: it is plain markup with classes, drawn from the model."
    },
    {
      "name": "button",
      "kind": "component",
      "title": "Button",
      "page": "https://material.spynejs.com/components/buttons",
      "markdown": "https://material.spynejs.com/components/buttons.md",
      "summary": "Material's common button, in five variants, five sizes and two shapes. In an app on the Material template a button is not a component you import: it is the class `btn` with classes for its look, and an app model asks for the look with a `button` key.",
      "model": {
        "says": "A call to action says how its button looks in a `button` key beside its words:",
        "example": {
          "ctaText": "Order ahead",
          "attrCtaHref": "/order",
          "button": {
            "variant": "tonal",
            "size": "md",
            "shape": "square"
          }
        },
        "keysOf": "button",
        "keys": [
          {
            "key": "variant",
            "values": [
              "filled",
              "tonal",
              "outlined",
              "elevated",
              "text"
            ],
            "default": "filled"
          },
          {
            "key": "size",
            "values": [
              "xs",
              "sm",
              "md",
              "lg",
              "xl"
            ],
            "default": "sm"
          },
          {
            "key": "shape",
            "values": [
              "round",
              "square"
            ],
            "default": "round"
          }
        ],
        "rules": [
          "Write only what is not a default. With the whole look at its defaults, leave `button` out.",
          "With no `button` key the button is written `btn btn-primary`, which draws as the filled button at the small size.",
          "A `button` key with nothing in it, or with only defaults in it, is written `btn btn-filled btn-sm`. That draws the same.",
          "The key is read where a call to action is: a page’s `hero`, a call-to-action banner (`cta-banner.tmpl.html`), each row of a split feature (`split-feature.tmpl.html`), and the contact form’s data beside `formFields`.",
          "A model does not say whether a button is disabled.",
          "To have no button, give `ctaText` no words (`\"\"`). A call to action with no words has no button drawn.",
          "The contact form’s button has no `ctaText`. Its words, “Send Message”, are in the form’s template."
        ]
      },
      "styles": {
        "title": "The classes",
        "says": "`btn`, then one class for the variant, one for the size, and `btn-square` for the square shape:",
        "code": "btn btn-tonal btn-md btn-square",
        "lang": "",
        "table": {
          "head": [
            "Choice",
            "Classes"
          ],
          "rows": [
            [
              "Variant",
              "`btn-filled`, `btn-tonal`, `btn-outlined`, `btn-elevated`, `btn-text`"
            ],
            [
              "Size",
              "`btn-xs`, `btn-sm`, `btn-md`, `btn-lg`, `btn-xl`"
            ],
            [
              "Shape",
              "`btn-square` (round needs no class)"
            ]
          ]
        },
        "notes": [
          "A template of your own can write these classes directly on an `<a>` or a `<button>`.",
          "Disabled is the attribute `disabled`, or `aria-disabled=\"true\"` on a link."
        ]
      },
      "files": [
        {
          "file": "src/app/traits/utils/material-button-options.js",
          "holds": "the keys, their values and defaults; the classes for a look",
          "names": [
            "MATERIAL_BUTTON_OPTIONS"
          ]
        },
        {
          "file": "src/app/traits/page/page-item-core-traits.js",
          "holds": "turns the `button` key into `attrButtonClass` before a template renders",
          "names": [
            "pageItemCore$GiveButtonLook"
          ]
        },
        {
          "file": "src/scss/00-spynejs-design-system/elements/_buttons.scss",
          "holds": "the styles"
        }
      ],
      "grammar": [
        "op:shape-data-for-logicless-template",
        "op:attr-prefix-for-attribute-placeholders",
        "op:default-class-with-sparse-exceptions"
      ]
    },
    {
      "name": "card",
      "kind": "component",
      "title": "Card",
      "page": "https://material.spynejs.com/components/cards",
      "markdown": "https://material.spynejs.com/components/cards.md",
      "summary": "Material's card. A page shows its sub-pages as cards, and a card is a link to its page. A card has no keys of its own: it is a sub-page's node in the model. The surface a section sits on is a card too, and a page item's `container` key says whether it has one.",
      "model": {
        "says": "A card is a sub-page’s node, in its page’s `content`. The page it opens is that same node:",
        "example": {
          "pageId": "components",
          "topicId": "buttons",
          "title": "Button",
          "meta": "Five variants, five sizes, two shapes.",
          "ctaText": "Open",
          "href": "#",
          "attrImageSrc": "imgs/gallery/buttons.svg",
          "attrImageAlt": "",
          "pageItems": []
        },
        "keysOf": "a sub-page’s node",
        "keys": [
          {
            "key": "pageId",
            "means": "the page the card is on"
          },
          {
            "key": "topicId",
            "means": "the sub-page it opens"
          },
          {
            "key": "title",
            "means": "the card’s title"
          },
          {
            "key": "meta",
            "means": "its supporting text"
          },
          {
            "key": "ctaText",
            "means": "the words at its foot"
          },
          {
            "key": "attrImageSrc",
            "means": "its picture"
          },
          {
            "key": "attrImageAlt",
            "means": "the picture’s words for a reader who cannot see it"
          },
          {
            "key": "pageItems",
            "means": "what the page it opens shows"
          }
        ],
        "rules": [
          "A sub-page needs its route as well: its `topicId` under its `pageId`, in `src/index.js`.",
          "Which card a thing is follows from where it is, not from a key. A card inside a page is outlined. The surface a section sits on is elevated.",
          "A page item says whether it has that surface in its `container` key: `{ \"isEnabled\": true }` for the elevated surface, `{ \"isEnabled\": false }` to sit straight on the page.",
          "`\"classOptions\": { \"variant\": \"muted\" }` in `container` is the Shell’s option for a quieter surface. In the Material template that surface is the page’s own colour with no shadow, so only its padding shows."
        ]
      },
      "styles": {
        "title": "The markup",
        "says": "The template writes a card as a list item holding a link. The link’s class, `page-card`, is what makes it a card that can be pressed, and what the move down into its page starts from:",
        "code": "<li class=\"card\">\n  <a\n    href=\"#\"\n    data-channel=\"ROUTE\"\n    data-page-id=\"components\"\n    data-topic-id=\"buttons\"\n    data-event-prevent-default=\"true\"\n    class=\"page-card\"\n  >\n    <div class=\"card__image-wrapper\">\n      <img alt=\"\" src=\"imgs/gallery/buttons.svg\" class=\"card__image\" />\n    </div>\n    <div class=\"card__content\">\n      <h2 class=\"card__title\">Button</h2>\n      <p class=\"card__meta\">Five variants, five sizes, two shapes.</p>\n      <p class=\"card__meta card__meta__cta\">Open</p>\n    </div>\n  </a>\n</li>",
        "lang": "html"
      },
      "files": [
        {
          "file": "src/app/components/page-items/templates/cards-container-view.tmpl.html",
          "holds": "a card’s markup"
        },
        {
          "file": "src/app/components/page-items/cards-container-view.js",
          "holds": "the view that shows a page’s sub-pages as cards"
        },
        {
          "file": "src/scss/03-components/material/_cards.scss",
          "holds": "the styles: which card each of the Shell’s containers is"
        }
      ],
      "grammar": [
        "op:author-app-model-node"
      ]
    },
    {
      "name": "text-field",
      "kind": "component",
      "title": "Text field",
      "page": "https://material.spynejs.com/components/text-fields",
      "markdown": "https://material.spynejs.com/components/text-fields.md",
      "summary": "Material's outlined text field. Any text input or textarea in an app on the template is one. In the contact form a field is an entry of `formFields`, and three keys of the entry say whether it must be filled in, whether it is disabled, and whether it has several lines.",
      "model": {
        "says": "A field is one entry of the contact form’s `formFields`:",
        "example": {
          "attrId": "reply-to",
          "attrName": "replyTo",
          "attrType": "email",
          "label": "Reply to",
          "attrPlaceholder": "you@example.com",
          "attrRequired": true
        },
        "keysOf": "an entry of `formFields`",
        "keys": [
          {
            "key": "attrId",
            "means": "the control’s `id`; unique on the page"
          },
          {
            "key": "attrName",
            "means": "the control’s `name`: the name its value is sent under"
          },
          {
            "key": "label",
            "means": "the label’s words"
          },
          {
            "key": "attrType",
            "means": "the input’s `type`, such as `text`, `email`, `tel`, `url`, `number`; left out when `multiline` is true"
          },
          {
            "key": "attrPlaceholder",
            "means": "the placeholder"
          },
          {
            "key": "attrRequired",
            "means": "`true`: the field must be filled in",
            "default": "it need not be"
          },
          {
            "key": "attrDisabled",
            "means": "`true`: shown, but not to be used",
            "default": "in use"
          },
          {
            "key": "multiline",
            "means": "`true`: several lines, a `<textarea>`",
            "default": "one line, an `<input>`"
          }
        ],
        "rules": [
          "Leave `attrRequired`, `attrDisabled` and `multiline` out when they are false.",
          "A disabled field takes no part in validation, so `attrRequired` on one does nothing.",
          "The form always has a Message field after the entries of `formFields`; it is not an entry. Its words are the form’s `messageLabel` and `attrMessagePlaceholder`.",
          "The whole form is the page item with `viewClass` `ContactUsView` and the template `contact-us.tmpl.html`. The From a model page writes one out in full.",
          "The form’s button says “Send Message”. The words are in the form’s template, and no key changes them. Its look is the form’s `button` key, beside `formFields`.",
          "What the form says once a message is sent is `successMessage`, in the page item’s `props`, beside `data`."
        ]
      },
      "styles": {
        "title": "The markup the styles need",
        "says": "Any `<input>` of a text kind and any `<textarea>` gets the field: its outline, and its hover, focus, error and disabled states. For the floating label and the line for an error, the control sits in a wrapper with its label before it and the error’s line after it:",
        "code": "<div class=\"contact-us__field\">\n  <label for=\"reply-to\">Reply to</label>\n  <input\n    id=\"reply-to\"\n    name=\"replyTo\"\n    type=\"email\"\n    placeholder=\"you@example.com\"\n    required\n    aria-describedby=\"reply-to-error\"\n  />\n  <p class=\"contact-us__field-error\" id=\"reply-to-error\"></p>\n</div>",
        "lang": "html",
        "notes": [
          "The label floats by styles alone: it rests inside the field, and rises when the field is focused or filled. “Filled” is read from the placeholder (`:not(:placeholder-shown)`), so give every field a `placeholder`: without one a field always counts as filled, and its label stays risen.",
          "The error shows once the visitor has used the field or tried to send the form. Whether a field is wrong is the browser’s own checking, from the control’s `type` and `required`.",
          "The words of the error are the browser’s own message, copied into the line by the form’s trait."
        ]
      },
      "files": [
        {
          "file": "src/app/traits/form/form-contact-us-traits.js",
          "holds": "which control an entry asks for; the form’s data as its template needs it; the error’s words",
          "names": [
            "contactUs$ControlFor",
            "contactUs$ShapeData",
            "contactUs$MirrorFieldError"
          ]
        },
        {
          "file": "src/app/components/page-items/templates/contact-us.tmpl.html",
          "holds": "the form’s markup: each control once for each case, each in a section of its own"
        },
        {
          "file": "src/app/components/page-items/form-contact-us-view.js",
          "holds": "the form’s view, `ContactUsView`"
        },
        {
          "file": "src/scss/03-components/material/_text-fields.scss",
          "holds": "the styles"
        }
      ],
      "grammar": [
        "op:conditional-via-object-section",
        "op:shape-data-for-logicless-template",
        "op:safeclone-for-proxified-data",
        "op:live-mirror-via-el$",
        "record:form-validate-submit"
      ]
    },
    {
      "name": "snackbar",
      "kind": "component",
      "title": "Snackbar",
      "page": "https://material.spynejs.com/components/snackbar",
      "markdown": "https://material.spynejs.com/components/snackbar.md",
      "summary": "Material's snackbar: a brief report of something the app has done, at the bottom of the window, one at a time, gone by itself after five seconds. A view asks the Material channel for one, in code. A model does not ask for one.",
      "model": {
        "none": "Nothing directly. A snackbar is asked for by a view, in code. A model reaches one only through a page item’s own words: the contact form shows its `successMessage` in one when a message has been sent. `successMessage` is in the page item’s `props`, beside `data`, not inside it.",
        "example": {
          "viewClass": "ContactUsView",
          "props": {
            "successMessage": "Your message has been sent."
          }
        }
      },
      "code": {
        "title": "In a view",
        "says": "A view asks by sending the request to the Material channel, with the words to show:",
        "code": "this.sendInfoToChannel(\n  'CHANNEL_MATERIAL',\n  { message: 'Your message has been sent.' },\n  'CHANNEL_MATERIAL_SNACKBAR_REQUEST',\n);",
        "lang": "js",
        "table": {
          "head": [
            "Action of `CHANNEL_MATERIAL`",
            "Direction",
            "Payload",
            "Means"
          ],
          "rows": [
            [
              "`CHANNEL_MATERIAL_SNACKBAR_REQUEST`",
              "in, from any view",
              "`{ message }`",
              "show this"
            ],
            [
              "`CHANNEL_MATERIAL_SNACKBAR_SHOW_EVENT`",
              "out",
              "`{ snackbarId, message }`",
              "one is being shown"
            ],
            [
              "`CHANNEL_MATERIAL_SNACKBAR_HIDE_EVENT`",
              "out",
              "`{ snackbarId }`",
              "its time is up"
            ]
          ]
        },
        "notes": [
          "That is all a view does. It does not make the snackbar, place it or time it: the channel and the snackbar’s own views do.",
          "A newer snackbar replaces the one on screen.",
          "Its words are announced to assistive technology without moving focus.",
          "It has no action button. The message is plain words."
        ]
      },
      "files": [
        {
          "file": "src/app/channels/channel-material.js",
          "holds": "the Material channel: its actions, and how long a snackbar stays (`snackbarDuration`, in milliseconds)",
          "names": [
            "CHANNEL_MATERIAL_SNACKBAR_REQUEST",
            "snackbarDuration"
          ]
        },
        {
          "file": "src/app/traits/channel/channel-material-traits.js",
          "holds": "takes the request, shows the snackbar, and hides it when its time is up",
          "names": [
            "channelMaterial$OnSnackbarRequest",
            "channelMaterial$OnSnackbarTimeUp"
          ]
        },
        {
          "file": "src/app/components/material/material-snackbar-host-view.js",
          "holds": "the region at the bottom of the app where snackbars appear"
        },
        {
          "file": "src/app/components/material/material-snackbar-view.js",
          "holds": "one snackbar, which removes itself"
        },
        {
          "file": "src/scss/03-components/material/_snackbar.scss",
          "holds": "the styles"
        }
      ],
      "grammar": [
        "record:toast-notification-system",
        "op:transmit-into-channel",
        "op:register-channel-action-vocabulary"
      ]
    },
    {
      "name": "top-app-bar",
      "kind": "component",
      "title": "Top app bar",
      "page": "https://material.spynejs.com/components/app-bar",
      "markdown": "https://material.spynejs.com/components/app-bar.md",
      "summary": "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.",
      "model": {
        "says": "The bar’s title is the model’s `text.header`:",
        "example": {
          "text": {
            "header": "Material shell gallery"
          }
        },
        "rules": [
          "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."
        ]
      },
      "code": {
        "title": "In a view",
        "says": "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:",
        "code": "import { SpyneTrait, ViewStream } from 'spyne';\n\nclass MyPanelTraits extends SpyneTrait {\n  constructor(context) {\n    let traitPrefix = 'myPanel$';\n    super(context, traitPrefix);\n  }\n\n  static myPanel$OnScrollState(e) {\n    const { scrolled } = e.payload;\n    this.props.el$.toggleClass('is-raised', scrolled);\n  }\n}\n\nexport class MyPanelView extends ViewStream {\n  constructor(props = {}) {\n    props.traits = [MyPanelTraits];\n    props.channels = ['CHANNEL_MATERIAL'];\n    super(props);\n  }\n\n  addActionListeners() {\n    return [['CHANNEL_MATERIAL_SCROLL_EVENT', 'myPanel$OnScrollState']];\n  }\n}",
        "lang": "js",
        "table": {
          "head": [
            "Action of `CHANNEL_MATERIAL`",
            "Direction",
            "Payload",
            "Means"
          ],
          "rows": [
            [
              "`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."
            ]
          ]
        },
        "notes": [
          "The listener is a method of a trait, named in `addActionListeners`. What the channel sent is `e.payload`."
        ]
      },
      "files": [
        {
          "file": "src/app/components/ui-elements/ui-header-view.js",
          "holds": "the header’s view; it listens to the Material channel"
        },
        {
          "file": "src/app/traits/ui/ui-header-view-traits.js",
          "holds": "sets `is-scrolled` on the header",
          "names": [
            "uiHeader$OnScrollState"
          ]
        },
        {
          "file": "src/app/traits/channel/channel-material-traits.js",
          "holds": "turns the window’s scrolling into the one change",
          "names": [
            "channelMaterial$OnWindowScroll"
          ]
        },
        {
          "file": "src/scss/03-components/material/_app-bar.scss",
          "holds": "the bar’s two looks"
        },
        {
          "file": "src/scss/03-components/material/_navigation.scss",
          "holds": "the bar’s links and its two icon buttons"
        }
      ],
      "grammar": [
        "op:state-machine-in-channel",
        "op:window-event-via-channel",
        "op:declare-action-listeners"
      ]
    },
    {
      "name": "navigation-drawer",
      "kind": "component",
      "title": "Navigation drawer",
      "page": "https://material.spynejs.com/components/drawer",
      "markdown": "https://material.spynejs.com/components/drawer.md",
      "summary": "Material's navigation drawer, as a modal: the app's destinations in a panel that opens over the page from a menu button, in a window narrower than 840px. From 840px the app bar shows the links itself and there is no drawer. A model does not ask for it; its links are the app's routes.",
      "model": {
        "none": "Nothing. The drawer’s links are the app’s routes, declared in `src/index.js`, and a link’s words are the route’s key. Add a route and the drawer has its link."
      },
      "code": {
        "title": "How it behaves",
        "says": "The drawer has a channel of its own, `CHANNEL_MENU_DRAWER`, which holds whether it is open. It closes when a destination is followed, when the scrim is pressed, on Escape, and when the window passes one of Material’s breakpoints. The Material channel reports the reasons that are not the drawer’s own:",
        "table": {
          "head": [
            "Action of `CHANNEL_MATERIAL`",
            "Direction",
            "Payload",
            "Means"
          ],
          "rows": [
            [
              "`CHANNEL_MATERIAL_DISMISS_EVENT`",
              "out",
              "`{ reason }`",
              "something asked for whatever is open to close. `reason` is `escape` or `route`."
            ],
            [
              "`CHANNEL_MATERIAL_BREAKPOINT_EVENT`",
              "out",
              "`{ breakpoint }`",
              "the window entered another of Material’s sizes"
            ]
          ]
        },
        "notes": [
          "Opening it moves focus to its first link.",
          "Anything of your own that opens over the page can close for the same reasons by listening to `CHANNEL_MATERIAL_DISMISS_EVENT`.",
          "The template has no drawer that stands open beside the page. The gallery’s sidebar is the gallery’s own layout."
        ]
      },
      "files": [
        {
          "file": "src/app/channels/channel-menu-drawer.js",
          "holds": "the drawer’s channel: whether it is open"
        },
        {
          "file": "src/app/traits/channel/channel-menu-drawer-traits.js",
          "holds": "what opens and closes it",
          "names": [
            "channelMenuDrawer$OnCloseRequest",
            "channelMenuDrawer$OnUiClick"
          ]
        },
        {
          "file": "src/app/components/ui-elements/ui-menu-drawer-view.js",
          "holds": "the drawer’s view"
        },
        {
          "file": "src/scss/03-components/ui/menu-drawer.scss",
          "holds": "the styles"
        },
        {
          "file": "src/index.js",
          "holds": "the routes its links come from"
        }
      ],
      "grammar": [
        "record:modal-open-close",
        "op:state-machine-in-channel",
        "op:choose-replay-semantics",
        "record:responsive-behavior-on-media-query"
      ]
    },
    {
      "name": "from-a-model",
      "kind": "component",
      "title": "From a model",
      "page": "https://material.spynejs.com/components/from-a-model",
      "markdown": "https://material.spynejs.com/components/from-a-model.md",
      "summary": "The model keys at work: a hero, a call-to-action banner, a split feature and a contact form, each one of the Shell's own page items drawn from the model as a generated app would write it, and each with the piece of the model that draws it written out beside it. This is the page to copy from.",
      "model": {
        "says": "Four things, and where each is written in a model. Each one’s model is written out in full below, as the page shows it.",
        "keys": [
          {
            "key": "hero",
            "means": "on a page’s own node: the page’s hero"
          },
          {
            "key": "pageItems",
            "means": "on a page’s node: the list of what the page shows under its hero, in order"
          },
          {
            "key": "viewClass",
            "means": "in a page item: `ViewStream` for one that is a template and data; `ContactUsView` for the contact form"
          },
          {
            "key": "isPrototype",
            "means": "in a page item: `false` where `props.template` is a file’s name. Without it the name is taken for the template’s own text and drawn as words."
          },
          {
            "key": "props.template",
            "means": "in a page item: which of the template’s page items it is, by its file’s name, such as `cta-banner.tmpl.html` or `split-feature.tmpl.html`"
          },
          {
            "key": "props.data",
            "means": "in a page item: its words, and its `button` key where it has a call to action"
          },
          {
            "key": "props.class",
            "means": "in the contact form’s page item: `contact-us`, the class its styles go by"
          },
          {
            "key": "container",
            "means": "in a page item: `{ \"isEnabled\": true }` for the surface it sits on"
          }
        ],
        "rules": [
          "A key that names an attribute starts with `attr`: `attrCtaHref`, `attrImageSrc`, `attrId`. A key that is words does not: `ctaText`, `headline`, `label`. One exception, which is the Shell’s: a split feature’s row writes its link as `ctaHref`.",
          "Each row of a split feature has its own `ctaText`, so each may have its own `button` key.",
          "In the contact form the `button` key sits beside `formFields`. The form always adds a Message field after the entries of `formFields`.",
          "A banner’s button is a link of the app’s router and goes by `attrPageId`, the `pageId` of the page it leads to; `attrCtaHref` is the same place as an address. A hero’s button and a row’s button are plain links and take only the address.",
          "The form on this page is a placeholder: it sends to the Shell’s mock endpoint, which answers only while a dev build is running."
        ]
      },
      "styles": {
        "title": "The keys each one reads",
        "says": "From each one’s template. Each is written out in full, with its values, in the page as it is shown below.",
        "table": {
          "head": [
            "Thing",
            "Where",
            "Keys"
          ],
          "rows": [
            [
              "Hero",
              "`hero`, on the page’s node",
              "`eyebrow`, `headline`, `subheadline`, `ctaText`, `attrCtaHref`, `attrImageSrc`, `attrImageAlt`, `button`"
            ],
            [
              "Call-to-action banner",
              "`props.data`",
              "`headline`, `text`, `ctaText`, `attrCtaHref`, `attrPageId`, `button`"
            ],
            [
              "Split feature",
              "`props.data.rows`, a list",
              "each row: `headline`, `text`, `attrImageSrc`, `ctaHref`, `ctaText`, `button`"
            ],
            [
              "Contact form",
              "`props.data`",
              "`title`, `subtitle`, `formFields`, `messageLabel`, `attrMessagePlaceholder`, `button`; and `successMessage` in `props`"
            ]
          ]
        },
        "notes": [
          "A row’s picture takes the row’s `headline` for its words; a row has no key for them.",
          "Give `ctaText` no words (`\"\"`) and no button is drawn."
        ]
      },
      "files": [
        {
          "file": "src/app/components/page-items/templates/hero.tmpl.html",
          "holds": "the hero"
        },
        {
          "file": "src/app/components/page-items/templates/cta-banner.tmpl.html",
          "holds": "the call-to-action banner"
        },
        {
          "file": "src/app/components/page-items/templates/split-feature.tmpl.html",
          "holds": "the split feature and its rows"
        },
        {
          "file": "src/app/components/page-items/templates/contact-us.tmpl.html",
          "holds": "the contact form"
        },
        {
          "file": "src/app/traits/page/page-item-core-traits.js",
          "holds": "makes a page item from its entry in the model, and gives a call to action its button’s look",
          "names": [
            "pageItemCore$GiveButtonLook"
          ]
        },
        {
          "file": "src/app/traits/utils/page-item-template-lookup.js",
          "holds": "every template in that folder by its file’s name: what a model’s `props.template` can name"
        }
      ],
      "grammar": [
        "op:author-pageitem-spec",
        "op:author-app-model-node"
      ]
    },
    {
      "name": "features",
      "kind": "section",
      "title": "Features",
      "page": "https://material.spynejs.com/features",
      "markdown": "https://material.spynejs.com/features.md",
      "summary": "What the template does everywhere without being asked: the ripple, reduced motion, and Material’s breakpoints. None of these is a thing a model asks for; every app on the template has them."
    },
    {
      "name": "ripple",
      "kind": "feature",
      "title": "Ripple",
      "page": "https://material.spynejs.com/features/ripple",
      "markdown": "https://material.spynejs.com/features/ripple.md",
      "summary": "Material's ripple: a press on a button, a card or a navigation link spreads from the point that was pressed. Every app on the template has it, on everything of the template's that can be pressed. A model does not ask for it.",
      "model": {
        "none": "Nothing. Everything of the template’s that can be pressed ripples: a generated app gets it with the template."
      },
      "styles": {
        "title": "What ripples",
        "says": "These, and nothing else:",
        "table": {
          "head": [
            "Selector",
            "What it is"
          ],
          "rows": [
            [
              "`.btn`",
              "a button"
            ],
            [
              "`a.page-card`",
              "a card that is a link"
            ],
            [
              "`.site-nav a.nav`",
              "a link in the app bar"
            ],
            [
              "`#menu-drawer a.nav`",
              "a link in the drawer"
            ],
            [
              "`.theme-toggle`",
              "the button for the colour scheme"
            ],
            [
              "`#menu_toggle`",
              "the menu button"
            ]
          ]
        },
        "notes": [
          "So a call to action written with the class `btn` ripples, and a card written as `a.page-card` does. Nothing more is needed.",
          "The styles draw the ripple. One view, `MaterialRippleNullView`, hears every press from the window channel and writes the pressed point on the pressed element as two custom properties, `--ripple-x` and `--ripple-y`, in pixels from its top-left corner. Pressed from the keyboard, a ripple starts in the middle.",
          "An element of your own does not ripple by being pressable. It would need to be in the trait’s list and to have the ripple’s styles; the two are kept in step by hand. Use `btn` or `a.page-card` instead where you can.",
          "With reduced motion asked for there is no ripple: the pressed layer shows flat, at once."
        ]
      },
      "files": [
        {
          "file": "src/app/components/material/material-ripple-null-view.js",
          "holds": "the one view that writes the pressed point",
          "names": [
            "MaterialRippleNullView"
          ]
        },
        {
          "file": "src/app/traits/material/material-ripple-traits.js",
          "holds": "the list of what ripples; the point of a press",
          "names": [
            "materialRipple$OnPointerDown",
            "materialRipple$OnKeyPress"
          ]
        },
        {
          "file": "src/scss/03-components/material/_ripple.scss",
          "holds": "the ripple for cards, navigation links and icon buttons"
        },
        {
          "file": "src/scss/00-spynejs-design-system/elements/_buttons.scss",
          "holds": "the button’s own ripple"
        }
      ],
      "grammar": [
        "op:null-appended-behavior-view",
        "op:window-event-via-channel",
        "op:dynamic-children-ingress"
      ]
    },
    {
      "name": "reduced-motion",
      "kind": "feature",
      "title": "Reduced motion",
      "page": "https://material.spynejs.com/features/reduced-motion",
      "markdown": "https://material.spynejs.com/features/reduced-motion.md",
      "summary": "What the template does when a visitor's system asks for less motion. Material's answer is subtle fades in place of sliding and scaling, not no motion at all. Every moving thing in the template has both ways. A model does not ask for it.",
      "model": {
        "none": "Nothing. It is the visitor’s setting, and every app on the template follows it."
      },
      "styles": {
        "title": "In a style",
        "says": "Anything of your own that slides, grows or shrinks needs a second rule, for a visitor who asks for less. Keep a fade; drop the rest:",
        "code": ".my-panel {\n  transition:\n    opacity var(--md-sys-motion-duration-short4)\n      var(--md-sys-motion-easing-standard-decelerate),\n    transform var(--md-sys-motion-duration-short4)\n      var(--md-sys-motion-easing-standard-decelerate);\n}\n\n@media (prefers-reduced-motion: reduce) {\n  .my-panel {\n    transition: opacity var(--md-sys-motion-duration-short4)\n      var(--md-sys-motion-easing-standard-decelerate);\n  }\n}",
        "lang": "css",
        "notes": [
          "A thing that only fades is already the reduced way and needs no second rule.",
          "Do not cut from one thing to another with nothing between: Material asks for a fade there.",
          "It is styles alone. No script reads the setting."
        ]
      },
      "files": [
        {
          "file": "src/scss/03-components/material/_motion.scss",
          "holds": "the moves between pages, each with its reduced way"
        },
        {
          "file": "src/scss/03-components/material/_ripple.scss",
          "holds": "the ripple, and what shows in its place"
        },
        {
          "file": "src/scss/03-components/material/_snackbar.scss",
          "holds": "the snackbar arriving"
        },
        {
          "file": "src/scss/03-components/ui/menu-drawer.scss",
          "holds": "the drawer opening"
        }
      ]
    },
    {
      "name": "breakpoints",
      "kind": "feature",
      "title": "Breakpoints",
      "page": "https://material.spynejs.com/features/breakpoints",
      "markdown": "https://material.spynejs.com/features/breakpoints.md",
      "summary": "Material's five window sizes, by width: compact, medium, expanded, large and extra-large. The template changes its navigation at 840px, and the Material channel reports each time the window enters a size. A model does not ask for any of it.",
      "model": {
        "none": "Nothing. The five are declared once, in `src/index.js`, as media queries for the window channel."
      },
      "code": {
        "title": "In a view",
        "says": "A view that changes with the window’s size listens to the Material channel, not to the window. A whole view and its trait:",
        "code": "import { SpyneTrait, ViewStream } from 'spyne';\n\nclass MyPanelTraits extends SpyneTrait {\n  constructor(context) {\n    let traitPrefix = 'myPanel$';\n    super(context, traitPrefix);\n  }\n\n  static myPanel$OnBreakpoint(e) {\n    const { breakpoint } = e.payload;\n    this.props.el$.toggleClass('is-compact', breakpoint === 'compact');\n  }\n}\n\nexport class MyPanelView extends ViewStream {\n  constructor(props = {}) {\n    props.traits = [MyPanelTraits];\n    props.channels = ['CHANNEL_MATERIAL'];\n    super(props);\n  }\n\n  addActionListeners() {\n    return [['CHANNEL_MATERIAL_BREAKPOINT_EVENT', 'myPanel$OnBreakpoint']];\n  }\n}",
        "lang": "js",
        "table": {
          "head": [
            "Action of `CHANNEL_MATERIAL`",
            "Direction",
            "Payload",
            "Means"
          ],
          "rows": [
            [
              "`CHANNEL_MATERIAL_BREAKPOINT_EVENT`",
              "out",
              "`{ breakpoint }`",
              "the window entered that size. `breakpoint` is `compact`, `medium`, `expanded`, `large` or `extra-large`."
            ]
          ]
        },
        "notes": [
          "The listener is a method of a trait, named in `addActionListeners`. What the channel sent is `e.payload`.",
          "It reports a change. It does not say which size the window started in, so a view hears nothing until the window is resized across a line.",
          "What must be right from the start belongs in styles, which always know: write a media query with the same widths, such as `@media (width < 600px)` for compact. There is no way to ask the channel for the size the window started in.",
          "The widths: compact under 600px; medium 600 to 839px; expanded 840 to 1199px; large 1200 to 1599px; extra-large 1600px and over."
        ]
      },
      "files": [
        {
          "file": "src/index.js",
          "holds": "the five media queries, under names that start with `material`",
          "names": [
            "materialCompact",
            "materialMedium",
            "materialExpanded",
            "materialLarge",
            "materialExtraLarge"
          ]
        },
        {
          "file": "src/app/traits/channel/channel-material-traits.js",
          "holds": "turns a media query starting to match into the size’s name",
          "names": [
            "channelMaterial$OnBreakpointEntered"
          ]
        },
        {
          "file": "src/app/channels/channel-material.js",
          "holds": "the Material channel and its actions"
        }
      ],
      "grammar": [
        "op:window-event-via-channel",
        "record:responsive-behavior-on-media-query"
      ]
    },
    {
      "name": "transitions",
      "kind": "transition",
      "title": "Transitions",
      "page": "https://material.spynejs.com/transitions",
      "markdown": "https://material.spynejs.com/transitions.md",
      "summary": "Material's transitions between pages. The template names every move from the route and moves the pages to suit: a fade between destinations, a slide down or up a level, and a card growing into its page. A model does not ask for a transition; which one a move takes follows from the route and from what was followed.",
      "model": {
        "none": "Nothing. A transition follows from where the move goes and from what was followed, not from a key. What a model decides is the pages and their levels: a page with sub-pages shows them as cards, and following a card down a level is the container transform."
      },
      "code": {
        "title": "Which move takes which transition",
        "says": "The Material channel reads the kind of move from the route change and names it:",
        "table": {
          "head": [
            "Transition",
            "The move",
            "What is seen"
          ],
          "rows": [
            [
              "`top-level`",
              "between destinations, or between two pages at the same level. A move from a sub-page straight to another destination is this one too.",
              "the page fades out, then the next fades in"
            ],
            [
              "`forward`",
              "down a level, by anything but a card",
              "the page slides out to one side as the next slides in from the other"
            ],
            [
              "`container-transform`",
              "down a level, by a card (`a.page-card`)",
              "the card’s shape grows into its page"
            ],
            [
              "`backward`",
              "back up a level, by any way: a link, the breadcrumb, the browser’s Back",
              "where the page returned to shows the page being left as a card, that page shrinks into its card, however it was reached. Where it has no such card, the pages slide, the mirror of forward."
            ]
          ]
        },
        "notes": [
          "To get the container transform, lead down a level with the template’s own card. Any other link down a level slides.",
          "The channel’s actions, for a view that must know of a move: `CHANNEL_MATERIAL_PAGE_LEAVING_EVENT` with `{ pageMoveId, transition, from }` when a move begins, and `CHANNEL_MATERIAL_PAGE_LEFT_EVENT` with `{ pageMoveId, transition }` when the leaving page’s time is up.",
          "A page learns of the move that made it from a second channel, `CHANNEL_MATERIAL_PAGES`, which replays. Its one action out, `CHANNEL_MATERIAL_PAGES_MOVE_EVENT`, always carries the whole move: `{ pageMoveId, transition, from, phase }`.",
          "A leaving page carries the class `is-leaving`; the stage carries the move’s name in `data-page-transition`. The moves themselves are styles.",
          "A card growing into its page, and a page shrinking into its card, use the browser’s view transitions. Where a browser has none, the move down takes `forward` and the move back stays the slide.",
          "With reduced motion asked for, every move keeps its fades and loses the rest.",
          "Never time a page’s exit in a view. The wait is the channel’s."
        ]
      },
      "files": [
        {
          "file": "src/app/channels/channel-material.js",
          "holds": "the Material channel: a move beginning and ending, and how long a leaving page is given (`pageExitDuration`)",
          "names": [
            "CHANNEL_MATERIAL_PAGE_LEAVING_EVENT",
            "CHANNEL_MATERIAL_PAGE_LEFT_EVENT",
            "pageExitDuration"
          ]
        },
        {
          "file": "src/app/traits/channel/channel-material-traits.js",
          "holds": "names the transition from the route change",
          "names": [
            "channelMaterial$OnRouteChange",
            "pageTransitionFromRoute"
          ]
        },
        {
          "file": "src/app/channels/channel-material-pages.js",
          "holds": "the move under way, in full, replayed to a page made by it",
          "names": [
            "CHANNEL_MATERIAL_PAGES_MOVE_EVENT"
          ]
        },
        {
          "file": "src/app/traits/app/stage-container-traits.js",
          "holds": "the stage: changes the pages over, and writes the move’s name on their holder",
          "names": [
            "stage$OnPageMove",
            "stage$OnPageLeaving",
            "stage$OnPageCollapse"
          ]
        },
        {
          "file": "src/app/traits/page/page-leave-traits.js",
          "holds": "how a page leaves; marks the card a move began on",
          "names": [
            "pageLeave$OnRouteChange"
          ]
        },
        {
          "file": "src/app/traits/page/page-return-traits.js",
          "holds": "a page being returned to: finds the card the leaving page collapses into",
          "names": [
            "pageReturn$OnPageMove"
          ]
        },
        {
          "file": "src/scss/03-components/material/_motion.scss",
          "holds": "the moves themselves, with their timings"
        }
      ],
      "grammar": [
        "op:react-to-route-diff",
        "op:state-machine-in-channel",
        "op:choose-replay-semantics",
        "op:escape-to-raw-rxjs"
      ]
    },
    {
      "name": "transitions-sample-a",
      "kind": "sample",
      "title": "Sample A",
      "page": "https://material.spynejs.com/transitions/sample-a",
      "markdown": "https://material.spynejs.com/transitions/sample-a.md",
      "summary": "A page under Transitions, there to be moved to and from. It has nothing of its own to ask for; see the Transitions page."
    },
    {
      "name": "transitions-sample-b",
      "kind": "sample",
      "title": "Sample B",
      "page": "https://material.spynejs.com/transitions/sample-b",
      "markdown": "https://material.spynejs.com/transitions/sample-b.md",
      "summary": "A second page under Transitions, there to be moved to and from. It has nothing of its own to ask for; see the Transitions page."
    },
    {
      "name": "transitions-sample-c",
      "kind": "sample",
      "title": "Sample C",
      "page": "https://material.spynejs.com/transitions/sample-c",
      "markdown": "https://material.spynejs.com/transitions/sample-c.md",
      "summary": "A third page under Transitions, there to be moved to and from. It has nothing of its own to ask for; see the Transitions page."
    }
  ]
}
