@vectoriox/iox-ui 5.37.0 → 5.39.0

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

@@ -0,0 +1,68 @@
+import {
+    accordionRootOfItem, accordionRuntimeOf, AccordionRuntime, AccordionRuntimeOptions, attachAccordionAt, closestAccordionItem, CompositeItemAction,
+    isAccordionItemOn, onAccordionItemState,
+} from './accordion-runtime';
+import { COMPOSITE_ATTRIBUTE } from './accordion';
+import { CompositeKind, isExclusiveKind } from './composite-kinds';
+import {
+    attachExclusiveAt, closestExclusive, closestExclusiveItemPart, ExclusiveRuntime, exclusiveRuntimeOf, ExclusiveRuntimeOptions, isExclusiveItemOn,
+    onExclusiveItemState,
+} from './exclusive-runtime';
+
+/**
+ * The composites' runtimes behind ONE door (CC4a): the open/close runtime (Accordion, Disclosure) and the exclusive
+ * runtime (Tabs; the Segmented control in CC4b). The engine attaches whichever a rendered root needs; the interaction
+ * engines (builder canvas and live site) ask these for `itemOn` / `itemOff` and run the item actions through them —
+ * never a family's own function, so a new kind joins without touching either engine.
+ */
+
+export type CompositeRuntime = AccordionRuntime | ExclusiveRuntime;
+
+/** Attach the runtime a rendered composite root needs (its `data-iox-composite`), unless it runs one already. Returns
+ *  the NEW runtime, or null. */
+export function attachCompositeAt(root: HTMLElement, options: Omit<AccordionRuntimeOptions, 'rootId' | 'behaviour'> & Omit<ExclusiveRuntimeOptions, 'behaviour'> = {}): CompositeRuntime | null {
+    const kind = root.getAttribute(COMPOSITE_ATTRIBUTE) as CompositeKind | null;
+    if (isExclusiveKind(kind)) return attachExclusiveAt(root, { observe: options.observe });
+    return attachAccordionAt(root, { observe: options.observe, reducedMotion: options.reducedMotion });
+}
+
+/** The nearer of the item elements `el` sits in — an accordion item / a disclosure, or a tab / a tab panel. */
+function nearestItem(el: Element | null | undefined): { el: HTMLElement; exclusive: boolean } | null {
+    const toggle = closestAccordionItem(el);
+    const exclusive = closestExclusiveItemPart(el);
+    if (!toggle && !exclusive) return null;
+    if (toggle && (!exclusive || exclusive.contains(toggle))) return { el: toggle, exclusive: false };
+    return { el: exclusive!, exclusive: true };
+}
+
+/** Subscribe to the item `el` sits in turning on / off — what the `itemOn` / `itemOff` interaction triggers listen to,
+ *  in both families. Returns the unsubscribe. */
+export function onCompositeItemState(el: Element, on: boolean, handler: () => void): () => void {
+    const item = nearestItem(el);
+    if (!item) return () => undefined;
+    return item.exclusive ? onExclusiveItemState(item.el, on, handler) : onAccordionItemState(item.el, on, handler);
+}
+
+/** True when the item `el` sits in is on now (an open accordion item, the active tab or its panel). */
+export function isCompositeItemOn(el: Element): boolean {
+    const item = nearestItem(el);
+    if (!item) return false;
+    return item.exclusive ? isExclusiveItemOn(item.el) : isAccordionItemOn(item.el);
+}
+
+/**
+ * Run an item action on the element of an ITEM — an accordion item, a disclosure, or a tab (CC4a: `openItem` turns it
+ * on; a Tabs always shows one, so Close and Toggle leave it) — the `openItem` / `closeItem` / `toggleItem` interaction
+ * actions, on the canvas and on the live site through this one function. Returns whether the item shows on
+ * afterwards, or null when `el` is in no running composite.
+ */
+export function runCompositeItemAction(el: Element | null | undefined, action: CompositeItemAction): boolean | null {
+    const item = nearestItem(el);
+    if (!item) return null;
+    if (item.exclusive) {
+        const runtime = exclusiveRuntimeOf(closestExclusive(item.el));
+        return runtime ? runtime.run(action === CompositeItemAction.Open, runtime.keyOf(item.el)) : null;
+    }
+    const runtime = accordionRuntimeOf(accordionRootOfItem(item.el));
+    return runtime ? runtime.run(action, runtime.keyOf(item.el)) : null;
+}

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

