@vectoriox/iox-ui 5.36.0 → 5.37.0

package/actions-core/index.d.ts

@@ -1,3 +1,5 @@
+import { CompositeItemAction } from '@vectoriox/iox-ui/composite-core';
+
 /**
  * The ONE descriptor shape for everything an author can put in an ordered action list —
  * a form's after-submit steps today, element behaviour actions (A1) next. Promoted out of
@@ -8,7 +10,7 @@
 /** How a step executes — decides which editor fields appear (timing only for `animated`). */
 type ActionKind = 'animated' | 'instant' | 'server';
 /** Picker grouping. Flat lists die at ~10 entries; the group is data, never a second list. */
-type ActionGroup = 'motion' | 'visibility' | 'navigate' | 'dialog' | 'form' | 'data' | 'consent' | 'service';
+type ActionGroup = 'motion' | 'visibility' | 'navigate' | 'dialog' | 'item' | 'form' | 'data' | 'consent' | 'service';
 /**
  * What a step does inside the live builder canvas (the canvas RUNS interactions):
  * `run` for real (open the dialog), `simulate` announce-only (navigate), `inert` with a
@@ -26,10 +28,12 @@ interface ActionParamSpec {
         labelKey: string;
     }[];
 }
-/** Does this action point at another node — and may it be any node or only certain types? */
+/** Does this action point at another node — and may it be any node, or only certain types / composite roles? */
 interface ActionTargetSpec {
     required: boolean;
     types?: string[];
+    /** Only nodes playing one of these composite roles (`openItem` targets an accordion item or a disclosure). */
+    roles?: string[];
 }
 /**
  * One row of an action catalog. Every field beyond `type`/`labelKey` is optional so the
@@ -105,6 +109,11 @@ declare const SERVER_ELEMENT_ACTION_TYPES: ReadonlySet<string>;
 /** The Tier-A behaviour executors' dispatch set (A1c) — the engines branch on it beside
  *  DIALOG/SWIPER. Dialog actions have their own set; context/visibility stay in the legacy path. */
 declare const BEHAVIOUR_ACTION_TYPES: ReadonlySet<string>;
+/** The item actions' dispatch set (T14) and what each does to its item — the engines branch on it beside
+ *  DIALOG/BEHAVIOUR, and composite-core `runCompositeItemAction` runs it on the target item's own runtime. */
+declare const ITEM_ACTION_TYPES: Readonly<Record<string, CompositeItemAction>>;
+/** The item action an action type runs, or null when it is not one. */
+declare function itemActionOf(type: string | null | undefined): CompositeItemAction | null;
 /** The consent actions' dispatch set (C3) — the engines branch on it beside DIALOG/BEHAVIOUR.
  *  `openConsentPreferences` is dialog-opening by nature and included so ONE branch owns consent. */
 declare const CONSENT_ACTION_TYPES: ReadonlySet<string>;
