@machfivetechchicago/machvive-neodigm55-ux 0.1.0 → 0.1.2

package/README.md

@@ -74,7 +74,7 @@ is the difference that makes a theme builder possible:
 ```js
 import { installTheme, themeCss } from '@machfivetechchicago/machvive-neodigm55-ux/conductor';
 
-installTheme();                    // --n55-brand, --n55-brand-deep, --n55-brand-glyph, …
+installTheme();                    // --n55-brand, --n55-brand-deep, --n55-brand-ink, …
 themeCss(myPalette, '.promo');     // or emit a stylesheet for a section, or for a build
 ```
 
@@ -82,6 +82,28 @@ Override `--n55-brand` on a page and every component follows, with no rebuild an
 component aware it happened. `disabled` doubles as the opt-out: an element themed
 `disabled` is never choreographed.
 
+Text on a theme colour uses `--n55-<name>-ink` (and `-deep-ink` on the deep shade):
+near-black or white, whichever contrasts more, computed by `inkFor()` so a custom
+palette stays readable. `contrast()` is exported for auditing a palette in CI.
+
+### Light and dark
+
+Components follow the `color-scheme` they inherit, per instance, with no JavaScript.
+Surfaces that are not a theme colour — Buffet's top row, an unthemed selection — come
+from `--n55-surface`, `--n55-surface-ink`, `--n55-line`, `--n55-inverse` and
+`--n55-inverse-ink`, each a `light-dark()` pair.
+
+```html
+<html style="color-scheme: light dark">        <!-- follow the OS -->
+<html data-n55-scheme="dark">                   <!-- pin the page -->
+<aside data-n55-scheme="dark">                  <!-- or one section -->
+<neodigm-buffet data-n55-scheme="light">        <!-- or one instance -->
+```
+
+The palette never sets `color-scheme` on `:root` itself, because that also restyles
+the page's scrollbars and form controls. Theme colours and their inks are the same in
+both modes.
+
 ## Toast
 
 ```html
@@ -99,6 +121,35 @@ Queued, with the original's debounce — the same message twice in a row is the
 notification. `|` breaks the line. **Message text is never parsed as HTML**, unlike the
 original's `innerHTML`, because toast text is routinely built from user input.
 
+## Buffet
+
+A full-width, two-level menu driven by metadata. The top row divides its
+container's width evenly; the selection's children sit below at half the height.
+Both levels keep a selection, and each item remembers its last child.
+
+```html
+<neodigm-buffet data-n55-theme="brand" data-n55-buffet='[
+  {"token":"shows","caption":"Shows","selected":true,"secondary":[
+    {"token":"live","caption":"Live"},{"token":"vod","caption":"VOD"}]},
+  {"token":"people","caption":"People","count":3,"theme":"marcom"}
+]'></neodigm-buffet>
+```
+
+```js
+const menu = document.querySelector('neodigm-buffet');
+menu.addEventListener('neodigm-buffet-select', (e) => {
+  if (hasUnsavedWork()) e.preventDefault();      // cancelable, at either level
+  else route(e.detail.primary, e.detail.secondary);
+});
+menu.select('shows', 'vod');                     // sync to a route, silently
+menu.items = relabelled;                         // selection survives where tokens do
+menu.updateCount('people', 4);
+```
+
+The theme on the host colours the whole menu, so a sweep moves across it as one
+instrument. An item's own `theme` is an accent that a sweep does not reach. Height
+is `--n55-buffet-height` (default `64px`). Sticky positioning is left to the page.
+
 ## What changed in the port
 
 | | Original | Here |

package/index.d.ts

@@ -4,4 +4,6 @@ export { NeodigmMarquee, DEFAULT_SPEED, parseRuns, plainText } from './src/wc/ne
 export type { MarqueeCell } from './src/wc/neodigm-marquee/neodigm-marquee.js';
 export { NeodigmTulip, TULIP_DEFAULTS, readConfig, configFrom } from './src/wc/neodigm-tulip/neodigm-tulip.js';
 export type { TulipConfig } from './src/wc/neodigm-tulip/neodigm-tulip.js';
+export { NeodigmBuffet, readItems } from './src/wc/neodigm-buffet/neodigm-buffet.js';
+export type { BuffetItem, BuffetSelection, BuffetSelectDetail } from './src/wc/neodigm-buffet/neodigm-buffet.js';
 export * from './src/conductor/index.js';

package/index.js

@@ -10,12 +10,15 @@
 import { NeodigmToast, DEFAULT_DURATION } from './src/wc/neodigm-toast/neodigm-toast.js';
 import { NeodigmMarquee, DEFAULT_SPEED, parseRuns, plainText } from './src/wc/neodigm-marquee/neodigm-marquee.js';
 import { NeodigmTulip, TULIP_DEFAULTS, readConfig, configFrom } from './src/wc/neodigm-tulip/neodigm-tulip.js';
+import { NeodigmBuffet, readItems } from './src/wc/neodigm-buffet/neodigm-buffet.js';
 
 export { NeodigmToast, DEFAULT_DURATION };
 export { NeodigmMarquee, DEFAULT_SPEED, parseRuns, plainText };
 export { NeodigmTulip, TULIP_DEFAULTS, readConfig, configFrom };
+export { NeodigmBuffet, readItems };
 export {
   THEMES, THEME_NAMES, OPT_OUT, THEME_ATTR, PULSE_ATTR,
+  INK_DARK, INK_LIGHT, contrast, inkFor, NEUTRALS, SCHEME_ATTR,
   themeCss, installTheme, resolveTheme,
   motionAllowed, setMotionAllowed, pause, play, onMotionChange, resetMotion,
   robinTheme, pulseTheme, flashTitle, resetTitle

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@machfivetechchicago/machvive-neodigm55-ux",
-  "version": "0.1.0",
-  "description": "Neodigm 55 as dependency-free Web Components \u2014 a page-level choreographer that moves colour and attention across every themed element, plus the components it conducts.",
+  "version": "0.1.2",
+  "description": "Neodigm 55 as dependency-free Web Components — a page-level choreographer that moves colour and attention across every themed element, plus the components it conducts.",
   "keywords": [
     "web-components",
     "webcomponents",
@@ -12,6 +12,8 @@
     "theme",
     "toast",
     "snackbar",
+    "navigation",
+    "menu",
     "neodigm",
     "no-dependencies",
     "esm"
@@ -41,6 +43,10 @@
       "types": "./src/wc/neodigm-tulip/neodigm-tulip.d.ts",
       "default": "./src/wc/neodigm-tulip/neodigm-tulip.js"
     },
+    "./buffet": {
+      "types": "./src/wc/neodigm-buffet/neodigm-buffet.d.ts",
+      "default": "./src/wc/neodigm-buffet/neodigm-buffet.js"
+    },
     "./package.json": "./package.json"
   },
   "sideEffects": true,

package/src/conductor/index.js

@@ -9,6 +9,7 @@
  */
 export {
   THEMES, THEME_NAMES, OPT_OUT, THEME_ATTR, PULSE_ATTR,
+  INK_DARK, INK_LIGHT, contrast, inkFor, NEUTRALS, SCHEME_ATTR,
   themeCss, installTheme, resolveTheme
 } from './theme.js';
 

package/src/conductor/theme.d.ts

@@ -1,12 +1,25 @@
 export interface NeodigmTheme {
   /** The theme's colour. */
   color: string;
-  /** Its darker companion, for text on the colour or for hover. */
+  /** Its darker companion, for a second surface or for hover. */
   deep: string;
   /** The emoji the tab title flashes. */
   glyph: string;
+  /** Text on `color`. Computed with `inkFor` when omitted. */
+  ink?: string;
+  /** Text on `deep`. Computed with `inkFor` when omitted. */
+  deepInk?: string;
 }
 
+/** The components' neutral dark ink. */
+export const INK_DARK: '#1a1a1a';
+/** White ink. */
+export const INK_LIGHT: '#fff';
+/** WCAG contrast ratio between two hex colours, 1–21; NaN if either is not hex. Pure. */
+export function contrast(a: string, b: string): number;
+/** INK_DARK or INK_LIGHT, whichever contrasts more with `surface`. Pure. */
+export function inkFor(surface: string): '#1a1a1a' | '#fff';
+
 /** The thirteen Neodigm 55 themes, in round-robin order. */
 export const THEMES: Readonly<Record<string, NeodigmTheme>>;
 export const THEME_NAMES: readonly string[];
@@ -16,15 +29,39 @@ export const OPT_OUT: 'disabled';
 export const THEME_ATTR: 'data-n55-theme';
 export const PULSE_ATTR: 'data-n55-theme-pulse';
 
+/** A `[light, dark]` pair, emitted as `light-dark(light, dark)`. */
+export type SchemePair = readonly [light: string, dark: string];
+
+/**
+ * The page surfaces components paint when not wearing a theme, as
+ * `--n55-surface`, `--n55-surface-ink`, `--n55-line`, `--n55-inverse`,
+ * `--n55-inverse-ink`. Each resolves against the using element's color-scheme.
+ */
+export const NEUTRALS: Readonly<{
+  surface: SchemePair;
+  surfaceInk: SchemePair;
+  line: SchemePair;
+  inverse: SchemePair;
+  inverseInk: SchemePair;
+}>;
+
+/** `data-n55-scheme="light|dark"` pins a subtree, or one component, to a mode. */
+export const SCHEME_ATTR: 'data-n55-scheme';
+
 /** Renders the palette as CSS custom properties, for a stylesheet or a builder. */
-export function themeCss(themes?: Record<string, NeodigmTheme>, selector?: string): string;
+export function themeCss(
+  themes?: Record<string, NeodigmTheme>,
+  selector?: string,
+  neutrals?: Record<string, SchemePair>
+): string;
 
 /** Puts the palette on the document. Idempotent; a second call replaces the first. */
 export function installTheme(options?: {
   themes?: Record<string, NeodigmTheme>;
   selector?: string;
+  neutrals?: Record<string, SchemePair>;
   doc?: Document;
 }): HTMLStyleElement | null;
 
-/** Reads a theme's *resolved* values, honouring any page override. */
+/** Reads a theme's *resolved* values, honouring any page override. Inks always present. */
 export function resolveTheme(name: string, options?: { doc?: Document }): NeodigmTheme | null;

package/src/conductor/theme.js

@@ -11,13 +11,24 @@
  * follows, with no rebuild and no component aware it happened.
  *
  * Each theme carries three values, matching the original's `[light, dark, glyph]`
- * triple:
- *   --n55-<name>        the colour
- *   --n55-<name>-deep   its darker companion, for text on the colour or hover
- *   --n55-<name>-glyph  the emoji the tab title flashes (see flashTitle)
+ * triple, plus two inks derived from them:
+ *   --n55-<name>           the colour
+ *   --n55-<name>-deep      its darker companion, for a second surface or hover
+ *   --n55-<name>-glyph     the emoji the tab title flashes (see flashTitle)
+ *   --n55-<name>-ink       text on the colour
+ *   --n55-<name>-deep-ink  text on the deep companion
+ *
+ * The inks exist because `-deep` was used as text on the colour, and measured
+ * that falls below WCAG AA (4.5:1) on twelve of the thirteen themes — party
+ * manages 1.76. Each ink is whichever of two neutrals contrasts more with its
+ * surface, computed rather than hand-picked so a custom palette gets readable
+ * text without anyone measuring it.
  */
 
-/** @typedef {{ color: string, deep: string, glyph: string }} NeodigmTheme */
+/**
+ * @typedef {{ color: string, deep: string, glyph: string,
+ *   ink?: string, deepInk?: string }} NeodigmTheme
+ */
 
 /**
  * Ported verbatim from `N55_THEME_COLORS` so an existing page's colours do not
@@ -42,6 +53,83 @@ export const THEMES = Object.freeze({
   party:     { color: '#FF6F61', deep: '#C93F60', glyph: '🟪' }
 });
 
+/** The two inks a surface can take: the components' neutral dark, and white. */
+export const INK_DARK = '#1a1a1a';
+export const INK_LIGHT = '#fff';
+
+/** WCAG relative luminance of `#rgb` or `#rrggbb`; null for anything else. */
+function luminance(hex) {
+  const m = /^#([0-9a-f]{3}|[0-9a-f]{6})$/i.exec(String(hex).trim());
+  if (!m) return null;
+  const h = m[1].length === 3 ? [...m[1]].map((c) => c + c).join('') : m[1];
+  const [r, g, b] = [0, 2, 4].map((i) => {
+    const v = parseInt(h.slice(i, i + 2), 16) / 255;
+    return v <= 0.03928 ? v / 12.92 : ((v + 0.055) / 1.055) ** 2.4;
+  });
+  return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+}
+
+/**
+ * WCAG contrast ratio between two hex colours, 1 to 21. Pure, so a theme
+ * builder or a CI check can audit a palette with no DOM. NaN if either is not
+ * a hex colour.
+ */
+export function contrast(a, b) {
+  const [la, lb] = [luminance(a), luminance(b)];
+  if (la === null || lb === null) return NaN;
+  return (Math.max(la, lb) + 0.05) / (Math.min(la, lb) + 0.05);
+}
+
+/**
+ * The readable ink for text on `surface`: INK_DARK or INK_LIGHT, whichever
+ * contrasts more. A surface that is not a hex colour gets INK_DARK — there is
+ * nothing to measure, so the palette author should pass `ink` explicitly.
+ */
+export function inkFor(surface) {
+  const dark = contrast(INK_DARK, surface);
+  if (Number.isNaN(dark)) return INK_DARK;
+  return contrast(INK_LIGHT, surface) > dark ? INK_LIGHT : INK_DARK;
+}
+
+/**
+ * The page's own surfaces, as opposed to a theme's: what a component paints
+ * when it is not wearing a theme. Each is a `[light, dark]` pair, emitted as
+ * `light-dark(light, dark)`.
+ *
+ * That function resolves on the element that *uses* the variable, against the
+ * `color-scheme` that element inherits — and `color-scheme` inherits through a
+ * shadow boundary just as custom properties do. So every instance works out
+ * its own mode where it stands, with no listener and no JavaScript: a dark
+ * sidebar in a light page needs nothing but `color-scheme: dark` on the
+ * sidebar. A browser without `light-dark()` drops the declaration and the
+ * component's own `var()` fallback — the light value — applies.
+ *
+ *   --n55-surface          a resting surface, such as Buffet's top row
+ *   --n55-surface-ink      text on it
+ *   --n55-line             hairlines and dividers on it
+ *   --n55-inverse          the emphasis surface when there is no theme
+ *   --n55-inverse-ink      text on that
+ */
+export const NEUTRALS = Object.freeze({
+  surface:      ['#fff', '#1a1a1a'],
+  surfaceInk:   ['#1a1a1a', '#fff'],
+  line:         ['rgb(0 0 0 / .12)', 'rgb(255 255 255 / .16)'],
+  inverse:      ['#1a1a1a', '#e8e8e8'],
+  inverseInk:   ['#fff', '#1a1a1a']
+});
+
+/**
+ * The attribute that pins a subtree to light or dark: `data-n55-scheme="dark"`
+ * on `<html>`, a section, or a single component. Without it, components follow
+ * whatever `color-scheme` the page already sets — `light dark` follows the OS.
+ * The palette deliberately does not set `color-scheme` on `:root` itself: that
+ * also restyles the page's own scrollbars and form controls, which is the
+ * page's decision.
+ */
+export const SCHEME_ATTR = 'data-n55-scheme';
+
+const kebab = (key) => key.replace(/[A-Z]/g, (c) => `-${c.toLowerCase()}`);
+
 /** Theme names in round-robin order. */
 export const THEME_NAMES = Object.freeze(Object.keys(THEMES));
 
