@vectoriox/iox-ui 5.35.0 → 5.37.0

package/src/composite-core/accordion-runtime.ts

@@ -0,0 +1,443 @@
+import {
+    AccordionBehaviour, AccordionClass, AccordionDefaultOn, accordionDomIds, accordionFocusIndex, accordionKeyAction,
+    ACCORDION_DEFAULT_ONS, closeAccordionItem, COMPOSITE_ATTRIBUTE, DEFAULT_ON_ATTRIBUTE, hasLabelledRegion, initialAccordionOpen, ITEM_KEY_ATTRIBUTE,
+    MULTIPLE_ATTRIBUTE, nextAccordionState, ON_ATTRIBUTE, openAccordionItem, SCOPE_ATTRIBUTE, UNTIL_FOUND,
+} from './accordion';
+import { CompositeKind } from './composite-kinds';
+
+/**
+ * The Accordion's RUNTIME (CC2) — ONE copy, DOM only, for the builder canvas and the live site (both engine
+ * paths render the same markup). It reads the markup the renderers write (iox-design.css + accordion.ts's
+ * attribute planners), so the server's first paint and every later state agree:
+ *
+ *   [root]  data-iox-composite="accordion"  data-iox-default-on  [data-iox-multiple]  [data-iox-scope]  (the node's
+ *           own element — its role class may sit on a wrapper host, as the engine's component-path Repeater draws it)
+ *     .iox-role-accordion-item  data-iox-item-key  [data-iox-on]
+ *       hN.iox-accordion-heading > button.iox-accordion-button  id  aria-expanded  aria-controls
+ *       .iox-accordion-track [data-iox-on] > .iox-accordion-region  role=region  [hidden=until-found]
+ *         .iox-role-accordion-panel
+ *
+ * The DISCLOSURE (CC2.1) runs on this same runtime: `data-iox-composite="disclosure"` on a root that IS its one
+ * item (it carries the key and `data-iox-on`), its button straight inside it (no heading), its panel in the same
+ * track + region (a plain block — no `role=region`), and no arrow keys (one button).
+ *
+ * It owns: a click on a header toggles its item; ↓ ↑ Home End move between the headers of THIS accordion
+ * (a nested one keeps its own); find-in-page (`beforematch`) opens the item that holds the match; a closed
+ * panel gets `hidden="until-found"` after its track has collapsed (at once under reduced motion). Every
+ * change dispatches `iox-item-on` / `iox-item-off` on the item, the `itemOn` / `itemOff` interaction
+ * triggers. The open set is LIVE ∪ FORCED: the builder forces items open (a selection inside a closed panel,
+ * "All open"); the live site forces nothing.
+ */
+
+export const ITEM_ON_EVENT = 'iox-item-on';
+export const ITEM_OFF_EVENT = 'iox-item-off';
+
+const KIND_ROOT = (kind: CompositeKind) => `[${COMPOSITE_ATTRIBUTE}="${kind}"]`;
+const ROOT_SELECTOR = Object.values(CompositeKind).map(KIND_ROOT).join(', ');
+/** An accordion's items are its `.iox-role-accordion-item` children; a disclosure is its own item. */
+const ACCORDION_ITEM_SELECTOR = '.iox-role-accordion-item';
+const ITEM_SELECTOR = `${ACCORDION_ITEM_SELECTOR}, ${KIND_ROOT(CompositeKind.Disclosure)}`;
+const PANEL_SELECTOR = '.iox-role-accordion-panel, .iox-role-disclosure-panel';
+const BUTTON_SELECTOR = `.${AccordionClass.Button}`;
+const TRACK_SELECTOR = `.${AccordionClass.Track}`;
+const REGION_SELECTOR = `.${AccordionClass.Region}`;
+/** How long a closing track may take before its region is hidden (dur-base is 200–320ms in every pack). */
+const MAX_CLOSE_MS = 600;
+const REDUCED_MOTION = '(prefers-reduced-motion: reduce)';
+
+export interface AccordionRuntimeOptions {
+    /** The composite's scope id — the ARIA ids' prefix (else the root's `data-iox-scope`, else its `iox-node-<id>`). A
+     *  function is read at every stamp (the builder canvas: a preview row's index is known once it is in the page). */
+    rootId?: string | (() => string);
+    /** Accordion or Disclosure (else read from the root's `data-iox-composite`). */
+    kind?: CompositeKind;
+    /** The behaviour (else read from the root's data attributes). */
+    behaviour?: AccordionBehaviour;
+    /** Keys forced open on top of the live state (the builder's design state). */
+    forced?: () => ReadonlySet<string>;
+    /** Re-stamp when the markup under the root changes (the builder canvas re-renders parts). */
+    observe?: boolean;
+    /** True to stop motion (default: the visitor's reduced-motion setting). */
+    reducedMotion?: () => boolean;
+}
+
+/** The composite (accordion or disclosure) an element belongs to (the element itself when it is a root). */
+export function closestAccordion(el: Element | null | undefined): HTMLElement | null {
+    return (el?.closest?.(ROOT_SELECTOR) as HTMLElement | null) ?? null;
+}
+
+/** The item an element sits in (itself when it is one) — an accordion item, or a disclosure. */
+export function closestAccordionItem(el: Element | null | undefined): HTMLElement | null {
+    return (el?.closest?.(ITEM_SELECTOR) as HTMLElement | null) ?? null;
+}
+
+const kindOf = (root: Element): CompositeKind =>
+    root.getAttribute(COMPOSITE_ATTRIBUTE) === CompositeKind.Disclosure ? CompositeKind.Disclosure : CompositeKind.Accordion;
+
+/** The composite root whose items an item belongs to: a disclosure is its own root. */
+function rootOfItem(item: HTMLElement): HTMLElement | null {
+    return kindOf(item) === CompositeKind.Disclosure && item.matches(KIND_ROOT(CompositeKind.Disclosure)) ? item : closestAccordion(item.parentElement);
+}
+
+/** Subscribe to an item turning on / off — what the `itemOn` / `itemOff` interaction triggers listen to. The
+ *  item is the element's own item (the element itself when it is one). Returns the unsubscribe. */
+export function onAccordionItemState(el: Element, on: boolean, handler: () => void): () => void {
+    const item = closestAccordionItem(el);
+    if (!item) return () => undefined;
+    const type = on ? ITEM_ON_EVENT : ITEM_OFF_EVENT;
+    item.addEventListener(type, handler);
+    return () => item.removeEventListener(type, handler);
+}
+
+/** True when the element's item is open now. */
+export function isAccordionItemOn(el: Element): boolean {
+    return !!closestAccordionItem(el)?.hasAttribute(ON_ATTRIBUTE);
+}
+
+const nodeIdOf = (el: Element): string => {
+    for (const c of Array.from(el.classList)) if (c.startsWith('iox-node-')) return c.slice('iox-node-'.length);
+    return '';
+};
+
+function behaviourOf(root: Element): AccordionBehaviour {
+    const raw = root.getAttribute(DEFAULT_ON_ATTRIBUTE);
+    return {
+        multiple: root.hasAttribute(MULTIPLE_ATTRIBUTE),
+        defaultOn: ACCORDION_DEFAULT_ONS.includes(raw as AccordionDefaultOn) ? raw as AccordionDefaultOn : AccordionDefaultOn.First,
+    };
+}
+
+function setAttr(el: Element | null | undefined, name: string, value: string | null): void {
+    if (!el) return;
+    if (value === null) { if (el.hasAttribute(name)) el.removeAttribute(name); }
+    else if (el.getAttribute(name) !== value) el.setAttribute(name, value);
+}
+
+export class AccordionRuntime {
+    private live: Set<string>;
+    private shown = new Set<string>();
+    private readonly closing = new Map<string, ReturnType<typeof setTimeout>>();
+    private observer: MutationObserver | null = null;
+    private stampQueued = false;
+    private behaviourValue: AccordionBehaviour;
+    /** The builder attaches a root before its items render: the saved default is applied once they do. */
+    private awaitingItems = false;
+    readonly kind: CompositeKind;
+
+    constructor(readonly root: HTMLElement, private readonly options: AccordionRuntimeOptions = {}) {
+        this.kind = options.kind ?? kindOf(root);
+        this.behaviourValue = options.behaviour ?? behaviourOf(root);
+        root.setAttribute(COMPOSITE_ATTRIBUTE, this.kind);
+        RUNTIMES.set(root, this);
+        // The server rendered the first state; with no server state the root's default decides.
+        // (The builder passes the behaviour and starts from the saved default; on the live site the server
+        // stamped every item's key and state, and that is the truth.)
+        const items = this.items();
+        const serverStamped = !options.behaviour && items.some(i => i.hasAttribute(ITEM_KEY_ATTRIBUTE));
+        this.live = serverStamped
+            ? new Set(items.filter(i => i.hasAttribute(ON_ATTRIBUTE)).map(i => this.keyOf(i, items)))
+            : initialAccordionOpen(items.map(i => this.keyOf(i, items)), this.behaviourValue.defaultOn);
+        this.awaitingItems = !serverStamped && !items.length;
+        this.shown = new Set(this.live);
+        // Capture: on the builder canvas every part's own listener stops the click (it selects that part), and
+        // the header must still toggle — the canvas is a live runtime.
+        root.addEventListener('click', this.onClick, true);
+        root.addEventListener('keydown', this.onKeydown);
+        root.addEventListener('beforematch', this.onBeforeMatch, true);
+        if (options.observe && typeof MutationObserver !== 'undefined') {
+            this.observer = new MutationObserver(() => this.queueStamp());
+            this.observer.observe(root, { childList: true, subtree: true });
+        }
+        this.stamp(true);
+    }
+
+    get behaviour(): AccordionBehaviour {
+        return this.behaviourValue;
+    }
+
+    /** The behaviour changed in the panel: re-read, and start from the new default. */
+    setBehaviour(behaviour: AccordionBehaviour): void {
+        const changedDefault = behaviour.defaultOn !== this.behaviourValue.defaultOn;
+        this.behaviourValue = behaviour;
+        if (behaviour.multiple) this.root.setAttribute(MULTIPLE_ATTRIBUTE, '');
+        else this.root.removeAttribute(MULTIPLE_ATTRIBUTE);
+        this.root.setAttribute(DEFAULT_ON_ATTRIBUTE, behaviour.defaultOn);
+        if (changedDefault) this.resetLive();
+        else this.stamp();
+    }
+
+    /** THIS composite's items, in document order (a nested composite's items are its own); a disclosure's is itself. */
+    items(): HTMLElement[] {
+        if (this.kind === CompositeKind.Disclosure) return [this.root];
+        return Array.from(this.root.querySelectorAll<HTMLElement>(ACCORDION_ITEM_SELECTOR)).filter(i => closestAccordion(i.parentElement) === this.root);
+    }
+
+    /** The open keys the live state holds (before anything forced). */
+    get liveKeys(): ReadonlySet<string> {
+        return this.live;
+    }
+
+    /** The keys showing open right now. */
+    get openKeys(): ReadonlySet<string> {
+        return this.shown;
+    }
+
+    keyOf(item: Element, items: HTMLElement[] = this.items()): string {
+        return item.getAttribute(ITEM_KEY_ATTRIBUTE) || `item-${items.indexOf(item as HTMLElement)}`;
+    }
+
+    toggle(key: string): void {
+        this.live = nextAccordionState(this.live, key, this.behaviourValue);
+        this.stamp();
+    }
+
+    open(key: string): void {
+        this.live = openAccordionItem(this.live, key, this.behaviourValue);
+        this.stamp();
+    }
+
+    close(key: string): void {
+        this.live = closeAccordionItem(this.live, key);
+        this.stamp();
+    }
+
+    /** Run an item action (`openItem` / `closeItem` / `toggleItem`, T14) on `key`. True when it shows open after. */
+    run(action: CompositeItemAction, key: string): boolean {
+        if (action === CompositeItemAction.Open) this.open(key);
+        else if (action === CompositeItemAction.Close) this.close(key);
+        else this.toggle(key);
+        return this.shown.has(key);
+    }
+
+    /** Back to the saved default ("Showing on canvas ▸ As saved"). */
+    resetLive(): void {
+        const items = this.items();
+        this.live = initialAccordionOpen(items.map(i => this.keyOf(i, items)), this.behaviourValue.defaultOn);
+        this.stamp();
+    }
+
+    /** The forced set changed (builder design state): show it. */
+    refresh(): void {
+        this.stamp();
+    }
+
+    destroy(): void {
+        if (RUNTIMES.get(this.root) === this) RUNTIMES.delete(this.root);
+        this.root.removeEventListener('click', this.onClick, true);
+        this.root.removeEventListener('keydown', this.onKeydown);
+        this.root.removeEventListener('beforematch', this.onBeforeMatch, true);
+        this.observer?.disconnect();
+        this.observer = null;
+        for (const t of this.closing.values()) clearTimeout(t);
+        this.closing.clear();
+    }
+
+    private queueStamp(): void {
+        if (this.stampQueued) return;
+        this.stampQueued = true;
+        const run = () => { this.stampQueued = false; this.stamp(); };
+        if (typeof queueMicrotask === 'function') queueMicrotask(run); else Promise.resolve().then(run);
+    }
+
+    private reduced(): boolean {
+        if (this.options.reducedMotion) return this.options.reducedMotion();
+        try { return typeof matchMedia === 'function' && matchMedia(REDUCED_MOTION).matches; } catch { return false; }
+    }
+
+    /** Write every item's state into its markup; announce what changed. */
+    private stamp(first = false): void {
+        // Our own writes must not wake the observer (they are attributes; it watches the child lists only).
+        const items = this.items();
+        if (this.awaitingItems && items.length) {
+            this.awaitingItems = false;
+            this.live = initialAccordionOpen(items.map(i => this.keyOf(i, items)), this.behaviourValue.defaultOn);
+            first = true;
+        }
+        const forced = this.options.forced?.() ?? new Set<string>();
+        const own = this.options.rootId;
+        const rootId = (typeof own === 'function' ? own() : own) ?? this.root.getAttribute(SCOPE_ATTRIBUTE) ?? nodeIdOf(this.root);
+        const next = new Set<string>();
+        items.forEach((item, index) => {
+            const key = this.keyOf(item, items);
+            const on = this.live.has(key) || forced.has(key);
+            if (on) next.add(key);
+            this.stampItem(item, key, index, on, rootId, first);
+        });
+        const was = first ? new Set<string>() : this.shown;
+        this.shown = next;
+        // On the first stamp an item open by default HAS opened: its `itemOn` listeners attached so far hear it
+        // (the builder renders an item's parts, and attaches their interactions, before its root's runtime; the
+        // live engine attaches the runtime first and its interactions run an already-open item's at once).
+        for (const item of items) {
+            const key = this.keyOf(item, items);
+            if (next.has(key) && !was.has(key)) dispatch(item, ITEM_ON_EVENT);
+            else if (!next.has(key) && was.has(key)) dispatch(item, ITEM_OFF_EVENT);
+        }
+    }
+
+    private stampItem(item: HTMLElement, key: string, index: number, on: boolean, rootId: string, first: boolean): void {
+        const ids = accordionDomIds(rootId, key, this.kind);
+        if (!item.hasAttribute(ITEM_KEY_ATTRIBUTE)) item.setAttribute(ITEM_KEY_ATTRIBUTE, key);
+        setAttr(item, ON_ATTRIBUTE, on ? '' : null);
+        const button = this.own(item, BUTTON_SELECTOR);
+        const track = this.own(item, TRACK_SELECTOR);
+        const region = this.own(item, REGION_SELECTOR);
+        const panel = this.own(item, PANEL_SELECTOR);
+        setAttr(button, 'type', 'button');
+        setAttr(button, 'id', ids.trigger);
+        setAttr(button, 'aria-expanded', on ? 'true' : 'false');
+        setAttr(button, 'aria-controls', ids.panel);
+        setAttr(button, ON_ATTRIBUTE, on ? '' : null);
+        setAttr(track, ON_ATTRIBUTE, on ? '' : null);
+        setAttr(panel, ON_ATTRIBUTE, on ? '' : null);
+        const labelled = hasLabelledRegion(this.kind);
+        setAttr(region, 'role', labelled ? 'region' : null);
+        setAttr(region, 'id', ids.panel);
+        setAttr(region, 'aria-labelledby', labelled ? ids.trigger : null);
+        if (!region) return;
+        const pending = this.closing.get(key);
+        if (on) {
+            if (pending) { clearTimeout(pending); this.closing.delete(key); }
+            setAttr(region, 'hidden', null);
+            return;
+        }
+        if (region.hasAttribute('hidden') || pending) return;
+        // Closing: the track collapses first (its transition), THEN the region is hidden — hiding it at once
+        // would collapse it with no motion. At first paint, or under reduced motion, it is hidden at once.
+        if (first || this.reduced()) { setAttr(region, 'hidden', UNTIL_FOUND); return; }
+        const hide = () => {
+            this.closing.delete(key);
+            if (!item.hasAttribute(ON_ATTRIBUTE)) setAttr(region, 'hidden', UNTIL_FOUND);
+        };
+        this.closing.set(key, setTimeout(hide, this.closeDelay(track)));
+    }
+
+    private closeDelay(track: Element | null): number {
+        try {
+            const view = track?.ownerDocument?.defaultView;
+            const raw = track && view ? view.getComputedStyle(track).transitionDuration : '';
+            const ms = Math.max(0, ...String(raw).split(',').map(s => (s.trim().endsWith('ms') ? parseFloat(s) : parseFloat(s) * 1000)).filter(n => !isNaN(n)));
+            return Math.min(MAX_CLOSE_MS, ms + 20);
+        } catch { return 0; }
+    }
+
+    /** The element `selector` matches inside `item` that belongs to it, not to an item nested in it. */
+    private own(item: HTMLElement, selector: string): HTMLElement | null {
+        return Array.from(item.querySelectorAll<HTMLElement>(selector)).find(el => closestAccordionItem(el) === item) ?? null;
+    }
+
+    private buttons(): HTMLElement[] {
+        return this.items().map(i => this.own(i, BUTTON_SELECTOR)).filter((b): b is HTMLElement => !!b);
+    }
+
+    private readonly onClick = (event: Event): void => {
+        const button = (event.target as Element | null)?.closest?.(BUTTON_SELECTOR);
+        if (!button || closestAccordion(button) !== this.root) return;
+        const item = closestAccordionItem(button);
+        if (!item) return;
+        event.preventDefault();
+        this.toggle(this.keyOf(item));
+    };
+
+    private readonly onKeydown = (event: Event): void => {
+        // A disclosure has one button: Enter / Space are the button's own, and there is nowhere to move.
+        if (this.kind !== CompositeKind.Accordion) return;
+        const e = event as KeyboardEvent;
+        const action = accordionKeyAction(e.key);
+        const button = (e.target as Element | null)?.closest?.(BUTTON_SELECTOR);
+        if (!action || !button || closestAccordion(button) !== this.root) return;
+        const buttons = this.buttons();
+        const at = buttons.indexOf(button as HTMLElement);
+        const target = buttons[accordionFocusIndex(action, at, buttons.length)];
+        if (!target) return;
+        e.preventDefault();
+        target.focus();
+    };
+
+    private readonly onBeforeMatch = (event: Event): void => {
+        const region = (event.target as Element | null)?.closest?.(REGION_SELECTOR);
+        const item = closestAccordionItem(region);
+        const items = this.items();
+        if (!item || !items.includes(item)) return;
+        this.open(this.keyOf(item, items));
+    };
+}
+
+function dispatch(el: Element, type: string): void {
+    const Ctor = (globalThis as { CustomEvent?: typeof CustomEvent }).CustomEvent;
+    if (Ctor) el.dispatchEvent(new Ctor(type, { bubbles: false }));
+}
+
+/** Attach the runtime to one rendered composite root, unless it already runs one. Returns the NEW runtime, or
+ *  null when the root already had one (so a caller destroys only what it created). */
+export function attachAccordionAt(root: HTMLElement, options: Omit<AccordionRuntimeOptions, 'rootId' | 'behaviour'> = {}): AccordionRuntime | null {
+    if (RUNTIMES.has(root)) return null;
+    return new AccordionRuntime(root, options);
+}
+
+/** Attach the runtime to every accordion under `container` that has none yet. Returns the new runtimes. */
+export function attachAccordions(container: ParentNode, options: Omit<AccordionRuntimeOptions, 'rootId' | 'behaviour'> = {}): AccordionRuntime[] {
+    const out: AccordionRuntime[] = [];
+    container.querySelectorAll<HTMLElement>(ROOT_SELECTOR).forEach(root => {
+        const runtime = attachAccordionAt(root, options);
+        if (runtime) out.push(runtime);
+    });
+    return out;
+}
+
+/** Detach a runtime `attachAccordions` created. */
+export function detachAccordion(runtime: AccordionRuntime): void {
+    runtime.destroy();
+}
+
+/** Every live runtime by its root — the canvas's and the site's alike (a runtime registers itself and leaves on
+ *  destroy), so an item action finds the runtime of whatever item it targets. */
+const RUNTIMES = new WeakMap<Element, AccordionRuntime>();
+
+const ROW_INDEX_ATTRIBUTE = 'data-iox-row-idx';
+
+/** The repeated rows an element sits in, outermost first — each row's index as its row wrappers stamp it
+ *  (`data-iox-row-idx`: the builder's Repeater rows, the engine's component path). The builder folds them into a
+ *  composite's scope id (`compositeScopeId`, vectoriox/iox-ui#20); the element itself is not counted. */
+export function compositeRowKeys(el: Element | null | undefined): string[] {
+    const keys: string[] = [];
+    for (let at = el?.parentElement?.closest?.(`[${ROW_INDEX_ATTRIBUTE}]`); at; at = at.parentElement?.closest(`[${ROW_INDEX_ATTRIBUTE}]`)) {
+        keys.unshift(at.getAttribute(ROW_INDEX_ATTRIBUTE) ?? '');
+    }
+    return keys;
+}
+
+/** The runtime running a composite root, or null. */
+export function accordionRuntimeOf(root: Element | null | undefined): AccordionRuntime | null {
+    return (root && RUNTIMES.get(root)) || null;
+}
+
+// ── T14: open / close / toggle an item from anywhere ─────────────────────────────────────────────
+
+/** What an item action does to its target item (actions-core `openItem` / `closeItem` / `toggleItem`). */
+export enum CompositeItemAction {
+    Open = 'open',
+    Close = 'close',
+    Toggle = 'toggle',
+}
+
+/**
+ * Run an item action on the element of an ITEM (an accordion item, or a disclosure) — the `openItem` /
+ * `closeItem` / `toggleItem` interaction actions, on the canvas and on the live site through this one function.
+ * Returns whether the item shows open afterwards, or null when `el` is in no running composite.
+ */
+export function runCompositeItemAction(el: Element | null | undefined, action: CompositeItemAction): boolean | null {
+    const item = closestAccordionItem(el);
+    const runtime = item ? accordionRuntimeOf(rootOfItem(item)) : null;
+    if (!item || !runtime) return null;
+    return runtime.run(action, runtime.keyOf(item));
+}
+
+/** How much of an opened item must already be on screen for the action NOT to scroll to it (its header row). */
+const VISIBLE_HEAD_PX = 48;
+
+/** True when an item an action just opened is out of view and the page should scroll to it (T14: "opens that item
+ *  and scrolls to it") — never when its head is already on screen, so a button beside it does not jolt the page. */
+export function shouldScrollToItem(top: number, viewportHeight: number): boolean {
+    return top < 0 || top + VISIBLE_HEAD_PX > viewportHeight;
+}