@vectoriox/iox-ui 5.68.0 → 5.70.0

package/src/scene-core/scene.ts

@@ -0,0 +1,232 @@
+import { SceneRole } from '@vectoriox/iox-ui/composite-core';
+
+/**
+ * A Scene's data and maths (premium-sites plan §5b). A Scene is a recipe of ordinary nodes — a tall Section, a pinned
+ * stage inside it, ordinary nodes as layers — so every word stays real, bound and translatable, and all three render
+ * paths already draw it. What moves a layer is its OWN `sceneTracks`, never a list on the root naming layer ids: a clone
+ * copies them with the layer, a delete takes them with it, and there is no id to remap.
+ *
+ * The vocabulary is closed. Every property is one the compositor can run without layout (CLS stays 0): a saved value
+ * outside it is dropped when read, so a page document can never write CSS through a track.
+ */
+
+export enum SceneProp {
+    /** Along the inline axis, in % of the stage's width. Positive runs toward the inline END (mirrored in RTL). */
+    X = 'x',
+    /** Down, in % of the stage's height. */
+    Y = 'y',
+    Scale = 'scale',
+    /** Degrees. */
+    Rotate = 'rotate',
+    /** 0–1. */
+    Opacity = 'opacity',
+    /** Inset from every side, in % of the layer (0 = whole, 50 = gone). */
+    Clip = 'clip',
+    /** The layer's background colour. */
+    Ground = 'ground',
+    /** The layer's text colour. */
+    Ink = 'ink',
+}
+
+/** One key: at progress `[0]` (0–1) the property holds `[1]`: a number, or a colour for Ground and Ink. */
+export type SceneKey = readonly [number, number | string];
+
+export interface SceneTrack {
+    prop: SceneProp;
+    /** Ascending by progress. Between two keys the value eases (smoothstep); outside them it holds the nearest. */
+    keys: ReadonlyArray<SceneKey>;
+}
+
+/** What a node carries (both a builder node and a saved one). */
+export interface SceneNodeSource {
+    role?: string | null;
+    /** How this layer moves, from the wide layout down to the phone's. */
+    sceneTracks?: ReadonlyArray<SceneTrack> | null;
+    /** How it moves at phone width instead (`SCENE_PHONE_MAX_WIDTH`). Absent = the same tracks. */
+    scenePhoneTracks?: ReadonlyArray<SceneTrack> | null;
+}
+
+/** A frame as inline-style properties (camelCase, as `CSSStyleDeclaration` and `Object.assign` take them). */
+export interface SceneFrame {
+    transform?: string;
+    opacity?: string;
+    clipPath?: string;
+    backgroundColor?: string;
+    color?: string;
+}
+
+export enum SceneAttribute {
+    Root = 'data-iox-scene',
+    Tracks = 'data-iox-tracks',
+    PhoneTracks = 'data-iox-tracks-phone',
+}
+
+/** At or under this stage width a layer plays its phone tracks. The `mobile` breakpoint's width. */
+export const SCENE_PHONE_MAX_WIDTH = 767;
+
+const DECIMALS = 10000;
+const round = (v: number): number => Math.round(v * DECIMALS) / DECIMALS;
+const clamp01 = (v: number): number => Math.min(1, Math.max(0, v));
+const smoothstep = (t: number): number => t * t * (3 - 2 * t);
+
+/** A colour a track may hold: a hex, an rgb()/hsl() literal, or a design token. Anything else could break out of the
+ *  inline style it lands in. */
+const COLOUR = /^(#[0-9a-f]{3,8}|(rgb|hsl)a?\([\d\s.,%/]+\)|var\(--iox-[\w-]+\))$/i;
+const COLOUR_PROPS: ReadonlySet<SceneProp> = new Set([SceneProp.Ground, SceneProp.Ink]);
+const ALL_PROPS: ReadonlySet<string> = new Set(Object.values(SceneProp));
+
+function validKey(key: unknown, colour: boolean): key is SceneKey {
+    if (!Array.isArray(key) || key.length !== 2) return false;
+    const [p, value] = key;
+    if (typeof p !== 'number' || !Number.isFinite(p) || p < 0 || p > 1) return false;
+    return colour ? typeof value === 'string' && COLOUR.test(value) : typeof value === 'number' && Number.isFinite(value);
+}
+
+/**
+ * The tracks a saved value really holds: unknown properties, bad keys and colours that are not colours are dropped,
+ * keys sorted by progress, a track left with no key dropped. Never throws on what a page document holds.
+ */
+export function normalizeTracks(tracks: unknown): SceneTrack[] {
+    if (!Array.isArray(tracks)) return [];
+    const out: SceneTrack[] = [];
+    for (const track of tracks) {
+        const prop = (track as SceneTrack | null)?.prop;
+        if (!prop || !ALL_PROPS.has(prop) || !Array.isArray((track as SceneTrack).keys)) continue;
+        const keys = (track as SceneTrack).keys
+            .filter(key => validKey(key, COLOUR_PROPS.has(prop)))
+            .slice()
+            .sort((a, b) => a[0] - b[0]);
+        if (keys.length) out.push({ prop, keys });
+    }
+    return out;
+}
+
+/** The two keys around `p` and how far between them it eases. */
+function span(keys: ReadonlyArray<SceneKey>, p: number): { a: SceneKey; b: SceneKey; f: number } {
+    const at = clamp01(p);
+    if (at <= keys[0][0]) return { a: keys[0], b: keys[0], f: 0 };
+    for (let i = 1; i < keys.length; i++) {
+        if (at <= keys[i][0]) {
+            const a = keys[i - 1];
+            const b = keys[i];
+            const width = b[0] - a[0];
+            return { a, b, f: width > 0 ? smoothstep((at - a[0]) / width) : 1 };
+        }
+    }
+    const last = keys[keys.length - 1];
+    return { a: last, b: last, f: 0 };
+}
+
+/** A numeric track's value at progress `p`. */
+export function valueAt(keys: ReadonlyArray<SceneKey>, p: number): number {
+    if (!keys.length) return 0;
+    const { a, b, f } = span(keys, p);
+    const from = Number(a[1]);
+    return round(from + (Number(b[1]) - from) * f);
+}
+
+/**
+ * A colour track's value at progress `p`. Mixed by the browser, never computed here, so a design token stays a live
+ * reference (a re-theme reaches a Scene, as it reaches every saved page) and the path is perceptual.
+ */
+export function colourAt(keys: ReadonlyArray<SceneKey>, p: number): string {
+    if (!keys.length) return '';
+    const { a, b, f } = span(keys, p);
+    if (f <= 0 || a === b) return String(a[1]);
+    if (f >= 1) return String(b[1]);
+    return `color-mix(in oklab, ${a[1]} ${round((1 - f) * 100)}%, ${b[1]})`;
+}
+
+export interface SceneFrameOptions {
+    /** -1 when the stage reads right-to-left: the inline axis mirrors. */
+    inlineSign?: 1 | -1;
+}
+
+/** What the tracks' transform-family properties rest at when a layer has no track for one. */
+const TRANSFORM_REST: Readonly<Partial<Record<SceneProp, number>>> = { [SceneProp.X]: 0, [SceneProp.Y]: 0, [SceneProp.Scale]: 1, [SceneProp.Rotate]: 0 };
+
+/**
+ * A layer's frame at progress `p`. Lengths are container-query units, so one frame is right at any width, under any
+ * canvas zoom, on the server and with no measuring: the stage is the size container (`iox-design.css`).
+ */
+export function sceneFrame(tracks: ReadonlyArray<SceneTrack>, p: number, options: SceneFrameOptions = {}): SceneFrame {
+    const frame: SceneFrame = {};
+    const moves: Partial<Record<SceneProp, number>> = {};
+    for (const { prop, keys } of tracks) {
+        if (prop in TRANSFORM_REST) moves[prop] = valueAt(keys, p);
+        else if (prop === SceneProp.Opacity) frame.opacity = String(clamp01(valueAt(keys, p)));
+        else if (prop === SceneProp.Clip) frame.clipPath = `inset(${Math.min(50, Math.max(0, valueAt(keys, p)))}%)`;
+        else if (prop === SceneProp.Ground) frame.backgroundColor = colourAt(keys, p);
+        else if (prop === SceneProp.Ink) frame.color = colourAt(keys, p);
+    }
+    if (Object.keys(moves).length) {
+        const value = (prop: SceneProp): number => moves[prop] ?? TRANSFORM_REST[prop]!;
+        const x = round(value(SceneProp.X) * (options.inlineSign ?? 1));
+        frame.transform = `translate3d(${x}cqw, ${value(SceneProp.Y)}cqh, 0) rotate(${value(SceneProp.Rotate)}deg) scale(${value(SceneProp.Scale)})`;
+    }
+    return frame;
+}
+
+const CSS_NAME: Readonly<Record<keyof SceneFrame, string>> = {
+    transform: 'transform',
+    opacity: 'opacity',
+    clipPath: 'clip-path',
+    backgroundColor: 'background-color',
+    color: 'color',
+};
+
+/** A frame as kebab-case style declarations, for a string renderer. */
+export function sceneFrameDeclarations(frame: SceneFrame): Record<string, string> {
+    const out: Record<string, string> = {};
+    for (const [key, value] of Object.entries(frame)) if (value) out[CSS_NAME[key as keyof SceneFrame]] = value;
+    return out;
+}
+
+/** The attributes a node's own element carries — the same decision in all three render paths. The runtime reads them,
+ *  so it needs no node tree and is the same on every path. Empty for any node that is no part of a Scene. */
+export function sceneNodeAttributes(node: SceneNodeSource | null | undefined): Record<string, string> {
+    const attrs: Record<string, string> = {};
+    if (node?.role === SceneRole.Scene) attrs[SceneAttribute.Root] = '';
+    const tracks = normalizeTracks(node?.sceneTracks);
+    const phone = normalizeTracks(node?.scenePhoneTracks);
+    if (tracks.length) attrs[SceneAttribute.Tracks] = JSON.stringify(tracks);
+    if (phone.length) attrs[SceneAttribute.PhoneTracks] = JSON.stringify(phone);
+    return attrs;
+}
+
+/** The frame a layer ships in from the server: where it stands before anyone has scrolled. Without it the page would
+ *  paint every layer at once, and then jump when the script arrives. */
+export function sceneFirstFrame(node: SceneNodeSource | null | undefined): SceneFrame {
+    return sceneFrame(normalizeTracks(node?.sceneTracks), 0);
+}
+
+/**
+ * Make an element carry its node's Scene attributes: the live sync on the canvas and the component path's stamp.
+ * Removes stale ones, touches nothing else.
+ */
+export function syncSceneAttributes(el: HTMLElement | null | undefined, node: SceneNodeSource | null | undefined): void {
+    if (!el?.setAttribute) return;
+    const attrs = sceneNodeAttributes(node);
+    for (const name of Object.values(SceneAttribute)) {
+        if (name in attrs) el.setAttribute(name, attrs[name]);
+        else el.removeAttribute(name);
+    }
+}
+
+/** Stamp a layer's first frame on its element (the component path, on the server too). */
+export function applySceneFirstFrame(el: HTMLElement | null | undefined, node: SceneNodeSource | null | undefined): void {
+    if (!el?.style) return;
+    for (const [name, value] of Object.entries(sceneFrameDeclarations(sceneFirstFrame(node)))) el.style.setProperty(name, value);
+}
+
+/**
+ * Where nothing will drive it (reduced motion, no script) a Scene is ordinary content: it flows, every layer in its
+ * place and in its own look, every word readable. `!important` because it must beat a node's compiled height and
+ * position, and the inline first frame. The engine wraps it in a reduced-motion query and in `<noscript>`.
+ */
+export const SCENE_FLOW_RULES = `.iox-role-scene{height:auto!important}`
+    + `.iox-role-scene-stage{position:relative!important;top:auto!important;height:auto!important;overflow:visible!important;container-type:normal!important}`
+    + `[${SceneAttribute.Tracks}]{transform:none!important;opacity:1!important;clip-path:none!important}`;
+
+/** Under reduced motion the driver never starts, so the same rules hold for the whole visit. */
+export const SCENE_REDUCED_MOTION_CSS = `@media (prefers-reduced-motion: reduce){${SCENE_FLOW_RULES}}`;

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

@@ -0,0 +1,220 @@
+import { SceneRole } from '@vectoriox/iox-ui/composite-core';
+
+import { normalizeTracks, SCENE_PHONE_MAX_WIDTH, SceneAttribute, sceneFrame, SceneFrame, SceneTrack } from './scene';
+
+/**
+ * The ONE scroll loop (premium-sites plan §5b, SC0). Every Scene on a page reads one progress value from it, on the
+ * canvas and on the live site alike. It reads where the root is and nothing else, so it has one code path: under the
+ * canvas's zoom the same rectangle divides by the same zoom, and the answer is the same at any scale.
+ *
+ * - The value is DAMPED: the scroll stops and the page settles a moment later. This is much of the prototype's weight,
+ *   and why this is not a CSS scroll timeline, which cannot do it.
+ * - The live site pins with `position: sticky`, on the compositor. The canvas cannot (its page never scrolls itself,
+ *   its Lenis scrolls a wrapper around a zoomed frame), so `pin` holds the stage there with `translate` instead.
+ *   `translate`, not `transform`: a Stage may carry tracks of its own.
+ * - It sleeps. No frame is asked for unless something moved, so a page holding a settled Scene costs nothing.
+ * - Reads come first in a frame and writes after, and a write only ever touches compositor properties.
+ */
+
+export const SCENE_DAMPING = 9;
+const SETTLED = 0.0005;
+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 TRANSFORM_WILL_CHANGE = 'transform, opacity';
+
+/** 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));
+}
+
+/** Where a root stands: scrolled `local` page px into its `travel`. `zoom` undoes the canvas's scale. */
+export function sceneScrollState(rootTop: number, originTop: number, zoom: number, travel: number): { local: number; progress: number } {
+    if (travel <= 0) return { local: 0, progress: 0 };
+    const local = Math.min(travel, Math.max(0, -(rootTop - originTop) / (zoom || 1)));
+    return { local, progress: local / travel };
+}
+
+export interface ScrollDriverOptions {
+    /** Hold the stage with `translate` (the canvas). The live site's stage is sticky and needs nothing. */
+    pin?: boolean;
+    /** The element a root scrolls under, when that is not the window (the canvas's frame, Preview's page). */
+    originOf?: (root: HTMLElement) => HTMLElement | null;
+    /** Follow what changes inside a root: tracks edited, layers added (the canvas). */
+    observe?: boolean;
+    damping?: number;
+    /** The window, for a test. */
+    host?: Window;
+}
+
+interface Layer {
+    el: HTMLElement;
+    tracks: SceneTrack[];
+    phoneTracks: SceneTrack[];
+    last: SceneFrame;
+}
+
+interface Scene {
+    root: HTMLElement;
+    stage: HTMLElement | null;
+    layers: Layer[];
+    progress: number;
+    /** Page px and the stage's own width, measured when something resizes and never per frame. */
+    height: number;
+    travel: number;
+    phone: boolean;
+    inlineSign: 1 | -1;
+    /** No frame written yet: the first one lands exactly where the scroll is, with no glide. */
+    fresh: boolean;
+    mutations: MutationObserver | null;
+}
+
+function parseTracks(raw: string | null): SceneTrack[] {
+    if (!raw) return [];
+    try { return normalizeTracks(JSON.parse(raw)); } catch { return []; }
+}
+
+export class ScrollDriver {
+    private readonly scenes = new Map<HTMLElement, Scene>();
+    private readonly host: Window;
+    private readonly resize: ResizeObserver | null;
+    private frame = 0;
+    private lastTime = 0;
+    private readonly wakeUp = (): void => 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 });
+        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 {
+        this.remove(root);
+        const scene: Scene = { root, stage: null, layers: [], progress: 0, height: 0, travel: 0, phone: false, inlineSign: 1, fresh: true, mutations: null };
+        this.scenes.set(root, scene);
+        this.resize?.observe(root);
+        if (this.options.observe) {
+            const Observer = (this.host as Window & { MutationObserver?: typeof MutationObserver }).MutationObserver;
+            if (Observer) {
+                scene.mutations = new Observer(() => this.reread(scene));
+                scene.mutations.observe(root, { childList: true, subtree: true, attributes: true, attributeFilter: [SceneAttribute.Tracks, SceneAttribute.PhoneTracks] });
+            }
+        }
+        this.reread(scene);
+    }
+
+    remove(root: HTMLElement): void {
+        const scene = this.scenes.get(root);
+        if (!scene) return;
+        scene.mutations?.disconnect();
+        this.resize?.unobserve(root);
+        if (scene.stage) scene.stage.style.removeProperty('translate');
+        for (const layer of scene.layers) layer.el.style.removeProperty('will-change');
+        this.scenes.delete(root);
+    }
+
+    /** The damped progress a root's layers stand at. */
+    progressOf(root: HTMLElement): number | null {
+        return this.scenes.get(root)?.progress ?? null;
+    }
+
+    /** Something moved that no scroll or resize announces (the canvas's zoom). */
+    wake(): void {
+        if (this.frame) return;
+        this.frame = this.host.requestAnimationFrame(this.tick);
+    }
+
+    destroy(): void {
+        if (this.frame) this.host.cancelAnimationFrame(this.frame);
+        this.frame = 0;
+        this.host.removeEventListener('scroll', this.wakeUp, { capture: true });
+        this.host.removeEventListener('resize', this.wakeUp);
+        for (const root of [...this.scenes.keys()]) this.remove(root);
+        this.resize?.disconnect();
+    }
+
+    /** Read a root's stage and layers from its DOM: its own Scene's only, never a nested one's. */
+    private reread(scene: Scene): void {
+        scene.stage = scene.root.querySelector<HTMLElement>(STAGE_SELECTOR);
+        scene.layers = Array.from(scene.root.querySelectorAll<HTMLElement>(`[${SceneAttribute.Tracks}], [${SceneAttribute.PhoneTracks}]`))
+            .filter(el => el === scene.root || el.parentElement?.closest(`[${SceneAttribute.Root}]`) === scene.root)
+            .map(el => this.readLayer(el, scene));
+        this.measure(scene);
+        scene.fresh = true;
+        this.wake();
+    }
+
+    private readLayer(el: HTMLElement, scene: Scene): Layer {
+        const previous = scene.layers.find(layer => layer.el === el);
+        el.style.setProperty('will-change', TRANSFORM_WILL_CHANGE);
+        return { el, tracks: parseTracks(el.getAttribute(SceneAttribute.Tracks)), phoneTracks: parseTracks(el.getAttribute(SceneAttribute.PhoneTracks)), last: previous?.last ?? {} };
+    }
+
+    private remeasureAll(): void {
+        for (const scene of this.scenes.values()) this.measure(scene);
+        this.wake();
+    }
+
+    private measure(scene: Scene): void {
+        scene.height = scene.root.offsetHeight;
+        scene.travel = Math.max(0, scene.height - (scene.stage?.offsetHeight ?? scene.height));
+        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.last = {};
+    }
+
+    private readonly tick = (now: number): void => {
+        this.frame = 0;
+        const seconds = this.lastTime ? Math.min(MAX_FRAME_SECONDS, (now - this.lastTime) / 1000) : WAKING_FRAME_SECONDS;
+        this.lastTime = now;
+        const reads = [...this.scenes.values()].map(scene => this.read(scene));
+        let moving = false;
+        for (const { scene, local, target } of reads) {
+            if (this.options.pin && scene.stage) scene.stage.style.setProperty('translate', `0 ${local}px`);
+            const next = scene.fresh ? target : dampToward(scene.progress, target, seconds, this.options.damping);
+            const settled = Math.abs(next - target) < SETTLED;
+            scene.progress = settled ? target : next;
+            scene.fresh = false;
+            this.write(scene);
+            moving = moving || !settled;
+        }
+        if (moving) this.wake();
+        else this.lastTime = 0;
+    };
+
+    private read(scene: Scene): { scene: Scene; local: number; target: number } {
+        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);
+        return { scene, local, target: progress };
+    }
+
+    private write(scene: Scene): void {
+        for (const layer of scene.layers) {
+            const tracks = scene.phone && layer.phoneTracks.length ? layer.phoneTracks : layer.tracks;
+            const frame = sceneFrame(tracks, scene.progress, { inlineSign: scene.inlineSign });
+            for (const key of Object.keys(frame) as (keyof SceneFrame)[]) {
+                if (frame[key] !== layer.last[key]) layer.el.style[key] = frame[key]!;
+            }
+            layer.last = frame;
+        }
+    }
+}
+
+/** A page's Scenes, driven by one driver; null when it holds none, or when the visitor asked for less motion (the
+ *  page's own CSS then lets each Scene flow). The live site's door. */
+export function attachScenes(container: HTMLElement, options: ScrollDriverOptions = {}): ScrollDriver | null {
+    const roots = container.querySelectorAll<HTMLElement>(`[${SceneAttribute.Root}]`);
+    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);
+    roots.forEach(root => driver.add(root));
+    return driver;
+}

package/styles/iox-design.css

@@ -67,6 +67,13 @@ iox-gallery.iox-es-media[data-iox-empty] > .iox-gallery {
     --iox-button-ghost-ink: currentColor;
 }
 
+/* ── Scene (premium-sites plan §5b) ───────────────────────────────────────────────────────────────
+   The stage is the size container its layers' tracks measure against (`cqw` / `cqh`, scene-core), so one frame is
+   right at any width and under any canvas zoom, with no measuring. Its pin, size and clip are the node's own styles. */
+.iox-role-scene-stage {
+    container-type: size;
+}
+
 /* ── Card v2 (composite T23; complex-components board 8) ──────────────────────────────────────────
    The parts are ordinary nodes; `nodeDesignClasses` writes `iox-role-<role>` on each, so these rules are
    the same in every renderer. Zero-specificity where an author's own value must win. */