@vectoriox/iox-ui 5.37.0 → 5.39.0

package/src/composite-core/tabs.ts

@@ -0,0 +1,628 @@
+import { elementStyleById } from '@vectoriox/iox-ui/design-core';
+
+import {
+    AccordionDomIds, accordionDomIds, AccordionKeyAction, CompositeBinding, compositeScopeId, ContentFieldLike, COMPOSITE_ATTRIBUTE, DomAttributes,
+    ITEM_KEY_ATTRIBUTE, ITEM_OPEN_STATE, ON_ATTRIBUTE, rowItemKey, SCOPE_ATTRIBUTE,
+} from './accordion';
+import { CARD_STACK_BREAKPOINT } from './card';
+import { CompositeKind, TabsRole } from './composite-kinds';
+import {
+    clearLayerStyles, CompositeNode, CompositeNodeFactory, makeCompositePart, readProp, walkComposite, writeLayerStyles, writeProp, writeStyles,
+} from './composite-node';
+
+/**
+ * TABS (CC4a — composite K2 T17–T20; complex-components boards 3 and 9, APPROVED 2026-10-20). Not a component: a
+ * recipe of ordinary nodes, each part carrying a role, so every tab and every panel is selectable on the canvas, in
+ * the layer tree and the breadcrumb, and wears its own element style (R2).
+ *
+ *   Container `box`                  role tabs          traits activateOn · orientation · ariaLabel (the list's name)
+ *   ├─ Container `tab-list`          role tabs.list     → role=tablist (locked)        — or a Repeater (From content)
+ *   │   └─ ButtonBlock `tab` ×3      role tabs.trigger  itemKey k1…  → <button role=tab> › Text `button-label`
+ *   └─ Container `box`               role tabs.panels   (locked)                        — or a Repeater (From content)
+ *       └─ Container `box` ×3        role tabs.panel    the SAME itemKey as its tab → role=tabpanel, hidden while off
+ *           ├─ Image `media`         4 / 3
+ *           └─ Text `body`
+ *
+ * A tab and its panel are a PAIR by `itemKey` — never by index, so a tab moved to the end still shows its own panel.
+ * The behaviour is BUILT IN (composite plan D1 = B): exactly one item is on (`exclusive`), the APG tabs pattern with
+ * AUTOMATIC activation (arrows move focus and activate, roving tabindex) — one runtime (`exclusive-runtime.ts`) on the
+ * builder canvas and both engine paths, from the attribute planners below.
+ */
+
+export enum TabsBehaviourTrait {
+    /** Which pointer gesture turns a tab on: a click (always) or also a hover. */
+    ActivateOn = 'activateOn',
+    /** The tab list across the top, or beside the panels. */
+    Orientation = 'orientation',
+    /** The tab list's accessible name (`aria-label` on the role=tablist element) — the root's, edited in Accessibility. */
+    Label = 'ariaLabel',
+}
+
+export enum TabsActivateOn {
+    Click = 'click',
+    Hover = 'hover',
+}
+
+export enum TabsOrientation {
+    Horizontal = 'horizontal',
+    Vertical = 'vertical',
+}
+
+export const TABS_ACTIVATE_ONS: ReadonlyArray<TabsActivateOn> = [TabsActivateOn.Click, TabsActivateOn.Hover];
+export const TABS_ORIENTATIONS: ReadonlyArray<TabsOrientation> = [TabsOrientation.Horizontal, TabsOrientation.Vertical];
+
+/** Tabs from content default to six rows: more tabs do not fit a row (board 9 Q13). */
+export const TABS_CONTENT_LIMIT = 6;
+
+/** The breakpoint whose layer stacks a VERTICAL tabs (the list above the panels) and a panel's picture above its words. */
+export const TABS_STACK_BREAKPOINT = CARD_STACK_BREAKPOINT;
+
+export interface TabWords {
+    label: string;
+    text: string;
+}
+
+/** The words a fresh Tabs starts with — generic, the author's to replace (Card v2.1: never invented facts). */
+export const TABS_WORDS: ReadonlyArray<TabWords> = [
+    { label: 'First tab', text: 'Say what this tab is about in a sentence or two. Its picture sits beside it.' },
+    { label: 'Second tab', text: 'Say what this tab is about in a sentence or two. Its picture sits beside it.' },
+    { label: 'Third tab', text: 'Say what this tab is about in a sentence or two. Its picture sits beside it.' },
+];
+export const TABS_NEW_TAB_WORDS: Readonly<TabWords> = { label: 'New tab', text: 'Say what this tab is about in a sentence or two. Its picture sits beside it.' };
+
+enum Type {
+    Container = 'Container',
+    ButtonBlock = 'ButtonBlock',
+    Text = 'Text',
+    Image = 'Image',
+    Repeater = 'Repeater',
+}
+
+enum Style {
+    Root = 'box',
+    List = 'tab-list',
+    Tab = 'tab',
+    Label = 'button-label',
+    Panels = 'box',
+    Panel = 'box',
+    Media = 'media',
+    Body = 'body',
+}
+
+const ZERO_BOX = '0px 0px 0px 0px';
+/** The list's hairline, as its element style writes it — read from the contract, never retyped. */
+const LIST_EDGE = String(elementStyleById(Style.List)?.base['borderWidth'] ?? ZERO_BOX);
+
+/** What each part holds — layout only; its LOOK is its element style. The list WRAPS at narrow widths (board 3). */
+const PART_BASE: Readonly<Record<string, Readonly<Record<string, string>>>> = {
+    [TabsRole.Tabs]: { display: 'flex', width: '100%', minHeight: 'auto', height: 'auto' },
+    [TabsRole.List]: { display: 'flex', gap: '4px', minHeight: 'auto', height: 'auto' },
+    [TabsRole.Trigger]: { width: 'auto', minHeight: 'auto', height: 'auto', cursor: 'pointer' },
+    [TabsRole.Panels]: { display: 'block', width: '100%', minWidth: '0px', minHeight: 'auto', height: 'auto' },
+    // Board 3: a panel is any nodes at all — the recipe's is a picture beside its words.
+    [TabsRole.Panel]: { display: 'grid', gridTemplateColumns: '1fr 1.2fr', gap: '24px', alignItems: 'center', width: '100%', minHeight: 'auto', height: 'auto' },
+};
+const LABEL_BASE: Readonly<Record<string, string>> = { width: 'auto', minHeight: 'auto', padding: ZERO_BOX, margin: ZERO_BOX };
+const IMAGE_BASE: Readonly<Record<string, string>> = { display: 'block', width: '100%', maxWidth: '100%', aspectRatio: '4 / 3', height: 'auto', minHeight: 'auto' };
+const BODY_BASE: Readonly<Record<string, string>> = { margin: ZERO_BOX, padding: ZERO_BOX, minHeight: 'auto' };
+/** On a phone a panel's picture sits above its words. */
+const PANEL_STACK: Readonly<Record<string, string>> = { gridTemplateColumns: '1fr' };
+
+/**
+ * Behaviour ▸ Orientation is a PRESET over the root's and the list's layout (the Card layout precedent): every
+ * orientation writes the same keys, so switching is clean and detection exact. Vertical puts the list beside the
+ * panels (a column, no divider — the active tab keeps its mark) and, on a phone, stacks it above them.
+ */
+interface OrientationLayout {
+    root: Readonly<Record<string, string>>;
+    list: Readonly<Record<string, string>>;
+    /** The phone layer (TABS_STACK_BREAKPOINT); Horizontal clears these keys from it. */
+    rootStack?: Readonly<Record<string, string>>;
+    listStack?: Readonly<Record<string, string>>;
+}
+const ORIENTATION_LAYOUT: Readonly<Record<TabsOrientation, OrientationLayout>> = {
+    [TabsOrientation.Horizontal]: {
+        root: { flexDirection: 'column', alignItems: 'stretch', gap: '20px' },
+        list: { flexDirection: 'row', flexWrap: 'wrap', width: '100%', flexShrink: '1', borderWidth: LIST_EDGE },
+    },
+    [TabsOrientation.Vertical]: {
+        root: { flexDirection: 'row', alignItems: 'flex-start', gap: '24px' },
+        list: { flexDirection: 'column', flexWrap: 'nowrap', width: 'auto', flexShrink: '0', borderWidth: ZERO_BOX },
+        rootStack: { flexDirection: 'column', alignItems: 'stretch', gap: '20px' },
+        listStack: { width: '100%' },
+    },
+};
+const ROOT_STACK_KEYS = ['flexDirection', 'alignItems', 'gap'];
+const LIST_STACK_KEYS = ['width'];
+
+// ── recipe ──────────────────────────────────────────────────────────────────────────────────────
+
+export interface TabsOptions {
+    tabs?: ReadonlyArray<TabWords>;
+    activateOn?: TabsActivateOn;
+    orientation?: TabsOrientation;
+    /** The tab list's accessible name (empty: unnamed — a section heading usually names the section). */
+    label?: string;
+}
+
+function make(create: CompositeNodeFactory, key: string, type: string, role: TabsRole | 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);
+}
+
+export interface TabPair {
+    tab: CompositeNode;
+    panel: CompositeNode;
+}
+
+/** One tab and its panel, sharing `itemKey`. */
+export function buildTabPair(create: CompositeNodeFactory, words: TabWords, itemKey: string): TabPair {
+    const tab = make(create, `${itemKey}-tab`, Type.ButtonBlock, TabsRole.Trigger, Style.Tab, {}, 'Tab');
+    tab.itemKey = itemKey;
+    const label = make(create, `${itemKey}-label`, Type.Text, null, Style.Label, { content: words.label, tag: 'span' }, 'Text');
+    writeStyles(label, LABEL_BASE);
+    tab.children = [label];
+    const panel = make(create, `${itemKey}-panel`, Type.Container, TabsRole.Panel, Style.Panel, {}, 'Panel');
+    panel.itemKey = itemKey;
+    writeLayerStyles(panel, TABS_STACK_BREAKPOINT, PANEL_STACK);
+    const image = make(create, `${itemKey}-image`, Type.Image, null, Style.Media, { src: '', alt: '' }, 'Image');
+    writeStyles(image, IMAGE_BASE);
+    const text = make(create, `${itemKey}-text`, Type.Text, null, Style.Body, { content: words.text, tag: 'p' }, 'Text');
+    writeStyles(text, BODY_BASE);
+    panel.children = [image, text];
+    return { tab, panel };
+}
+
+/** A fresh Tabs: three tabs, the first on, activated by a click, the list across the top (board 3). */
+export function buildTabsRecipe(create: CompositeNodeFactory, options: TabsOptions = {}): CompositeNode {
+    const root = make(create, 'tabs', Type.Container, TabsRole.Tabs, Style.Root, {}, 'Tabs');
+    writeProp(root, TabsBehaviourTrait.ActivateOn, options.activateOn ?? TabsActivateOn.Click);
+    writeProp(root, TabsBehaviourTrait.Orientation, options.orientation ?? TabsOrientation.Horizontal);
+    if (options.label) writeProp(root, TabsBehaviourTrait.Label, options.label);
+    const list = make(create, 'list', Type.Container, TabsRole.List, Style.List, {}, 'Tab list');
+    const panels = make(create, 'panels', Type.Container, TabsRole.Panels, Style.Panels, {}, 'Panels');
+    const pairs = (options.tabs ?? TABS_WORDS).map((w, i) => buildTabPair(create, w, `k${i + 1}`));
+    list.children = pairs.map(p => p.tab);
+    panels.children = pairs.map(p => p.panel);
+    root.children = [list, panels];
+    applyOrientation(root, options.orientation ?? TabsOrientation.Horizontal);
+    return root;
+}
+
+// ── reading a tree ──────────────────────────────────────────────────────────────────────────────
+
+export function isTabsRoot(node: { role?: string | null } | null | undefined): boolean {
+    return node?.role === TabsRole.Tabs;
+}
+
+/** The tab list (the holder of the triggers). */
+export function tabsListOf(root: CompositeNode): CompositeNode | undefined {
+    return (root.children ?? []).find(c => c.role === TabsRole.List);
+}
+
+/** The holder of the panels. */
+export function tabsPanelsOf(root: CompositeNode): CompositeNode | undefined {
+    return (root.children ?? []).find(c => c.role === TabsRole.Panels);
+}
+
+/** The tabs in order — every tab (Manual), or the one template tab (From content). */
+export function tabsTriggers(root: CompositeNode): CompositeNode[] {
+    return (tabsListOf(root)?.children ?? []).filter(c => c.role === TabsRole.Trigger);
+}
+
+/** The panels in their holder's order (their order does not pair them — their key does). */
+export function tabsPanels(root: CompositeNode): CompositeNode[] {
+    return (tabsPanelsOf(root)?.children ?? []).filter(c => c.role === TabsRole.Panel);
+}
+
+/** True when the Tabs takes its tabs from content (its list is a Repeater, R3). */
+export function isTabsFromContent(root: CompositeNode | null | undefined): boolean {
+    return !!root && tabsListOf(root)?.type === Type.Repeater;
+}
+
+/** The panel paired with `tab` (the same key), or undefined. From content the one template panel pairs the template tab. */
+export function tabPanelOf(root: CompositeNode, tab: CompositeNode): CompositeNode | undefined {
+    if (isTabsFromContent(root)) return tabsPanels(root)[0];
+    return tab.itemKey ? tabsPanels(root).find(p => p.itemKey === tab.itemKey) : undefined;
+}
+
+/** The tab paired with `panel` (the same key), or undefined. */
+export function tabTriggerOf(root: CompositeNode, panel: CompositeNode): CompositeNode | undefined {
+    if (isTabsFromContent(root)) return tabsTriggers(root)[0];
+    return panel.itemKey ? tabsTriggers(root).find(t => t.itemKey === panel.itemKey) : undefined;
+}
+
+/** The other half of a tab ⇄ panel pair, or undefined for any other node. */
+export function tabsPartnerOf(root: CompositeNode, node: CompositeNode): CompositeNode | undefined {
+    if (node.role === TabsRole.Trigger) return tabPanelOf(root, node);
+    if (node.role === TabsRole.Panel) return tabTriggerOf(root, node);
+    return undefined;
+}
+
+/** The words a tab shows: its first Text's. */
+export function tabLabelNodeOf(tab: CompositeNode): CompositeNode | undefined {
+    let hit: CompositeNode | undefined;
+    walkComposite(tab, n => { if (!hit && n !== tab && n.type === Type.Text) hit = n; });
+    return hit;
+}
+
+const stripTags = (v: unknown) => String(v ?? '').replace(/<[^>]*>/g, '').trim();
+
+/** A tab's name in the Items list, the layer tree and the item-action picker: its words. */
+export function tabLabel(tab: CompositeNode): string {
+    const label = tabLabelNodeOf(tab);
+    return label ? stripTags(readProp(label, 'content')) : '';
+}
+
+/** Items ▸ rename: the tab's words. */
+export function renameTab(tab: CompositeNode, words: string): boolean {
+    const label = tabLabelNodeOf(tab);
+    return !!label && writeProp(label, 'content', words);
+}
+
+/** The first Text inside a panel (the words From content binds to). */
+export function tabPanelTextOf(panel: CompositeNode): CompositeNode | undefined {
+    let hit: CompositeNode | undefined;
+    walkComposite(panel, n => { if (!hit && n !== panel && n.type === Type.Text) hit = n; });
+    return hit;
+}
+
+/** The first Image inside a panel. */
+export function tabPanelImageOf(panel: CompositeNode): CompositeNode | undefined {
+    let hit: CompositeNode | undefined;
+    walkComposite(panel, n => { if (!hit && n.type === Type.Image) hit = n; });
+    return hit;
+}
+
+export interface TabsBehaviour {
+    activateOn: TabsActivateOn;
+    orientation: TabsOrientation;
+}
+
+/** The root's behaviour (an unset trait reads its default: a click, the list across the top). */
+export function tabsBehaviour(root: CompositeNode | null | undefined): TabsBehaviour {
+    const on = root ? readProp(root, TabsBehaviourTrait.ActivateOn) : undefined;
+    const orientation = root ? readProp(root, TabsBehaviourTrait.Orientation) : undefined;
+    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,
+    };
+}
+
+/** The tab list's accessible name (empty when unnamed). */
+export function tabsLabel(root: CompositeNode | null | undefined): string {
+    return root ? String(readProp(root, TabsBehaviourTrait.Label) ?? '').trim() : '';
+}
+
+/** Write the orientation preset into the root's and the list's layout (both orientations write the same keys). */
+function applyOrientation(root: CompositeNode, orientation: TabsOrientation): void {
+    const spec = ORIENTATION_LAYOUT[orientation];
+    const list = tabsListOf(root);
+    writeStyles(root, spec.root);
+    if (list) writeStyles(list, spec.list);
+    if (spec.rootStack) writeLayerStyles(root, TABS_STACK_BREAKPOINT, spec.rootStack);
+    else clearLayerStyles(root, TABS_STACK_BREAKPOINT, ROOT_STACK_KEYS);
+    if (list) {
+        if (spec.listStack) writeLayerStyles(list, TABS_STACK_BREAKPOINT, spec.listStack);
+        else clearLayerStyles(list, TABS_STACK_BREAKPOINT, LIST_STACK_KEYS);
+    }
+}
+
+/** Behaviour ▸ Activate on / Orientation (and Accessibility ▸ the list's name). False when the root has no such trait. */
+export function setTabsBehaviour(root: CompositeNode, patch: Partial<TabsBehaviour> & { label?: string }): boolean {
+    let ok = true;
+    if (patch.activateOn !== undefined) ok = writeProp(root, TabsBehaviourTrait.ActivateOn, patch.activateOn) && ok;
+    if (patch.orientation !== undefined) {
+        ok = writeProp(root, TabsBehaviourTrait.Orientation, patch.orientation) && ok;
+        applyOrientation(root, patch.orientation);
+    }
+    if (patch.label !== undefined) ok = writeProp(root, TabsBehaviourTrait.Label, patch.label) && ok;
+    return ok;
+}
+
+// ── editing (Items list, selection toolbar ▸ Add tab, the structure guard) ──────────────────────
+
+/** A key no tab of `root` holds yet (`k4`…). */
+export function nextTabKey(root: CompositeNode): string {
+    const taken = new Set([...tabsTriggers(root), ...tabsPanels(root)].map(n => n.itemKey).filter(Boolean));
+    let n = tabsTriggers(root).length + 1;
+    while (taken.has(`k${n}`)) n++;
+    return `k${n}`;
+}
+
+/** Items ▸ Add tab (and the toolbar's "Add tab"): a fresh tab after `after` (or at the end) AND its panel. */
+export function addTabPair(root: CompositeNode, create: CompositeNodeFactory, after?: CompositeNode | null, words: TabWords = TABS_NEW_TAB_WORDS): TabPair | null {
+    const list = tabsListOf(root);
+    const panels = tabsPanelsOf(root);
+    if (!list || !panels || isTabsFromContent(root)) return null;
+    const pair = buildTabPair(create, words, nextTabKey(root));
+    const tabs = [...(list.children ?? [])];
+    const afterTab = after ? (after.role === TabsRole.Panel ? tabTriggerOf(root, after) : after) : null;
+    const at = afterTab ? tabs.indexOf(afterTab) : -1;
+    tabs.splice(at < 0 ? tabs.length : at + 1, 0, pair.tab);
+    list.children = tabs;
+    const afterPanel = afterTab ? tabPanelOf(root, afterTab) : null;
+    const held = [...(panels.children ?? [])];
+    const pAt = afterPanel ? held.indexOf(afterPanel) : -1;
+    held.splice(pAt < 0 ? held.length : pAt + 1, 0, pair.panel);
+    panels.children = held;
+    return pair;
+}
+
+function moveIn(holder: CompositeNode, node: CompositeNode, toIndex: number, role: TabsRole): void {
+    const children = [...(holder.children ?? [])];
+    const from = children.indexOf(node);
+    if (from < 0) return;
+    children.splice(from, 1);
+    const same = children.filter(c => c.role === role);
+    const anchor = same[Math.max(0, Math.min(toIndex, same.length))];
+    children.splice(anchor ? children.indexOf(anchor) : children.length, 0, node);
+    holder.children = children;
+}
+
+/** Items ▸ drag to reorder: move a tab — and its panel, so the layer tree reads in the same order — to `toIndex`.
+ *  The pairing never depended on the order. False when `tab` is not one of the root's tabs. */
+export function moveTabPair(root: CompositeNode, tab: CompositeNode, toIndex: number): boolean {
+    const list = tabsListOf(root);
+    const panels = tabsPanelsOf(root);
+    if (!list || tab.role !== TabsRole.Trigger || !(list.children ?? []).includes(tab)) return false;
+    const panel = tabPanelOf(root, tab);
+    moveIn(list, tab, toIndex, TabsRole.Trigger);
+    if (panel && panels) moveIn(panels, panel, toIndex, TabsRole.Panel);
+    return true;
+}
+
+/** Remove a tab and its panel (the pair) — what "Delete tab and its panel" does. True when the tab was removed. */
+export function removeTabPair(root: CompositeNode, node: CompositeNode): boolean {
+    const tab = node.role === TabsRole.Panel ? tabTriggerOf(root, node) : node;
+    const list = tabsListOf(root);
+    if (!tab || !list || tab.role !== TabsRole.Trigger) return false;
+    const panel = tabPanelOf(root, tab);
+    list.children = (list.children ?? []).filter(c => c !== tab);
+    const panels = tabsPanelsOf(root);
+    if (panel && panels) panels.children = (panels.children ?? []).filter(c => c !== panel);
+    return true;
+}
+
+export enum TabsEditRefusal {
+    /** A Tabs keeps at least one tab (composite plan T18). */
+    LastTab = 'last-tab',
+}
+
+/** Why removing `node` (a tab or a panel) from `root` is refused, or null. */
+export function tabsRemovalRefusal(root: CompositeNode | null | undefined, node: CompositeNode | null | undefined): TabsEditRefusal | null {
+    if (!root || (node?.role !== TabsRole.Trigger && node?.role !== TabsRole.Panel)) return null;
+    return tabsTriggers(root).length <= 1 ? TabsEditRefusal.LastTab : null;
+}
+
+/** Every "Item open" (`trigger-on`) state inside a tab or a panel points at ITS tab or panel — the part that carries
+ *  `data-iox-on` while its item is on. */
+export function tabsItemTriggerIds(root: CompositeNode): void {
+    for (const part of [...tabsTriggers(root), ...tabsPanels(root)]) {
+        if (!part.id) continue;
+        walkComposite(part, n => {
+            if (n === part || !n.stateStyles?.[ITEM_OPEN_STATE]) return;
+            n.stateTriggers = { ...(n.stateTriggers ?? {}), [ITEM_OPEN_STATE]: part.id! };
+        });
+    }
+}
+
+// ── state, ids and attributes (both renderers, SSR included) ───────────────────────────────────
+
+/** The render scope of one Tabs: its scope id, behaviour, every item key in order and the one that is on. */
+export interface TabsScope {
+    rootId: string;
+    behaviour: TabsBehaviour;
+    keys: ReadonlyArray<string>;
+    /** The key on at first paint: the first tab (null when there is none). */
+    active: string | null;
+    label: string;
+}
+
+export function tabsScope(rootId: string, behaviour: TabsBehaviour, keys: ReadonlyArray<string>, label = ''): TabsScope {
+    return { rootId, behaviour, keys, active: keys[0] ?? null, label };
+}
+
+/** The item keys a manual Tabs pairs by — its tabs' own keys, in order (a tab with none by its index). */
+export function manualTabKeys(root: CompositeNode): string[] {
+    return tabsTriggers(root).map((t, i) => t.itemKey || `item-${i}`);
+}
+
+export interface TabsItemState {
+    key: string;
+    on: boolean;
+    ids: AccordionDomIds;
+}
+
+/** One item's render state: its key, whether it is on, and its ARIA ids (`iox-tab-<scope>-<key>-h` / `-p`). */
+export function tabsItemState(scope: TabsScope, key: string): TabsItemState {
+    return { key, on: scope.active === key, ids: accordionDomIds(scope.rootId, key, CompositeKind.Tabs) };
+}
+
+export const ACTIVATE_ON_ATTRIBUTE = 'data-iox-activate-on';
+export const ORIENTATION_ATTRIBUTE = 'data-iox-orientation';
+
+export function tabsRootAttributes(behaviour: TabsBehaviour, scopeId?: string): DomAttributes {
+    return {
+        [COMPOSITE_ATTRIBUTE]: CompositeKind.Tabs,
+        [ACTIVATE_ON_ATTRIBUTE]: behaviour.activateOn,
+        [ORIENTATION_ATTRIBUTE]: behaviour.orientation,
+        ...(scopeId ? { [SCOPE_ATTRIBUTE]: scopeId } : {}),
+    };
+}
+
+/** The tab list: `role=tablist`, vertical said aloud, named by the root's label. */
+export function tabListAttributes(behaviour: TabsBehaviour, label = ''): DomAttributes {
+    return {
+        role: 'tablist',
+        ...(behaviour.orientation === TabsOrientation.Vertical ? { 'aria-orientation': 'vertical' } : {}),
+        ...(label ? { 'aria-label': label } : {}),
+    };
+}
+
+/** A tab: a real button that selects its panel — selected = the one tab in the Tab order (roving tabindex). */
+export function tabTriggerAttributes(state: TabsItemState): DomAttributes {
+    return {
+        type: 'button',
+        role: 'tab',
+        id: state.ids.trigger,
+        'aria-selected': state.on ? 'true' : 'false',
+        'aria-controls': state.ids.panel,
+        tabindex: state.on ? '0' : '-1',
+        [ITEM_KEY_ATTRIBUTE]: state.key,
+        ...(state.on ? { [ON_ATTRIBUTE]: '' } : {}),
+    };
+}
+
+/** A panel: `role=tabpanel`, named by its tab, a Tab stop of its own, and `hidden` (display:none) while off. */
+export function tabPanelAttributes(state: TabsItemState): DomAttributes {
+    return {
+        role: 'tabpanel',
+        id: state.ids.panel,
+        'aria-labelledby': state.ids.trigger,
+        tabindex: '0',
+        [ITEM_KEY_ATTRIBUTE]: state.key,
+        ...(state.on ? { [ON_ATTRIBUTE]: '' } : { hidden: '' }),
+    };
+}
+
+/**
+ * The render scope of one rendered Tabs — ONE decision for both engine paths (and the composer's checks): its scope id
+ * (its node id + the rows around it, vectoriox/iox-ui#20), its behaviour, its list's name and every item key in order —
+ * a manual tab's own `itemKey`, or, From content, each ROW's own id (R3: never its index — a reorder in the CMS keeps
+ * every tab with its own panel). `rows` = the rows the tab list's Repeater resolved (null for a manual Tabs).
+ */
+export function tabsScopeFor(root: CompositeNode, rootCssId: string, rows: ReadonlyArray<unknown> | null, rowKeys: ReadonlyArray<string> = []): TabsScope {
+    const keys = rows ? rows.map((row, i) => rowItemKey(row, i)) : manualTabKeys(root);
+    return tabsScope(compositeScopeId(rootCssId, rowKeys), tabsBehaviour(root), keys, tabsLabel(root));
+}
+
+/** The key a manual tab or panel renders with: its own key, else its index among its kind. */
+export function tabPartKey(node: CompositeNode, index: number): string {
+    return node.itemKey || `item-${index}`;
+}
+
+/**
+ * The attributes a part of a Tabs writes on its own element (both engine paths, SSR included): the root's data
+ * attributes (its scope id when it sits in repeated rows), the list's role and name, a tab's and a panel's state by
+ * `key` (its own key, or — From content — its row's). Anything else writes nothing.
+ */
+export function tabsPartAttributes(node: { role?: string | null }, scope: TabsScope, key: string | null, rowScoped = false): DomAttributes {
+    switch (node.role) {
+        case TabsRole.Tabs: return tabsRootAttributes(scope.behaviour, rowScoped ? scope.rootId : undefined);
+        case TabsRole.List: return tabListAttributes(scope.behaviour, scope.label);
+        case TabsRole.Trigger: return key ? tabTriggerAttributes(tabsItemState(scope, key)) : {};
+        case TabsRole.Panel: return key ? tabPanelAttributes(tabsItemState(scope, key)) : {};
+        default: return {};
+    }
+}
+
+/**
+ * The APG tabs keys on a tab (automatic activation): → / ← move along a horizontal list — mirrored under RTL — and ↓ /
+ * ↑ along a vertical one; Home / End jump. Every move wraps. Enter / Space are the button's own.
+ */
+export function tabsKeyAction(key: string, orientation: TabsOrientation, rtl = false): AccordionKeyAction | null {
+    if (key === 'Home') return AccordionKeyAction.First;
+    if (key === 'End') return AccordionKeyAction.Last;
+    if (orientation === TabsOrientation.Vertical) {
+        if (key === 'ArrowDown') return AccordionKeyAction.Next;
+        if (key === 'ArrowUp') return AccordionKeyAction.Previous;
+        return null;
+    }
+    if (key === 'ArrowRight') return rtl ? AccordionKeyAction.Previous : AccordionKeyAction.Next;
+    if (key === 'ArrowLeft') return rtl ? AccordionKeyAction.Next : AccordionKeyAction.Previous;
+    return null;
+}
+
+// ── Items from content (R3, composite T39) ──────────────────────────────────────────────────────
+
+const SHORT_TEXT = new Set(['text']);
+const LONG_TEXT = new Set(['textarea', 'richText', 'editor']);
+const IMAGE_CONTROLLERS = new Set(['image', 'media', 'file']);
+
+export interface TabsAutoBinds {
+    /** The first short-text field: the tab's words. */
+    label: string | null;
+    /** The first long-text field: the panel's words. */
+    text: string | null;
+    /** The first image field: the panel's picture. */
+    image: string | null;
+}
+
+/** R3 (board 3 "Tabs from content"): switching to From content binds the tab's words to the first short-text field,
+ *  the panel's words to the first long-text field and its picture to the first image field. ONE rule for the builder's
+ *  switch and the composer. */
+export function pickTabsAutoBinds(fields: ReadonlyArray<ContentFieldLike>): TabsAutoBinds {
+    const isString = (f: ContentFieldLike) => !f.type || f.type === 'string';
+    const label = fields.find(f => isString(f) && SHORT_TEXT.has(String(f.controller ?? 'text')))?.name ?? null;
+    const text = fields.find(f => isString(f) && LONG_TEXT.has(String(f.controller ?? '')) && f.name !== label)?.name ?? null;
+    const image = fields.find(f => IMAGE_CONTROLLERS.has(String(f.controller ?? '')) && f.name !== label && f.name !== text)?.name ?? null;
+    return { label, text, image };
+}
+
+/** The bound props of a tab's words, a panel's words and its picture. */
+export const TABS_LABEL_BIND_PROP = 'content';
+export const TABS_TEXT_BIND_PROP = 'content';
+export const TABS_IMAGE_BIND_PROP = 'src';
+
+/**
+ * Manual → From content (board 9 "Items: Manual · From content"): the list becomes `listRepeater` and the panels
+ * holder `panelsRepeater` (Repeater nodes the caller created with the same ids, roles, names, element styles and
+ * styles — a type change is the consumer's). The FIRST tab and ITS panel become the templates (their parts, styles
+ * and interactions kept; their keys dropped — a row's key is its id); every other pair is removed. Returns the removed
+ * nodes.
+ */
+export function tabsToContent(root: CompositeNode, listRepeater: CompositeNode, panelsRepeater: CompositeNode): CompositeNode[] {
+    const [tab, ...restTabs] = tabsTriggers(root);
+    const panel = tab ? tabPanelOf(root, tab) : undefined;
+    const restPanels = tabsPanels(root).filter(p => p !== panel);
+    if (tab) delete tab.itemKey;
+    if (panel) delete panel.itemKey;
+    listRepeater.role = TabsRole.List;
+    panelsRepeater.role = TabsRole.Panels;
+    listRepeater.children = tab ? [tab] : [];
+    panelsRepeater.children = panel ? [panel] : [];
+    root.children = (root.children ?? []).map(c => (c.role === TabsRole.List ? listRepeater : c.role === TabsRole.Panels ? panelsRepeater : c));
+    return [...restTabs, ...restPanels];
+}
+
+interface BoundNode extends CompositeNode {
+    bindings?: CompositeBinding[];
+}
+
+function writeRowIn(node: CompositeNode, row: unknown, resolve: (row: unknown, binding: CompositeBinding) => unknown): void {
+    walkComposite(node, 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 = [];
+    });
+}
+
+/**
+ * From content → Manual: the rows come in as static pairs — each a copy of the template tab and panel (`clone`, which
+ * gives the copy fresh ids) whose bound words are written in as its own and whose bindings are dropped. `list` and
+ * `panels` are the manual holders the caller created. Returns the new pairs.
+ */
+export function tabsToManual(root: CompositeNode, list: CompositeNode, panels: CompositeNode, rows: ReadonlyArray<unknown>,
+    clone: (template: CompositeNode) => CompositeNode, resolve: (row: unknown, binding: CompositeBinding) => unknown): TabPair[] {
+    const [tabTemplate] = tabsTriggers(root);
+    const panelTemplate = tabsPanels(root)[0];
+    list.role = TabsRole.List;
+    panels.role = TabsRole.Panels;
+    const pairs = tabTemplate && panelTemplate ? rows.map((row, i) => {
+        const tab = clone(tabTemplate);
+        const panel = clone(panelTemplate);
+        tab.itemKey = panel.itemKey = `k${i + 1}`;
+        writeRowIn(tab, row, resolve);
+        writeRowIn(panel, row, resolve);
+        return { tab, panel };
+    }) : [];
+    list.children = pairs.map(p => p.tab);
+    panels.children = pairs.map(p => p.panel);
+    root.children = (root.children ?? []).map(c => (c.role === TabsRole.List ? list : c.role === TabsRole.Panels ? panels : c));
+    return pairs;
+}
+

