@vectoriox/iox-ui 5.39.0 → 5.41.0

package/src/composite-core/segmented.ts

@@ -0,0 +1,349 @@
+import {
+    AccordionKeyAction, CompositeBehaviourTrait, compositeScopeId, COMPOSITE_ATTRIBUTE, DEFAULT_ON_ATTRIBUTE, DomAttributes, ITEM_KEY_ATTRIBUTE,
+    ITEM_OPEN_STATE, ON_ATTRIBUTE, SCOPE_ATTRIBUTE,
+} from './accordion';
+import { BadgeTone, buildBadge } from './badge';
+import { CompositeKind, SegmentedRole } from './composite-kinds';
+import { CompositeNode, CompositeNodeFactory, makeCompositePart, readProp, walkComposite, writeProp, writeStyles } from './composite-node';
+import { TabsActivateOn, TabsBehaviour, TabsOrientation, TabsScope } from './tabs';
+
+/**
+ * THE SEGMENTED CONTROL (CC4b — composite K4 T32, pulled forward; complex-components board 10, APPROVED 2026-10-23 with
+ * Q31–Q40 as recommended). One of a few, always one on, FIXED options (R3 / Q36). Not a component: a recipe of
+ * ordinary nodes, each part carrying a role, so every option, its words and its optional badge are selectable on the
+ * canvas, in the layer tree and the breadcrumb, and wear their own element styles (R2).
+ *
+ *   Container `segmented`            role segmented          traits defaultOn (an option's key) · ariaLabel (its name)
+ *   └─ ButtonBlock `segmented-option` ×2–4   role segmented.option   itemKey monthly · yearly …  → <button role=radio>
+ *       ├─ Text `button-label`       the words
+ *       └─ Container `badge-success` role segmented.badge (optional, off) › Icon + Text — a placeholder (a price claim)
+ *
+ * The ARIA shape is the APG RADIO GROUP (Q31): `role=radiogroup` + its accessible name on the root, `<button role=radio
+ * aria-checked>` per option with a roving tabindex — one Tab stop; ← → follow the reading direction (mirrored under
+ * RTL), ↑ ↓ the DOM order, every move wraps and turns the option on. It runs the EXCLUSIVE runtime the Tabs run
+ * (`exclusive-runtime.ts`), on the builder canvas and both engine paths, from the attribute planners below. What follows
+ * the control (a price) is an ordinary node OUTSIDE it styled "when its option is on" — the targeted `trigger-on`.
+ */
+
+export enum SegmentedTrait {
+    /** The option on at first paint — an option's key. */
+    DefaultOn = CompositeBehaviourTrait.DefaultOn,
+    /** The radio group's accessible name (`aria-label` on the root). Empty → an audit finding. */
+    Label = 'ariaLabel',
+}
+
+/** Q40: two options at least, four at most (past four the words no longer fit a phone row — a Select or Tabs then). */
+export const SEGMENTED_MIN_OPTIONS = 2;
+export const SEGMENTED_MAX_OPTIONS = 4;
+
+export interface SegmentedOptionWords {
+    key: string;
+    label: string;
+}
+
+/** A fresh Segmented control's options (board 10: a billing period) — generic words, the author's to rename. */
+export const SEGMENTED_WORDS: ReadonlyArray<SegmentedOptionWords> = [
+    { key: 'monthly', label: 'Monthly' },
+    { key: 'yearly', label: 'Yearly' },
+];
+export const SEGMENTED_NEW_OPTION_WORDS = 'New option';
+/** The name a fresh control carries (board 10). */
+export const SEGMENTED_NAME = 'Billing period';
+/** Q33: the saving badge's words start as a PLACEHOLDER — a saving is a price claim, never invented. */
+export const SEGMENTED_BADGE_WORDS = 'Yearly saving';
+export const SEGMENTED_BADGE_TONE = BadgeTone.Success;
+
+enum Type {
+    Container = 'Container',
+    ButtonBlock = 'ButtonBlock',
+    Text = 'Text',
+}
+
+enum Style {
+    Root = 'segmented',
+    Option = 'segmented-option',
+    Label = 'button-label',
+}
+
+const ZERO_BOX = '0px 0px 0px 0px';
+
+/** What each part holds — layout only; its LOOK is its element style (the track's fill, border, radius and pad; the
+ *  option's ink, pad, radius and 44px target). The options sit in a flex row a gap token apart (board 10). */
+const PART_BASE: Readonly<Record<string, Readonly<Record<string, string>>>> = {
+    [SegmentedRole.Segmented]: { display: 'inline-flex', flexDirection: 'row', alignItems: 'stretch', gap: 'var(--iox-segmented-gap)', width: 'auto', maxWidth: '100%', height: 'auto' },
+    [SegmentedRole.Option]: { display: 'inline-flex', alignItems: 'center', justifyContent: 'center', gap: '8px', width: 'auto', height: 'auto', cursor: 'pointer' },
+};
+const LABEL_BASE: Readonly<Record<string, string>> = { width: 'auto', minHeight: 'auto', padding: ZERO_BOX, margin: ZERO_BOX };
+/** The badge inside an option keeps to the option's row (never its own line). */
+const BADGE_IN_OPTION: Readonly<Record<string, string>> = { alignSelf: 'center' };
+
+function make(create: CompositeNodeFactory, key: string, type: string, role: SegmentedRole | 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);
+}
+
+// ── recipe ──────────────────────────────────────────────────────────────────────────────────────
+
+export interface SegmentedOptions {
+    options?: ReadonlyArray<SegmentedOptionWords>;
+    /** The option on by default (its key); else the first. */
+    defaultOn?: string;
+    /** The radio group's accessible name. */
+    label?: string;
+}
+
+/** One option: a ButtonBlock carrying its key, holding its words. */
+export function buildSegmentedOption(create: CompositeNodeFactory, words: SegmentedOptionWords): CompositeNode {
+    const option = make(create, `${words.key}-option`, Type.ButtonBlock, SegmentedRole.Option, Style.Option, {}, 'Option');
+    option.itemKey = words.key;
+    const label = make(create, `${words.key}-label`, Type.Text, null, Style.Label, { content: words.label, tag: 'span' }, 'Text');
+    writeStyles(label, LABEL_BASE);
+    option.children = [label];
+    return option;
+}
+
+/** A fresh Segmented control: Monthly · Yearly, Monthly on, named "Billing period" (board 10 ▸ Palette). */
+export function buildSegmentedRecipe(create: CompositeNodeFactory, options: SegmentedOptions = {}): CompositeNode {
+    const words = options.options ?? SEGMENTED_WORDS;
+    const root = make(create, 'segmented', Type.Container, SegmentedRole.Segmented, Style.Root, {}, 'Segmented');
+    root.children = words.map(w => buildSegmentedOption(create, w));
+    writeProp(root, SegmentedTrait.DefaultOn, options.defaultOn && words.some(w => w.key === options.defaultOn) ? options.defaultOn : words[0]?.key ?? '');
+    writeProp(root, SegmentedTrait.Label, options.label ?? SEGMENTED_NAME);
+    return root;
+}
+
+// ── reading a tree ──────────────────────────────────────────────────────────────────────────────
+
+export function isSegmentedRoot(node: { role?: string | null } | null | undefined): boolean {
+    return node?.role === SegmentedRole.Segmented;
+}
+
+/** The options in order. */
+export function segmentedOptions(root: CompositeNode | null | undefined): CompositeNode[] {
+    return (root?.children ?? []).filter(c => c.role === SegmentedRole.Option);
+}
+
+/** The key an option renders with: its own key, else its index among the options. */
+export function segmentedOptionKey(option: CompositeNode, index: number): string {
+    return option.itemKey || `item-${index}`;
+}
+
+/** Every option's key, in order. */
+export function segmentedKeys(root: CompositeNode | null | undefined): string[] {
+    return segmentedOptions(root).map((o, i) => segmentedOptionKey(o, i));
+}
+
+/** The words an option shows: its first Text that is not inside its badge. */
+export function segmentedOptionLabelNodeOf(option: CompositeNode): CompositeNode | undefined {
+    for (const child of option.children ?? []) {
+        if (child.role === SegmentedRole.Badge) continue;
+        if (child.type === Type.Text) return child;
+        let hit: CompositeNode | undefined;
+        walkComposite(child, n => { if (!hit && n.type === Type.Text) hit = n; });
+        if (hit) return hit;
+    }
+    return undefined;
+}
+
+const stripTags = (v: unknown) => String(v ?? '').replace(/<[^>]*>/g, '').trim();
+
+/** An option's name in the Options list, the layer tree, the item pickers and "Showing on canvas": its words. */
+export function segmentedOptionLabel(option: CompositeNode): string {
+    const label = segmentedOptionLabelNodeOf(option);
+    return label ? stripTags(readProp(label, 'content')) : '';
+}
+
+/** Options ▸ rename: the option's words. */
+export function renameSegmentedOption(option: CompositeNode, words: string): boolean {
+    const label = segmentedOptionLabelNodeOf(option);
+    return !!label && writeProp(label, 'content', words);
+}
+
+/** The radio group's accessible name (empty when unnamed). */
+export function segmentedLabel(root: CompositeNode | null | undefined): string {
+    return root ? String(readProp(root, SegmentedTrait.Label) ?? '').trim() : '';
+}
+
+/** The option on by default: the stored key when it still names an option, else the first option. */
+export function segmentedDefaultOn(root: CompositeNode | null | undefined): string | null {
+    const keys = segmentedKeys(root);
+    const stored = root ? String(readProp(root, SegmentedTrait.DefaultOn) ?? '') : '';
+    return keys.includes(stored) ? stored : keys[0] ?? null;
+}
+
+/** Behaviour ▸ On by default and Accessibility ▸ Name. False when the root has no such trait. */
+export function setSegmentedBehaviour(root: CompositeNode, patch: { defaultOn?: string; label?: string }): boolean {
+    let ok = true;
+    if (patch.defaultOn !== undefined) ok = writeProp(root, SegmentedTrait.DefaultOn, patch.defaultOn) && ok;
+    if (patch.label !== undefined) ok = writeProp(root, SegmentedTrait.Label, patch.label) && ok;
+    return ok;
+}
+
+// ── editing (Options list, toolbar ▸ Add option, the structure guard) ───────────────────────────
+
+export enum SegmentedEditRefusal {
+    /** Q40: a Segmented control keeps at least two options. */
+    MinOptions = 'min-options',
+    /** Q40: a Segmented control holds four options at most. */
+    MaxOptions = 'max-options',
+}
+
+/** Why adding an option to `root` is refused (four already), or null. */
+export function segmentedAddRefusal(root: CompositeNode | null | undefined): SegmentedEditRefusal | null {
+    return root && segmentedOptions(root).length >= SEGMENTED_MAX_OPTIONS ? SegmentedEditRefusal.MaxOptions : null;
+}
+
+/** Why removing an option from `root` is refused (two left), or null. */
+export function segmentedRemovalRefusal(root: CompositeNode | null | undefined, node?: CompositeNode | null): SegmentedEditRefusal | null {
+    if (!root || (node && node.role !== SegmentedRole.Option)) return null;
+    return segmentedOptions(root).length <= SEGMENTED_MIN_OPTIONS ? SegmentedEditRefusal.MinOptions : null;
+}
+
+/** A key no option of `root` holds yet (`k3`…). */
+export function nextSegmentedKey(root: CompositeNode): string {
+    const taken = new Set(segmentedOptions(root).map(o => o.itemKey).filter(Boolean));
+    let n = segmentedOptions(root).length + 1;
+    while (taken.has(`k${n}`)) n++;
+    return `k${n}`;
+}
+
+/** Options ▸ Add option (and the toolbar's "Add option"): a fresh option after `after` (or at the end). Null when
+ *  refused (four already). */
+export function addSegmentedOption(root: CompositeNode, create: CompositeNodeFactory, after?: CompositeNode | null,
+    words: string = SEGMENTED_NEW_OPTION_WORDS): CompositeNode | null {
+    if (segmentedAddRefusal(root)) return null;
+    const option = buildSegmentedOption(create, { key: nextSegmentedKey(root), label: words });
+    const children = [...(root.children ?? [])];
+    const at = after ? children.indexOf(after) : -1;
+    children.splice(at < 0 ? children.length : at + 1, 0, option);
+    root.children = children;
+    return option;
+}
+
+/** Options ▸ ✕: remove an option. False when refused (two left) or `option` is not one of the root's. A removed
+ *  default hands "On by default" to the first option left. */
+export function removeSegmentedOption(root: CompositeNode, option: CompositeNode): boolean {
+    if (segmentedRemovalRefusal(root, option) || !segmentedOptions(root).includes(option)) return false;
+    const wasDefault = segmentedDefaultOn(root) === option.itemKey;
+    root.children = (root.children ?? []).filter(c => c !== option);
+    if (wasDefault) writeProp(root, SegmentedTrait.DefaultOn, segmentedKeys(root)[0] ?? '');
+    return true;
+}
+
+/** Options ▸ drag to reorder: move an option to `toIndex` among the options. */
+export function moveSegmentedOption(root: CompositeNode, option: CompositeNode, toIndex: number): boolean {
+    const children = [...(root.children ?? [])];
+    const from = children.indexOf(option);
+    if (from < 0 || option.role !== SegmentedRole.Option) return false;
+    children.splice(from, 1);
+    const options = children.filter(c => c.role === SegmentedRole.Option);
+    const anchor = options[Math.max(0, Math.min(toIndex, options.length))];
+    children.splice(anchor ? children.indexOf(anchor) : children.length, 0, option);
+    root.children = children;
+    return true;
+}
+
+/** The saving badge inside an option, or undefined. */
+export function segmentedBadgeOf(option: CompositeNode | null | undefined): CompositeNode | undefined {
+    return (option?.children ?? []).find(c => c.role === SegmentedRole.Badge);
+}
+
+/** Option ▸ Saving badge (Q33): stamp the badge (`badge-success` › Icon + Text, the placeholder words) inside the
+ *  option, after its words — or remove it. Returns the badge stamped, or null (removed / nothing changed). */
+export function setSegmentedBadge(option: CompositeNode, on: boolean, create?: CompositeNodeFactory): CompositeNode | null {
+    const existing = segmentedBadgeOf(option);
+    if (!on) {
+        if (existing) option.children = (option.children ?? []).filter(c => c !== existing);
+        return null;
+    }
+    if (existing || !create) return null;
+    const badge = buildBadge(create, { tone: SEGMENTED_BADGE_TONE, text: SEGMENTED_BADGE_WORDS, key: `${option.itemKey ?? 'option'}-badge` });
+    badge.role = SegmentedRole.Badge;
+    badge.label = 'Badge';
+    writeStyles(badge, BADGE_IN_OPTION);
+    option.children = [...(option.children ?? []), badge];
+    return badge;
+}
+
+/** Every "Option on" (`trigger-on`) state inside an option points at ITS option — the part that carries
+ *  `data-iox-on` while it is on. */
+export function segmentedItemTriggerIds(root: CompositeNode): void {
+    for (const option of segmentedOptions(root)) {
+        if (!option.id) continue;
+        walkComposite(option, n => {
+            if (n === option || !n.stateStyles?.[ITEM_OPEN_STATE]) return;
+            n.stateTriggers = { ...(n.stateTriggers ?? {}), [ITEM_OPEN_STATE]: option.id! };
+        });
+    }
+}
+
+// ── state and attributes (both renderers, SSR included) ────────────────────────────────────────
+
+/** A Segmented control behaves like a horizontal Tabs activated by a click — only its keys and markup differ. */
+export const SEGMENTED_BEHAVIOUR: Readonly<TabsBehaviour> = { activateOn: TabsActivateOn.Click, orientation: TabsOrientation.Horizontal };
+
+/** The render scope of one Segmented control: its scope id, every option key in order, the one on at first paint (its
+ *  default) and its name — ONE decision for both engine paths. */
+export function segmentedScopeFor(root: CompositeNode, rootCssId: string, rowKeys: ReadonlyArray<string> = []): TabsScope {
+    const keys = segmentedKeys(root);
+    return {
+        kind: CompositeKind.Segmented,
+        rootId: compositeScopeId(rootCssId, rowKeys),
+        behaviour: SEGMENTED_BEHAVIOUR,
+        keys,
+        active: segmentedDefaultOn(root),
+        label: segmentedLabel(root),
+    };
+}
+
+/** The root: the radio group, named; its default and (inside repeated rows) its scope id ride on it. */
+export function segmentedRootAttributes(label: string, defaultOn: string | null, scopeId?: string): DomAttributes {
+    return {
+        [COMPOSITE_ATTRIBUTE]: CompositeKind.Segmented,
+        role: 'radiogroup',
+        ...(label ? { 'aria-label': label } : {}),
+        ...(defaultOn ? { [DEFAULT_ON_ATTRIBUTE]: defaultOn } : {}),
+        ...(scopeId ? { [SCOPE_ATTRIBUTE]: scopeId } : {}),
+    };
+}
+
+/** The root's attributes read off the node itself (the engine writes a root's own attributes from its parent's scope). */
+export function segmentedRootAttributesOf(root: CompositeNode, scopeId?: string): DomAttributes {
+    return segmentedRootAttributes(segmentedLabel(root), segmentedDefaultOn(root), scopeId);
+}
+
+/** An option: a real button announced as a radio — checked = the one option in the Tab order (roving tabindex). */
+export function segmentedOptionAttributes(key: string, on: boolean): DomAttributes {
+    return {
+        type: 'button',
+        role: 'radio',
+        'aria-checked': on ? 'true' : 'false',
+        tabindex: on ? '0' : '-1',
+        [ITEM_KEY_ATTRIBUTE]: key,
+        ...(on ? { [ON_ATTRIBUTE]: '' } : {}),
+    };
+}
+
+/** The attributes a part of a Segmented control writes on its own element (both engine paths, SSR included). */
+export function segmentedPartAttributes(node: { role?: string | null }, scope: TabsScope, key: string | null, rowScoped = false): DomAttributes {
+    switch (node.role) {
+        case SegmentedRole.Segmented: return segmentedRootAttributes(scope.label, scope.active, rowScoped ? scope.rootId : undefined);
+        case SegmentedRole.Option: return key ? segmentedOptionAttributes(key, scope.active === key) : {};
+        default: return {};
+    }
+}
+
+/**
+ * The APG radio group's keys on an option: → / ↓ the next option, ← / ↑ the previous — ← and → follow the reading
+ * direction (mirrored under RTL: ← is the next option), ↑ ↓ always the DOM order. Every move wraps and turns the option
+ * on. Space / Enter are the button's own (a click: it turns on).
+ */
+export function segmentedKeyAction(key: string, rtl = false): AccordionKeyAction | null {
+    switch (key) {
+        case 'ArrowDown': return AccordionKeyAction.Next;
+        case 'ArrowUp': return AccordionKeyAction.Previous;
+        case 'ArrowRight': return rtl ? AccordionKeyAction.Previous : AccordionKeyAction.Next;
+        case 'ArrowLeft': return rtl ? AccordionKeyAction.Next : AccordionKeyAction.Previous;
+        default: return null;
+    }
+}

