@vectoriox/iox-ui 5.38.0 → 5.39.0

package/generation-core/index.d.ts

@@ -852,6 +852,46 @@ declare const SPEC_SITE_PATTERNS: {
             }];
         };
     };
+    readonly "feature.tabbed": {
+        readonly family: "feature";
+        readonly label: "Features — tabs that switch";
+        readonly node: {
+            readonly t: "Section";
+            readonly es: "section";
+            readonly c: readonly [{
+                readonly t: "Container";
+                readonly es: "box";
+                readonly lay: {
+                    readonly display: "flex";
+                    readonly flexDirection: "column";
+                    readonly gap: "14px";
+                    readonly maxWidth: "1100px";
+                    readonly width: "100%";
+                    readonly margin: "0px auto 0px auto";
+                };
+                readonly c: readonly [{
+                    readonly t: "Text";
+                    readonly es: "eyebrow";
+                    readonly slot: "eyebrow";
+                    readonly ph: "copy";
+                    readonly text: "What we offer";
+                }, {
+                    readonly t: "Heading";
+                    readonly es: "h2";
+                    readonly level: "h2";
+                    readonly slot: "title";
+                    readonly ph: "copy";
+                    readonly text: "What we design";
+                }, {
+                    readonly t: "Container";
+                    readonly recipe: "tabs";
+                    readonly src: "$binding?";
+                    readonly ph: "copy";
+                    readonly name: "What we design";
+                }];
+            }];
+        };
+    };
     readonly "hero.full-bleed-media": {
         readonly family: "hero";
         readonly label: "Hero — words over a background video";
@@ -1400,6 +1440,9 @@ declare enum PatternRecipe {
     /** CC2: the Accordion — Manual (three placeholder items), or From content when the section names a list
      *  `binding` (`src: '$binding?'`): one template item bound to the type's question / answer fields. */
     Accordion = "accordion",
+    /** CC4a: Tabs — Manual (three placeholder tabs), or From content when the section names a list `binding`: the tab
+     *  list and the panels are both Repeaters over it, one row giving its tab AND its panel. */
+    Tabs = "tabs",
     /** CC3: the accessible carousel — a named Slider whose controls are parts, one quote per slide (placeholders). */
     Carousel = "carousel",
     /** CC3: the Lightbox — a Dialog holding a Slider over the node's `src` (the gallery's own source). */

package/index.d.ts

@@ -1706,21 +1706,26 @@ declare enum ComponentState {
     Current = "current",
     /** A composite part that IS on — an open accordion item, its header, its panel (board 9 "Open"). */
     On = "on",
-    /** A part INSIDE an item, styled by its item being open (board 9 "Item open") — a TARGETED state: its
-     *  trigger is the item (`stateTriggers['trigger-on']`), compiled through `targetedStateSelector`. */
+    /** A part INSIDE an item, styled by its item being open (board 9 "Item open"; "Tab active" inside a tab or a panel)
+     *  — a TARGETED state: its trigger is the item (`stateTriggers['trigger-on']`), compiled through
+     *  `targetedStateSelector`. On a node OUTSIDE every item (composite T20, CC4a) the author PICKS the item — "when tab
+     *  Night is on" — the same state and the same `:has()` scoped to the nearest common ancestor. */
     ItemOpen = "trigger-on"
 }
 /** The attribute selector each (non-targeted) component state compiles to. */
 declare const COMPONENT_STATE_SELECTOR: Readonly<Record<string, string>>;
 /** The composite roles that are themselves "on" when their item is open (they carry `data-iox-on`): an accordion's
- *  item, header and panel; a disclosure (its own item), its toggle and its panel (CC2.1). The main entry does not
- *  import composite-core, so the roles are spelled here — `style-compiler.spec` pins them to its enums. */
+ *  item, header and panel; a disclosure (its own item), its toggle and its panel (CC2.1); a tab and its panel (CC4a —
+ *  "Active"). The main entry does not import composite-core, so the roles are spelled here — `style-compiler.spec` pins
+ *  them to its enums. */
 declare const ON_STATE_ROLES: ReadonlyArray<string>;
 /**
  * The component states a node offers in the Style panel's "Component state" group: Current page (a link),
- * Open (an accordion's item, header or panel), Item open (any other part inside an item — `insideItem`).
+ * Open / Active (an accordion's item, header or panel; a tab or its panel), Item open (any other part inside an item —
+ * `insideItem`), and — on a node outside every item, on a page that has items to pick (`itemsToPick`, composite T20) —
+ * the same Item open state with a picked trigger.
  */
-declare function componentStatesFor(type: string | null | undefined, role?: string | null, insideItem?: boolean): ComponentState[];
+declare function componentStatesFor(type: string | null | undefined, role?: string | null, insideItem?: boolean, itemsToPick?: boolean): ComponentState[];
 /**
  * What follows `.iox-node-<id>` in a stored state's rule: `:hover`, `:focus-visible`, or a component
  * state's attribute selector (`[aria-current="page"]`). Shared by the builder canvas and both engine paths.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vectoriox/iox-ui",
-  "version": "5.38.0",
+  "version": "5.39.0",
   "peerDependencies": {
     "@angular/common": ">=20.0.0",
     "@angular/core": ">=20.0.0",

package/src/actions-core/element-actions.ts

@@ -1,9 +1,11 @@
-import { AccordionRole, CompositeItemAction, DisclosureRole, SLIDE_TO_ROW } from '@vectoriox/iox-ui/composite-core';
+import { AccordionRole, CompositeItemAction, DisclosureRole, SLIDE_TO_ROW, TabsRole } from '@vectoriox/iox-ui/composite-core';
 
 import { ActionDescriptor } from './action.model';
 
 /** The items an item action may target: an accordion's item, or a disclosure (its own one item). */
 const ITEM_TARGET_ROLES = [AccordionRole.Item, DisclosureRole.Disclosure];
+/** Open also takes a TAB (CC4a): it turns it on. A Tabs always shows one, so Close and Toggle never aim at one. */
+const OPEN_TARGET_ROLES = [...ITEM_TARGET_ROLES, TabsRole.Trigger];
 
 /**
  * The ELEMENT action catalog (actions plan A1) — what a node can DO, as data. One list feeds the
@@ -58,7 +60,7 @@ export const ELEMENT_ACTION_DESCRIPTORS: readonly ActionDescriptor[] = Object.fr
     // opens FAQ item 3). The canvas RUNS them, like the dialog actions: it is the same runtime, and an item you
     // cannot open from the button is a button you cannot design.
     { type: 'openItem',   labelKey: 'builder.actions.openItem',   kind: 'instant', group: 'item', builderBehaviour: 'run',
-      target: { required: true, roles: ITEM_TARGET_ROLES } },
+      target: { required: true, roles: OPEN_TARGET_ROLES } },
     { type: 'closeItem',  labelKey: 'builder.actions.closeItem',  kind: 'instant', group: 'item', builderBehaviour: 'run',
       target: { required: true, roles: ITEM_TARGET_ROLES } },
     { type: 'toggleItem', labelKey: 'builder.actions.toggleItem', kind: 'instant', group: 'item', builderBehaviour: 'run',

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

@@ -3,7 +3,7 @@ import {
     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';
+import { COMPOSITE_KIND_ROLES, CompositeKind, ToggleCompositeKind } from './composite-kinds';
 
 /**
  * The Accordion's RUNTIME (CC2) — ONE copy, DOM only, for the builder canvas and the live site (both engine
@@ -33,7 +33,7 @@ export const ITEM_ON_EVENT = 'iox-item-on';
 export const ITEM_OFF_EVENT = 'iox-item-off';
 
 const KIND_ROOT = (kind: CompositeKind) => `[${COMPOSITE_ATTRIBUTE}="${kind}"]`;
-const ROOT_SELECTOR = Object.values(CompositeKind).map(KIND_ROOT).join(', ');
+const ROOT_SELECTOR = (Object.keys(COMPOSITE_KIND_ROLES) as ToggleCompositeKind[]).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)}`;
@@ -75,7 +75,7 @@ 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 {
+export function accordionRootOfItem(item: HTMLElement): HTMLElement | null {
     return kindOf(item) === CompositeKind.Disclosure && item.matches(KIND_ROOT(CompositeKind.Disclosure)) ? item : closestAccordion(item.parentElement);
 }
 
@@ -421,18 +421,6 @@ export enum CompositeItemAction {
     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;
 

package/src/composite-core/accordion.ts

@@ -1,7 +1,7 @@
 import { readOwnedTrait } from '@vectoriox/iox-ui/design-core';
 
 import {
-    AccordionRole, COMPOSITE_KIND_ROLES, CompositeKind, compositeKindOfRole,
+    AccordionRole, COMPOSITE_KIND_ROLES, CompositeKind, compositeKindOfRole, isToggleKind,
 } from './composite-kinds';
 import {
     CompositeNode, CompositeNodeFactory, findByRole, makeCompositePart, readProp, removeFromComposite, walkComposite, writeProp, writeStyles,
@@ -233,7 +233,8 @@ export function setAccordionBehaviour(root: CompositeNode, patch: Partial<Accord
 
 /** 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];
+    const kind = compositeKindOfRole(node.role);
+    return COMPOSITE_KIND_ROLES[isToggleKind(kind) ? kind : CompositeKind.Accordion];
 }
 
 /** The header of an item (either kind). */
@@ -479,6 +480,7 @@ export interface AccordionDomIds {
 const DOM_ID_PREFIX: Readonly<Record<CompositeKind, string>> = {
     [CompositeKind.Accordion]: 'iox-acc',
     [CompositeKind.Disclosure]: 'iox-dis',
+    [CompositeKind.Tabs]: 'iox-tab',
 };
 
 /** The ARIA pairing ids of an item: unique per composite (its SCOPE id — `compositeScopeId`) and per item (its key). */

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

@@ -1,15 +1,23 @@
 /**
- * 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.
+ * The composites' kinds and roles. Two families:
+ * - OPEN/CLOSE (CC2 Accordion, CC2.1 Disclosure — composite plan T9 / T21): a Disclosure is a one-item accordion whose
+ *   ROOT is its item, so both run the same state machine, attribute planners and runtime (`accordion-runtime.ts`);
+ * - EXCLUSIVE (CC4 Tabs — composite T17; the Segmented control joins in CC4b): exactly one item is on, a trigger and
+ *   its panel paired by `itemKey` (`tabs.ts`, `exclusive-runtime.ts`).
+ * Every consumer that treats "an item", "a trigger" or "a panel" alike asks these predicates, never a role literal.
  */
 
 export enum CompositeKind {
     Accordion = 'accordion',
     Disclosure = 'disclosure',
+    Tabs = 'tabs',
 }
 
+/** The kinds the open/close runtime runs (`AccordionRuntime`). */
+export type ToggleCompositeKind = CompositeKind.Accordion | CompositeKind.Disclosure;
+/** The kinds the exclusive runtime runs (`ExclusiveRuntime`): one item on at a time, always one. */
+export type ExclusiveCompositeKind = CompositeKind.Tabs;
+
 export enum AccordionRole {
     Accordion = 'accordion',
     Item = 'accordion.item',
@@ -32,9 +40,22 @@ export enum DisclosureRole {
     Panel = 'disclosure.panel',
 }
 
+/**
+ * TABS (CC4a — composite T17). The tab LIST holds the triggers, the PANELS holder holds the panels; a tab and its panel
+ * share an `itemKey` (never their index — moving a tab keeps its own panel). From content (R3) the list and the panels
+ * holder are both Repeaters over the SAME source, one row giving its tab AND its panel (paired by the row's id).
+ */
+export enum TabsRole {
+    Tabs = 'tabs',
+    List = 'tabs.list',
+    Trigger = 'tabs.trigger',
+    Panels = 'tabs.panels',
+    Panel = 'tabs.panel',
+}
+
 interface RoleLike { role?: string | null }
 
-/** The roles each kind plays in the shared runtime. */
+/** The roles each open/close kind plays in the shared runtime. */
 export interface CompositeKindRoles {
     root: string;
     item: string;
@@ -43,17 +64,40 @@ export interface CompositeKindRoles {
     icon: string;
 }
 
-export const COMPOSITE_KIND_ROLES: Readonly<Record<CompositeKind, CompositeKindRoles>> = {
+export const COMPOSITE_KIND_ROLES: Readonly<Record<ToggleCompositeKind, 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 },
 };
 
+/** The roles each EXCLUSIVE kind plays: its root, the holder of its triggers, its triggers, and — when its items show
+ *  a panel (Tabs; a Segmented control has none) — the holder of its panels and the panels. */
+export interface ExclusiveKindRoles {
+    root: string;
+    list: string;
+    trigger: string;
+    panels: string | null;
+    panel: string | null;
+}
+
+export const EXCLUSIVE_KIND_ROLES: Readonly<Record<ExclusiveCompositeKind, ExclusiveKindRoles>> = {
+    [CompositeKind.Tabs]: { root: TabsRole.Tabs, list: TabsRole.List, trigger: TabsRole.Trigger, panels: TabsRole.Panels, panel: TabsRole.Panel },
+};
+
 const KINDS = Object.values(CompositeKind);
-const rolesOf = (pick: keyof CompositeKindRoles): ReadonlySet<string> => new Set(KINDS.map(k => COMPOSITE_KIND_ROLES[k][pick]));
+const TOGGLE_KINDS = Object.keys(COMPOSITE_KIND_ROLES) as ToggleCompositeKind[];
+const EXCLUSIVE_KINDS = Object.keys(EXCLUSIVE_KIND_ROLES) as ExclusiveCompositeKind[];
+const rolesOf = (pick: keyof CompositeKindRoles): ReadonlySet<string> => new Set(TOGGLE_KINDS.map(k => COMPOSITE_KIND_ROLES[k][pick]));
+const exclusiveRolesOf = (pick: keyof ExclusiveKindRoles): ReadonlySet<string> =>
+    new Set(EXCLUSIVE_KINDS.map(k => EXCLUSIVE_KIND_ROLES[k][pick]).filter((r): r is string => !!r));
 const ROOT_ROLES = rolesOf('root');
 const ITEM_ROLES = rolesOf('item');
 const TRIGGER_ROLES = rolesOf('trigger');
 const PANEL_ROLES = rolesOf('panel');
+const EXCLUSIVE_ROOT_ROLES = exclusiveRolesOf('root');
+const EXCLUSIVE_LIST_ROLES = exclusiveRolesOf('list');
+const EXCLUSIVE_TRIGGER_ROLES = exclusiveRolesOf('trigger');
+const EXCLUSIVE_PANELS_ROLES = exclusiveRolesOf('panels');
+const EXCLUSIVE_PANEL_ROLES = exclusiveRolesOf('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 {
@@ -61,6 +105,16 @@ export function compositeKindOfRole(role: string | null | undefined): CompositeK
     return (KINDS as string[]).includes(head ?? '') ? head as CompositeKind : null;
 }
 
+/** True for a kind the open/close runtime runs. */
+export function isToggleKind(kind: CompositeKind | null | undefined): kind is ToggleCompositeKind {
+    return !!kind && (TOGGLE_KINDS as string[]).includes(kind);
+}
+
+/** True for a kind the exclusive runtime runs. */
+export function isExclusiveKind(kind: CompositeKind | null | undefined): kind is ExclusiveCompositeKind {
+    return !!kind && (EXCLUSIVE_KINDS as string[]).includes(kind);
+}
+
 /** 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);
@@ -108,3 +162,63 @@ export function compositeItemOf<T extends RoleLike>(node: T, path: ReadonlyArray
     }
     return null;
 }
+
+// ── the exclusive family (CC4a Tabs) ───────────────────────────────────────────────────────────
+
+/** A root that runs the exclusive runtime (Tabs). */
+export function isExclusiveRoot(node: RoleLike | null | undefined): boolean {
+    return !!node?.role && EXCLUSIVE_ROOT_ROLES.has(node.role);
+}
+
+/** The holder of an exclusive composite's triggers (a tab list): it takes only triggers. */
+export function isExclusiveList(node: RoleLike | null | undefined): boolean {
+    return !!node?.role && EXCLUSIVE_LIST_ROLES.has(node.role);
+}
+
+/** One of an exclusive composite's triggers (a tab): pressing it turns its item on. */
+export function isExclusiveTrigger(node: RoleLike | null | undefined): boolean {
+    return !!node?.role && EXCLUSIVE_TRIGGER_ROLES.has(node.role);
+}
+
+/** The holder of an exclusive composite's panels: it takes only panels. */
+export function isExclusivePanels(node: RoleLike | null | undefined): boolean {
+    return !!node?.role && EXCLUSIVE_PANELS_ROLES.has(node.role);
+}
+
+/** One of an exclusive composite's panels (a tab panel): shown only while its item is on. */
+export function isExclusivePanel(node: RoleLike | null | undefined): boolean {
+    return !!node?.role && EXCLUSIVE_PANEL_ROLES.has(node.role);
+}
+
+/** True for a trigger or a panel — a part that IS one item of an exclusive composite (it carries the `itemKey`). */
+export function isExclusiveItemPart(node: RoleLike | null | undefined): boolean {
+    return isExclusiveTrigger(node) || isExclusivePanel(node);
+}
+
+/** True for any part of a Tabs (its root included). */
+export function isTabsPart(node: RoleLike | null | undefined): boolean {
+    return compositeKindOfRole(node?.role) === CompositeKind.Tabs;
+}
+
+/** A root of either family — anything that runs a composite runtime. */
+export function isAnyCompositeRoot(node: RoleLike | null | undefined): boolean {
+    return isCompositeRoot(node) || isExclusiveRoot(node);
+}
+
+/** The exclusive root a node belongs to (the node itself when it is one), or null. `path` = its ancestors, root first. */
+export function exclusiveRootOf<T extends RoleLike>(node: T, path: ReadonlyArray<T>): T | null {
+    if (isExclusiveRoot(node)) return node;
+    for (let i = path.length - 1; i >= 0; i--) if (isExclusiveRoot(path[i])) return path[i];
+    return null;
+}
+
+/** The trigger or panel a node sits in (itself when it is one) inside an exclusive composite, or null. A nested
+ *  exclusive root ends the walk. */
+export function exclusiveItemPartOf<T extends RoleLike>(node: T, path: ReadonlyArray<T>): T | null {
+    if (isExclusiveItemPart(node)) return node;
+    for (let i = path.length - 1; i >= 0; i--) {
+        if (isExclusiveItemPart(path[i])) return path[i];
+        if (isExclusiveRoot(path[i])) return null;
+    }
+    return null;
+}

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

@@ -0,0 +1,68 @@
+import {
+    accordionRootOfItem, accordionRuntimeOf, AccordionRuntime, AccordionRuntimeOptions, attachAccordionAt, closestAccordionItem, CompositeItemAction,
+    isAccordionItemOn, onAccordionItemState,
+} from './accordion-runtime';
+import { COMPOSITE_ATTRIBUTE } from './accordion';
+import { CompositeKind, isExclusiveKind } from './composite-kinds';
+import {
+    attachExclusiveAt, closestExclusive, closestExclusiveItemPart, ExclusiveRuntime, exclusiveRuntimeOf, ExclusiveRuntimeOptions, isExclusiveItemOn,
+    onExclusiveItemState,
+} from './exclusive-runtime';
+
+/**
+ * The composites' runtimes behind ONE door (CC4a): the open/close runtime (Accordion, Disclosure) and the exclusive
+ * runtime (Tabs; the Segmented control in CC4b). The engine attaches whichever a rendered root needs; the interaction
+ * engines (builder canvas and live site) ask these for `itemOn` / `itemOff` and run the item actions through them —
+ * never a family's own function, so a new kind joins without touching either engine.
+ */
+
+export type CompositeRuntime = AccordionRuntime | ExclusiveRuntime;
+
+/** Attach the runtime a rendered composite root needs (its `data-iox-composite`), unless it runs one already. Returns
+ *  the NEW runtime, or null. */
+export function attachCompositeAt(root: HTMLElement, options: Omit<AccordionRuntimeOptions, 'rootId' | 'behaviour'> & Omit<ExclusiveRuntimeOptions, 'behaviour'> = {}): CompositeRuntime | null {
+    const kind = root.getAttribute(COMPOSITE_ATTRIBUTE) as CompositeKind | null;
+    if (isExclusiveKind(kind)) return attachExclusiveAt(root, { observe: options.observe });
+    return attachAccordionAt(root, { observe: options.observe, reducedMotion: options.reducedMotion });
+}
+
+/** The nearer of the item elements `el` sits in — an accordion item / a disclosure, or a tab / a tab panel. */
+function nearestItem(el: Element | null | undefined): { el: HTMLElement; exclusive: boolean } | null {
+    const toggle = closestAccordionItem(el);
+    const exclusive = closestExclusiveItemPart(el);
+    if (!toggle && !exclusive) return null;
+    if (toggle && (!exclusive || exclusive.contains(toggle))) return { el: toggle, exclusive: false };
+    return { el: exclusive!, exclusive: true };
+}
+
+/** Subscribe to the item `el` sits in turning on / off — what the `itemOn` / `itemOff` interaction triggers listen to,
+ *  in both families. Returns the unsubscribe. */
+export function onCompositeItemState(el: Element, on: boolean, handler: () => void): () => void {
+    const item = nearestItem(el);
+    if (!item) return () => undefined;
+    return item.exclusive ? onExclusiveItemState(item.el, on, handler) : onAccordionItemState(item.el, on, handler);
+}
+
+/** True when the item `el` sits in is on now (an open accordion item, the active tab or its panel). */
+export function isCompositeItemOn(el: Element): boolean {
+    const item = nearestItem(el);
+    if (!item) return false;
+    return item.exclusive ? isExclusiveItemOn(item.el) : isAccordionItemOn(item.el);
+}
+
+/**
+ * Run an item action on the element of an ITEM — an accordion item, a disclosure, or a tab (CC4a: `openItem` turns it
+ * on; a Tabs always shows one, so Close and Toggle leave it) — the `openItem` / `closeItem` / `toggleItem` interaction
+ * actions, on the canvas and on the live site through this one function. Returns whether the item shows on
+ * afterwards, or null when `el` is in no running composite.
+ */
+export function runCompositeItemAction(el: Element | null | undefined, action: CompositeItemAction): boolean | null {
+    const item = nearestItem(el);
+    if (!item) return null;
+    if (item.exclusive) {
+        const runtime = exclusiveRuntimeOf(closestExclusive(item.el));
+        return runtime ? runtime.run(action === CompositeItemAction.Open, runtime.keyOf(item.el)) : null;
+    }
+    const runtime = accordionRuntimeOf(accordionRootOfItem(item.el));
+    return runtime ? runtime.run(action, runtime.keyOf(item.el)) : null;
+}