@vectoriox/iox-ui 5.38.0 → 5.39.0

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/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';
@@ -18,3 +18,6 @@ export * from './structure';
 export * from './slider';
 export * from './slider-runtime';
 export * from './lightbox';
+export * from './tabs';
+export * from './exclusive-runtime';
+export * from './composite-runtime';

package/src/composite-core/structure.ts

@@ -1,4 +1,4 @@
-import { AccordionRole, DisclosureRole } from './composite-kinds';
+import { AccordionRole, DisclosureRole, TabsRole } from './composite-kinds';
 import { CardPart, CardRole } from './card';
 import { SLIDER_TYPE, SliderRole } from './slider';
 
@@ -17,6 +17,8 @@ export interface CompositeRoleSpec {
     /** May be deleted, but never moved out of its parent (a Slider's controls work only as its direct children). */
     readonly pinned?: boolean;
     readonly part?: CardPart;
+    /** The only roles that may be dropped INTO this part (a tab list takes tabs, a panels holder takes panels). */
+    readonly accepts?: ReadonlyArray<string>;
 }
 
 export const COMPOSITE_ROLE_SPECS: Readonly<Record<string, CompositeRoleSpec>> = {
@@ -41,6 +43,14 @@ export const COMPOSITE_ROLE_SPECS: Readonly<Record<string, CompositeRoleSpec>> =
     [DisclosureRole.More]: { parent: DisclosureRole.Trigger },
     [DisclosureRole.Less]: { parent: DisclosureRole.Trigger },
     [DisclosureRole.Icon]: { parent: DisclosureRole.Trigger },
+    // CC4a — a Tabs always keeps its tab list and its panels holder; a tab lives in the list and a panel in the
+    // holder (each may be deleted — with its pair — but never moved out); the list takes only tabs, the holder only
+    // panels, and a panel takes anything.
+    [TabsRole.Tabs]: { parent: null },
+    [TabsRole.List]: { parent: TabsRole.Tabs, locked: true, accepts: [TabsRole.Trigger] },
+    [TabsRole.Panels]: { parent: TabsRole.Tabs, locked: true, accepts: [TabsRole.Panel] },
+    [TabsRole.Trigger]: { parent: TabsRole.List, pinned: true },
+    [TabsRole.Panel]: { parent: TabsRole.Panels, pinned: true },
     // CC3 — a Slider's controls are its own direct children (Swiper is handed them). The pause control stays while
     // Autoplay is on (WCAG 2.2.2): the Autoplay switch removes it, never Delete. The arrows and the dots follow
     // their switches and may be deleted.
@@ -61,6 +71,8 @@ export enum StructureRefusal {
     LockedPart = 'locked-part',
     /** A locked part can only live directly inside its own parent role. */
     LockedPlacement = 'locked-placement',
+    /** The new parent takes only certain roles (a tab list takes only tabs, CC4a). */
+    NotAccepted = 'not-accepted',
 }
 
 interface RoleLike { role?: string | null; type?: string }
@@ -71,9 +83,10 @@ interface RoleLike { role?: string | null; type?: string }
  */
 export function structureRefusal(node: RoleLike | null | undefined, edit: StructureEdit, ancestors: ReadonlyArray<RoleLike> = []): StructureRefusal | null {
     const spec = node?.role ? COMPOSITE_ROLE_SPECS[node.role] : undefined;
+    const parent = ancestors[ancestors.length - 1];
+    if (edit === StructureEdit.Move && acceptsRefusal(node, parent)) return StructureRefusal.NotAccepted;
     if (!spec?.locked && !spec?.pinned) return null;
     if (edit === StructureEdit.Delete) return spec.locked ? StructureRefusal.LockedPart : null;
-    const parent = ancestors[ancestors.length - 1];
     const placed = spec.parentType ? parent?.type === spec.parentType : parent?.role === spec.parent;
     return placed ? null : StructureRefusal.LockedPlacement;
 }
@@ -83,3 +96,10 @@ export function structureRefusal(node: RoleLike | null | undefined, edit: Struct
 export function isLockedPart(node: RoleLike | null | undefined): boolean {
     return !!(node?.role && COMPOSITE_ROLE_SPECS[node.role]?.locked);
 }
+
+/** Why `parent` refuses `node` as a child (it takes only certain roles), or null. */
+export function acceptsRefusal(node: RoleLike | null | undefined, parent: RoleLike | null | undefined): StructureRefusal | null {
+    const accepts = parent?.role ? COMPOSITE_ROLE_SPECS[parent.role]?.accepts : undefined;
+    if (!accepts) return null;
+    return node?.role && accepts.includes(node.role) ? null : StructureRefusal.NotAccepted;
+}