package/src/composite-core/structure.ts

@@ -1,4 +1,4 @@
-import { AccordionRole, DisclosureRole, TabsRole } from './composite-kinds';
+import { AccordionRole, DisclosureRole, SegmentedRole, TabsRole } from './composite-kinds';
 import { CardPart, CardRole } from './card';
 import { SLIDER_TYPE, SliderRole } from './slider';
 
@@ -51,6 +51,11 @@ export const COMPOSITE_ROLE_SPECS: Readonly<Record<string, CompositeRoleSpec>> =
     [TabsRole.Panels]: { parent: TabsRole.Tabs, locked: true, accepts: [TabsRole.Panel] },
     [TabsRole.Trigger]: { parent: TabsRole.List, pinned: true },
     [TabsRole.Panel]: { parent: TabsRole.Panels, pinned: true },
+    // CC4b — a Segmented control holds only its options (each may be deleted — two stay — but never moved out); an
+    // option's saving badge is optional (Option ▸ Saving badge) and stays in its option.
+    [SegmentedRole.Segmented]: { parent: null, accepts: [SegmentedRole.Option] },
+    [SegmentedRole.Option]: { parent: SegmentedRole.Segmented, pinned: true },
+    [SegmentedRole.Badge]: { parent: SegmentedRole.Option, pinned: true },
     // CC3 — a Slider's controls are its own direct children (Swiper is handed them). The pause control stays while
     // Autoplay is on (WCAG 2.2.2): the Autoplay switch removes it, never Delete. The arrows and the dots follow
     // their switches and may be deleted.