@@ -166,5 +175,5 @@ declare function dialogOpenerAttributes(node: OpenerNodeLike | null | undefined,
 /** The selector of every opener of one dialog (by its DOM id) — what a runtime updates on open/close. */
 declare function dialogOpenersSelector(dialogDomIdValue: string): string;
 
-export { BEHAVIOUR_ACTION_TYPES, CONSENT_ACTION_TYPES, DIALOG_ACTION_TYPE_SET, DIALOG_OPENER_ACTION_TYPES, DIALOG_OPENER_TRIGGER, DIALOG_SELECTOR, ELEMENT_ACTION_DESCRIPTORS, ELEMENT_ACTION_GROUP_ORDER, FORM_SUBMIT_ACTION_DESCRIPTORS, OpenerAttribute, SERVER_ELEMENT_ACTION_TYPES, addableActions, dialogDomId, dialogOpenerAttributes, dialogOpenersSelector, groupedElementActions, nodeIdOfDialogDomId, openedDialogId, resolveActionAvailability };
+export { BEHAVIOUR_ACTION_TYPES, CONSENT_ACTION_TYPES, DIALOG_ACTION_TYPE_SET, DIALOG_OPENER_ACTION_TYPES, DIALOG_OPENER_TRIGGER, DIALOG_SELECTOR, ELEMENT_ACTION_DESCRIPTORS, ELEMENT_ACTION_GROUP_ORDER, FORM_SUBMIT_ACTION_DESCRIPTORS, ITEM_ACTION_TYPES, OpenerAttribute, SERVER_ELEMENT_ACTION_TYPES, addableActions, dialogDomId, dialogOpenerAttributes, dialogOpenersSelector, groupedElementActions, itemActionOf, nodeIdOfDialogDomId, openedDialogId, resolveActionAvailability };
 export type { ActionAvailability, ActionAvailabilityContext, ActionAvailabilityState, ActionDescriptor, ActionGroup, ActionKind, ActionParamSpec, ActionTargetSpec, BuilderBehaviour, OpenerActionLike, OpenerInteractionLike, OpenerNodeLike };

package/composite-core/index.d.ts

@@ -41,6 +41,9 @@ interface CompositeNodeSpec {
     elementStyle?: string | null;
 }
 type CompositeNodeFactory = (spec: CompositeNodeSpec) => CompositeNode;
+/** A recipe part: a NEW node (`create`) playing `role` under `label`, with the layout `base` styles its recipe
+ *  gives it — its LOOK is its element style. Shared by every recipe (Accordion, Disclosure). */
+declare function makeCompositePart(create: CompositeNodeFactory, spec: CompositeNodeSpec, role: string | null, label: string | undefined, base?: Readonly<Record<string, string>>): CompositeNode;
 /** A content trait's value — `traits[].default` on a builder node, `props[name]` on a saved one. */
 declare function readProp(node: CompositeNode, name: string): unknown;
 /** Write a content trait. False when a builder node has no such trait (the value would be dropped). */
@@ -68,6 +71,68 @@ declare function parentInComposite(root: CompositeNode, node: CompositeNode): Co
 /** Detach `node` from its parent inside `root`. True when it was found. */
 declare function removeFromComposite(root: CompositeNode, node: CompositeNode): boolean;
 
+/**
+ * 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.
+ */
+declare enum CompositeKind {
+    Accordion = "accordion",
+    Disclosure = "disclosure"
+}
+declare enum AccordionRole {
+    Accordion = "accordion",
+    Item = "accordion.item",
+    Trigger = "accordion.trigger",
+    Icon = "accordion.icon",
+    Panel = "accordion.panel"
+}
+/**
+ * DISCLOSURE ("Read more") — one trigger, one panel. The root IS its item (it carries the item key and
+ * `data-iox-on`); the trigger holds two words, the one shown while closed (`more`) and the one shown while open
+ * (`less`), swapped by the Item open state — never by script.
+ */
+declare enum DisclosureRole {
+    Disclosure = "disclosure",
+    Trigger = "disclosure.trigger",
+    More = "disclosure.more",
+    Less = "disclosure.less",
+    Icon = "disclosure.icon",
+    Panel = "disclosure.panel"
+}
+interface RoleLike$1 {
+    role?: string | null;
+}
+/** The roles each kind plays in the shared runtime. */
+interface CompositeKindRoles {
+    root: string;
+    item: string;
+    trigger: string;
+    panel: string;
+    icon: string;
+}
+declare const COMPOSITE_KIND_ROLES: Readonly<Record<CompositeKind, CompositeKindRoles>>;
+/** The kind a role belongs to (`disclosure.panel` → Disclosure), or null for any other role. */
+declare function compositeKindOfRole(role: string | null | undefined): CompositeKind | null;
+/** A root that runs the open/close runtime (an Accordion or a Disclosure). */
+declare function isCompositeRoot(node: RoleLike$1 | null | undefined): boolean;
+/** An ITEM — an accordion's item, or a disclosure (its own item). */
+declare function isCompositeItem(node: RoleLike$1 | null | undefined): boolean;
+/** A trigger — rendered as a `<button>` that opens its item, never a link. */
+declare function isCompositeTrigger(node: RoleLike$1 | null | undefined): boolean;
+/** A panel — rendered inside the track + region the one hiding rule collapses. */
+declare function isCompositePanel(node: RoleLike$1 | null | undefined): boolean;
+declare function isDisclosureRoot(node: RoleLike$1 | null | undefined): boolean;
+/** True for any part of a disclosure (its root included). */
+declare function isDisclosurePart(node: RoleLike$1 | null | undefined): boolean;
+/** The composite root a node belongs to: the nearest ancestor (or the node itself) that is one. `path` = the
+ *  node's ancestors, root first. */
+declare function compositeRootOf<T extends RoleLike$1>(node: T, path: ReadonlyArray<T>): T | null;
+/** The item a node sits in — the nearest item of either kind (itself when it is one) — or null. An accordion
+ *  root ends the walk (its items are below it). */
+declare function compositeItemOf<T extends RoleLike$1>(node: T, path: ReadonlyArray<T>): T | null;
+
 /**
  * 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
@@ -86,13 +151,6 @@ declare function removeFromComposite(root: CompositeNode, node: CompositeNode):
  * (`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.
  */
-declare enum AccordionRole {
-    Accordion = "accordion",
-    Item = "accordion.item",
-    Trigger = "accordion.trigger",
-    Icon = "accordion.icon",
-    Panel = "accordion.panel"
-}
 /** The behaviour options a composite root stores as ordinary TRAITS (composite plan §3). */
 declare enum CompositeBehaviourTrait {
     /** Several items may be open at once ("Allow several open"). */
@@ -138,6 +196,9 @@ interface AccordionOptions {
     defaultOn?: AccordionDefaultOn;
     icon?: AccordionIcon;
 }
+/** 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. */
+declare function buildCompositeIcon(create: CompositeNodeFactory, key: string, icon: Exclude<AccordionIcon, AccordionIcon.None>, itemId?: string, role?: string): CompositeNode;
 /** One item: header (question + icon) and panel (answer). `key` makes every part's recipe key unique. */
 declare function buildAccordionItem(create: CompositeNodeFactory, words: AccordionWords, itemKey: string, icon?: AccordionIcon): CompositeNode;
 /** A fresh Accordion: three items, one open at a time, the first open by default (board 4). */
@@ -170,11 +231,14 @@ interface AccordionBehaviour {
 declare function accordionBehaviour(root: CompositeNode | null | undefined): AccordionBehaviour;
 /** Behaviour ▸ Allow several open / Open by default. False when the node has no such trait. */
 declare function setAccordionBehaviour(root: CompositeNode, patch: Partial<AccordionBehaviour>): boolean;
-/** The header of an item. */
+/** The header of an item (either kind). */
 declare function accordionTriggerOf(item: CompositeNode): CompositeNode | undefined;
-/** The panel of an item. */
+/** The panel of an item (either kind). */
 declare function accordionPanelOf(item: CompositeNode): CompositeNode | undefined;
-/** The question: the first Heading inside the header. */
+/** A root's items — an accordion's (`accordionItems`), or a disclosure, which is its own one item. */
+declare function compositeItems(root: CompositeNode): CompositeNode[];
+/** 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"). */
 declare function accordionQuestionOf(item: CompositeNode): CompositeNode | undefined;
 /** The answer: the first Text inside the panel. */
 declare function accordionAnswerOf(item: CompositeNode): CompositeNode | undefined;
@@ -199,7 +263,7 @@ declare enum AccordionEditRefusal {
 }
 /** Why removing `item` from `root` is refused, or null. */
 declare function accordionRemovalRefusal(root: CompositeNode | null | undefined, item: CompositeNode | null | undefined): AccordionEditRefusal | null;
-/** The icon the accordion's items wear now (the first item's; None when it has no icon). */
+/** The icon the composite's items wear now (the first item's; None when it has no icon). Either kind. */
 declare function detectAccordionIcon(root: CompositeNode): AccordionIcon;
 /**
  * Behaviour ▸ Icon: every item's header shows the chevron, the plus, or no icon. A switch between glyphs
@@ -213,8 +277,10 @@ declare function itemOpenTriggerIds(root: CompositeNode): void;
 declare function initialAccordionOpen(keys: ReadonlyArray<string>, defaultOn: AccordionDefaultOn): Set<string>;
 /** The open keys after toggling `key`: one at a time closes the others; several leaves them. */
 declare function nextAccordionState(open: ReadonlySet<string>, key: string, behaviour: Pick<AccordionBehaviour, 'multiple'>): Set<string>;
-/** The open keys after OPENING `key` (find-in-page, selecting into a closed panel). */
+/** The open keys after OPENING `key` (find-in-page, selecting into a closed panel, the `openItem` action). */
 declare function openAccordionItem(open: ReadonlySet<string>, key: string, behaviour: Pick<AccordionBehaviour, 'multiple'>): Set<string>;
+/** The open keys after CLOSING `key` (the `closeItem` action). */
+declare function closeAccordionItem(open: ReadonlySet<string>, key: string): Set<string>;
 declare enum AccordionKeyAction {
     Next = "next",
     Previous = "previous",
@@ -233,23 +299,32 @@ interface AccordionDomIds {
     trigger: string;
     panel: string;
 }
-/** The ARIA pairing ids of an item: unique per accordion (its root's node id) and per item (its key). */
-declare function accordionDomIds(rootId: string, itemKey: string): AccordionDomIds;
+/** The ARIA pairing ids of an item: unique per composite (its SCOPE id — `compositeScopeId`) and per item (its key). */
+declare function accordionDomIds(rootId: string, itemKey: string, kind?: CompositeKind): AccordionDomIds;
+/**
+ * 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.
+ */
+declare function compositeScopeId(rootId: string, rowKeys?: ReadonlyArray<string>): string;
 /** One item's render state: its identity, whether it is open, and its ARIA ids. */
 interface AccordionItemState {
+    kind: CompositeKind;
     key: string;
     index: number;
     on: boolean;
     ids: AccordionDomIds;
 }
-/** The render scope of one accordion: its root id, behaviour and every item key in order. */
+/** The render scope of one composite: its kind, scope id, behaviour and every item key in order. */
 interface AccordionScope {
+    kind: CompositeKind;
     rootId: string;
     behaviour: AccordionBehaviour;
     keys: ReadonlyArray<string>;
     open: ReadonlySet<string>;
 }
-declare function accordionScope(rootId: string, behaviour: AccordionBehaviour, keys: ReadonlyArray<string>): AccordionScope;
+declare function accordionScope(rootId: string, behaviour: AccordionBehaviour, keys: ReadonlyArray<string>, kind?: CompositeKind): AccordionScope;
 declare function accordionItemState(scope: AccordionScope, index: number): AccordionItemState;
 /** Attribute values: a string, or '' for a present boolean attribute. Absent attributes are left out. */
 type DomAttributes = Record<string, string>;
@@ -259,6 +334,9 @@ declare const ITEM_KEY_ATTRIBUTE = "data-iox-item-key";
 declare const COMPOSITE_ATTRIBUTE = "data-iox-composite";
 declare const MULTIPLE_ATTRIBUTE = "data-iox-multiple";
 declare 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. */
+declare const SCOPE_ATTRIBUTE = "data-iox-scope";
 /** The value a closed panel's region carries: find-in-page can still reveal it (D9, board 4). */
 declare const UNTIL_FOUND = "until-found";
 /** The structural classes the renderers write around an accordion's parts (no node owns them). */
@@ -268,13 +346,16 @@ declare enum AccordionClass {
     Track = "iox-accordion-track",
     Region = "iox-accordion-region"
 }
-declare function accordionRootAttributes(behaviour: AccordionBehaviour): DomAttributes;
+declare function accordionRootAttributes(behaviour: AccordionBehaviour, kind?: CompositeKind, scopeId?: string): DomAttributes;
 declare function accordionItemAttributes(state: AccordionItemState): DomAttributes;
 declare function accordionTriggerAttributes(state: AccordionItemState): DomAttributes;
 /** The track wrapping a panel: its row collapses to 0 while closed (the ONE hiding rule, iox-design.css). */
 declare function accordionTrackAttributes(state: AccordionItemState): DomAttributes;
-/** The region the panel sits in: `hidden="until-found"` while closed, so its words stay in the page. */
+/** The region the panel sits in: `hidden="until-found"` while closed, so its words stay in the page. An accordion's
+ *  is a labelled `region` (APG accordion); a disclosure's is a plain block (APG disclosure: the button names it). */
 declare function accordionRegionAttributes(state: AccordionItemState): DomAttributes;
+/** True when a region of this kind is a labelled `role=region`. */
+declare function hasLabelledRegion(kind: CompositeKind): boolean;
 declare function accordionPanelAttributes(state: AccordionItemState): DomAttributes;
 /** `attrs` as an HTML attribute string (` a="b" c`), values escaped by `esc`. */
 declare function serializeDomAttributes(attrs: DomAttributes, esc: (v: string) => string): string;
@@ -322,13 +403,17 @@ declare function accordionPartStyle(node: CompositeNode, name: string): unknown;
  * paths render the same markup). It reads the markup the renderers write (iox-design.css + accordion.ts's
  * attribute planners), so the server's first paint and every later state agree:
  *
- *   [root]  data-iox-composite="accordion"  data-iox-default-on  [data-iox-multiple]   (the node's own element —
- *           its role class may sit on a wrapper host, as the engine's component-path Repeater draws it)
+ *   [root]  data-iox-composite="accordion"  data-iox-default-on  [data-iox-multiple]  [data-iox-scope]  (the node's
+ *           own element — its role class may sit on a wrapper host, as the engine's component-path Repeater draws it)
  *     .iox-role-accordion-item  data-iox-item-key  [data-iox-on]
  *       hN.iox-accordion-heading > button.iox-accordion-button  id  aria-expanded  aria-controls
  *       .iox-accordion-track [data-iox-on] > .iox-accordion-region  role=region  [hidden=until-found]
  *         .iox-role-accordion-panel
  *
+ * The DISCLOSURE (CC2.1) runs on this same runtime: `data-iox-composite="disclosure"` on a root that IS its one
+ * item (it carries the key and `data-iox-on`), its button straight inside it (no heading), its panel in the same
+ * track + region (a plain block — no `role=region`), and no arrow keys (one button).
+ *
  * It owns: a click on a header toggles its item; ↓ ↑ Home End move between the headers of THIS accordion
  * (a nested one keeps its own); find-in-page (`beforematch`) opens the item that holds the match; a closed
  * panel gets `hidden="until-found"` after its track has collapsed (at once under reduced motion). Every
@@ -339,8 +424,11 @@ declare function accordionPartStyle(node: CompositeNode, name: string): unknown;
 declare const ITEM_ON_EVENT = "iox-item-on";
 declare const ITEM_OFF_EVENT = "iox-item-off";
 interface AccordionRuntimeOptions {
-    /** The root's node id — the ARIA ids' prefix (else read from the root's `iox-node-<id>` class). */
-    rootId?: string;
+    /** The composite's scope id — the ARIA ids' prefix (else the root's `data-iox-scope`, else its `iox-node-<id>`). A
+     *  function is read at every stamp (the builder canvas: a preview row's index is known once it is in the page). */
+    rootId?: string | (() => string);
+    /** Accordion or Disclosure (else read from the root's `data-iox-composite`). */
+    kind?: CompositeKind;
     /** The behaviour (else read from the root's data attributes). */
     behaviour?: AccordionBehaviour;
     /** Keys forced open on top of the live state (the builder's design state). */
@@ -350,9 +438,9 @@ interface AccordionRuntimeOptions {
     /** True to stop motion (default: the visitor's reduced-motion setting). */
     reducedMotion?: () => boolean;
 }
-/** The accordion an element belongs to (the element itself when it is a root). */
+/** The composite (accordion or disclosure) an element belongs to (the element itself when it is a root). */
 declare function closestAccordion(el: Element | null | undefined): HTMLElement | null;
-/** The item an element sits in (itself when it is one). */
+/** The item an element sits in (itself when it is one) — an accordion item, or a disclosure. */
 declare function closestAccordionItem(el: Element | null | undefined): HTMLElement | null;
 /** Subscribe to an item turning on / off — what the `itemOn` / `itemOff` interaction triggers listen to. The
  *  item is the element's own item (the element itself when it is one). Returns the unsubscribe. */
@@ -370,11 +458,12 @@ declare class AccordionRuntime {
     private behaviourValue;
     /** The builder attaches a root before its items render: the saved default is applied once they do. */
     private awaitingItems;
+    readonly kind: CompositeKind;
     constructor(root: HTMLElement, options?: AccordionRuntimeOptions);
     get behaviour(): AccordionBehaviour;
     /** The behaviour changed in the panel: re-read, and start from the new default. */
     setBehaviour(behaviour: AccordionBehaviour): void;
-    /** THIS accordion's items, in document order (a nested accordion's items are its own). */
+    /** THIS composite's items, in document order (a nested composite's items are its own); a disclosure's is itself. */
     items(): HTMLElement[];
     /** The open keys the live state holds (before anything forced). */
     get liveKeys(): ReadonlySet<string>;
@@ -383,6 +472,9 @@ declare class AccordionRuntime {
     keyOf(item: Element, items?: HTMLElement[]): string;
     toggle(key: string): void;
     open(key: string): void;
+    close(key: string): void;
+    /** Run an item action (`openItem` / `closeItem` / `toggleItem`, T14) on `key`. True when it shows open after. */
+    run(action: CompositeItemAction, key: string): boolean;
     /** Back to the saved default ("Showing on canvas ▸ As saved"). */
     resetLive(): void;
     /** The forced set changed (builder design state): show it. */
@@ -401,13 +493,73 @@ declare class AccordionRuntime {
     private readonly onKeydown;
     private readonly onBeforeMatch;
 }
-/** Attach the runtime to one rendered accordion root, unless it already runs one. Returns the NEW runtime, or
+/** Attach the runtime to one rendered composite root, unless it already runs one. Returns the NEW runtime, or
  *  null when the root already had one (so a caller destroys only what it created). */
 declare function attachAccordionAt(root: HTMLElement, options?: Omit<AccordionRuntimeOptions, 'rootId' | 'behaviour'>): AccordionRuntime | null;
 /** Attach the runtime to every accordion under `container` that has none yet. Returns the new runtimes. */
 declare function attachAccordions(container: ParentNode, options?: Omit<AccordionRuntimeOptions, 'rootId' | 'behaviour'>): AccordionRuntime[];
 /** Detach a runtime `attachAccordions` created. */
 declare function detachAccordion(runtime: AccordionRuntime): void;
+/** The repeated rows an element sits in, outermost first — each row's index as its row wrappers stamp it
+ *  (`data-iox-row-idx`: the builder's Repeater rows, the engine's component path). The builder folds them into a
+ *  composite's scope id (`compositeScopeId`, vectoriox/iox-ui#20); the element itself is not counted. */
+declare function compositeRowKeys(el: Element | null | undefined): string[];
+/** The runtime running a composite root, or null. */
+declare function accordionRuntimeOf(root: Element | null | undefined): AccordionRuntime | null;
+/** What an item action does to its target item (actions-core `openItem` / `closeItem` / `toggleItem`). */
+declare enum CompositeItemAction {
+    Open = "open",
+    Close = "close",
+    Toggle = "toggle"
+}
+/**
+ * Run an item action on the element of an ITEM (an accordion item, or a disclosure) — the `openItem` /
+ * `closeItem` / `toggleItem` interaction actions, on the canvas and on the live site through this one function.
+ * Returns whether the item shows open afterwards, or null when `el` is in no running composite.
+ */
+declare function runCompositeItemAction(el: Element | null | undefined, action: CompositeItemAction): boolean | null;
+/** True when an item an action just opened is out of view and the page should scroll to it (T14: "opens that item
+ *  and scrolls to it") — never when its head is already on screen, so a button beside it does not jolt the page. */
+declare function shouldScrollToItem(top: number, viewportHeight: number): boolean;
+
+/**
+ * DISCLOSURE / "Read more" (CC2.1 — composite T21). Not a component: a recipe of ordinary nodes on the
+ * ACCORDION's machinery — a disclosure is a one-item accordion whose root is its item, so it runs the same
+ * state machine, attribute planners and runtime (`accordion-runtime.ts`), on the canvas and on the live site.
+ *
+ *   Container `box`                         role disclosure          itemKey k1 · trait defaultOn (none | first)
+ *   ├─ LinkedContainer `accordion-trigger`  role disclosure.trigger  → <button aria-expanded aria-controls>
+ *   │   ├─ Text `body` (span)               role disclosure.more     "Read more" — hidden while open
+ *   │   ├─ Text `body` (span)               role disclosure.less     "Read less" — shown only while open
+ *   │   └─ Icon `icon`                      role disclosure.icon     Item open → turns
+ *   └─ Container `accordion-panel`          role disclosure.panel    inside a hidden="until-found" track
+ *       └─ Text `body`                      the rest of the text
+ *
+ * The words swap through the ordinary Item open state (`trigger-on` → the root), so the label an author sees on
+ * the canvas is the one the visitor gets, with no script and nothing to break. The look is the accordion's own
+ * element styles (no `disclosure-*` contract: the boards draw none) — the header's ink, hover ink and focus ring;
+ * the panel's padding and muted ink — and the words are `body` text: the site's body type, with `color: inherit`, so
+ * the toggle's ink and its hover ink reach them.
+ */
+interface DisclosureWords {
+    more: string;
+    less: string;
+    body: string;
+}
+/** The words a fresh disclosure starts with — generic, the author's to replace. */
+declare const DISCLOSURE_WORDS: Readonly<DisclosureWords>;
+interface DisclosureOptions {
+    words?: Partial<DisclosureWords>;
+    /** Open on first render (default: closed). */
+    open?: boolean;
+    icon?: AccordionIcon;
+}
+/** A disclosure's one item key — its root IS its item. */
+declare const DISCLOSURE_ITEM_KEY = "k1";
+/** A fresh Disclosure: "Read more" opens the text below and reads "Read less" while it is open; closed by default. */
+declare function buildDisclosureRecipe(create: CompositeNodeFactory, options?: DisclosureOptions): CompositeNode;
+/** Behaviour ▸ Open by default (a disclosure: on or off). */
+declare function disclosureOpenByDefault(root: CompositeNode): boolean;
 
 /**
  * BADGE + CHIP (composite T25; complex-components board 8). A Badge is a Container wearing
@@ -615,5 +767,5 @@ declare function structureRefusal(node: RoleLike | null | undefined, edit: Struc
  *  composite is always allowed — only its locked parts are refused. */
 declare function isLockedPart(node: RoleLike | null | undefined): boolean;
 
-export { ACCORDION_BIND_PROP, ACCORDION_CONTENT_LIMIT, ACCORDION_DEFAULT_ONS, ACCORDION_ICONS, ACCORDION_ICON_GLYPH, ACCORDION_NEW_ITEM_WORDS, ACCORDION_WORDS, AccordionClass, AccordionDefaultOn, AccordionEditRefusal, AccordionIcon, AccordionKeyAction, AccordionRole, AccordionRuntime, BADGE_TONES, BADGE_TONE_ICONS, BadgeTone, CARD_LAYOUTS, CARD_LAYOUT_CUSTOM, CARD_PARTS, CARD_PART_ROLE, CARD_STACK_BREAKPOINT, CARD_WORDS, CHIP_ICON, CHIP_STYLE, COMPOSITE_ATTRIBUTE, COMPOSITE_ROLE_SPECS, CardLayout, CardPart, CardRole, CompositeBehaviourTrait, DEFAULT_ON_ATTRIBUTE, ITEM_KEY_ATTRIBUTE, ITEM_OFF_EVENT, ITEM_ON_EVENT, ITEM_OPEN_STATE, MULTIPLE_ATTRIBUTE, ON_ATTRIBUTE, ON_STATE, PILL_LABEL_STYLE, StructureEdit, StructureRefusal, UNTIL_FOUND, accordionAnswerOf, accordionBehaviour, accordionDomIds, accordionFocusIndex, accordionHeadingLevel, accordionItemAttributes, accordionItemLabel, accordionItemOf, accordionItemState, accordionItems, accordionKeyAction, accordionPanelAttributes, accordionPanelOf, accordionPartStyle, accordionQuestionOf, accordionRegionAttributes, accordionRemovalRefusal, accordionRootAttributes, accordionRootOf, accordionScope, accordionToContent, accordionToManual, accordionTrackAttributes, accordionTriggerAttributes, accordionTriggerOf, addAccordionItem, applyCardLayout, attachAccordionAt, attachAccordions, badgeStyleId, badgeToneOf, buildAccordionItem, buildAccordionRecipe, buildBadge, buildCardRecipe, buildChip, cardPartsOf, cardRootOf, cardTitleOf, clearLayerStyles, closestAccordion, closestAccordionItem, detachAccordion, detectAccordionIcon, detectCardLayout, domSafeKey, findByRole, initialAccordionOpen, isAccordionFromContent, isAccordionItemOn, isAccordionPart, isAccordionRoot, isCardLinked, isCardRoot, isLockedPart, isPillNode, itemOpenTriggerIds, moveAccordionItem, nextAccordionState, nextItemKey, onAccordionItemState, openAccordionItem, parentInComposite, pickAccordionAutoBinds, readLayerStyle, readProp, readStyle, removeFromComposite, renameAccordionItem, rowItemKey, serializeDomAttributes, setAccordionBehaviour, setAccordionIcon, setBadgeTone, setCardLinked, setCardPart, structureRefusal, walkComposite, writeLayerStyles, writeProp, writeStyles };
-export type { AccordionAutoBinds, AccordionBehaviour, AccordionDomIds, AccordionItemState, AccordionOptions, AccordionRuntimeOptions, AccordionScope, AccordionWords, BaselineStyles, CardEditOptions, CardLayoutResult, CardLayoutState, CardOptions, CardPartChange, CardWords, CompositeBinding, CompositeLayer, CompositeNode, CompositeNodeFactory, CompositeNodeSpec, CompositeRoleSpec, CompositeTrait, ContentFieldLike, DomAttributes, PillOptions };
+export { ACCORDION_BIND_PROP, ACCORDION_CONTENT_LIMIT, ACCORDION_DEFAULT_ONS, ACCORDION_ICONS, ACCORDION_ICON_GLYPH, ACCORDION_NEW_ITEM_WORDS, ACCORDION_WORDS, AccordionClass, AccordionDefaultOn, AccordionEditRefusal, AccordionIcon, AccordionKeyAction, AccordionRole, AccordionRuntime, BADGE_TONES, BADGE_TONE_ICONS, BadgeTone, CARD_LAYOUTS, CARD_LAYOUT_CUSTOM, CARD_PARTS, CARD_PART_ROLE, CARD_STACK_BREAKPOINT, CARD_WORDS, CHIP_ICON, CHIP_STYLE, COMPOSITE_ATTRIBUTE, COMPOSITE_KIND_ROLES, COMPOSITE_ROLE_SPECS, CardLayout, CardPart, CardRole, CompositeBehaviourTrait, CompositeItemAction, CompositeKind, DEFAULT_ON_ATTRIBUTE, DISCLOSURE_ITEM_KEY, DISCLOSURE_WORDS, DisclosureRole, ITEM_KEY_ATTRIBUTE, ITEM_OFF_EVENT, ITEM_ON_EVENT, ITEM_OPEN_STATE, MULTIPLE_ATTRIBUTE, ON_ATTRIBUTE, ON_STATE, PILL_LABEL_STYLE, SCOPE_ATTRIBUTE, StructureEdit, StructureRefusal, UNTIL_FOUND, accordionAnswerOf, accordionBehaviour, accordionDomIds, accordionFocusIndex, accordionHeadingLevel, accordionItemAttributes, accordionItemLabel, accordionItemOf, accordionItemState, accordionItems, accordionKeyAction, accordionPanelAttributes, accordionPanelOf, accordionPartStyle, accordionQuestionOf, accordionRegionAttributes, accordionRemovalRefusal, accordionRootAttributes, accordionRootOf, accordionRuntimeOf, accordionScope, accordionToContent, accordionToManual, accordionTrackAttributes, accordionTriggerAttributes, accordionTriggerOf, addAccordionItem, applyCardLayout, attachAccordionAt, attachAccordions, badgeStyleId, badgeToneOf, buildAccordionItem, buildAccordionRecipe, buildBadge, buildCardRecipe, buildChip, buildCompositeIcon, buildDisclosureRecipe, cardPartsOf, cardRootOf, cardTitleOf, clearLayerStyles, closeAccordionItem, closestAccordion, closestAccordionItem, compositeItemOf, compositeItems, compositeKindOfRole, compositeRootOf, compositeRowKeys, compositeScopeId, detachAccordion, detectAccordionIcon, detectCardLayout, disclosureOpenByDefault, domSafeKey, findByRole, hasLabelledRegion, initialAccordionOpen, isAccordionFromContent, isAccordionItemOn, isAccordionPart, isAccordionRoot, isCardLinked, isCardRoot, isCompositeItem, isCompositePanel, isCompositeRoot, isCompositeTrigger, isDisclosurePart, isDisclosureRoot, isLockedPart, isPillNode, itemOpenTriggerIds, makeCompositePart, moveAccordionItem, nextAccordionState, nextItemKey, onAccordionItemState, openAccordionItem, parentInComposite, pickAccordionAutoBinds, readLayerStyle, readProp, readStyle, removeFromComposite, renameAccordionItem, rowItemKey, runCompositeItemAction, serializeDomAttributes, setAccordionBehaviour, setAccordionIcon, setBadgeTone, setCardLinked, setCardPart, shouldScrollToItem, structureRefusal, walkComposite, writeLayerStyles, writeProp, writeStyles };
+export type { AccordionAutoBinds, AccordionBehaviour, AccordionDomIds, AccordionItemState, AccordionOptions, AccordionRuntimeOptions, AccordionScope, AccordionWords, BaselineStyles, CardEditOptions, CardLayoutResult, CardLayoutState, CardOptions, CardPartChange, CardWords, CompositeBinding, CompositeKindRoles, CompositeLayer, CompositeNode, CompositeNodeFactory, CompositeNodeSpec, CompositeRoleSpec, CompositeTrait, ContentFieldLike, DisclosureOptions, DisclosureWords, DomAttributes, PillOptions };

package/fesm2022/vectoriox-iox-ui-actions-core.mjs

@@ -1,3 +1,5 @@
+import { AccordionRole, DisclosureRole, CompositeItemAction } from '@vectoriox/iox-ui/composite-core';
+
 /**
  * The ONE descriptor shape for everything an author can put in an ordered action list —
  * a form's after-submit steps today, element behaviour actions (A1) next. Promoted out of
@@ -38,6 +40,8 @@ function resolveActionAvailability(descriptor, ctx = {}) {
     return { state: 'available' };
 }
 
+/** 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];
 /**
  * The ELEMENT action catalog (actions plan A1) — what a node can DO, as data. One list feeds the
  * grouped picker, the two interaction engines, and the AI composer's validation (§9: the model
@@ -81,6 +85,15 @@ const ELEMENT_ACTION_DESCRIPTORS = Object.freeze([
         target: { required: true, types: ['Dialog'] } },
     { type: 'toggleDialog', labelKey: 'builder.actions.toggleDialog', kind: 'instant', group: 'dialog', builderBehaviour: 'run',
         target: { required: true, types: ['Dialog'] } },
+    // ── Item (CC2.1 — composite T14): drive an accordion item or a disclosure from anywhere ("See shipping"
+    // 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 } },
+    { 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',
+        target: { required: true, roles: ITEM_TARGET_ROLES } },
     // ── Form (A1 — Tier A; the submit transport is the forms module's, I7 of its plan) ──
     // simulate in the CANVAS: the builder's Form is a container twin with no real <form>,
     // so there is nothing honest to run — the live engine requestSubmit()s the real one.
@@ -137,11 +150,22 @@ const SERVER_ELEMENT_ACTION_TYPES = new Set(['sendEmail', 'callWebhook', 'create
 /** The Tier-A behaviour executors' dispatch set (A1c) — the engines branch on it beside
  *  DIALOG/SWIPER. Dialog actions have their own set; context/visibility stay in the legacy path. */
 const BEHAVIOUR_ACTION_TYPES = new Set(['navigate', 'scrollTo', 'submitForm', 'copyToClipboard']);
+/** The item actions' dispatch set (T14) and what each does to its item — the engines branch on it beside
+ *  DIALOG/BEHAVIOUR, and composite-core `runCompositeItemAction` runs it on the target item's own runtime. */
+const ITEM_ACTION_TYPES = Object.freeze({
+    openItem: CompositeItemAction.Open,
+    closeItem: CompositeItemAction.Close,
+    toggleItem: CompositeItemAction.Toggle,
+});
+/** The item action an action type runs, or null when it is not one. */
+function itemActionOf(type) {
+    return (type && ITEM_ACTION_TYPES[type]) || null;
+}
 /** The consent actions' dispatch set (C3) — the engines branch on it beside DIALOG/BEHAVIOUR.
  *  `openConsentPreferences` is dialog-opening by nature and included so ONE branch owns consent. */
 const CONSENT_ACTION_TYPES = new Set(['grantConsent', 'denyConsent', 'setConsentCategory', 'openConsentPreferences']);
 /** Picker order — most-used groups first, services last (they are the shop window, not the shop). */
-const ELEMENT_ACTION_GROUP_ORDER = Object.freeze(['motion', 'visibility', 'navigate', 'dialog', 'form', 'data', 'consent', 'service']);
+const ELEMENT_ACTION_GROUP_ORDER = Object.freeze(['motion', 'visibility', 'navigate', 'dialog', 'item', 'form', 'data', 'consent', 'service']);
 /** The catalog, grouped and ordered for the picker — one derivation, no hand-kept second list. */
 function groupedElementActions() {
     return ELEMENT_ACTION_GROUP_ORDER
@@ -232,5 +256,5 @@ function dialogOpenersSelector(dialogDomIdValue) {
  * Generated bundle index. Do not edit.
  */
 
-export { BEHAVIOUR_ACTION_TYPES, CONSENT_ACTION_TYPES, DIALOG_ACTION_TYPE_SET, DIALOG_OPENER_ACTION_TYPES, DIALOG_OPENER_TRIGGER, DIALOG_SELECTOR, ELEMENT_ACTION_DESCRIPTORS, ELEMENT_ACTION_GROUP_ORDER, FORM_SUBMIT_ACTION_DESCRIPTORS, OpenerAttribute, SERVER_ELEMENT_ACTION_TYPES, addableActions, dialogDomId, dialogOpenerAttributes, dialogOpenersSelector, groupedElementActions, nodeIdOfDialogDomId, openedDialogId, resolveActionAvailability };
+export { BEHAVIOUR_ACTION_TYPES, CONSENT_ACTION_TYPES, DIALOG_ACTION_TYPE_SET, DIALOG_OPENER_ACTION_TYPES, DIALOG_OPENER_TRIGGER, DIALOG_SELECTOR, ELEMENT_ACTION_DESCRIPTORS, ELEMENT_ACTION_GROUP_ORDER, FORM_SUBMIT_ACTION_DESCRIPTORS, ITEM_ACTION_TYPES, OpenerAttribute, SERVER_ELEMENT_ACTION_TYPES, addableActions, dialogDomId, dialogOpenerAttributes, dialogOpenersSelector, groupedElementActions, itemActionOf, nodeIdOfDialogDomId, openedDialogId, resolveActionAvailability };
 //# sourceMappingURL=vectoriox-iox-ui-actions-core.mjs.map