@vectoriox/iox-ui 5.84.0 → 5.85.0

package/src/design-core/header-behaviour.ts

@@ -0,0 +1,76 @@
+/**
+ * How a site's header behaves as the page scrolls (premium components T2, M4). Two traits on the header's ROOT (the
+ * Navigation bar, generation-core `NavRole.Root`) — edited in its "Header" section, stamped by the composer from a
+ * `nav.*` pattern's `header` — and ONE answer every renderer applies: the attributes below, which the shared CSS
+ * (`iox-design.css`) and the header runtime (`HeaderRuntime`, main entry) read. A header with neither trait renders
+ * exactly as before (it scrolls away with the page, its divider line as its look draws it).
+ *
+ * Framework-free: the composer (generation-core) and both renderers read it.
+ */
+
+export enum HeaderBehaviour {
+    /** It scrolls away with the page (the default; what every header saved before M4 does). */
+    Scrolls = 'scrolls',
+    /** It stays at the top while the page scrolls under it. */
+    Stays = 'stays',
+    /** It steps aside while the page scrolls down and comes back the moment it scrolls up. */
+    Hides = 'hides',
+}
+
+/** What separates the header from the page once the page has moved under it (Emil 99: an edge, not a divider). */
+export enum HeaderEdge {
+    /** A soft fade of the header's own ground over the content under it. */
+    Fade = 'fade',
+    /** A hairline in the header's border colour. */
+    Line = 'line',
+    None = 'none',
+}
+
+/** The traits, stored in the root's props (no default: a plain Container saves neither). */
+export enum HeaderTrait {
+    Behaviour = 'headerBehaviour',
+    Edge = 'headerEdge',
+}
+
+export enum HeaderAttribute {
+    /** `stays` | `hides` on a header that stays at the top. Absent: it scrolls away. */
+    Behaviour = 'data-iox-header',
+    /** `fade` | `line` | `none`: the edge it shows once the page has scrolled. Absent: its look's own divider stays. */
+    Edge = 'data-iox-header-edge',
+    /** Written by the header runtime while a `hides` header has stepped aside. */
+    Hidden = 'data-iox-header-hidden',
+}
+
+/** What a composed header gets (the `nav.*` patterns' `header`, the palette's Navigation bar). */
+export const COMPOSED_HEADER: Readonly<{ behaviour: HeaderBehaviour; edge: HeaderEdge }> = {
+    behaviour: HeaderBehaviour.Hides,
+    edge: HeaderEdge.Fade,
+};
+
+const BEHAVIOURS = new Set<string>(Object.values(HeaderBehaviour));
+const EDGES = new Set<string>(Object.values(HeaderEdge));
+
+/** A stored behaviour, or Scrolls for anything else. */
+export function headerBehaviourOf(value: unknown): HeaderBehaviour {
+    return typeof value === 'string' && BEHAVIOURS.has(value) ? value as HeaderBehaviour : HeaderBehaviour.Scrolls;
+}
+
+/** A stored edge, or null (none chosen: the look's divider stays as it is). */
+export function headerEdgeOf(value: unknown): HeaderEdge | null {
+    return typeof value === 'string' && EDGES.has(value) ? value as HeaderEdge : null;
+}
+
+/** True when the header keeps its place at the top of the screen (it stays, or it hides and comes back). */
+export function headerStaysAtTop(behaviour: unknown): boolean {
+    return headerBehaviourOf(behaviour) !== HeaderBehaviour.Scrolls;
+}
+
+/** The attributes a header renders, from its two trait values — `{}` for a header that keeps today's behaviour. */
+export function headerAttributes(behaviour: unknown, edge: unknown): Record<string, string> {
+    const out: Record<string, string> = {};
+    const b = headerBehaviourOf(behaviour);
+    if (b !== HeaderBehaviour.Scrolls) out[HeaderAttribute.Behaviour] = b;
+    const e = headerEdgeOf(edge);
+    if (e) out[HeaderAttribute.Edge] = e;
+    return out;
+}

package/src/design-core/public-api.ts

@@ -13,6 +13,7 @@ export * from './design-token.model';
 export * from './css-names';
 export * from './token-css';
 export * from './theme-color';
+export * from './header-behaviour';
 export * from './flavor';
 export * from './element-styles';
 export * from './adopt';