@@ -0,0 +1,358 @@
+import { roleClass } from '@vectoriox/iox-ui/design-core';
+
+import { accordionDomIds, accordionFocusIndex, COMPOSITE_ATTRIBUTE, ITEM_KEY_ATTRIBUTE, ON_ATTRIBUTE, SCOPE_ATTRIBUTE } from './accordion';
+import { ITEM_OFF_EVENT, ITEM_ON_EVENT } from './accordion-runtime';
+import { CompositeKind, EXCLUSIVE_KIND_ROLES, ExclusiveCompositeKind, isExclusiveKind } from './composite-kinds';
+import {
+    ACTIVATE_ON_ATTRIBUTE, ORIENTATION_ATTRIBUTE, TABS_ACTIVATE_ONS, TABS_ORIENTATIONS, TabsActivateOn, TabsBehaviour, tabsKeyAction, TabsOrientation,
+} from './tabs';
+
+/**
+ * The EXCLUSIVE composites' RUNTIME (CC4a Tabs; the Segmented control runs it too in CC4b) — ONE copy, DOM only, for
+ * the builder canvas and the live site (both engine paths render the same markup from `tabs.ts`'s attribute planners):
+ *
+ *   [root]   data-iox-composite="tabs"  data-iox-activate-on  data-iox-orientation  [data-iox-scope]
+ *     .iox-role-tabs-list      role=tablist  [aria-orientation=vertical]
+ *       .iox-role-tabs-trigger role=tab  id  aria-selected  aria-controls  tabindex 0|-1  data-iox-item-key  [data-iox-on]
+ *     .iox-role-tabs-panels
+ *       .iox-role-tabs-panel   role=tabpanel  id  aria-labelledby  tabindex=0  data-iox-item-key  [hidden] | [data-iox-on]
+ *
+ * Exactly one item is on, always (a Tabs with tabs never shows none). It owns: a click on a trigger turns its item on
+ * (and a hover, when the root says `activate-on=hover`); the APG tabs keys with AUTOMATIC activation — ← → along a
+ * horizontal list (mirrored under RTL), ↑ ↓ along a vertical one, Home / End — moving focus AND turning the item on,
+ * the roving tabindex keeping one trigger in the Tab order. A trigger and its panel pair by `data-iox-item-key`
+ * (else their index among their kind — the builder's From-content rows). Every change dispatches `iox-item-on` /
+ * `iox-item-off` on the trigger AND its panel (the `itemOn` / `itemOff` interaction triggers). The item shown is
+ * FORCED ?? LIVE: the builder forces one (a selection inside an inactive panel); the live site forces nothing. The
+ * server's first state is trusted (no flash).
+ */
+
+export interface ExclusiveRuntimeOptions {
+    /** The scope id the ARIA ids are built from (else `data-iox-scope`, else the root's `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);
+    /** The behaviour (else read from the root's data attributes). */
+    behaviour?: TabsBehaviour;
+    /** The list's accessible name, stamped by the runtime (the builder canvas; the engine renders it). */
+    label?: () => string;
+    /** The key forced on, on top of the live state (the builder's design state), or null. */
+    forced?: () => string | null;
+    /** The live item changed (a click, a key, a hover, an action) — the builder's "Showing on canvas" follows it. */
+    onChange?: (key: string) => void;
+    /** Re-stamp when the markup under the root changes (the builder canvas re-renders parts). */
+    observe?: boolean;
+}
+
+const KIND_ROOT = (kind: ExclusiveCompositeKind) => `[${COMPOSITE_ATTRIBUTE}="${kind}"]`;
+const EXCLUSIVE_KINDS = Object.keys(EXCLUSIVE_KIND_ROLES) as ExclusiveCompositeKind[];
+const ROOT_SELECTOR = EXCLUSIVE_KINDS.map(KIND_ROOT).join(', ');
+const roleSelector = (pick: 'list' | 'trigger' | 'panel') =>
+    EXCLUSIVE_KINDS.map(k => EXCLUSIVE_KIND_ROLES[k][pick]).filter((r): r is string => !!r).map(r => `.${roleClass(r)}`).join(', ');
+const LIST_SELECTOR = roleSelector('list');
+const TRIGGER_SELECTOR = roleSelector('trigger');
+const PANEL_SELECTOR = roleSelector('panel');
+const ITEM_PART_SELECTOR = `${TRIGGER_SELECTOR}, ${PANEL_SELECTOR}`;
+const TABLIST_SELECTOR = '[role="tablist"]';
+
+/** The exclusive composite an element belongs to (the element itself when it is a root). */
+export function closestExclusive(el: Element | null | undefined): HTMLElement | null {
+    return (el?.closest?.(ROOT_SELECTOR) as HTMLElement | null) ?? null;
+}
+
+/** The trigger or panel an element sits in (itself when it is one) — its ITEM part — or null. */
+export function closestExclusiveItemPart(el: Element | null | undefined): HTMLElement | null {
+    return (el?.closest?.(ITEM_PART_SELECTOR) as HTMLElement | null) ?? null;
+}
+
+const kindOf = (root: Element): ExclusiveCompositeKind => {
+    const raw = root.getAttribute(COMPOSITE_ATTRIBUTE) as CompositeKind | null;
+    return isExclusiveKind(raw) ? raw : CompositeKind.Tabs;
+};
+
+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): TabsBehaviour {
+    const on = root.getAttribute(ACTIVATE_ON_ATTRIBUTE);
+    const orientation = root.getAttribute(ORIENTATION_ATTRIBUTE);
+    return {
+        activateOn: TABS_ACTIVATE_ONS.includes(on as TabsActivateOn) ? on as TabsActivateOn : TabsActivateOn.Click,
+        orientation: TABS_ORIENTATIONS.includes(orientation as TabsOrientation) ? orientation as TabsOrientation : TabsOrientation.Horizontal,
+    };
+}
+
+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);
+}
+
+function dispatch(el: Element | null | undefined, type: string): void {
+    const Ctor = (globalThis as { CustomEvent?: typeof CustomEvent }).CustomEvent;
+    if (el && Ctor) el.dispatchEvent(new Ctor(type, { bubbles: false }));
+}
+
+export class ExclusiveRuntime {
+    private live: string | null;
+    private shown: string | null = null;
+    private observer: MutationObserver | null = null;
+    private stampQueued = false;
+    private behaviourValue: TabsBehaviour;
+    private awaitingItems = false;
+    readonly kind: ExclusiveCompositeKind;
+
+    constructor(readonly root: HTMLElement, private readonly options: ExclusiveRuntimeOptions = {}) {
+        this.kind = kindOf(root);
+        this.behaviourValue = options.behaviour ?? behaviourOf(root);
+        root.setAttribute(COMPOSITE_ATTRIBUTE, this.kind);
+        EXCLUSIVE_RUNTIMES.set(root, this);
+        // The server rendered the first state (every trigger keyed, one on); with no server state the first is on.
+        const triggers = this.triggers();
+        const serverOn = !options.behaviour ? triggers.find(t => t.hasAttribute(ON_ATTRIBUTE) && t.hasAttribute(ITEM_KEY_ATTRIBUTE)) : undefined;
+        this.live = serverOn ? this.keyOf(serverOn) : (triggers[0] ? this.keyOf(triggers[0]) : null);
+        this.awaitingItems = !triggers.length;
+        // Capture: on the builder canvas every part's own listener stops the click (it selects that part), and the tab
+        // must still turn on — the canvas is a live runtime.
+        root.addEventListener('click', this.onClick, true);
+        root.addEventListener('mouseover', this.onHover, true);
+        root.addEventListener('keydown', this.onKeydown);
+        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(): TabsBehaviour {
+        return this.behaviourValue;
+    }
+
+    /** The behaviour changed in the panel (Activate on, Orientation). */
+    setBehaviour(behaviour: TabsBehaviour): void {
+        this.behaviourValue = behaviour;
+        this.root.setAttribute(ACTIVATE_ON_ATTRIBUTE, behaviour.activateOn);
+        this.root.setAttribute(ORIENTATION_ATTRIBUTE, behaviour.orientation);
+        this.stamp();
+    }
+
+    /** THIS composite's triggers in document order (a nested composite's are its own). */
+    triggers(): HTMLElement[] {
+        return this.own(TRIGGER_SELECTOR);
+    }
+
+    /** THIS composite's panels in document order. */
+    panels(): HTMLElement[] {
+        return this.own(PANEL_SELECTOR);
+    }
+
+    /** The key on right now (forced ?? live). */
+    get activeKey(): string | null {
+        return this.shown;
+    }
+
+    /** The key the live state holds (before anything forced). */
+    get liveKey(): string | null {
+        return this.live;
+    }
+
+    /** The key of a trigger or a panel: its `data-iox-item-key`, else its index among its kind. */
+    keyOf(part: Element): string {
+        const own = part.getAttribute(ITEM_KEY_ATTRIBUTE);
+        if (own) return own;
+        const peers = part.matches(TRIGGER_SELECTOR) ? this.triggers() : this.panels();
+        return `item-${peers.indexOf(part as HTMLElement)}`;
+    }
+
+    /** The key of the item an element sits in (a part inside a tab or a panel), or null. */
+    keyAt(el: Element | null | undefined): string | null {
+        const part = closestExclusiveItemPart(el);
+        return part && closestExclusive(part) === this.root ? this.keyOf(part) : null;
+    }
+
+    /** Turn `key` on (a click, a key, a hover, the `openItem` action, "Showing on canvas"). */
+    activate(key: string): void {
+        if (!this.keys().includes(key)) return;
+        const changed = key !== this.live;
+        this.live = key;
+        this.stamp();
+        if (changed) this.options.onChange?.(key);
+    }
+
+    /** Run an item action on `key`: Open turns it on; Close and Toggle do nothing (one item is always on). True when it
+     *  is on afterwards. */
+    run(open: boolean, key: string): boolean {
+        if (open) this.activate(key);
+        return this.shown === key;
+    }
+
+    /** The forced key changed (builder design state): show it. */
+    refresh(): void {
+        this.stamp();
+    }
+
+    destroy(): void {
+        if (EXCLUSIVE_RUNTIMES.get(this.root) === this) EXCLUSIVE_RUNTIMES.delete(this.root);
+        this.root.removeEventListener('click', this.onClick, true);
+        this.root.removeEventListener('mouseover', this.onHover, true);
+        this.root.removeEventListener('keydown', this.onKeydown);
+        this.observer?.disconnect();
+        this.observer = null;
+    }
+
+    private keys(): string[] {
+        return this.triggers().map(t => this.keyOf(t));
+    }
+
+    /** The element(s) that ARE the tablist: the ones a renderer already gave the role (the engine's component-path
+     *  Repeater puts it on its inner root, which holds the tabs), else the elements carrying the list's role class. */
+    private lists(): HTMLElement[] {
+        const stamped = this.own(TABLIST_SELECTOR);
+        return stamped.length ? stamped : this.own(LIST_SELECTOR);
+    }
+
+    private own(selector: string): HTMLElement[] {
+        return Array.from(this.root.querySelectorAll<HTMLElement>(selector)).filter(el => closestExclusive(el.parentElement) === this.root);
+    }
+
+    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 rootId(): string {
+        const own = this.options.rootId;
+        return (typeof own === 'function' ? own() : own) ?? this.root.getAttribute(SCOPE_ATTRIBUTE) ?? nodeIdOf(this.root);
+    }
+
+    /** Write every part's state into its markup; announce what changed. */
+    private stamp(first = false): void {
+        const triggers = this.triggers();
+        const keys = triggers.map(t => this.keyOf(t));
+        if (this.awaitingItems && keys.length) {
+            this.awaitingItems = false;
+            this.live = keys[0];
+            first = true;
+        }
+        if (this.live === null || !keys.includes(this.live)) this.live = keys[0] ?? null;
+        const forced = this.options.forced?.() ?? null;
+        const next = forced !== null && keys.includes(forced) ? forced : this.live;
+        const rootId = this.rootId();
+        const vertical = this.behaviourValue.orientation === TabsOrientation.Vertical;
+        for (const list of this.lists()) {
+            setAttr(list, 'role', 'tablist');
+            setAttr(list, 'aria-orientation', vertical ? 'vertical' : null);
+            if (this.options.label) setAttr(list, 'aria-label', this.options.label() || null);
+        }
+        const panels = this.panels();
+        const panelOf = (key: string) => panels.find(p => this.keyOf(p) === key) ?? null;
+        for (const trigger of triggers) {
+            const key = this.keyOf(trigger);
+            const on = key === next;
+            const ids = accordionDomIds(rootId, key, CompositeKind.Tabs);
+            setAttr(trigger, ITEM_KEY_ATTRIBUTE, key);
+            setAttr(trigger, 'type', trigger.tagName === 'BUTTON' ? 'button' : null);
+            setAttr(trigger, 'role', 'tab');
+            setAttr(trigger, 'id', ids.trigger);
+            setAttr(trigger, 'aria-selected', on ? 'true' : 'false');
+            setAttr(trigger, 'aria-controls', panelOf(key) ? ids.panel : null);
+            setAttr(trigger, 'tabindex', on ? '0' : '-1');
+            setAttr(trigger, ON_ATTRIBUTE, on ? '' : null);
+        }
+        for (const panel of panels) {
+            const key = this.keyOf(panel);
+            const on = key === next;
+            const ids = accordionDomIds(rootId, key, CompositeKind.Tabs);
+            setAttr(panel, ITEM_KEY_ATTRIBUTE, key);
+            setAttr(panel, 'role', 'tabpanel');
+            setAttr(panel, 'id', ids.panel);
+            setAttr(panel, 'aria-labelledby', ids.trigger);
+            setAttr(panel, 'tabindex', '0');
+            setAttr(panel, ON_ATTRIBUTE, on ? '' : null);
+            setAttr(panel, 'hidden', on ? null : '');
+        }
+        const was = first ? null : this.shown;
+        this.shown = next;
+        if (was === next && !first) return;
+        if (was !== null) {
+            dispatch(triggers.find(t => this.keyOf(t) === was), ITEM_OFF_EVENT);
+            dispatch(panelOf(was), ITEM_OFF_EVENT);
+        }
+        if (next !== null) {
+            dispatch(triggers.find(t => this.keyOf(t) === next), ITEM_ON_EVENT);
+            dispatch(panelOf(next), ITEM_ON_EVENT);
+        }
+    }
+
+    private ownTrigger(target: EventTarget | null): HTMLElement | null {
+        const trigger = (target as Element | null)?.closest?.(TRIGGER_SELECTOR) as HTMLElement | null;
+        return trigger && closestExclusive(trigger.parentElement) === this.root ? trigger : null;
+    }
+
+    private readonly onClick = (event: Event): void => {
+        const trigger = this.ownTrigger(event.target);
+        if (!trigger) return;
+        event.preventDefault();
+        this.activate(this.keyOf(trigger));
+    };
+
+    private readonly onHover = (event: Event): void => {
+        if (this.behaviourValue.activateOn !== TabsActivateOn.Hover) return;
+        const trigger = this.ownTrigger(event.target);
+        if (trigger) this.activate(this.keyOf(trigger));
+    };
+
+    private readonly onKeydown = (event: Event): void => {
+        const e = event as KeyboardEvent;
+        const trigger = this.ownTrigger(e.target);
+        if (!trigger) return;
+        const rtl = isRtl(trigger);
+        const action = tabsKeyAction(e.key, this.behaviourValue.orientation, rtl);
+        if (!action) return;
+        const triggers = this.triggers();
+        const target = triggers[accordionFocusIndex(action, triggers.indexOf(trigger), triggers.length)];
+        if (!target) return;
+        e.preventDefault();
+        target.focus();
+        this.activate(this.keyOf(target));
+    };
+}
+
+/** The direction the tab is laid out in — the computed `direction` (a page's own CSS included), else its nearest `dir`. */
+function isRtl(el: Element): boolean {
+    let computed = '';
+    try { computed = el.ownerDocument?.defaultView?.getComputedStyle(el).direction ?? ''; } catch { computed = ''; }
+    if (computed) return computed === 'rtl';
+    return el.closest('[dir]')?.getAttribute('dir') === 'rtl';
+}
+
+/** Every live exclusive runtime by its root — so an item action finds the runtime of whatever item it targets. */
+const EXCLUSIVE_RUNTIMES = new WeakMap<Element, ExclusiveRuntime>();
+
+/** The runtime running an exclusive root, or null. */
+export function exclusiveRuntimeOf(root: Element | null | undefined): ExclusiveRuntime | null {
+    return (root && EXCLUSIVE_RUNTIMES.get(root)) || null;
+}
+
+/** Attach the runtime to one rendered exclusive root, unless it already runs one. Returns the NEW runtime, or null. */
+export function attachExclusiveAt(root: HTMLElement, options: Omit<ExclusiveRuntimeOptions, 'behaviour'> = {}): ExclusiveRuntime | null {
+    if (EXCLUSIVE_RUNTIMES.has(root)) return null;
+    return new ExclusiveRuntime(root, options);
+}
+
+/** True when `el` is (or sits in) an exclusive item part — a tab or a panel. */
+export function isExclusiveItemOn(el: Element): boolean {
+    return !!closestExclusiveItemPart(el)?.hasAttribute(ON_ATTRIBUTE);
+}
+
+/** Subscribe to the item part `el` sits in turning on / off. Returns the unsubscribe. */
+export function onExclusiveItemState(el: Element, on: boolean, handler: () => void): () => void {
+    const part = closestExclusiveItemPart(el);
+    if (!part) return () => undefined;
+    const type = on ? ITEM_ON_EVENT : ITEM_OFF_EVENT;
+    part.addEventListener(type, handler);
+    return () => part.removeEventListener(type, handler);
+}

package/src/composite-core/lightbox.ts

@@ -0,0 +1,192 @@
+import { setColorScheme } from '@vectoriox/iox-ui/design-core';
+
+import { CompositeNode, CompositeNodeFactory, makeCompositePart, NO_ELEMENT_STYLE, readProp, writeProp, writeStyles } from './composite-node';
+import { buildSliderPart, SLIDE_TYPE, SLIDER_TYPE, SliderRole } from './slider';
+
+/**
+ * THE LIGHTBOX (CC3 — complex-components plan §7d, board 6). Not a component: a Dialog holding a Slider bound to the
+ * SAME source as the grid of thumbnails. The one new thing is `openDialog`'s "Open at the clicked item"
+ * (`slideTo: 'row'`): a thumbnail in a repeater row opens the lightbox at ITS slide.
+ *
+ *   Dialog `dialog` · centre · full viewport · Inverse scheme      "Lightbox" (a free-standing Dialog: board A4)
+ *   ├─ ButtonBlock `button-ghost`  "Close"  › Icon ×                click → closeDialog
+ *   └─ SliderContainer  one slide in view · keyboard · the source's rows
+ *       ├─ Previous · Next (slider.prev / slider.next, button-secondary)   hidden on a phone (swipe)
+ *       ├─ SliderSlide › Image `media` (contain, keeps its alt) + Text `small` caption
+ *       └─ Pagination (slider.pagination) — the counter "3 / 6"
+ *
+ * Keyboard ← → are the Slider's Keyboard module; Esc and the focus trap are the `<dialog>`'s; focus returns to the
+ * thumbnail that opened it (the dialog opener's own rule).
+ */
+
+export const SLIDE_TO_ROW = 'row';
+/** The attribute a renderer writes on every repeated row (the context-state provenance, both engine paths, the canvas). */
+export const ROW_INDEX_ATTRIBUTE = 'data-iox-row-idx';
+export const LIGHTBOX_LABEL = 'Lightbox';
+const DIALOG = 'Dialog';
+const REPEATER = 'Repeater';
+const SOURCE = 'source';
+const SOURCE_PATH = 'sourcePath';
+
+export interface LightboxOptions {
+    /** The list the slides come from (the grid's own source). Empty = three manual slides. */
+    source?: string;
+    sourcePath?: string;
+    /** The row field each slide's image and caption read (`item` = the row itself, a bare URL). */
+    imageField?: string;
+    captionField?: string;
+    /** The image's alt binding; '' = decorative (a bare URL row has no words of its own). */
+    altField?: string;
+}
+
+const ZERO = '0px 0px 0px 0px';
+const DIALOG_BASE: Readonly<Record<string, string>> = {
+    width: '100vw', maxWidth: '100vw', height: '100dvh', maxHeight: '100dvh', borderRadius: '0px', padding: '18px 18px 18px 18px',
+    display: 'flex', flexDirection: 'column', gap: '0px',
+};
+/** The top row (board 6): the counter at its start, Close at its end — Close sits above the slider, which rises into
+ *  the row so its counter shares it. */
+const CLOSE_BASE: Readonly<Record<string, string>> = {
+    display: 'flex', alignItems: 'center', justifyContent: 'center', width: '44px', height: '44px', minWidth: '44px',
+    padding: ZERO, margin: ZERO, borderRadius: '999px', alignSelf: 'flex-end', flexShrink: '0', position: 'relative', zIndex: '20',
+};
+const SLIDER_BASE: Readonly<Record<string, string>> = { width: '100%', height: '100%', minHeight: '0px', flexGrow: '1', margin: '-44px 0px 0px 0px' };
+const SLIDE_BASE: Readonly<Record<string, string>> = {
+    width: '100%', height: '100%', aspectRatio: 'auto', display: 'flex', flexDirection: 'column', alignItems: 'center',
+    justifyContent: 'center', gap: '12px', padding: '56px 64px 16px 64px',
+};
+const IMAGE_BASE: Readonly<Record<string, string>> = { width: '100%', height: 'auto', maxHeight: '72dvh', minHeight: '0px', objectFit: 'contain', aspectRatio: '4 / 3', flexShrink: '1' };
+const CAPTION_BASE: Readonly<Record<string, string>> = { textAlign: 'center', margin: ZERO, padding: ZERO, minHeight: 'auto', width: 'auto' };
+/** The counter "3 / 6" sits at the START of the top row, Close at its end (board 6). */
+const COUNTER_BASE: Readonly<Record<string, string>> = { color: 'var(--iox-text-muted)', top: '12px', alignItems: 'flex-start', justifyContent: 'flex-start' };
+/** On a phone the arrows give way to a swipe (board 6, "the arrows hide on touch-only widths"). */
+export const LIGHTBOX_ARROWS_HIDE_AT = 'mobile';
+
+interface WithInteractions { interactions?: unknown[] }
+
+/** A click on `node` runs one instant action on `target`. */
+function onClick(node: CompositeNode, type: string, target: string, params?: Record<string, unknown>): void {
+    (node as WithInteractions).interactions = [{
+        id: `${node.id ?? 'node'}-click`, trigger: 'click',
+        actions: [{ type, target, duration: 0, delay: 0, easing: 'ease', ...(params ? { params } : {}) }],
+    }];
+}
+
+/** A binding of `prop` to the row field `field` of `source` (`item` = the row itself). */
+function bindRow(node: CompositeNode, prop: string, source: string, field: string): void {
+    const bindings = ((node as { bindings?: unknown[] }).bindings ?? []).filter((b) => (b as { prop?: string }).prop !== prop);
+    bindings.push({ prop, source, path: field === 'item' ? '' : field });
+    (node as { bindings?: unknown[] }).bindings = bindings;
+}
+
+function buildSlide(create: CompositeNodeFactory, key: string, options: LightboxOptions, rowAlias: string | null): CompositeNode {
+    const slide = makeCompositePart(create, { key, type: SLIDE_TYPE, props: {}, elementStyle: NO_ELEMENT_STYLE }, null, 'Slide', SLIDE_BASE);
+    const image = makeCompositePart(create, { key: `${key}-image`, type: 'Image', props: { src: '', alt: '' }, elementStyle: 'media' }, null, 'Image', IMAGE_BASE);
+    const caption = makeCompositePart(create, { key: `${key}-caption`, type: 'Text', props: { content: 'Caption', tag: 'p' }, elementStyle: 'small' }, null, 'Caption', CAPTION_BASE);
+    if (rowAlias) {
+        bindRow(image, 'src', rowAlias, options.imageField ?? 'item');
+        if (options.altField) bindRow(image, 'alt', rowAlias, options.altField);
+        if (options.captionField) bindRow(caption, 'content', rowAlias, options.captionField);
+    }
+    slide.children = options.captionField || !rowAlias ? [image, caption] : [image];
+    return slide;
+}
+
+/** A fresh lightbox: the Dialog, its Close part and the Slider (bound to `source`, or three manual slides). */
+export function buildLightboxRecipe(create: CompositeNodeFactory, options: LightboxOptions = {}): CompositeNode {
+    const dialog = makeCompositePart(create, { key: 'lightbox', type: DIALOG, props: {}, elementStyle: 'dialog' }, null, LIGHTBOX_LABEL, DIALOG_BASE);
+    writeProp(dialog, 'placement', 'center');
+    writeProp(dialog, 'closeOnBackdrop', true);
+    writeProp(dialog, 'showCloseButton', false);
+    writeProp(dialog, 'ariaLabel', 'Gallery');
+    setColorScheme(dialog, 'inverse');
+
+    const close = makeCompositePart(create, { key: 'close', type: 'ButtonBlock', props: { tag: 'button', type: 'button', ariaLabel: 'Close' }, elementStyle: 'button-ghost' }, null, 'Close', CLOSE_BASE);
+    close.children = [makeCompositePart(create, { key: 'close-icon', type: 'Icon', props: { iconClass: 'ph ph-x' }, elementStyle: 'icon' }, null, 'Icon', { fontSize: '22px', color: 'inherit' })];
+    onClick(close, 'closeDialog', dialog.id ?? '');
+
+    const slider = makeCompositePart(create, { key: 'slider', type: SLIDER_TYPE, props: {}, elementStyle: NO_ELEMENT_STYLE }, null, 'Slider', SLIDER_BASE);
+    for (const [name, value] of Object.entries({
+        slidesPerView: 1, spaceBetween: 0, loop: 'off', enableNavigation: true, enablePagination: true, paginationType: 'fraction',
+        enableKeyboard: true, ariaLabel: 'Gallery', limit: 50,
+    })) writeProp(slider, name, value);
+    const rowAlias = options.source ? lastSegment(options.sourcePath) || options.source : null;
+    if (options.source) {
+        writeProp(slider, SOURCE, options.source);
+        if (options.sourcePath) writeProp(slider, SOURCE_PATH, options.sourcePath);
+    }
+    const prev = buildSliderPart(create, SliderRole.Prev);
+    const next = buildSliderPart(create, SliderRole.Next);
+    for (const arrow of [prev, next]) {
+        const layers = { ...(arrow.responsive ?? {}) };
+        layers[LIGHTBOX_ARROWS_HIDE_AT] = { styleProps: { display: 'none' } };
+        arrow.responsive = layers;
+    }
+    const counter = buildSliderPart(create, SliderRole.Pagination);
+    counter.label = 'Counter';
+    writeStyles(counter, COUNTER_BASE);
+    const slides = rowAlias ? [buildSlide(create, 'slide', options, rowAlias)] : [1, 2, 3].map(n => buildSlide(create, `slide-${n}`, options, null));
+    slider.children = [prev, next, ...slides, counter];
+    dialog.children = [close, slider];
+    return dialog;
+}
+
+const lastSegment = (path: string | undefined): string => (path ? String(path).split('.').filter(Boolean).pop() ?? '' : '');
+
+// ── "Open at the clicked item" ─────────────────────────────────────────────────────────────────────
+
+export interface RepeatSource {
+    source: string;
+    path: string;
+}
+
+/** What a Repeater (its `source` binding) or a bound Slider (its `source` / `sourcePath` traits) repeats over. */
+export function repeatSourceOf(node: CompositeNode | null | undefined): RepeatSource | null {
+    if (!node || (node.type !== REPEATER && node.type !== SLIDER_TYPE)) return null;
+    const binding = ((node as { bindings?: Array<{ prop?: string; source?: string; path?: string }> }).bindings ?? []).find(b => b?.prop === SOURCE);
+    if (binding?.source) return { source: binding.source, path: binding.path ?? '' };
+    const source = readProp(node, SOURCE);
+    if (typeof source !== 'string' || !source) return null;
+    const path = readProp(node, SOURCE_PATH);
+    return { source, path: typeof path === 'string' ? path : '' };
+}
+
+export function sameRepeatSource(a: RepeatSource | null, b: RepeatSource | null): boolean {
+    return !!a && !!b && a.source === b.source && (a.path ?? '') === (b.path ?? '');
+}
+
+/** The Slider a lightbox Dialog holds (the first one, depth first), or null. */
+export function lightboxSliderOf(dialog: CompositeNode | null | undefined): CompositeNode | null {
+    for (const child of dialog?.children ?? []) {
+        if (child.type === SLIDER_TYPE) return child;
+        const below = lightboxSliderOf(child);
+        if (below) return below;
+    }
+    return null;
+}
+
+/** The repeated rows the element is in: the nearest Repeater or bound Slider among its ancestors (`path` = root → the
+ *  element, inclusive). */
+export function rowSourceOf(path: ReadonlyArray<CompositeNode>): RepeatSource | null {
+    for (let i = path.length - 2; i >= 0; i--) {
+        const source = repeatSourceOf(path[i]);
+        if (source) return source;
+    }
+    return null;
+}
+
+/**
+ * Interactions ▸ openDialog ▸ "Open at the clicked item" is offered only when it can work (board 9): the clicked
+ * element sits in a repeater row AND the target Dialog holds a Slider bound to the same source.
+ */
+export function canOpenAtClickedItem(ownerPath: ReadonlyArray<CompositeNode>, dialog: CompositeNode | null | undefined): boolean {
+    if (!dialog || dialog.type !== DIALOG) return false;
+    return sameRepeatSource(rowSourceOf(ownerPath), repeatSourceOf(lightboxSliderOf(dialog)));
+}
+
+/** The repeated row an element sits in (its row index), 0 when it is in none (the canvas' template row). */
+export function rowIndexOf(el: Element | null | undefined): number {
+    const row = el?.closest?.(`[${ROW_INDEX_ATTRIBUTE}]`);
+    const index = Number(row?.getAttribute(ROW_INDEX_ATTRIBUTE));
+    return Number.isInteger(index) && index >= 0 ? index : 0;
+}

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

@@ -3,8 +3,8 @@
  * plan §3a). FRAMEWORK-FREE: the builder, the SSR engine and iox-cms (generation-core's composer, the site
  * build) read the same recipes, roles and structure rules. Card v2 + Badge / Chip (T23 / T25) are the
  * first; the Accordion (CC2) adds the first composite RUNTIME (accordion-runtime.ts — DOM only, no
- * framework), which the Disclosure (CC2.1) runs too — a one-item accordion whose root is its item; Tabs join with
- * their own phase.
+ * framework), which the Disclosure (CC2.1) runs too — a one-item accordion whose root is its item; Tabs (CC4a) run the
+ * EXCLUSIVE runtime (exclusive-runtime.ts — one item always on); composite-runtime.ts is the one door to both.
  * ⚠️ Consumers wire the usual trio — ng-package raw-ts assets, jest moduleNameMapper, tsconfig paths.
  */
 export * from './composite-node';
@@ -15,3 +15,9 @@ export * from './disclosure';
 export * from './badge';
 export * from './card';
 export * from './structure';
+export * from './slider';
+export * from './slider-runtime';
+export * from './lightbox';
+export * from './tabs';
+export * from './exclusive-runtime';
+export * from './composite-runtime';