package/src/design-core/contrast-audit.ts

@@ -150,6 +150,8 @@ export function auditDesignContrast(rows: ReadonlyArray<DesignTokenLike>, mode:
                     ['base', ownStyle(e)],
                     ...(e.hover ? [['hover', { ...ownStyle(e), ...e.hover }] as [string, StyleMap]] : []),
                     ...(e.current ? [['current', { ...ownStyle(e), ...e.current }] as [string, StyleMap]] : []),
+                    // `on` (CC4a): the active tab, on every ground it can sit on.
+                    ...(e.on ? [['on', { ...ownStyle(e), ...e.on }] as [string, StyleMap]] : []),
                 ];
                 const glyph = e.group === GLYPH_GROUP;
                 for (const [state, s] of states) {
@@ -157,6 +159,9 @@ export function auditDesignContrast(rows: ReadonlyArray<DesignTokenLike>, mode:
                     const under = fill.length && opaque(fill) ? overAll(fill, bgs) : bgs;
                     const ink = s['color'] ? parseCssColour(resolveIn(values, s['color']), boxInk) : boxInk;
                     check(e.id, state === 'base' ? (glyph ? 'glyph' : 'text') : `${state} text`, ink, under, glyph ? WCAG_AA_UI : WCAG_AA_TEXT);
+                    // The active tab's mark is the selected state's indicator (WCAG 1.4.11) — the contract's audit, 1:1.
+                    const mark = state === 'on' ? (e.on as StyleMap | undefined)?.['borderColor'] : undefined;
+                    if (mark) check(e.id, 'on mark', parseCssColour(resolveIn(values, mark), ink), bgs, WCAG_AA_UI);
                     // What a filled element HOLDS (inkScopes): a button's or a badge's icon reads its ink.
                     if (state === 'base' && INK_SCOPES.some(sc => sc.styles.includes(e.id))) {
                         check(e.id, 'icon', parseCssColour(resolveIn(inkScoped(values, e.id), iconColour), ink), under, WCAG_AA_UI);