package/src/design-core/theme-color.ts

@@ -3,6 +3,8 @@ import { DesignTokenLike } from './token-css';
 
 /** The token the browser's own chrome takes its colour from: the page's ground. */
 export const THEME_COLOR_TOKEN = 'bg';
+/** …or the header's ground, when a header stays at the top of the screen (premium components T2, M4). */
+export const HEADER_THEME_COLOR_TOKEN = 'nav-bg';
 
 const VAR_REF = /^var\(\s*--iox-([\w-]+)\s*(?:,\s*([^()]+))?\)$/;
 /** A colour the browser's chrome can wear: opaque hex, rgb() or hsl() — never a gradient, a mix or a translucent one. */
@@ -20,22 +22,36 @@ function resolveIn(map: ReadonlyMap<string, string>, value: string | undefined,
     return resolveIn(map, map.get(ref[1]) ?? ref[2]?.trim(), depth + 1);
 }
 
-function colourFor(rows: ReadonlyArray<DesignTokenLike>, dark: boolean): string | undefined {
+function colourFor(rows: ReadonlyArray<DesignTokenLike>, dark: boolean, token: string): string | undefined {
     const map = new Map(rows.map(r => [r.name, dark ? (r.values?.dark ?? r.value) : r.value] as [string, string]));
-    const colour = resolveIn(map, map.get(THEME_COLOR_TOKEN));
+    const colour = resolveIn(map, map.get(token));
     return colour && SOLID_COLOUR.test(colour) ? colour : undefined;
 }
 
+export interface ThemeColorOptions {
+    /** A header stays at the top of the screen (it stays, or hides and comes back): the browser's chrome meets the
+     *  HEADER, so it takes the header's ground when that is a solid colour (a translucent one falls back to the page's). */
+    header?: boolean;
+}
+
+function themeColourFor(rows: ReadonlyArray<DesignTokenLike>, dark: boolean, options: ThemeColorOptions): string | undefined {
+    return (options.header ? colourFor(rows, dark, HEADER_THEME_COLOR_TOKEN) : undefined) ?? colourFor(rows, dark, THEME_COLOR_TOKEN);
+}
+
 /**
  * The `theme-color` the browser's chrome takes per colour scheme (premium components G15 — mobile-native M10): the
  * page's ground in each mode the site shows, resolved through the org's rows. A light or dark site answers its one
  * mode; `auto` answers both (the engine writes them with `media="(prefers-color-scheme: …)"`). A value that is not a
  * solid colour answers nothing — the browser keeps its own.
  */
-export function themeColors(rows: ReadonlyArray<DesignTokenLike> | null | undefined, mode: DesignMode | string | null | undefined = 'auto'): ThemeColors {
+export function themeColors(
+    rows: ReadonlyArray<DesignTokenLike> | null | undefined,
+    mode: DesignMode | string | null | undefined = 'auto',
+    options: ThemeColorOptions = {},
+): ThemeColors {
     const list = rows ?? [];
     const out: ThemeColors = {};
-    if (mode !== 'dark') { const light = colourFor(list, false); if (light) out.light = light; }
-    if (mode !== 'light') { const dark = colourFor(list, true); if (dark) out.dark = dark; }
+    if (mode !== 'dark') { const light = themeColourFor(list, false, options); if (light) out.light = light; }
+    if (mode !== 'light') { const dark = themeColourFor(list, true, options); if (dark) out.dark = dark; }
     return out;
 }

package/src/generation-core/compose-site.ts

@@ -7,6 +7,7 @@ import {
     AccordionAutoBinds, CompositeNodeSpec, findByRole, LIGHTBOX_LABEL, SLIDE_TO_ROW, SLIDE_TYPE, buildTabsRecipe, tabLabelNodeOf,
     tabPanelImageOf, tabPanelTextOf, tabsListOf, tabsPanels, tabsPanelsOf, tabsTriggers, TABS_CONTENT_LIMIT, TABS_IMAGE_BIND_PROP, TABS_LABEL_BIND_PROP,
     TABS_TEXT_BIND_PROP, TABS_WORDS, TabsAutoBinds, BadgeTone, BADGE_TONES, buildSegmentedRecipe, CardWords, ITEM_OPEN_STATE, segmentedOptions,
+    setHeaderBehaviour,
 } from '@vectoriox/iox-ui/composite-core';
 
 import { EntranceMark, EntrancePart, planEntrances } from './entrances';
@@ -1210,6 +1211,12 @@ export function composeSite(plan: SitePlan, context: ComposeContext): ComposedSi
         const shape = patternById(plan.globals[slot])?.phoneMenu;
         if (shape) globals = planNavShape(globals, shape as NavShape, {}, slot).globals;
     }
+    // Premium M4 (T2): a header pattern's behaviour as the page scrolls — the same edit the Header section makes.
+    for (const slot of Object.values(GlobalSlot)) {
+        const header = patternById(plan.globals[slot])?.header;
+        const root = header ? globals.find(g => g.id === slot) : null;
+        if (header && root) setHeaderBehaviour(root as unknown as CompositeNode, header.behaviour, header.edge ?? null);
+    }
 
     return {
         source: clone(plan.source),
@@ -1302,6 +1309,7 @@ export function composeNavHeader(input: NavHeaderInput, options: NavHeaderOption
     root.globalPosition = pattern.global;
     const shape = pattern.phoneMenu as NavShape | undefined;
     const header = shape ? planNavShape([root], shape, { newId: options.newId }, root.id).globals[0] : root;
+    if (pattern.header) setHeaderBehaviour(header as unknown as CompositeNode, pattern.header.behaviour, pattern.header.edge ?? null);
     return { header, issues };
 }
 

package/src/generation-core/node-baselines.generated.ts

@@ -691,7 +691,9 @@ export const NODE_BASELINES: Readonly<Record<string, NodeBaseline>> = {
       "defaultOn",
       "activateOn",
       "orientation",
-      "ariaLabel"
+      "ariaLabel",
+      "headerBehaviour",
+      "headerEdge"
     ],
     "styleTraits": [
       "position",
@@ -3114,6 +3116,10 @@ export const NODE_BASELINES: Readonly<Record<string, NodeBaseline>> = {
       "slideToClickedSlide": false,
       "effect": "slide",
       "speed": 300,
+      "scrollPlays": false,
+      "controlsPlacement": "under",
+      "enableCaption": false,
+      "enableCount": false,
       "enableNavigation": false,
       "navigationColor": "#ffffff",
       "navigationSize": 44,
@@ -3221,7 +3227,11 @@ export const NODE_BASELINES: Readonly<Record<string, NodeBaseline>> = {
       "__effectsLabel",
       "effect",
       "speed",
+      "scrollPlays",
       "__navLabel",
+      "controlsPlacement",
+      "enableCaption",
+      "enableCount",
       "enableNavigation",
       "navigationColor",
       "navigationSize",
@@ -3326,7 +3336,9 @@ export const NODE_BASELINES: Readonly<Record<string, NodeBaseline>> = {
     "container": true
   },
   "SliderSlide": {
-    "props": {},
+    "props": {
+      "caption": ""
+    },
     "styleProps": {
       "position": "static",
       "top": "auto",
@@ -3405,7 +3417,9 @@ export const NODE_BASELINES: Readonly<Record<string, NodeBaseline>> = {
       "transitionDelay": "0ms",
       "transitionTimingFunction": "ease"
     },
-    "traits": [],
+    "traits": [
+      "caption"
+    ],
     "styleTraits": [
       "position",
       "top",

package/src/generation-core/patterns.ts

@@ -153,6 +153,8 @@ export interface SitePattern {
     readonly global?: `${PatternGlobalPosition}`;
     /** A navigation pattern's phone shape (CC1): `planNavShape` adds it after the pattern is stamped. */
     readonly phoneMenu?: 'drawer' | 'bar' | 'both';
+    /** A navigation pattern's behaviour as the page scrolls (premium M4, T2): design-core HeaderBehaviour / HeaderEdge. */
+    readonly header?: { readonly behaviour: 'scrolls' | 'stays' | 'hides'; readonly edge?: 'fade' | 'line' | 'none' };
     /** SC6: a Scene section — held while the page scrolls, moved by the scroll. Only at How animated Expressive, at
      *  most one per page and on at most two pages (`validateSitePlan`); it never takes the look's entrances. */
     readonly scene?: boolean;

package/src/generation-core/site-spec.generated.ts

@@ -1148,6 +1148,10 @@ export const SPEC_SITE_PATTERNS = {
     "label": "Navigation bar",
     "global": "before",
     "phoneMenu": "drawer",
+    "header": {
+      "behaviour": "hides",
+      "edge": "fade"
+    },
     "intent": "The brand on one side, the pages and one call to action on the other — the default header.",
     "node": {
       "t": "Container",
@@ -1217,6 +1221,10 @@ export const SPEC_SITE_PATTERNS = {
     "label": "Navigation — the name centred",
     "global": "before",
     "phoneMenu": "drawer",
+    "header": {
+      "behaviour": "hides",
+      "edge": "fade"
+    },
     "intent": "The name centred above a centred row of pages — when the name is the brand.",
     "node": {
       "t": "Container",

package/src/scene-core/scene.ts

@@ -80,6 +80,24 @@ export enum SceneAttribute {
     Root = 'data-iox-scene',
     Tracks = 'data-iox-tracks',
     PhoneTracks = 'data-iox-tracks-phone',
+    /** A root's stage that is not a Scene's `scene.stage` part: the slider a scroll plays (premium M4). */
+    Stage = 'data-iox-scene-stage',
+}
+
+/**
+ * A SLIDER THE SCROLL PLAYS (premium components M4 — M1.3's held gallery). Its progress rests on each picture and changes
+ * only over the middle share of each step, so every picture arrives and stays a moment while the page holds it: `p` is
+ * the scroll's progress through the runway (0–1), `n` the slides; the answer is Swiper's progress (0–1).
+ */
+export const SLIDER_HOLD_SHARE = 0.2;
+/** Page px of scroll per picture, as a share of the screen's height (the runway the renderers reserve). */
+export const SLIDER_SCROLL_STEP_SCREENS = 0.55;
+export function heldProgress(p: number, n: number): number {
+    if (!(n >= 2) || !Number.isFinite(p)) return 0;
+    const s = clamp01(p) * (n - 1);
+    const i = Math.min(n - 2, Math.floor(s));
+    const f = clamp01((s - i - SLIDER_HOLD_SHARE) / (1 - 2 * SLIDER_HOLD_SHARE));
+    return round((i + smoothstep(f)) / (n - 1));
 }
 
 /** At or under this stage width a layer plays its phone tracks. The `mobile` breakpoint's width. */

package/src/scene-core/scroll-driver.ts

@@ -1,7 +1,7 @@
 import { SceneRole } from '@vectoriox/iox-ui/composite-core';
 import { FramePlayer, normalizeFrameSequence, VideoAttribute } from '@vectoriox/iox-ui/media-core';
 
-import { normalizeTracks, SCENE_PHONE_MAX_WIDTH, SceneAttribute, sceneFrame, SceneFrame, scenePlayed, sceneWordOpacity, sceneWordsLit, SceneTrack } from './scene';
+import { heldProgress, normalizeTracks, SCENE_PHONE_MAX_WIDTH, SceneAttribute, sceneFrame, SceneFrame, scenePlayed, sceneWordOpacity, sceneWordsLit, SceneTrack } from './scene';
 import { LIGHT_UP_PIECE_CAP, SplitText, splitText } from './split-text';
 
 /**
@@ -24,9 +24,32 @@ const SETTLED_PX = 0.25;
 const MAX_FRAME_SECONDS = 0.1;
 /** The first frame after a sleep has no previous one to measure from: it counts as one frame, or a scroll would lose it. */
 const WAKING_FRAME_SECONDS = 1 / 60;
-const STAGE_SELECTOR = `.iox-role-${SceneRole.Stage.replace(/\./g, '-')}`;
+const STAGE_SELECTOR = `.iox-role-${SceneRole.Stage.replace(/\./g, '-')}, [${SceneAttribute.Stage}]`;
 const TRANSFORM_WILL_CHANGE = 'transform, opacity';
 
+/**
+ * Dispatched (bubbling) by something the driver plays that arrived after the driver last looked — a Swiper booted on a
+ * slider's stage. Never a DOM `scroll`: nothing that follows the driver may dispatch one (SC2).
+ */
+export const SCENE_WAKE_EVENT = 'iox-scene-wake';
+
+/**
+ * ONE driver per root (premium M4 — §0 "To verify first"). The live site attaches a driver per runtime instance (the
+ * page's and the globals'); an instance that scanned a container holding the other's Scenes would drive them a second
+ * time, two damped values fighting over one layer. A root is held by the first driver that adds it until that driver
+ * lets it go.
+ */
+const HELD = new WeakMap<HTMLElement, ScrollDriver>();
+
+/** The slider a stage carries when the scroll plays it: a booted Swiper (it sets `el.swiper`), read by shape. */
+interface PlayedSlider { slides?: ArrayLike<unknown>; setProgress?: (progress: number, speed?: number) => void; destroyed?: boolean }
+function sliderOf(stage: HTMLElement | null): PlayedSlider | null {
+    // The stage is the runway's child: the `.swiper` itself (both engine paths), or the canvas's shell around it.
+    const holder = (stage?.classList.contains('swiper') ? stage : stage?.querySelector('.swiper')) as (HTMLElement & { swiper?: PlayedSlider }) | null | undefined;
+    const swiper = holder?.swiper;
+    return swiper && typeof swiper.setProgress === 'function' && !swiper.destroyed ? swiper : null;
+}
+
 /** One frame of the damping: frame-rate independent, so 60 Hz and 120 Hz settle in the same time. */
 export function dampToward(current: number, target: number, seconds: number, rate: number = SCENE_DAMPING): number {
     return current + (target - current) * (1 - Math.exp(-seconds * rate));
@@ -86,6 +109,8 @@ interface Scene {
     /** Page px and the stage's own width, measured when something resizes and never per frame. */
     height: number;
     travel: number;
+    /** Page px from the top of the screen at which the stage holds: 0 for a Scene, mid-screen for a played slider. */
+    stick: number;
     phone: boolean;
     inlineSign: 1 | -1;
     /** No frame written yet: the first one lands exactly where the scroll is, with no glide. */
@@ -105,20 +130,28 @@ export class ScrollDriver {
     private frame = 0;
     private lastTime = 0;
     private readonly wakeUp = (): void => this.wake();
+    private readonly onWakeEvent = (e: Event): void => {
+        const scene = [...this.scenes.values()].find(s => s.root.contains(e.target as Node));
+        if (scene) { scene.fresh = true; this.wake(); }
+    };
 
     constructor(private readonly options: ScrollDriverOptions = {}) {
         this.host = options.host ?? window;
         // In capture: a scroll does not bubble, and the canvas's Lenis scrolls an element, not the window.
         this.host.addEventListener('scroll', this.wakeUp, { capture: true, passive: true });
         this.host.addEventListener('resize', this.wakeUp, { passive: true });
+        this.host.addEventListener(SCENE_WAKE_EVENT, this.onWakeEvent, { capture: true });
         const Observer = (this.host as Window & { ResizeObserver?: typeof ResizeObserver }).ResizeObserver;
         this.resize = Observer ? new Observer(() => this.remeasureAll()) : null;
     }
 
-    /** Drive a Scene's root. Idempotent: adding a root again re-reads it. */
-    add(root: HTMLElement): void {
+    /** Drive a Scene's root. Idempotent: adding a root again re-reads it. False when another driver holds it. */
+    add(root: HTMLElement): boolean {
+        const holder = HELD.get(root);
+        if (holder && holder !== this) return false;
         this.remove(root);
-        const scene: Scene = { root, stage: null, layers: [], progress: 0, target: 0, height: 0, travel: 0, phone: false, inlineSign: 1, fresh: true, mutations: null };
+        HELD.set(root, this);
+        const scene: Scene = { root, stage: null, layers: [], progress: 0, target: 0, height: 0, travel: 0, stick: 0, phone: false, inlineSign: 1, fresh: true, mutations: null };
         this.scenes.set(root, scene);
         this.resize?.observe(root);
         if (this.options.observe) {
@@ -129,11 +162,18 @@ export class ScrollDriver {
             }
         }
         this.readScene(scene);
+        return true;
+    }
+
+    /** True when this driver holds `root`. */
+    holds(root: HTMLElement): boolean {
+        return this.scenes.has(root);
     }
 
     remove(root: HTMLElement): void {
         const scene = this.scenes.get(root);
         if (!scene) return;
+        if (HELD.get(root) === this) HELD.delete(root);
         scene.mutations?.disconnect();
         this.resize?.unobserve(root);
         if (scene.stage) scene.stage.style.removeProperty('translate');
@@ -198,6 +238,7 @@ export class ScrollDriver {
         this.frame = 0;
         this.host.removeEventListener('scroll', this.wakeUp, { capture: true });
         this.host.removeEventListener('resize', this.wakeUp);
+        this.host.removeEventListener(SCENE_WAKE_EVENT, this.onWakeEvent, { capture: true });
         for (const root of [...this.scenes.keys()]) this.remove(root);
         this.resize?.disconnect();
     }
@@ -250,6 +291,9 @@ export class ScrollDriver {
     private measure(scene: Scene): void {
         scene.height = scene.root.offsetHeight;
         scene.travel = Math.max(0, scene.height - (scene.stage?.offsetHeight ?? scene.height));
+        // Where the stage holds: its sticky top (a played slider holds mid-screen; a Scene's stage at 0). Read when
+        // something resizes, never per frame.
+        scene.stick = scene.stage ? (parseFloat(this.host.getComputedStyle(scene.stage).top) || 0) : 0;
         scene.phone = (scene.stage?.offsetWidth ?? Infinity) <= SCENE_PHONE_MAX_WIDTH;
         scene.inlineSign = scene.stage && this.host.getComputedStyle(scene.stage).direction === 'rtl' ? -1 : 1;
         for (const layer of scene.layers) layer.stale = true;
@@ -281,11 +325,14 @@ export class ScrollDriver {
         const rect = scene.root.getBoundingClientRect();
         const origin = this.options.originOf?.(scene.root)?.getBoundingClientRect().top ?? 0;
         const zoom = scene.height ? rect.height / scene.height : 1;
-        const { local, progress } = sceneScrollState(rect.top, origin, zoom, scene.travel);
+        const { local, progress } = sceneScrollState(rect.top, origin + scene.stick * zoom, zoom, scene.travel);
         return { scene, local, target: progress };
     }
 
     private write(scene: Scene): void {
+        // A slider the scroll plays (M4): the damped moment, held on each picture.
+        const slider = sliderOf(scene.stage);
+        if (slider) slider.setProgress!(heldProgress(scene.progress, slider.slides?.length ?? 0), 0);
         for (const layer of scene.layers) {
             const tracks = scene.phone && layer.phoneTracks.length ? layer.phoneTracks : layer.tracks;
             this.writeWords(layer, sceneWordsLit(tracks, scene.progress));
@@ -359,3 +406,33 @@ export function attachScenes(container: HTMLElement, options: ScrollDriverOption
     roots.forEach(root => driver.add(root));
     return driver;
 }
+
+/**
+ * The Scene roots that belong to `elements` (each, and what it holds) — what one runtime instance owns: the page's nodes,
+ * or the globals'. Never a whole container that also holds another instance's Scenes (premium M4: the globals' instance
+ * scanned the app root and drove the page's Scenes a second time).
+ */
+export function sceneRootsIn(elements: Iterable<Element>): HTMLElement[] {
+    const out = new Set<HTMLElement>();
+    for (const el of elements) {
+        if ((el as HTMLElement).hasAttribute?.(SceneAttribute.Root)) out.add(el as HTMLElement);
+        // A wrapper the node renders around itself (a played slider's runway around its `.swiper`) is the node's own.
+        const parent = el.parentElement;
+        if (parent?.hasAttribute(SceneAttribute.Root) && parent.children.length === 1) out.add(parent);
+        el.querySelectorAll?.<HTMLElement>(`[${SceneAttribute.Root}]`).forEach(root => out.add(root));
+    }
+    return [...out];
+}
+
+/** The live site's door for a runtime that owns some nodes: their Scenes on one driver (null when none, or under reduced
+ *  motion — the page's own CSS then lets each Scene flow). A root another driver holds stays with it. */
+export function attachSceneRoots(roots: ReadonlyArray<HTMLElement>, options: ScrollDriverOptions = {}): ScrollDriver | null {
+    if (!roots.length) return null;
+    const host = options.host ?? window;
+    if (host.matchMedia?.('(prefers-reduced-motion: reduce)').matches) return null;
+    const driver = new ScrollDriver(options);
+    const held = roots.filter(root => driver.add(root));
+    if (held.length) return driver;
+    driver.destroy();
+    return null;
+}