@vectoriox/iox-ui 5.35.0 → 5.37.0

package/src/composite-core/accordion.ts

@@ -0,0 +1,694 @@
+import { readOwnedTrait } from '@vectoriox/iox-ui/design-core';
+
+import {
+    AccordionRole, COMPOSITE_KIND_ROLES, CompositeKind, compositeKindOfRole,
+} from './composite-kinds';
+import {
+    CompositeNode, CompositeNodeFactory, findByRole, makeCompositePart, readProp, removeFromComposite, walkComposite, writeProp, writeStyles,
+} from './composite-node';
+
+/**
+ * ACCORDION (CC2 — composite K1; complex-components boards 3, 4 and 9, APPROVED 2026-10-20). Not a
+ * component: a recipe of ordinary nodes, each part carrying a role, so every part is selectable on the
+ * canvas, in the layer tree and the breadcrumb, and wears its own element style (R2).
+ *
+ *   Container `box`                      role accordion      traits multiple · defaultOn   (Manual)
+ *     — or a Repeater bound to a list    role accordion      ONE template item             (From content, R3)
+ *   └─ Container `accordion-item`        role accordion.item      itemKey k1 … (Manual) · the row's id (From content)
+ *       ├─ LinkedContainer `accordion-trigger`  role accordion.trigger   → <hN><button> (the question's level)
+ *       │   ├─ Heading `h3`               the question (rendered as phrasing inside the button)
+ *       │   └─ Icon `icon`                role accordion.icon      Item open → rotate
+ *       └─ Container `accordion-panel`    role accordion.panel     inside a hidden="until-found" region
+ *           └─ Text `body`                the answer
+ *
+ * The behaviour is BUILT IN (composite plan D1 = B): which items are open is one state machine
+ * (`nextAccordionState`), the ARIA and DOM state one planner (`accordionItemState` and the attribute
+ * functions), the keyboard one key map — read by the builder canvas, both engine paths and the composer.
+ */
+
+/** 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"). */
+    Multiple = 'multiple',
+    /** Which items open by default: first · none · all. */
+    DefaultOn = 'defaultOn',
+}
+
+export enum AccordionDefaultOn {
+    First = 'first',
+    None = 'none',
+    All = 'all',
+}
+
+export const ACCORDION_DEFAULT_ONS: ReadonlyArray<AccordionDefaultOn> = [AccordionDefaultOn.First, AccordionDefaultOn.None, AccordionDefaultOn.All];
+
+/** Behaviour ▸ Icon — a preset over the items' icons, never a stored trait (detected from the icons). */
+export enum AccordionIcon {
+    Chevron = 'chevron',
+    Plus = 'plus',
+    None = 'none',
+}
+
+export const ACCORDION_ICONS: ReadonlyArray<AccordionIcon> = [AccordionIcon.Chevron, AccordionIcon.Plus, AccordionIcon.None];
+
+/** Each icon's glyph and how far it turns when its item opens (board 4: a chevron flips, a plus becomes ×). */
+export const ACCORDION_ICON_GLYPH: Readonly<Record<Exclude<AccordionIcon, AccordionIcon.None>, { iconClass: string; turn: string }>> = {
+    [AccordionIcon.Chevron]: { iconClass: 'ph ph-caret-down', turn: '180deg' },
+    [AccordionIcon.Plus]: { iconClass: 'ph ph-plus', turn: '45deg' },
+};
+
+/** The item-open style state (a part INSIDE an item, styled by its item being open — board 9 "Item open"). */
+export const ITEM_OPEN_STATE = 'trigger-on';
+/** A part that IS on (an item, its header, its panel — board 9 "Open"). */
+export const ON_STATE = 'on';
+
+/** Items from content default to twenty rows (board 9 Q13). */
+export const ACCORDION_CONTENT_LIMIT = 20;
+
+export interface AccordionWords {
+    question: string;
+    answer: string;
+}
+
+/** The words a fresh accordion starts with — generic, the author's to replace (as Card v2's are). */
+export const ACCORDION_WORDS: ReadonlyArray<AccordionWords> = [
+    { question: 'Write the first question people ask', answer: 'Answer it plainly, in two or three short sentences.' },
+    { question: 'Write the second question', answer: 'Answer it plainly, in two or three short sentences.' },
+    { question: 'Write the third question', answer: 'Answer it plainly, in two or three short sentences.' },
+];
+export const ACCORDION_NEW_ITEM_WORDS: Readonly<AccordionWords> = { question: 'Write a new question', answer: 'Answer it plainly, in two or three short sentences.' };
+
+enum Type {
+    Container = 'Container',
+    LinkedContainer = 'LinkedContainer',
+    Heading = 'Heading',
+    Text = 'Text',
+    Icon = 'Icon',
+    Repeater = 'Repeater',
+}
+
+enum Style {
+    Root = 'box',
+    Item = 'accordion-item',
+    Trigger = 'accordion-trigger',
+    Question = 'h3',
+    Icon = 'icon',
+    Panel = 'accordion-panel',
+    Answer = 'body',
+}
+
+const ZERO_BOX = '0px 0px 0px 0px';
+const HEADING_LEVELS = ['h2', 'h3', 'h4', 'h5', 'h6'];
+const DEFAULT_LEVEL = 'h3';
+/** A linked trait the header must never carry: it is a button, not a link. */
+const LINK_TYPE = 'linkType';
+
+/** What each part holds in the recipe — layout only; its LOOK is its element style. */
+const PART_BASE: Readonly<Record<string, Readonly<Record<string, string>>>> = {
+    // The items are a column a token apart (`accordion-gap`: 0 for a divider list, 12px for cards).
+    [AccordionRole.Accordion]: { display: 'flex', flexDirection: 'column', gap: 'var(--iox-accordion-gap)', width: '100%', minHeight: 'auto', height: 'auto' },
+    [AccordionRole.Item]: { display: 'block', width: '100%', minHeight: 'auto', height: 'auto' },
+    // The header is the whole row: the question takes the line, the icon sits at its end (board 4).
+    [AccordionRole.Trigger]: { display: 'flex', alignItems: 'center', justifyContent: 'space-between', gap: '16px', width: '100%', minHeight: 'auto', height: 'auto', textAlign: 'start', cursor: 'pointer' },
+    [AccordionRole.Icon]: { flexShrink: '0', fontSize: '22px', transitionDuration: 'var(--iox-dur-base)', transitionTimingFunction: 'var(--iox-ease-standard)' },
+    [AccordionRole.Panel]: { display: 'block', width: '100%', minHeight: 'auto', height: 'auto' },
+};
+/** The question INHERITS the header's ink (board 4's wears table: the Question reads no colour token), so the
+ *  header's hover ink reaches the words; and it sits in the row with no margin of its own. */
+const QUESTION_BASE: Readonly<Record<string, string>> = { color: 'inherit', margin: ZERO_BOX, flexGrow: '1', minWidth: '0px' };
+const ANSWER_BASE: Readonly<Record<string, string>> = { margin: ZERO_BOX, padding: ZERO_BOX, minHeight: 'auto' };
+
+// ── recipe ──────────────────────────────────────────────────────────────────────────────────────
+
+export interface AccordionOptions {
+    /** The items' words (three generic items by default). */
+    items?: ReadonlyArray<AccordionWords>;
+    multiple?: boolean;
+    defaultOn?: AccordionDefaultOn;
+    icon?: AccordionIcon;
+}
+
+function make(create: CompositeNodeFactory, key: string, type: string, role: AccordionRole | null, style: string,
+    props: Record<string, unknown> = {}, label?: string): CompositeNode {
+    return makeCompositePart(create, { key, type, props, elementStyle: style }, role, label, role ? PART_BASE[role] : undefined);
+}
+
+/** 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 = 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;
+}
+
+/** One item: header (question + icon) and panel (answer). `key` makes every part's recipe key unique. */
+export function buildAccordionItem(create: CompositeNodeFactory, words: AccordionWords, itemKey: string, icon: AccordionIcon = AccordionIcon.Chevron): CompositeNode {
+    const item = make(create, `${itemKey}`, Type.Container, AccordionRole.Item, Style.Item, {}, 'Item');
+    item.itemKey = itemKey;
+    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 ? [] : [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);
+    panel.children = [answer];
+    item.children = [trigger, panel];
+    return item;
+}
+
+/** A fresh Accordion: three items, one open at a time, the first open by default (board 4). */
+export function buildAccordionRecipe(create: CompositeNodeFactory, options: AccordionOptions = {}): CompositeNode {
+    const root = make(create, 'accordion', Type.Container, AccordionRole.Accordion, Style.Root, {}, 'Accordion');
+    writeProp(root, CompositeBehaviourTrait.Multiple, options.multiple ?? false);
+    writeProp(root, CompositeBehaviourTrait.DefaultOn, options.defaultOn ?? AccordionDefaultOn.First);
+    const words = options.items ?? ACCORDION_WORDS;
+    root.children = words.map((w, i) => buildAccordionItem(create, w, `k${i + 1}`, options.icon ?? AccordionIcon.Chevron));
+    return root;
+}
+
+// ── reading a tree ──────────────────────────────────────────────────────────────────────────────
+
+export function isAccordionRoot(node: { role?: string | null } | null | undefined): boolean {
+    return node?.role === AccordionRole.Accordion;
+}
+
+/** True for any part of an accordion (its root included). */
+export function isAccordionPart(node: { role?: string | null } | null | undefined): boolean {
+    return !!node?.role && (node.role === AccordionRole.Accordion || node.role.startsWith(`${AccordionRole.Accordion}.`));
+}
+
+/** The accordion a node belongs to: the nearest ancestor (or the node itself) playing `accordion`.
+ *  `path` = the node's ancestors, root first. */
+export function accordionRootOf<T extends { role?: string | null }>(node: T, path: ReadonlyArray<T>): T | null {
+    if (isAccordionRoot(node)) return node;
+    for (let i = path.length - 1; i >= 0; i--) if (isAccordionRoot(path[i])) return path[i];
+    return null;
+}
+
+/** The item a node sits in (the node itself when it is one), or null. */
+export function accordionItemOf<T extends { role?: string | null }>(node: T, path: ReadonlyArray<T>): T | null {
+    if (node.role === AccordionRole.Item) return node;
+    for (let i = path.length - 1; i >= 0; i--) {
+        if (path[i].role === AccordionRole.Item) return path[i];
+        if (isAccordionRoot(path[i])) return null;
+    }
+    return null;
+}
+
+/** True when the root takes its items from content (a Repeater bound to a list, R3). */
+export function isAccordionFromContent(root: CompositeNode | null | undefined): boolean {
+    return !!root && root.type === Type.Repeater;
+}
+
+/** The root's items in order — every item (Manual), or the one template item (From content). */
+export function accordionItems(root: CompositeNode): CompositeNode[] {
+    return (root.children ?? []).filter(c => c.role === AccordionRole.Item);
+}
+
+export interface AccordionBehaviour {
+    multiple: boolean;
+    defaultOn: AccordionDefaultOn;
+}
+
+const asBool = (v: unknown) => v === true || v === 'true';
+
+/** The root's behaviour (an unset trait reads its default: one at a time, the first open). */
+export function accordionBehaviour(root: CompositeNode | null | undefined): AccordionBehaviour {
+    const raw = root ? readProp(root, CompositeBehaviourTrait.DefaultOn) : undefined;
+    const defaultOn = ACCORDION_DEFAULT_ONS.includes(raw as AccordionDefaultOn) ? raw as AccordionDefaultOn : AccordionDefaultOn.First;
+    return { multiple: root ? asBool(readProp(root, CompositeBehaviourTrait.Multiple)) : false, defaultOn };
+}
+
+/** Behaviour ▸ Allow several open / Open by default. False when the node has no such trait. */
+export function setAccordionBehaviour(root: CompositeNode, patch: Partial<AccordionBehaviour>): boolean {
+    let ok = true;
+    if (patch.multiple !== undefined) ok = writeProp(root, CompositeBehaviourTrait.Multiple, patch.multiple) && ok;
+    if (patch.defaultOn !== undefined) ok = writeProp(root, CompositeBehaviourTrait.DefaultOn, patch.defaultOn) && ok;
+    return ok;
+}
+
+/** 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, kindRolesOf(item).trigger);
+}
+
+/** The panel of an item (either kind). */
+export function accordionPanelOf(item: CompositeNode): CompositeNode | undefined {
+    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 — 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;
+    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. */
+export function accordionAnswerOf(item: CompositeNode): CompositeNode | undefined {
+    const panel = accordionPanelOf(item);
+    let hit: CompositeNode | undefined;
+    if (panel) walkComposite(panel, n => { if (!hit && n.type === Type.Text) hit = n; });
+    return hit;
+}
+
+const stripTags = (v: unknown) => String(v ?? '').replace(/<[^>]*>/g, '').trim();
+
+/** An item's name in the Items list and the layer tree: its question's words. */
+export function accordionItemLabel(item: CompositeNode): string {
+    const q = accordionQuestionOf(item);
+    return q ? stripTags(readProp(q, 'content')) : '';
+}
+
+/** Items ▸ rename: the question's words. */
+export function renameAccordionItem(item: CompositeNode, question: string): boolean {
+    const q = accordionQuestionOf(item);
+    return !!q && writeProp(q, 'content', question);
+}
+
+/** The heading level the header's wrapper renders (`<h3><button>`): its question's level. */
+export function accordionHeadingLevel(trigger: { children?: ReadonlyArray<CompositeNode> | null } | null | undefined): string {
+    let level: unknown;
+    const visit = (n: CompositeNode) => {
+        if (level !== undefined) return;
+        if (n.type === Type.Heading) { level = readProp(n, 'level'); return; }
+        for (const c of n.children ?? []) visit(c);
+    };
+    for (const c of trigger?.children ?? []) visit(c);
+    return HEADING_LEVELS.includes(level as string) ? level as string : DEFAULT_LEVEL;
+}
+
+// ── editing (Items list, selection toolbar, Behaviour ▸ Icon) ──────────────────────────────────
+
+/** A key no item of `root` holds yet (`k4`…). */
+export function nextItemKey(root: CompositeNode): string {
+    const taken = new Set(accordionItems(root).map(i => i.itemKey).filter(Boolean));
+    let n = taken.size + 1;
+    while (taken.has(`k${n}`)) n++;
+    return `k${n}`;
+}
+
+/** Items ▸ Add item (and the toolbar's "Add item"): a fresh item after `after` (or at the end), wearing the
+ *  accordion's current icon. Returns the new item. */
+export function addAccordionItem(root: CompositeNode, create: CompositeNodeFactory, after?: CompositeNode | null, words: AccordionWords = ACCORDION_NEW_ITEM_WORDS): CompositeNode {
+    const key = nextItemKey(root);
+    const item = buildAccordionItem(create, words, key, detectAccordionIcon(root));
+    const children = [...(root.children ?? [])];
+    const at = after ? children.indexOf(after) : -1;
+    children.splice(at < 0 ? children.length : at + 1, 0, item);
+    root.children = children;
+    return item;
+}
+
+/** Items ▸ drag to reorder: move an item to `toIndex` among the items. False when it is not an item of `root`. */
+export function moveAccordionItem(root: CompositeNode, item: CompositeNode, toIndex: number): boolean {
+    const children = [...(root.children ?? [])];
+    const from = children.indexOf(item);
+    if (from < 0 || item.role !== AccordionRole.Item) return false;
+    children.splice(from, 1);
+    const items = children.filter(c => c.role === AccordionRole.Item);
+    const anchor = items[Math.max(0, Math.min(toIndex, items.length))];
+    const at = anchor ? children.indexOf(anchor) : children.length;
+    children.splice(at, 0, item);
+    root.children = children;
+    return true;
+}
+
+export enum AccordionEditRefusal {
+    /** An accordion keeps at least one item (composite plan T11). */
+    LastItem = 'last-item',
+}
+
+/** Why removing `item` from `root` is refused, or null. */
+export function accordionRemovalRefusal(root: CompositeNode | null | undefined, item: CompositeNode | null | undefined): AccordionEditRefusal | null {
+    if (!root || item?.role !== AccordionRole.Item) return null;
+    return accordionItems(root).length <= 1 ? AccordionEditRefusal.LastItem : null;
+}
+
+/** 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 = 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;
+}
+
+/**
+ * Behaviour ▸ Icon: every item's header shows the chevron, the plus, or no icon. A switch between glyphs
+ * keeps the icon NODE (its styles and interactions) and changes its glyph and turn; None removes it, and a
+ * glyph after None stamps it back from the recipe. Returns how many items changed.
+ */
+export function setAccordionIcon(root: CompositeNode, icon: AccordionIcon, create?: CompositeNodeFactory): number {
+    let changed = 0;
+    const iconRole = kindRolesOf(root).icon;
+    for (const item of compositeItems(root)) {
+        const trigger = accordionTriggerOf(item);
+        if (!trigger) continue;
+        const existing = findByRole(trigger, iconRole);
+        if (icon === AccordionIcon.None) {
+            if (existing && removeFromComposite(trigger, existing)) changed++;
+            continue;
+        }
+        const glyph = ACCORDION_ICON_GLYPH[icon];
+        if (existing) {
+            writeProp(existing, 'iconClass', glyph.iconClass);
+            existing.stateStyles = { ...(existing.stateStyles ?? {}), [ITEM_OPEN_STATE]: { ...(existing.stateStyles?.[ITEM_OPEN_STATE] ?? {}), rotate: glyph.turn } };
+            changed++;
+        } else if (create) {
+            trigger.children = [...(trigger.children ?? []), buildCompositeIcon(create, `${item.itemKey ?? 'item'}-icon`, icon, item.id, iconRole)];
+            changed++;
+        }
+    }
+    return changed;
+}
+
+/** The node id every `trigger-on` state inside an item points at: its ITEM (`stateTriggers['trigger-on']`). */
+export function itemOpenTriggerIds(root: CompositeNode): void {
+    for (const item of accordionItems(root)) {
+        if (!item.id) continue;
+        walkComposite(item, n => {
+            if (n === item || !n.stateStyles?.[ITEM_OPEN_STATE]) return;
+            n.stateTriggers = { ...(n.stateTriggers ?? {}), [ITEM_OPEN_STATE]: item.id! };
+        });
+    }
+}
+
+// ── state machine ───────────────────────────────────────────────────────────────────────────────
+
+/** The keys open on first render: the first item, none, or all (From content: resolved against the rows). */
+export function initialAccordionOpen(keys: ReadonlyArray<string>, defaultOn: AccordionDefaultOn): Set<string> {
+    if (defaultOn === AccordionDefaultOn.None || !keys.length) return new Set();
+    if (defaultOn === AccordionDefaultOn.All) return new Set(keys);
+    return new Set([keys[0]]);
+}
+
+/** The open keys after toggling `key`: one at a time closes the others; several leaves them. */
+export function nextAccordionState(open: ReadonlySet<string>, key: string, behaviour: Pick<AccordionBehaviour, 'multiple'>): Set<string> {
+    if (open.has(key)) {
+        const next = new Set(open);
+        next.delete(key);
+        return next;
+    }
+    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 `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',
+    First = 'first',
+    Last = 'last',
+}
+
+/** The APG accordion's keys on a header: ↓ ↑ move (and wrap), Home / End jump. Enter and Space are the
+ *  button's own. */
+const KEY_ACTIONS: Readonly<Record<string, AccordionKeyAction>> = {
+    ArrowDown: AccordionKeyAction.Next,
+    ArrowUp: AccordionKeyAction.Previous,
+    Home: AccordionKeyAction.First,
+    End: AccordionKeyAction.Last,
+};
+
+export function accordionKeyAction(key: string): AccordionKeyAction | null {
+    return KEY_ACTIONS[key] ?? null;
+}
+
+/** The header index `action` moves focus to, from `current` among `count` headers (↓ ↑ wrap). */
+export function accordionFocusIndex(action: AccordionKeyAction, current: number, count: number): number {
+    if (count <= 0) return -1;
+    switch (action) {
+        case AccordionKeyAction.Next: return (current + 1) % count;
+        case AccordionKeyAction.Previous: return (current - 1 + count) % count;
+        case AccordionKeyAction.First: return 0;
+        case AccordionKeyAction.Last: return count - 1;
+    }
+}
+
+// ── identity, ids and attributes (both renderers, SSR included) ────────────────────────────────
+
+/** A key safe in an element id. */
+export function domSafeKey(raw: unknown): string {
+    return String(raw ?? '').replace(/[^A-Za-z0-9_-]/g, '-');
+}
+
+/** A content row's identity: its own id (never its index — a reorder in the CMS must never pair a header with
+ *  another row's panel, R3); the index only for a row that has none. */
+export function rowItemKey(row: unknown, index: number): string {
+    const r = row as { _id?: unknown; id?: unknown } | null;
+    const id = r && typeof r === 'object' ? (r._id ?? r.id) : undefined;
+    return id !== undefined && id !== null && id !== '' ? domSafeKey(id) : `row-${index}`;
+}
+
+export interface AccordionDomIds {
+    trigger: string;
+    panel: string;
+}
+
+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 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>, 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 { 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. */
+export type DomAttributes = Record<string, string>;
+
+/** `data-iox-on` — the ONE attribute every "on" style keys on (Open, Item open). */
+export const ON_ATTRIBUTE = 'data-iox-on';
+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';
+
+/** The structural classes the renderers write around an accordion's parts (no node owns them). */
+export enum AccordionClass {
+    Heading = 'iox-accordion-heading',
+    Button = 'iox-accordion-button',
+    Track = 'iox-accordion-track',
+    Region = 'iox-accordion-region',
+}
+
+export function accordionRootAttributes(behaviour: AccordionBehaviour, kind: CompositeKind = CompositeKind.Accordion, scopeId?: string): DomAttributes {
+    return {
+        [COMPOSITE_ATTRIBUTE]: kind,
+        [DEFAULT_ON_ATTRIBUTE]: behaviour.defaultOn,
+        ...(behaviour.multiple && kind === CompositeKind.Accordion ? { [MULTIPLE_ATTRIBUTE]: '' } : {}),
+        ...(scopeId ? { [SCOPE_ATTRIBUTE]: scopeId } : {}),
+    };
+}
+
+export function accordionItemAttributes(state: AccordionItemState): DomAttributes {
+    return { [ITEM_KEY_ATTRIBUTE]: state.key, ...(state.on ? { [ON_ATTRIBUTE]: '' } : {}) };
+}
+
+export function accordionTriggerAttributes(state: AccordionItemState): DomAttributes {
+    return {
+        type: 'button',
+        id: state.ids.trigger,
+        'aria-expanded': state.on ? 'true' : 'false',
+        'aria-controls': state.ids.panel,
+        ...(state.on ? { [ON_ATTRIBUTE]: '' } : {}),
+    };
+}
+
+/** The track wrapping a panel: its row collapses to 0 while closed (the ONE hiding rule, iox-design.css). */
+export function accordionTrackAttributes(state: AccordionItemState): DomAttributes {
+    return state.on ? { [ON_ATTRIBUTE]: '' } : {};
+}
+
+/** 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 {
+        ...(labelled ? { role: 'region' } : {}),
+        id: state.ids.panel,
+        ...(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]: '' } : {};
+}
+
+/** `attrs` as an HTML attribute string (` a="b" c`), values escaped by `esc`. */
+export function serializeDomAttributes(attrs: DomAttributes, esc: (v: string) => string): string {
+    return Object.entries(attrs).map(([k, v]) => (v === '' ? ` ${k}` : ` ${k}="${esc(v)}"`)).join('');
+}
+
+// ── Items from content (R3) ─────────────────────────────────────────────────────────────────────
+
+/** A field of a content type, as both the CMS schema and a site plan describe it. */
+export interface ContentFieldLike {
+    name: string;
+    type?: string;
+    controller?: string;
+}
+
+const SHORT_TEXT = new Set(['text']);
+const LONG_TEXT = new Set(['textarea', 'richText', 'editor']);
+
+export interface AccordionAutoBinds {
+    /** The first short-text field: the question. */
+    question: string | null;
+    /** The first long-text field: the answer. */
+    answer: string | null;
+}
+
+/** R3 (board 9 Q19): switching to From content binds the question to the first short-text field and the
+ *  answer to the first long-text field. ONE rule for the builder's switch and the composer. */
+export function pickAccordionAutoBinds(fields: ReadonlyArray<ContentFieldLike>): AccordionAutoBinds {
+    const isString = (f: ContentFieldLike) => !f.type || f.type === 'string';
+    const question = fields.find(f => isString(f) && SHORT_TEXT.has(String(f.controller ?? 'text')))?.name ?? null;
+    const answer = fields.find(f => isString(f) && LONG_TEXT.has(String(f.controller ?? '')) && f.name !== question)?.name ?? null;
+    return { question, answer };
+}
+
+/** The bound props of the question and the answer (each a content trait). */
+export const ACCORDION_BIND_PROP = 'content';
+
+/**
+ * Manual → From content (board 9 "Items: Manual · From content"): the root becomes `repeater` (a Repeater node
+ * the caller created with the same id, role, label, element style and styles — a type change is the
+ * consumer's), the FIRST item becomes the one template (its parts, styles and interactions kept; its key
+ * dropped — a row's key is its id) and the others are removed. Returns the removed items.
+ */
+export function accordionToContent(root: CompositeNode, repeater: CompositeNode): CompositeNode[] {
+    const items = accordionItems(root);
+    const [template, ...rest] = items;
+    if (template) delete template.itemKey;
+    repeater.role = AccordionRole.Accordion;
+    repeater.children = template ? [template] : [];
+    writeProp(repeater, CompositeBehaviourTrait.Multiple, accordionBehaviour(root).multiple);
+    writeProp(repeater, CompositeBehaviourTrait.DefaultOn, accordionBehaviour(root).defaultOn);
+    return rest;
+}
+
+/**
+ * From content → Manual: the rows come in as static items — each a copy of the template (`cloneItem`, which
+ * gives the copy fresh ids) whose bound words are written in as its own and whose bindings are dropped.
+ * `container` is the manual root the caller created. Returns the new items.
+ */
+export function accordionToManual(root: CompositeNode, container: CompositeNode, rows: ReadonlyArray<unknown>,
+    cloneItem: (template: CompositeNode) => CompositeNode, resolve: (row: unknown, binding: CompositeBinding) => unknown): CompositeNode[] {
+    const template = accordionItems(root)[0];
+    container.role = AccordionRole.Accordion;
+    writeProp(container, CompositeBehaviourTrait.Multiple, accordionBehaviour(root).multiple);
+    writeProp(container, CompositeBehaviourTrait.DefaultOn, accordionBehaviour(root).defaultOn);
+    const items = template ? rows.map((row, i) => {
+        const item = cloneItem(template);
+        item.itemKey = `k${i + 1}`;
+        walkComposite(item, n => {
+            const bindings = (n as BoundNode).bindings ?? [];
+            for (const b of bindings) {
+                const value = resolve(row, b);
+                if (value !== undefined && value !== null) writeProp(n, b.prop, value);
+            }
+            if (bindings.length) (n as BoundNode).bindings = [];
+        });
+        return item;
+    }) : [];
+    container.children = items;
+    return items;
+}
+
+export interface CompositeBinding {
+    prop: string;
+    source: string;
+    path?: string;
+    pipes?: unknown[];
+}
+
+interface BoundNode extends CompositeNode {
+    bindings?: CompositeBinding[];
+}
+
+/** The style a part holds for `name` (both node shapes) — exported for the consumers' detectors. */
+export function accordionPartStyle(node: CompositeNode, name: string): unknown {
+    return readOwnedTrait(node, { trait: name });
+}