package/src/composite-core/tabs.ts

@@ -5,7 +5,7 @@ import {
     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 { CompositeKind, ExclusiveCompositeKind, TabsRole } from './composite-kinds';
 import {
     clearLayerStyles, CompositeNode, CompositeNodeFactory, makeCompositePart, readProp, walkComposite, writeLayerStyles, writeProp, writeStyles,
 } from './composite-node';
@@ -409,8 +409,11 @@ export function tabsItemTriggerIds(root: CompositeNode): void {
 
 // ── 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. */
+/** The render scope of one EXCLUSIVE composite (a Tabs; a Segmented control, CC4b): its kind, scope id, behaviour, every
+ *  item key in order and the one that is on. */
 export interface TabsScope {
+    /** The exclusive kind it renders (a scope without one is a Tabs'). */
+    kind?: ExclusiveCompositeKind;
     rootId: string;
     behaviour: TabsBehaviour;
     keys: ReadonlyArray<string>;
@@ -420,7 +423,7 @@ export interface TabsScope {
 }
 
 export function tabsScope(rootId: string, behaviour: TabsBehaviour, keys: ReadonlyArray<string>, label = ''): TabsScope {
-    return { rootId, behaviour, keys, active: keys[0] ?? null, label };
+    return { kind: CompositeKind.Tabs, 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). */

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

@@ -160,14 +160,19 @@ export function auditDesignContrast(rows: ReadonlyArray<DesignTokenLike>, mode:
                     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;
+                    const on = state === 'on' ? (e.on as StyleMap | undefined) : undefined;
+                    const mark = on?.['borderColor'];
                     if (mark) check(e.id, 'on mark', parseCssColour(resolveIn(values, mark), ink), bgs, WCAG_AA_UI);
+                    // CC4b: a Segmented option's mark IS its on fill (no border) — the fill against the ground it sits on.
+                    else if (on?.['backgroundColor']) for (const f of fill) check(e.id, 'on mark', f, 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);
-                        const focus = (e.focus as StyleMap | undefined)?.['boxShadow'];
-                        if (focus) check(e.id, 'focus ring', ringColour(resolveIn(values, focus), ink), bgs, WCAG_AA_UI);
                     }
+                    // Every focus ring an element style draws, on every ground the element sits on (CC4b: a Segmented
+                    // option on its track — not only the buttons).
+                    const focus = state === 'base' ? (e.focus as StyleMap | undefined)?.['boxShadow'] : undefined;
+                    if (focus) check(e.id, 'focus ring', ringColour(resolveIn(values, focus), ink), bgs, WCAG_AA_UI);
                 }
             }
             for (const part of FORM_PARTS) {