@vectoriox/iox-ui 5.36.0 → 5.38.0

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

@@ -1,21 +1,26 @@
 import {
-    AccordionBehaviour, AccordionClass, AccordionDefaultOn, accordionDomIds, accordionFocusIndex, accordionKeyAction, AccordionRole,
-    ACCORDION_DEFAULT_ONS, COMPOSITE_ATTRIBUTE, DEFAULT_ON_ATTRIBUTE, initialAccordionOpen, ITEM_KEY_ATTRIBUTE, MULTIPLE_ATTRIBUTE,
-    nextAccordionState, ON_ATTRIBUTE, openAccordionItem, UNTIL_FOUND,
+    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]   (the node's own element —
- *           its role class may sit on a wrapper host, as the engine's component-path Repeater draws it)
+ *   [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
@@ -27,9 +32,12 @@ import {
 export const ITEM_ON_EVENT = 'iox-item-on';
 export const ITEM_OFF_EVENT = 'iox-item-off';
 
-const ROOT_SELECTOR = `[${COMPOSITE_ATTRIBUTE}="${AccordionRole.Accordion}"]`;
-const ITEM_SELECTOR = '.iox-role-accordion-item';
-const PANEL_SELECTOR = '.iox-role-accordion-panel';
+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}`;
@@ -38,8 +46,11 @@ const MAX_CLOSE_MS = 600;
 const REDUCED_MOTION = '(prefers-reduced-motion: reduce)';
 
 export interface AccordionRuntimeOptions {
-    /** The root's node id — the ARIA ids' prefix (else read from the root's `iox-node-<id>` class). */
-    rootId?: string;
+    /** 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). */
@@ -50,16 +61,24 @@ export interface AccordionRuntimeOptions {
     reducedMotion?: () => boolean;
 }
 
-/** The accordion an element belongs to (the element itself when it is a root). */
+/** 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). */
+/** 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 {
@@ -103,10 +122,13 @@ export class AccordionRuntime {
     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, AccordionRole.Accordion);
+        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.)
@@ -144,9 +166,10 @@ export class AccordionRuntime {
         else this.stamp();
     }
 
-    /** THIS accordion's items, in document order (a nested accordion's items are its own). */
+    /** THIS composite's items, in document order (a nested composite's items are its own); a disclosure's is itself. */
     items(): HTMLElement[] {
-        return Array.from(this.root.querySelectorAll<HTMLElement>(ITEM_SELECTOR)).filter(i => closestAccordion(i.parentElement) === this.root);
+        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). */
@@ -173,6 +196,19 @@ export class AccordionRuntime {
         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();
@@ -186,6 +222,7 @@ export class AccordionRuntime {
     }
 
     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);
@@ -217,7 +254,8 @@ export class AccordionRuntime {
             first = true;
         }
         const forced = this.options.forced?.() ?? new Set<string>();
-        const rootId = this.options.rootId ?? nodeIdOf(this.root);
+        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);
@@ -238,7 +276,7 @@ export class AccordionRuntime {
     }
 
     private stampItem(item: HTMLElement, key: string, index: number, on: boolean, rootId: string, first: boolean): void {
-        const ids = accordionDomIds(rootId, key);
+        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);
@@ -252,9 +290,10 @@ export class AccordionRuntime {
         setAttr(button, ON_ATTRIBUTE, on ? '' : null);
         setAttr(track, ON_ATTRIBUTE, on ? '' : null);
         setAttr(panel, ON_ATTRIBUTE, on ? '' : null);
-        setAttr(region, 'role', 'region');
+        const labelled = hasLabelledRegion(this.kind);
+        setAttr(region, 'role', labelled ? 'region' : null);
         setAttr(region, 'id', ids.panel);
-        setAttr(region, 'aria-labelledby', ids.trigger);
+        setAttr(region, 'aria-labelledby', labelled ? ids.trigger : null);
         if (!region) return;
         const pending = this.closing.get(key);
         if (on) {
@@ -301,6 +340,8 @@ export class AccordionRuntime {
     };
 
     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);
@@ -316,8 +357,9 @@ export class AccordionRuntime {
     private readonly onBeforeMatch = (event: Event): void => {
         const region = (event.target as Element | null)?.closest?.(REGION_SELECTOR);
         const item = closestAccordionItem(region);
-        if (!item || closestAccordion(item.parentElement) !== this.root) return;
-        this.open(this.keyOf(item));
+        const items = this.items();
+        if (!item || !items.includes(item)) return;
+        this.open(this.keyOf(item, items));
     };
 }
 
@@ -326,13 +368,11 @@ function dispatch(el: Element, type: string): void {
     if (Ctor) el.dispatchEvent(new Ctor(type, { bubbles: false }));
 }
 
-/** Attach the runtime to one rendered accordion root, unless it already runs one. Returns the NEW runtime, or
+/** 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 (ATTACHED.has(root)) return null;
-    const runtime = new AccordionRuntime(root, options);
-    ATTACHED.set(root, runtime);
-    return runtime;
+    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. */
@@ -348,7 +388,56 @@ export function attachAccordions(container: ParentNode, options: Omit<AccordionR
 /** Detach a runtime `attachAccordions` created. */
 export function detachAccordion(runtime: AccordionRuntime): void {
     runtime.destroy();
-    ATTACHED.delete(runtime.root);
 }
 
-const ATTACHED = new WeakMap<Element, AccordionRuntime>();
+/** 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;
+}

package/src/composite-core/accordion.ts

@@ -1,7 +1,10 @@
 import { readOwnedTrait } from '@vectoriox/iox-ui/design-core';
 
 import {
-    CompositeNode, CompositeNodeFactory, findByRole, readProp, removeFromComposite, walkComposite, writeProp, writeStyles,
+    AccordionRole, COMPOSITE_KIND_ROLES, CompositeKind, compositeKindOfRole,
+} from './composite-kinds';
+import {
+    CompositeNode, CompositeNodeFactory, findByRole, makeCompositePart, readProp, removeFromComposite, walkComposite, writeProp, writeStyles,
 } from './composite-node';
 
 /**
@@ -23,14 +26,6 @@ import {
  * functions), the keyboard one key map — read by the builder canvas, both engine paths and the composer.
  */
 
-export enum AccordionRole {
-    Accordion = 'accordion',
-    Item = 'accordion.item',
-    Trigger = 'accordion.trigger',
-    Icon = 'accordion.icon',
-    Panel = 'accordion.panel',
-}
-
 /** The behaviour options a composite root stores as ordinary TRAITS (composite plan §3). */
 export enum CompositeBehaviourTrait {
     /** Several items may be open at once ("Allow several open"). */
@@ -135,17 +130,15 @@ export interface AccordionOptions {
 
 function make(create: CompositeNodeFactory, key: string, type: string, role: AccordionRole | null, style: string,
     props: Record<string, unknown> = {}, label?: string): CompositeNode {
-    const node = create({ key, type, props, elementStyle: style });
-    if (role) node.role = role;
-    if (label) node.label = label;
-    if (role && PART_BASE[role]) writeStyles(node, PART_BASE[role]);
-    return node;
+    return makeCompositePart(create, { key, type, props, elementStyle: style }, role, label, role ? PART_BASE[role] : undefined);
 }
 
-/** The item's icon; its Item-open state (the turn) is driven by ITS item (`stateTriggers`). */
-function buildIcon(create: CompositeNodeFactory, key: string, icon: Exclude<AccordionIcon, AccordionIcon.None>, itemId?: string): CompositeNode {
+/** The icon of an item (an accordion's, or a disclosure's — `role`); its Item-open state (the turn) is driven by
+ *  ITS item (`stateTriggers`). ONE builder for both kinds. */
+export function buildCompositeIcon(create: CompositeNodeFactory, key: string, icon: Exclude<AccordionIcon, AccordionIcon.None>, itemId?: string,
+    role: string = AccordionRole.Icon): CompositeNode {
     const glyph = ACCORDION_ICON_GLYPH[icon];
-    const node = make(create, key, Type.Icon, AccordionRole.Icon, Style.Icon, { iconClass: glyph.iconClass }, 'Icon');
+    const node = makeCompositePart(create, { key, type: Type.Icon, props: { iconClass: glyph.iconClass }, elementStyle: Style.Icon }, role, 'Icon', PART_BASE[AccordionRole.Icon]);
     node.stateStyles = { ...(node.stateStyles ?? {}), [ITEM_OPEN_STATE]: { rotate: glyph.turn } };
     if (itemId) node.stateTriggers = { ...(node.stateTriggers ?? {}), [ITEM_OPEN_STATE]: itemId };
     return node;
@@ -158,7 +151,7 @@ export function buildAccordionItem(create: CompositeNodeFactory, words: Accordio
     const trigger = make(create, `${itemKey}-trigger`, Type.LinkedContainer, AccordionRole.Trigger, Style.Trigger, {}, 'Header');
     const question = make(create, `${itemKey}-question`, Type.Heading, null, Style.Question, { content: words.question, level: DEFAULT_LEVEL }, 'Heading');
     writeStyles(question, QUESTION_BASE);
-    trigger.children = [question, ...(icon === AccordionIcon.None ? [] : [buildIcon(create, `${itemKey}-icon`, icon, item.id)])];
+    trigger.children = [question, ...(icon === AccordionIcon.None ? [] : [buildCompositeIcon(create, `${itemKey}-icon`, icon, item.id)])];
     const panel = make(create, `${itemKey}-panel`, Type.Container, AccordionRole.Panel, Style.Panel, {}, 'Panel');
     const answer = make(create, `${itemKey}-answer`, Type.Text, null, Style.Answer, { content: words.answer, tag: 'p' }, 'Text');
     writeStyles(answer, ANSWER_BASE);
@@ -238,22 +231,37 @@ export function setAccordionBehaviour(root: CompositeNode, patch: Partial<Accord
     return ok;
 }
 
-/** The header of an item. */
+/** The roles of the kind an item belongs to (an accordion item, or a disclosure — its own item). */
+function kindRolesOf(node: CompositeNode) {
+    return COMPOSITE_KIND_ROLES[compositeKindOfRole(node.role) ?? CompositeKind.Accordion];
+}
+
+/** The header of an item (either kind). */
 export function accordionTriggerOf(item: CompositeNode): CompositeNode | undefined {
-    return findByRole(item, AccordionRole.Trigger);
+    return findByRole(item, kindRolesOf(item).trigger);
 }
 
-/** The panel of an item. */
+/** The panel of an item (either kind). */
 export function accordionPanelOf(item: CompositeNode): CompositeNode | undefined {
-    return findByRole(item, AccordionRole.Panel);
+    return findByRole(item, kindRolesOf(item).panel);
+}
+
+/** A root's items — an accordion's (`accordionItems`), or a disclosure, which is its own one item. */
+export function compositeItems(root: CompositeNode): CompositeNode[] {
+    return compositeKindOfRole(root.role) === CompositeKind.Disclosure ? [root] : accordionItems(root);
 }
 
-/** The question: the first Heading inside the header. */
+/** The question: the first Heading inside the header — a disclosure's toggle holds no heading, so its first word
+ *  (the Text shown while closed, "Read more"). */
 export function accordionQuestionOf(item: CompositeNode): CompositeNode | undefined {
     const trigger = accordionTriggerOf(item);
     let hit: CompositeNode | undefined;
-    if (trigger) walkComposite(trigger, n => { if (!hit && n.type === Type.Heading) hit = n; });
-    return hit;
+    let text: CompositeNode | undefined;
+    if (trigger) walkComposite(trigger, n => {
+        if (!hit && n.type === Type.Heading) hit = n;
+        if (!text && n.type === Type.Text) text = n;
+    });
+    return hit ?? text;
 }
 
 /** The answer: the first Text inside the panel. */
@@ -337,10 +345,10 @@ export function accordionRemovalRefusal(root: CompositeNode | null | undefined,
     return accordionItems(root).length <= 1 ? AccordionEditRefusal.LastItem : null;
 }
 
-/** The icon the accordion's items wear now (the first item's; None when it has no icon). */
+/** The icon the composite's items wear now (the first item's; None when it has no icon). Either kind. */
 export function detectAccordionIcon(root: CompositeNode): AccordionIcon {
-    const first = accordionItems(root)[0];
-    const icon = first ? findByRole(first, AccordionRole.Icon) : undefined;
+    const first = compositeItems(root)[0];
+    const icon = first ? findByRole(first, kindRolesOf(root).icon) : undefined;
     if (!icon) return first ? AccordionIcon.None : AccordionIcon.Chevron;
     const cls = String(readProp(icon, 'iconClass') ?? '');
     return cls.includes(ACCORDION_ICON_GLYPH[AccordionIcon.Plus].iconClass.split(' ')[1]) ? AccordionIcon.Plus : AccordionIcon.Chevron;
@@ -353,10 +361,11 @@ export function detectAccordionIcon(root: CompositeNode): AccordionIcon {
  */
 export function setAccordionIcon(root: CompositeNode, icon: AccordionIcon, create?: CompositeNodeFactory): number {
     let changed = 0;
-    for (const item of accordionItems(root)) {
+    const iconRole = kindRolesOf(root).icon;
+    for (const item of compositeItems(root)) {
         const trigger = accordionTriggerOf(item);
         if (!trigger) continue;
-        const existing = findByRole(trigger, AccordionRole.Icon);
+        const existing = findByRole(trigger, iconRole);
         if (icon === AccordionIcon.None) {
             if (existing && removeFromComposite(trigger, existing)) changed++;
             continue;
@@ -367,7 +376,7 @@ export function setAccordionIcon(root: CompositeNode, icon: AccordionIcon, creat
             existing.stateStyles = { ...(existing.stateStyles ?? {}), [ITEM_OPEN_STATE]: { ...(existing.stateStyles?.[ITEM_OPEN_STATE] ?? {}), rotate: glyph.turn } };
             changed++;
         } else if (create) {
-            trigger.children = [...(trigger.children ?? []), buildIcon(create, `${item.itemKey ?? 'item'}-icon`, icon, item.id)];
+            trigger.children = [...(trigger.children ?? []), buildCompositeIcon(create, `${item.itemKey ?? 'item'}-icon`, icon, item.id, iconRole)];
             changed++;
         }
     }
@@ -404,11 +413,18 @@ export function nextAccordionState(open: ReadonlySet<string>, key: string, behav
     return behaviour.multiple ? new Set([...open, key]) : new Set([key]);
 }
 
-/** The open keys after OPENING `key` (find-in-page, selecting into a closed panel). */
+/** The open keys after OPENING `key` (find-in-page, selecting into a closed panel, the `openItem` action). */
 export function openAccordionItem(open: ReadonlySet<string>, key: string, behaviour: Pick<AccordionBehaviour, 'multiple'>): Set<string> {
     return open.has(key) ? new Set(open) : nextAccordionState(open, key, behaviour);
 }
 
+/** The open keys after CLOSING `key` (the `closeItem` action). */
+export function closeAccordionItem(open: ReadonlySet<string>, key: string): Set<string> {
+    const next = new Set(open);
+    next.delete(key);
+    return next;
+}
+
 export enum AccordionKeyAction {
     Next = 'next',
     Previous = 'previous',
@@ -460,35 +476,52 @@ export interface AccordionDomIds {
     panel: string;
 }
 
-/** The ARIA pairing ids of an item: unique per accordion (its root's node id) and per item (its key). */
-export function accordionDomIds(rootId: string, itemKey: string): AccordionDomIds {
-    const base = `iox-acc-${domSafeKey(rootId)}-${domSafeKey(itemKey)}`;
+const DOM_ID_PREFIX: Readonly<Record<CompositeKind, string>> = {
+    [CompositeKind.Accordion]: 'iox-acc',
+    [CompositeKind.Disclosure]: 'iox-dis',
+};
+
+/** The ARIA pairing ids of an item: unique per composite (its SCOPE id — `compositeScopeId`) and per item (its key). */
+export function accordionDomIds(rootId: string, itemKey: string, kind: CompositeKind = CompositeKind.Accordion): AccordionDomIds {
+    const base = `${DOM_ID_PREFIX[kind]}-${domSafeKey(rootId)}-${domSafeKey(itemKey)}`;
     return { trigger: `${base}-h`, panel: `${base}-p` };
 }
 
+/**
+ * The id a rendered composite's ARIA ids are built from: its node id, and — when it sits inside repeated rows —
+ * every enclosing row's identity, outermost first (vectoriox/iox-ui#20: an accordion repeated per card used to
+ * pair every row's header with the FIRST row's panel). The engine folds each row's `rowItemKey`; the builder
+ * canvas its preview row's index. Unrepeated, it is the node id unchanged.
+ */
+export function compositeScopeId(rootId: string, rowKeys: ReadonlyArray<string> = []): string {
+    return rowKeys.length ? [rootId, ...rowKeys.map(domSafeKey)].join('-') : rootId;
+}
+
 /** One item's render state: its identity, whether it is open, and its ARIA ids. */
 export interface AccordionItemState {
+    kind: CompositeKind;
     key: string;
     index: number;
     on: boolean;
     ids: AccordionDomIds;
 }
 
-/** The render scope of one accordion: its root id, behaviour and every item key in order. */
+/** The render scope of one composite: its kind, scope id, behaviour and every item key in order. */
 export interface AccordionScope {
+    kind: CompositeKind;
     rootId: string;
     behaviour: AccordionBehaviour;
     keys: ReadonlyArray<string>;
     open: ReadonlySet<string>;
 }
 
-export function accordionScope(rootId: string, behaviour: AccordionBehaviour, keys: ReadonlyArray<string>): AccordionScope {
-    return { rootId, behaviour, keys, open: initialAccordionOpen(keys, behaviour.defaultOn) };
+export function accordionScope(rootId: string, behaviour: AccordionBehaviour, keys: ReadonlyArray<string>, kind: CompositeKind = CompositeKind.Accordion): AccordionScope {
+    return { kind, rootId, behaviour, keys, open: initialAccordionOpen(keys, behaviour.defaultOn) };
 }
 
 export function accordionItemState(scope: AccordionScope, index: number): AccordionItemState {
     const key = scope.keys[index] ?? `item-${index}`;
-    return { key, index, on: scope.open.has(key), ids: accordionDomIds(scope.rootId, key) };
+    return { kind: scope.kind, key, index, on: scope.open.has(key), ids: accordionDomIds(scope.rootId, key, scope.kind) };
 }
 
 /** Attribute values: a string, or '' for a present boolean attribute. Absent attributes are left out. */
@@ -500,6 +533,9 @@ export const ITEM_KEY_ATTRIBUTE = 'data-iox-item-key';
 export const COMPOSITE_ATTRIBUTE = 'data-iox-composite';
 export const MULTIPLE_ATTRIBUTE = 'data-iox-multiple';
 export const DEFAULT_ON_ATTRIBUTE = 'data-iox-default-on';
+/** The scope id the ARIA ids are built from (`compositeScopeId`), written by the engine so the runtime re-stamps
+ *  exactly the ids the server rendered. */
+export const SCOPE_ATTRIBUTE = 'data-iox-scope';
 /** The value a closed panel's region carries: find-in-page can still reveal it (D9, board 4). */
 export const UNTIL_FOUND = 'until-found';
 
@@ -511,11 +547,12 @@ export enum AccordionClass {
     Region = 'iox-accordion-region',
 }
 
-export function accordionRootAttributes(behaviour: AccordionBehaviour): DomAttributes {
+export function accordionRootAttributes(behaviour: AccordionBehaviour, kind: CompositeKind = CompositeKind.Accordion, scopeId?: string): DomAttributes {
     return {
-        [COMPOSITE_ATTRIBUTE]: AccordionRole.Accordion,
+        [COMPOSITE_ATTRIBUTE]: kind,
         [DEFAULT_ON_ATTRIBUTE]: behaviour.defaultOn,
-        ...(behaviour.multiple ? { [MULTIPLE_ATTRIBUTE]: '' } : {}),
+        ...(behaviour.multiple && kind === CompositeKind.Accordion ? { [MULTIPLE_ATTRIBUTE]: '' } : {}),
+        ...(scopeId ? { [SCOPE_ATTRIBUTE]: scopeId } : {}),
     };
 }
 
@@ -538,16 +575,23 @@ export function accordionTrackAttributes(state: AccordionItemState): DomAttribut
     return state.on ? { [ON_ATTRIBUTE]: '' } : {};
 }
 
-/** The region the panel sits in: `hidden="until-found"` while closed, so its words stay in the page. */
+/** The region the panel sits in: `hidden="until-found"` while closed, so its words stay in the page. An accordion's
+ *  is a labelled `region` (APG accordion); a disclosure's is a plain block (APG disclosure: the button names it). */
 export function accordionRegionAttributes(state: AccordionItemState): DomAttributes {
+    const labelled = hasLabelledRegion(state.kind);
     return {
-        role: 'region',
+        ...(labelled ? { role: 'region' } : {}),
         id: state.ids.panel,
-        'aria-labelledby': state.ids.trigger,
+        ...(labelled ? { 'aria-labelledby': state.ids.trigger } : {}),
         ...(state.on ? {} : { hidden: UNTIL_FOUND }),
     };
 }
 
+/** True when a region of this kind is a labelled `role=region`. */
+export function hasLabelledRegion(kind: CompositeKind): boolean {
+    return kind === CompositeKind.Accordion;
+}
+
 export function accordionPanelAttributes(state: AccordionItemState): DomAttributes {
     return state.on ? { [ON_ATTRIBUTE]: '' } : {};
 }

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

@@ -0,0 +1,110 @@
+/**
+ * The open/close composites' kinds and roles (CC2 Accordion, CC2.1 Disclosure — composite plan T9 / T21). ONE
+ * family: a Disclosure is a one-item accordion whose ROOT is its item, so both run the same state machine, the
+ * same attribute planners and the same runtime (`accordion-runtime.ts`). Every consumer that treats "an item",
+ * "a header" or "a panel" alike asks these predicates, never a role literal.
+ */
+
+export enum CompositeKind {
+    Accordion = 'accordion',
+    Disclosure = 'disclosure',
+}
+
+export enum AccordionRole {
+    Accordion = 'accordion',
+    Item = 'accordion.item',
+    Trigger = 'accordion.trigger',
+    Icon = 'accordion.icon',
+    Panel = 'accordion.panel',
+}
+
+/**
+ * DISCLOSURE ("Read more") — one trigger, one panel. The root IS its item (it carries the item key and
+ * `data-iox-on`); the trigger holds two words, the one shown while closed (`more`) and the one shown while open
+ * (`less`), swapped by the Item open state — never by script.
+ */
+export enum DisclosureRole {
+    Disclosure = 'disclosure',
+    Trigger = 'disclosure.trigger',
+    More = 'disclosure.more',
+    Less = 'disclosure.less',
+    Icon = 'disclosure.icon',
+    Panel = 'disclosure.panel',
+}
+
+interface RoleLike { role?: string | null }
+
+/** The roles each kind plays in the shared runtime. */
+export interface CompositeKindRoles {
+    root: string;
+    item: string;
+    trigger: string;
+    panel: string;
+    icon: string;
+}
+
+export const COMPOSITE_KIND_ROLES: Readonly<Record<CompositeKind, CompositeKindRoles>> = {
+    [CompositeKind.Accordion]: { root: AccordionRole.Accordion, item: AccordionRole.Item, trigger: AccordionRole.Trigger, panel: AccordionRole.Panel, icon: AccordionRole.Icon },
+    [CompositeKind.Disclosure]: { root: DisclosureRole.Disclosure, item: DisclosureRole.Disclosure, trigger: DisclosureRole.Trigger, panel: DisclosureRole.Panel, icon: DisclosureRole.Icon },
+};
+
+const KINDS = Object.values(CompositeKind);
+const rolesOf = (pick: keyof CompositeKindRoles): ReadonlySet<string> => new Set(KINDS.map(k => COMPOSITE_KIND_ROLES[k][pick]));
+const ROOT_ROLES = rolesOf('root');
+const ITEM_ROLES = rolesOf('item');
+const TRIGGER_ROLES = rolesOf('trigger');
+const PANEL_ROLES = rolesOf('panel');
+
+/** The kind a role belongs to (`disclosure.panel` → Disclosure), or null for any other role. */
+export function compositeKindOfRole(role: string | null | undefined): CompositeKind | null {
+    const head = role?.split('.')[0];
+    return (KINDS as string[]).includes(head ?? '') ? head as CompositeKind : null;
+}
+
+/** A root that runs the open/close runtime (an Accordion or a Disclosure). */
+export function isCompositeRoot(node: RoleLike | null | undefined): boolean {
+    return !!node?.role && ROOT_ROLES.has(node.role);
+}
+
+/** An ITEM — an accordion's item, or a disclosure (its own item). */
+export function isCompositeItem(node: RoleLike | null | undefined): boolean {
+    return !!node?.role && ITEM_ROLES.has(node.role);
+}
+
+/** A trigger — rendered as a `<button>` that opens its item, never a link. */
+export function isCompositeTrigger(node: RoleLike | null | undefined): boolean {
+    return !!node?.role && TRIGGER_ROLES.has(node.role);
+}
+
+/** A panel — rendered inside the track + region the one hiding rule collapses. */
+export function isCompositePanel(node: RoleLike | null | undefined): boolean {
+    return !!node?.role && PANEL_ROLES.has(node.role);
+}
+
+export function isDisclosureRoot(node: RoleLike | null | undefined): boolean {
+    return node?.role === DisclosureRole.Disclosure;
+}
+
+/** True for any part of a disclosure (its root included). */
+export function isDisclosurePart(node: RoleLike | null | undefined): boolean {
+    return compositeKindOfRole(node?.role) === CompositeKind.Disclosure;
+}
+
+/** The composite root a node belongs to: the nearest ancestor (or the node itself) that is one. `path` = the
+ *  node's ancestors, root first. */
+export function compositeRootOf<T extends RoleLike>(node: T, path: ReadonlyArray<T>): T | null {
+    if (isCompositeRoot(node)) return node;
+    for (let i = path.length - 1; i >= 0; i--) if (isCompositeRoot(path[i])) return path[i];
+    return null;
+}
+
+/** The item a node sits in — the nearest item of either kind (itself when it is one) — or null. An accordion
+ *  root ends the walk (its items are below it). */
+export function compositeItemOf<T extends RoleLike>(node: T, path: ReadonlyArray<T>): T | null {
+    if (isCompositeItem(node)) return node;
+    for (let i = path.length - 1; i >= 0; i--) {
+        if (isCompositeItem(path[i])) return path[i];
+        if (isCompositeRoot(path[i])) return null;
+    }
+    return null;
+}