@@ -68,15 +156,22 @@ export const PULSE_ATTR = 'data-n55-theme-pulse';
  * @param {Record<string, NeodigmTheme>} [themes]
  * @param {string} [selector] Where to hang the variables. A section-scoped
  *   selector gives that subtree its own palette, since custom properties cascade.
+ * @param {Record<string, [string, string]>} [neutrals] `[light, dark]` pairs.
  * @returns {string}
  */
-export function themeCss(themes = THEMES, selector = ':root') {
+export function themeCss(themes = THEMES, selector = ':root', neutrals = NEUTRALS) {
   const lines = Object.entries(themes).flatMap(([name, t]) => [
     `  --n55-${name}: ${t.color};`,
     `  --n55-${name}-deep: ${t.deep};`,
-    `  --n55-${name}-glyph: "${t.glyph}";`
+    `  --n55-${name}-glyph: "${t.glyph}";`,
+    `  --n55-${name}-ink: ${t.ink ?? inkFor(t.color)};`,
+    `  --n55-${name}-deep-ink: ${t.deepInk ?? inkFor(t.deep)};`
   ]);
-  return `${selector} {\n${lines.join('\n')}\n}\n`;
+  const surfaces = Object.entries(neutrals).map(([key, [light, dark]]) =>
+    `  --n55-${kebab(key)}: light-dark(${light}, ${dark});`);
+  return `${selector} {\n${[...lines, ...surfaces].join('\n')}\n}\n` +
+    `[${SCHEME_ATTR}="light"] { color-scheme: light; }\n` +
+    `[${SCHEME_ATTR}="dark"] { color-scheme: dark; }\n`;
 }
 
 /** The id of the stylesheet this installs, so a second call can replace it. */
@@ -88,14 +183,17 @@ const STYLE_ID = 'n55-theme-tokens';
  * Idempotent: calling it again replaces the stylesheet rather than stacking a
  * second one, which is what lets a theme builder preview a palette live.
  *
- * @param {{ themes?: Record<string, NeodigmTheme>, selector?: string, doc?: Document }} [options]
+ * @param {{ themes?: Record<string, NeodigmTheme>, selector?: string,
+ *   neutrals?: Record<string, [string, string]>, doc?: Document }} [options]
  * @returns {HTMLStyleElement|null} null where there is no document.
  */
-export function installTheme({ themes = THEMES, selector = ':root', doc = globalThis.document } = {}) {
+export function installTheme({
+  themes = THEMES, selector = ':root', neutrals = NEUTRALS, doc = globalThis.document
+} = {}) {
   if (!doc?.head) return null;
   const style = doc.getElementById(STYLE_ID) ?? doc.createElement('style');
   style.id = STYLE_ID;
-  style.textContent = themeCss(themes, selector);
+  style.textContent = themeCss(themes, selector, neutrals);
   if (!style.isConnected) doc.head.append(style);
   return style;
 }
@@ -115,13 +213,18 @@ export function installTheme({ themes = THEMES, selector = ':root', doc = global
 export function resolveTheme(name, { doc = globalThis.document } = {}) {
   if (!THEMES[name]) return null;
   const root = doc?.documentElement;
-  if (!root || typeof globalThis.getComputedStyle !== 'function') return THEMES[name];
+  const built = THEMES[name];
+  if (!root || typeof globalThis.getComputedStyle !== 'function') {
+    return { ...built, ink: inkFor(built.color), deepInk: inkFor(built.deep) };
+  }
   const read = (suffix) =>
     globalThis.getComputedStyle(root).getPropertyValue(`--n55-${name}${suffix}`).trim();
   return {
     color: read('') || THEMES[name].color,
     deep: read('-deep') || THEMES[name].deep,
     // The glyph round-trips through CSS as a quoted string.
-    glyph: (read('-glyph') || '').replace(/^["']|["']$/g, '') || THEMES[name].glyph
+    glyph: (read('-glyph') || '').replace(/^["']|["']$/g, '') || THEMES[name].glyph,
+    ink: read('-ink') || inkFor(THEMES[name].color),
+    deepInk: read('-deep-ink') || inkFor(THEMES[name].deep)
   };
 }

package/src/wc/neodigm-buffet/neodigm-buffet.d.ts

@@ -0,0 +1,59 @@
+/** One menu entry. The schema `m5t-primary-nav` uses, so existing data drops in. */
+export interface BuffetItem {
+  /** Unique identifier. Selection, events and `updateCount` are keyed by it. */
+  token: string;
+  /** Display text. Falls back to the token. Shown as text, never parsed as markup. */
+  caption?: string;
+  /** Only `false` disables; a missing value means enabled. */
+  enabled?: boolean;
+  /** Selects this item initially. */
+  selected?: boolean;
+  /** Accepted for compatibility and ignored. Icons are deferred; no icon fonts. */
+  icon?: string;
+  /** Shown as the native tooltip. */
+  tagline?: string;
+  /** A badge. */
+  count?: number;
+  /** A palette theme used as this item's accent. Not reached by sweeps. */
+  theme?: string;
+  /** Children, shown in the half-height row when this item is selected. */
+  secondary?: BuffetItem[];
+  [key: string]: unknown;
+}
+
+export interface BuffetSelection {
+  primary: string | null;
+  secondary: string | null;
+}
+
+export interface BuffetSelectDetail extends BuffetSelection {
+  level: 'primary' | 'secondary';
+  token: string;
+  item: BuffetItem;
+}
+
+/** Parses metadata: JSON or an array. Never throws; drops items without a token. */
+export function readItems(raw: string | unknown[] | null): BuffetItem[];
+
+export class NeodigmBuffet extends HTMLElement {
+  /** The metadata, as a copy. Assign to change it; selection survives where tokens do. */
+  items: BuffetItem[];
+  /** The current selection at both levels. */
+  readonly selection: BuffetSelection;
+  /**
+   * Selects without dispatching an event, for keeping in step with a route.
+   * Omit `secondary` for the child last chosen under `primary`.
+   * False if either token is unknown or disabled.
+   */
+  select(primary: string, secondary?: string | null): boolean;
+  /** Updates a badge in place; `null` removes it. False if no item has that token. */
+  updateCount(token: string, count: number | null): boolean;
+}
+
+declare global {
+  interface HTMLElementTagNameMap { 'neodigm-buffet': NeodigmBuffet }
+  interface HTMLElementEventMap {
+    /** Cancelable. Fires on every click, including the current selection. */
+    'neodigm-buffet-select': CustomEvent<BuffetSelectDetail>;
+  }
+}

package/src/wc/neodigm-buffet/neodigm-buffet.js

@@ -0,0 +1,403 @@
+/**
+ * `<neodigm-buffet>` — a full-width, two-level menu, driven by metadata.
+ *
+ * The top row splits the width of its container evenly between its buttons.
+ * Below it sits the selected button's children, at half the height and in a
+ * smaller type. Both levels keep a selection, and each top-level button
+ * remembers which child was last chosen under it.
+ *
+ * ```html
+ * <neodigm-buffet data-n55-theme="brand" data-n55-buffet='[
+ *   {"token":"shows","caption":"Shows","selected":true,"secondary":[
+ *     {"token":"live","caption":"Live"},{"token":"vod","caption":"VOD"}]},
+ *   {"token":"people","caption":"People","count":3}
+ * ]'></neodigm-buffet>
+ * ```
+ *
+ * The metadata is the schema `m5t-primary-nav` already uses — `token`,
+ * `caption`, `enabled`, `selected`, `icon`, `tagline`, `count`, children under
+ * `secondary` — so existing navigation data drops straight in. `data-buttons`
+ * is read as an alias for the same reason. What did not come across, and why:
+ *
+ * - **The logo, PubSub, the i18n listener and `admin_role`** belong to the app.
+ *   An app that re-resolves its labels sets `items` again; selection survives
+ *   wherever the tokens do.
+ * - **Re-rendering on every click.** That one rebuilt its whole shadow root per
+ *   selection, which dropped keyboard focus. Here the top row is built once per
+ *   `items` and selection only moves attributes.
+ * - **`innerHTML` with captions and taglines**, which made every label an
+ *   injection point. Labels are text nodes and the tagline is a `title`.
+ * - **A missing `enabled` meant disabled.** Only `enabled: false` disables.
+ * - **`icon` is not rendered.** It held a Font Awesome class there, which
+ *   cannot style anything inside a shadow root, and icon fonts are not
+ *   wanted here at all. Icons are deferred; until then the field is accepted
+ *   and ignored, so existing data neither breaks nor prints class names.
+ *
+ * **Theming.** The whole menu is one instrument: `data-n55-theme` on the host
+ * colours the selection and the child row, so a `robinTheme()` sweep recolours
+ * the menu as a unit. An item may carry a `theme` of its own as an accent; that
+ * lives inside the shadow root, so a sweep passes it by — deliberately, it is
+ * the item's identity rather than page state.
+ */
+import { THEMES, THEME_ATTR } from '../../conductor/theme.js';
+
+/**
+ * The four colours the menu is painted from, for one theme: two surfaces and
+ * the palette's ink for each. Every theme sets all four, so an accent inside a
+ * menu of another theme never inherits the wrong ink.
+ */
+const colours = (name) =>
+  `--_fill: var(--n55-${name}); --_ink: var(--n55-${name}-ink); ` +
+  `--_row: var(--n55-${name}-deep); --_row-ink: var(--n55-${name}-deep-ink);`;
+
+const STYLES = `
+  :host {
+    /* Unthemed: the palette's inverse surface for the selection — dark on a
+       light page, light on a dark one — and a dark child row in both. The
+       literals are fallbacks for a page that never called installTheme(). */
+    --_fill: var(--n55-inverse, #1a1a1a);
+    --_ink: var(--n55-inverse-ink, #fff);
+    --_row: #2b2b2b;
+    --_row-ink: #fff;
+
+    display: block;
+    inline-size: 100%;
+    box-sizing: border-box;
+    font: 600 .875rem/1.2 system-ui, sans-serif;
+    user-select: none;
+    -webkit-user-select: none;
+  }
+  :host([hidden]) { display: none; }
+
+  /* Theme comes from the host attribute, which is what a sweep sets. Generated
+     from the palette so a new theme cannot be missed here. */
+  ${Object.keys(THEMES).map((name) => `
+  :host([${THEME_ATTR}="${name}"]) { ${colours(name)} }`).join('')}
+
+  /* Per-item accents. Not data-n55-theme: that attribute is the page's
+     contract, and putting it on a shadow-internal node implies a sweep can
+     reach it, which it cannot. */
+  ${Object.keys(THEMES).map((name) => `
+  [data-accent="${name}"] { ${colours(name)} }`).join('')}
+
+  .primary, .secondary {
+    display: grid;
+    grid-auto-flow: column;
+    /* minmax(0, …) rather than 1fr, so a long caption truncates instead of
+       widening its column: the width is the container's divided by the count. */
+    grid-auto-columns: minmax(0, 1fr);
+  }
+  .primary {
+    block-size: var(--n55-buffet-height, 64px);
+    /* The page's surface, so the top row follows light and dark. */
+    background: var(--n55-surface, #fff);
+    border-block-end: 1px solid var(--n55-line, rgb(0 0 0 / .12));
+  }
+  .secondary {
+    block-size: calc(var(--n55-buffet-height, 64px) / 2);
+    background: var(--_row);
+    color: var(--_row-ink);
+    font-size: .8em;
+    font-weight: 500;
+  }
+
+  .item {
+    position: relative;
+    display: flex;
+    align-items: center;
+    justify-content: center;
+    gap: .4em;
+    min-inline-size: 0;
+    margin: 0;
+    padding: 0 .75em;
+    border: 0;
+    border-inline-start: 1px solid var(--n55-line, rgb(0 0 0 / .12));
+    background: transparent;
+    color: inherit;
+    font: inherit;
+    cursor: pointer;
+    transition: background-color .2s ease, color .2s ease;
+  }
+  .item:first-child { border-inline-start: 0; }
+  .primary .item { color: var(--n55-surface-ink, #1a1a1a); }
+  .secondary .item { border-inline-start-color: rgb(255 255 255 / .14); }
+
+  .primary .item:hover:not(:disabled):not([aria-current]) {
+    background: color-mix(in srgb, var(--_fill) 14%, transparent);
+  }
+  .secondary .item:hover:not(:disabled):not([aria-current]) {
+    background: color-mix(in srgb, var(--_row-ink) 12%, transparent);
+  }
+
+  /* Selected, at either level: the theme's colour with its own ink, plus a bar
+     along the bottom so selection never rests on colour alone — white on a
+     white row would otherwise be invisible. */
+  .item[aria-current] {
+    background: var(--_fill);
+    color: var(--_ink);
+    box-shadow: inset 0 -3px 0 var(--_ink);
+  }
+  .secondary .item[aria-current] { box-shadow: inset 0 -2px 0 var(--_ink); }
+
+  .item:focus-visible { outline: 2px solid currentColor; outline-offset: -5px; }
+  .item:disabled { opacity: .45; cursor: not-allowed; }
+
+  .caption { overflow: hidden; text-overflow: ellipsis; white-space: nowrap; }
+  .count {
+    position: absolute;
+    inset-block-start: 6px;
+    inset-inline-end: 8px;
+    min-inline-size: 1.5em;
+    padding: .15em .45em;
+    border-radius: 1em;
+    box-sizing: border-box;
+    background: var(--_row);
+    color: var(--_row-ink);
+    font-size: .75em;
+    line-height: 1.2;
+  }
+  .secondary .count { inset-block-start: 2px; }
+
+  @media (prefers-reduced-motion: reduce) {
+    .item { transition: none; }
+  }
+`;
+
+/**
+ * Reads menu metadata: a JSON array, or an array already parsed.
+ *
+ * Never throws. A menu that renders empty is easier to diagnose than one that
+ * takes the page down, and anything without a string `token` is dropped,
+ * because selection, events and `updateCount` are all keyed by it.
+ *
+ * @param {string|unknown[]|null} raw
+ * @returns {object[]}
+ */
+export function readItems(raw) {
+  let list = raw;
+  if (typeof raw === 'string') {
+    try { list = JSON.parse(raw); } catch { return []; }
+  }
+  if (!Array.isArray(list)) return [];
+  const clean = (item) => item && typeof item === 'object' && typeof item.token === 'string';
+  return list.filter(clean).map((item) => ({
+    ...item,
+    secondary: Array.isArray(item.secondary)
+      ? item.secondary.filter(clean).map((child) => ({ ...child }))
+      : []
+  }));
+}
+
+const usable = (item) => item && item.enabled !== false;
+const copy = (item) => (item ? JSON.parse(JSON.stringify(item)) : null);
+
+export class NeodigmBuffet extends HTMLElement {
+  #items = [];
+  #primary = null;
+  #secondary = null;
+  /** primary token → the child last selected under it */
+  #memory = new Map();
+
+  static get observedAttributes() { return ['data-n55-buffet', 'data-buttons']; }
+
+  constructor() {
+    super();
+    this.attachShadow({ mode: 'open' });
+    this.shadowRoot.addEventListener('click', this.#onClick);
+  }
+
+  connectedCallback() {
+    if (!this.shadowRoot.firstChild) {
+      this.shadowRoot.innerHTML =
+        `<style>${STYLES}</style>` +
+        `<div class="primary" part="primary"></div>` +
+        `<div class="secondary" part="secondary"></div>`;
+    }
+    if (!this.hasAttribute('role')) this.setAttribute('role', 'navigation');
+    if (!this.#items.length) this.#setItems(readItems(this.#source()));
+    else this.#render();
+  }
+
+  attributeChangedCallback(name, before, after) {
+    if (before === after) return;
+    this.#setItems(readItems(this.#source()));
+  }
+
+  /** The menu's metadata. A copy: change it by assigning, not by mutating. */
+  get items() { return copy(this.#items); }
+  set items(value) { this.#setItems(readItems(value)); }
+
+  /** The current selection at both levels. */
+  get selection() { return { primary: this.#primary, secondary: this.#secondary }; }
+
+  /**
+   * Selects by token without announcing it, for keeping the menu in step with
+   * a route. Clicks announce; this does not, or syncing would loop.
+   *
+   * @param {string} primary
+   * @param {string|null} [secondary] Omitted: the child last chosen under it.
+   * @returns {boolean} false if either token is unknown or disabled.
+   */
+  select(primary, secondary) {
+    const item = this.#find(primary);
+    if (!usable(item)) return false;
+    let child = secondary === undefined ? this.#remembered(item) : secondary;
+    if (child !== null && !usable(item.secondary.find((c) => c.token === child))) return false;
+    this.#apply(primary, child);
+    return true;
+  }
+
+  /**
+   * Updates a badge in place. `null` removes it.
+   * @returns {boolean} false if no item has that token.
+   */
+  updateCount(token, count) {
+    for (const item of this.#items) {
+      const hit = item.token === token ? item : item.secondary.find((c) => c.token === token);
+      if (!hit) continue;
+      if (typeof count === 'number') hit.count = count; else delete hit.count;
+      const level = hit === item ? 'primary' : 'secondary';
+      const button = [...this.shadowRoot.querySelectorAll(`.${level} .item`)]
+        .find((b) => b.dataset.token === token);
+      if (button) this.#fill(button, hit);
+      return true;
+    }
+    return false;
+  }
+
+  #source() {
+    return this.getAttribute('data-n55-buffet') ?? this.getAttribute('data-buttons');
+  }
+
+  #find(token) { return this.#items.find((item) => item.token === token) ?? null; }
+
+  #remembered(item) {
+    const token = this.#memory.get(item.token);
+    return usable(item.secondary.find((c) => c.token === token)) ? token : null;
+  }
+
+  /**
+   * Takes new metadata, keeping the selection wherever its tokens survive —
+   * which is what lets an app swap in relabelled items without the menu
+   * jumping.
+   */
+  #setItems(items) {
+    this.#items = items;
+    for (const item of items) {
+      const flagged = item.secondary.find((c) => c.selected && usable(c));
+      if (flagged) this.#memory.set(item.token, flagged.token);
+    }
+    const kept = usable(this.#find(this.#primary)) ? this.#primary : null;
+    const primary = kept
+      ?? items.find((i) => i.selected && usable(i))?.token
+      ?? items.find(usable)?.token
+      ?? null;
+    const item = this.#find(primary);
+    const child = item?.secondary.find((c) => c.token === this.#secondary && usable(c))
+      ? this.#secondary
+      : item ? this.#remembered(item) : null;
+    this.#primary = primary;
+    this.#secondary = child;
+    this.#render();
+  }
+
+  #render() {
+    const row = this.shadowRoot.querySelector('.primary');
+    if (!row) return;   // not connected yet; connectedCallback renders
+    row.replaceChildren(...this.#items.map((item) => this.#button(item, 'primary')));
+    this.#renderChildren();
+    this.#paint();
+  }
+
+  #renderChildren() {
+    const row = this.shadowRoot.querySelector('.secondary');
+    if (!row) return;
+    const item = this.#find(this.#primary);
+    row.replaceChildren(...(item?.secondary ?? []).map((c) => this.#button(c, 'secondary')));
+    // The child row belongs to its parent, so it takes the parent's accent.
+    this.#accent(row, item?.theme);
+  }
+
+  #apply(primary, secondary) {
+    const moved = primary !== this.#primary;
+    this.#primary = primary;
+    this.#secondary = secondary;
+    if (secondary !== null) this.#memory.set(primary, secondary);
+    if (moved) this.#renderChildren();
+    this.#paint();
+  }
+
+  /** Moves the selection markers. Nothing is rebuilt, so focus stays put. */
+  #paint() {
+    for (const [level, token] of [['primary', this.#primary], ['secondary', this.#secondary]]) {
+      for (const button of this.shadowRoot.querySelectorAll(`.${level} .item`)) {
+        if (button.dataset.token === token) button.setAttribute('aria-current', 'true');
+        else button.removeAttribute('aria-current');
+      }
+    }
+  }
+
+  #button(item, level) {
+    const button = this.ownerDocument.createElement('button');
+    button.type = 'button';
+    button.className = 'item';
+    button.setAttribute('part', `item ${level}-item`);
+    button.dataset.token = item.token;
+    button.dataset.level = level;
+    button.disabled = item.enabled === false;
+    if (typeof item.tagline === 'string' && item.tagline) button.title = item.tagline;
+    this.#accent(button, item.theme);
+    this.#fill(button, item);
+    return button;
+  }
+
+  #accent(node, theme) {
+    if (theme && Object.hasOwn(THEMES, theme)) node.dataset.accent = theme;
+    else delete node.dataset.accent;
+  }
+
+  /** Writes a button's contents as text nodes, never markup. */
+  #fill(button, item) {
+    const doc = this.ownerDocument;
+    const span = (cls, text) => {
+      const s = doc.createElement('span');
+      s.className = cls;
+      s.textContent = text;
+      return s;
+    };
+    const parts = [span('caption', String(item.caption ?? item.token))];
+    if (typeof item.count === 'number') parts.push(span('count', String(item.count)));
+    button.replaceChildren(...parts);
+  }
+
+  #onClick = (ev) => {
+    const button = ev.target.closest?.('.item');
+    if (!button || button.disabled) return;
+    const { token, level } = button.dataset;
+
+    let primary = this.#primary;
+    let secondary = token;
+    let item;
+    if (level === 'primary') {
+      item = this.#find(token);
+      primary = token;
+      secondary = item ? this.#remembered(item) : null;
+    } else {
+      item = this.#find(this.#primary)?.secondary.find((c) => c.token === token);
+    }
+    if (!item) return;
+
+    // Cancelable, as Tulip's open is: a page with unsaved work can veto the
+    // move. It fires on every click, including the current selection, because
+    // re-choosing where you are is how a user asks to go back to its start.
+    const proceed = this.dispatchEvent(new CustomEvent('neodigm-buffet-select', {
+      bubbles: true, composed: true, cancelable: true,
+      detail: { level, token, item: copy(item), primary, secondary }
+    }));
+    if (proceed) this.#apply(primary, secondary);
+  };
+}
+
+if (!customElements.get('neodigm-buffet')) {
+  customElements.define('neodigm-buffet', NeodigmBuffet);
+}

package/src/wc/neodigm-toast/neodigm-toast.js

@@ -50,10 +50,17 @@ const STYLES = `
 
     max-width: min(92vw, 560px);
     box-sizing: border-box;
-    padding: 14px 20px;
+    /* Clips the progress bar to the rounded corners. */
+    overflow: hidden;
+    padding: 18px;
     border-radius: 8px;
-    font: 15px/1.45 system-ui, sans-serif;
+    /* The original's type, white on every theme but the two light ones below.
+       A faint shadow keeps it legible at the light end of the gradient. */
+    font: 18px/1.4 'Helvetica', 'Helvetica Neue', sans-serif;
+    text-shadow: 0 1px 2px rgb(0 0 0 / .35);
     text-align: center;
+    user-select: none;
+    -webkit-user-select: none;
     box-shadow: 0 6px 24px rgb(0 0 0 / .28);
 
     /* The unthemed default, for a page that imported the toast but never called
@@ -61,21 +68,46 @@ const STYLES = `
        night-deep here would mean the two drift apart the first time anyone edits
        the palette, and nothing would fail. Both sides are declared so the toast
        never inherits a page colour it cannot guarantee contrast against. */
-    background: var(--n55-night-deep, #2b2b2b);
-    color: var(--n55-white, #fff);
+    background: linear-gradient(45deg, var(--n55-night, #2b2b2b), var(--n55-night-deep, #2b2b2b));
+    color: #fff;
   }
 
   :host([open]) {
     opacity: 1;
     visibility: visible;
     transform: translateX(-50%) translateY(0);
+    animation: n55-toast-in .5s ease-in-out;
   }
 
+  /* From the original's toast_bottom: rise from below the fold, overshoot,
+     settle back. Entry only — leaving is the plain transition above. */
+  @keyframes n55-toast-in {
+    0%   { transform: translateX(-50%) translateY(136px); }
+    80%  { transform: translateX(-50%) translateY(-6px); }
+    100% { transform: translateX(-50%) translateY(0); }
+  }
+
+  /* Time remaining, filling left to right across the top over the toast's own
+     duration, which #next() writes onto it. The original fixed this at 5.2s
+     whatever the toast's duration. Like the original it runs dark to light,
+     the reverse of the background; each theme's colours are set below. */
+  .bar {
+    position: absolute;
+    inset-block-start: 0;
+    inset-inline-start: 0;
+    block-size: 3px;
+    inline-size: 0;
+    background: linear-gradient(90deg, var(--n55-night-deep, #2b2b2b), var(--n55-night, #2b2b2b));
+    animation: n55-toast-bar linear forwards;
+  }
+  @keyframes n55-toast-bar { to { inline-size: 100%; } }
+
   /* A visitor who asked for less motion still gets the toast — it carries
      information — but it appears rather than slides. */
   @media (prefers-reduced-motion: reduce) {
     :host { transition: opacity .01s linear; transform: translateX(-50%); }
-    :host([open]) { transform: translateX(-50%); }
+    :host([open]) { transform: translateX(-50%); animation: none; }
+    .bar { display: none; }
   }
 
   :host([hidden]) { display: none; }
@@ -85,13 +117,18 @@ const STYLES = `
      and silently missed here. */
   ${Object.keys(THEMES).map((name) => `
   :host([${THEME_ATTR}="${name}"]) {
-    background: var(--n55-${name});
-    color: var(--n55-${name}-deep);
+    background: linear-gradient(45deg, var(--n55-${name}), var(--n55-${name}-deep));
+  }
+  :host([${THEME_ATTR}="${name}"]) .bar {
+    background: linear-gradient(90deg, var(--n55-${name}-deep), var(--n55-${name}));
   }`).join('')}
 
-  /* ghost and white are light backgrounds; their -deep value is the readable ink. */
+  /* white and ghost start from pure white, where white text would vanish. The
+     original never styled a toast for either; dark ink is the readable choice. */
   :host([${THEME_ATTR}="white"]),
-  :host([${THEME_ATTR}="ghost"]) { color: #1a1a1a; }
+  :host([${THEME_ATTR}="ghost"]) { color: #1a1a1a; text-shadow: none; }
+  /* white's two colours are both white, so its bar would vanish too. */
+  :host([${THEME_ATTR}="white"]) .bar { background: currentColor; }
 
   .msg { margin: 0; }
   .msg b { font-weight: 600; }
@@ -197,6 +234,7 @@ export class NeodigmToast extends HTMLElement {
     this.#showing = true;
 
     this.#render(entry.message);
+    this.#progress(entry.duration);
     if (entry.theme) this.setAttribute(THEME_ATTR, entry.theme);
     this.setAttribute('open', '');
     this.dispatchEvent(new CustomEvent('neodigm-toast-show', {
@@ -218,6 +256,21 @@ export class NeodigmToast extends HTMLElement {
     this.#timer = setTimeout(() => this.#next(), gap);
   }
 
+  /**
+   * Replaces the progress bar with a fresh one, which is what restarts its CSS
+   * animation for each queued message. Left out entirely when motion is off: a
+   * moving bar is motion, and the toast still closes on time without it.
+   */
+  #progress(duration) {
+    this.shadowRoot.querySelector('.bar')?.remove();
+    if (!motionAllowed()) return;
+    const bar = this.ownerDocument.createElement('span');
+    bar.className = 'bar';
+    bar.setAttribute('part', 'progress');
+    bar.style.animationDuration = `${duration}ms`;
+    this.shadowRoot.append(bar);
+  }
+
   /**
    * Writes the message.
    *

package/src/wc/neodigm-tulip/neodigm-tulip.js

@@ -109,7 +109,7 @@ const STYLES = `
     text-align: center;
     box-shadow: 0 4px 16px rgb(0 0 0 / .24);
     background: var(--n55-brand, #2b2b2b);
-    color: var(--n55-brand-deep, #fff);
+    color: var(--n55-brand-ink, #fff);
   }
   :host([open]) { opacity: 1; visibility: visible; }
   :host([hidden]) { display: none; }
@@ -122,10 +122,8 @@ const STYLES = `
   ${Object.keys(THEMES).map((name) => `
   :host([${THEME_ATTR}="${name}"]) {
     background: var(--n55-${name});
-    color: var(--n55-${name}-deep);
+    color: var(--n55-${name}-ink);
   }`).join('')}
-  :host([${THEME_ATTR}="white"]),
-  :host([${THEME_ATTR}="ghost"]) { color: #1a1a1a; }
 
   .msg { margin: 0; }
   .icon { margin-inline-end: 6px; font-style: normal; }