@vectoriox/iox-ui 5.36.0 → 5.37.0

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

@@ -0,0 +1,110 @@
+/**
+ * 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.
+ */
+
+export enum CompositeKind {
+    Accordion = 'accordion',
+    Disclosure = 'disclosure',
+}
+
+export 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.
+ */
+export enum DisclosureRole {
+    Disclosure = 'disclosure',
+    Trigger = 'disclosure.trigger',
+    More = 'disclosure.more',
+    Less = 'disclosure.less',
+    Icon = 'disclosure.icon',
+    Panel = 'disclosure.panel',
+}
+
+interface RoleLike { role?: string | null }
+
+/** The roles each kind plays in the shared runtime. */
+export interface CompositeKindRoles {
+    root: string;
+    item: string;
+    trigger: string;
+    panel: string;
+    icon: string;
+}
+
+export const COMPOSITE_KIND_ROLES: Readonly<Record<CompositeKind, 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 },
+};
+
+const KINDS = Object.values(CompositeKind);
+const rolesOf = (pick: keyof CompositeKindRoles): ReadonlySet<string> => new Set(KINDS.map(k => COMPOSITE_KIND_ROLES[k][pick]));
+const ROOT_ROLES = rolesOf('root');
+const ITEM_ROLES = rolesOf('item');
+const TRIGGER_ROLES = rolesOf('trigger');
+const PANEL_ROLES = rolesOf('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 {
+    const head = role?.split('.')[0];
+    return (KINDS as string[]).includes(head ?? '') ? head as CompositeKind : null;
+}
+
+/** 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);
+}
+
+/** An ITEM — an accordion's item, or a disclosure (its own item). */
+export function isCompositeItem(node: RoleLike | null | undefined): boolean {
+    return !!node?.role && ITEM_ROLES.has(node.role);
+}
+
+/** A trigger — rendered as a `<button>` that opens its item, never a link. */
+export function isCompositeTrigger(node: RoleLike | null | undefined): boolean {
+    return !!node?.role && TRIGGER_ROLES.has(node.role);
+}
+
+/** A panel — rendered inside the track + region the one hiding rule collapses. */
+export function isCompositePanel(node: RoleLike | null | undefined): boolean {
+    return !!node?.role && PANEL_ROLES.has(node.role);
+}
+
+export function isDisclosureRoot(node: RoleLike | null | undefined): boolean {
+    return node?.role === DisclosureRole.Disclosure;
+}
+
+/** True for any part of a disclosure (its root included). */
+export function isDisclosurePart(node: RoleLike | null | undefined): boolean {
+    return compositeKindOfRole(node?.role) === CompositeKind.Disclosure;
+}
+
+/** The composite root a node belongs to: the nearest ancestor (or the node itself) that is one. `path` = the
+ *  node's ancestors, root first. */
+export function compositeRootOf<T extends RoleLike>(node: T, path: ReadonlyArray<T>): T | null {
+    if (isCompositeRoot(node)) return node;
+    for (let i = path.length - 1; i >= 0; i--) if (isCompositeRoot(path[i])) return path[i];
+    return 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). */
+export function compositeItemOf<T extends RoleLike>(node: T, path: ReadonlyArray<T>): T | null {
+    if (isCompositeItem(node)) return node;
+    for (let i = path.length - 1; i >= 0; i--) {
+        if (isCompositeItem(path[i])) return path[i];
+        if (isCompositeRoot(path[i])) return null;
+    }
+    return null;
+}

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

@@ -46,6 +46,17 @@ export interface CompositeNodeSpec {
 
 export 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). */
+export function makeCompositePart(create: CompositeNodeFactory, spec: CompositeNodeSpec, role: string | null, label: string | undefined,
+    base?: Readonly<Record<string, string>>): CompositeNode {
+    const node = create(spec);
+    if (role) node.role = role;
+    if (label) node.label = label;
+    if (base) writeStyles(node, base);
+    return node;
+}
+
 const usesTraits = (node: CompositeNode): boolean => Array.isArray(node.traits);
 
 /** A content trait's value — `traits[].default` on a builder node, `props[name]` on a saved one. */

package/src/composite-core/disclosure.ts

@@ -0,0 +1,125 @@
+import { accordionBehaviour, AccordionDefaultOn, AccordionIcon, buildCompositeIcon, CompositeBehaviourTrait, ITEM_OPEN_STATE } from './accordion';
+import { DisclosureRole } from './composite-kinds';
+import { CompositeNode, CompositeNodeFactory, makeCompositePart, writeProp, writeStyles } from './composite-node';
+
+/**
+ * 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.
+ */
+
+export interface DisclosureWords {
+    more: string;
+    less: string;
+    body: string;
+}
+
+/** The words a fresh disclosure starts with — generic, the author's to replace. */
+export const DISCLOSURE_WORDS: Readonly<DisclosureWords> = {
+    more: 'Read more',
+    less: 'Read less',
+    body: 'Write the rest of the story here. It stays out of the way until someone asks for it.',
+};
+
+export 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. */
+export const DISCLOSURE_ITEM_KEY = 'k1';
+
+enum Type {
+    Container = 'Container',
+    LinkedContainer = 'LinkedContainer',
+    Text = 'Text',
+}
+
+enum Style {
+    Root = 'box',
+    Trigger = 'accordion-trigger',
+    Word = 'body',
+    Panel = 'accordion-panel',
+    Body = 'body',
+}
+
+const ZERO_BOX = '0px 0px 0px 0px';
+const HIDDEN = 'none';
+const INHERIT = 'inherit';
+/** A word is a flex item of the toggle — `block` (never `inline`: the compiler drops a value equal to the CSS initial,
+ *  and the Text's own default would come back in its place). */
+const SHOWN = 'block';
+
+/** What each part holds — layout only; its LOOK is its element style. The trigger sizes to its words (a button in
+ *  the flow, not a full-width header row — `fit-content` keeps it from stretching) and the panel spans the root. The
+ *  trigger is `flex`, not `inline-flex`: it is a flex item of the root, which blockifies it on the site anyway. */
+const PART_BASE: Readonly<Record<string, Readonly<Record<string, string>>>> = {
+    [DisclosureRole.Disclosure]: { display: 'flex', flexDirection: 'column', width: '100%', minHeight: 'auto', height: 'auto' },
+    // The toggle reads the text around it (the page's body type, through the root) — a LinkedContainer is born with
+    // its own literal font, which an accordion's heading masks and a disclosure's words would show.
+    [DisclosureRole.Trigger]: {
+        display: 'flex', alignItems: 'center', gap: '8px', width: 'fit-content', minHeight: 'auto', height: 'auto', textAlign: 'start', cursor: 'pointer',
+        fontFamily: INHERIT, fontSize: INHERIT, fontWeight: INHERIT, lineHeight: INHERIT,
+    },
+    // A word is just its words: none of a Text's own box (its type's 10px padding, its full width) — the toggle's
+    // padding is the click target.
+    [DisclosureRole.More]: { display: SHOWN, margin: ZERO_BOX, padding: ZERO_BOX, width: 'auto' },
+    [DisclosureRole.Less]: { display: HIDDEN, margin: ZERO_BOX, padding: ZERO_BOX, width: 'auto' },
+    [DisclosureRole.Panel]: { display: 'block', width: '100%', minHeight: 'auto', height: 'auto' },
+};
+const BODY_BASE: Readonly<Record<string, string>> = { margin: ZERO_BOX, padding: ZERO_BOX, minHeight: 'auto' };
+
+function make(create: CompositeNodeFactory, key: string, type: string, role: DisclosureRole | 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);
+}
+
+/** One of the trigger's two words: shown while the disclosure is closed (`more`) or open (`less`). */
+function buildWord(create: CompositeNodeFactory, role: DisclosureRole.More | DisclosureRole.Less, words: string, rootId?: string): CompositeNode {
+    const node = make(create, role === DisclosureRole.More ? 'more' : 'less', Type.Text, role, Style.Word, { content: words, tag: 'span' }, 'Text');
+    node.stateStyles = { ...(node.stateStyles ?? {}), [ITEM_OPEN_STATE]: { display: role === DisclosureRole.More ? HIDDEN : SHOWN } };
+    if (rootId) node.stateTriggers = { ...(node.stateTriggers ?? {}), [ITEM_OPEN_STATE]: rootId };
+    return node;
+}
+
+/** A fresh Disclosure: "Read more" opens the text below and reads "Read less" while it is open; closed by default. */
+export function buildDisclosureRecipe(create: CompositeNodeFactory, options: DisclosureOptions = {}): CompositeNode {
+    const words = { ...DISCLOSURE_WORDS, ...(options.words ?? {}) };
+    const root = make(create, 'disclosure', Type.Container, DisclosureRole.Disclosure, Style.Root, {}, 'Disclosure');
+    root.itemKey = DISCLOSURE_ITEM_KEY;
+    writeProp(root, CompositeBehaviourTrait.DefaultOn, options.open ? AccordionDefaultOn.First : AccordionDefaultOn.None);
+    const icon = options.icon ?? AccordionIcon.Chevron;
+    const trigger = make(create, 'trigger', Type.LinkedContainer, DisclosureRole.Trigger, Style.Trigger, {}, 'Toggle');
+    trigger.children = [
+        buildWord(create, DisclosureRole.More, words.more, root.id),
+        buildWord(create, DisclosureRole.Less, words.less, root.id),
+        ...(icon === AccordionIcon.None ? [] : [buildCompositeIcon(create, 'icon', icon, root.id, DisclosureRole.Icon)]),
+    ];
+    const panel = make(create, 'panel', Type.Container, DisclosureRole.Panel, Style.Panel, {}, 'Panel');
+    const body = make(create, 'body', Type.Text, null, Style.Body, { content: words.body, tag: 'p' }, 'Text');
+    writeStyles(body, BODY_BASE);
+    panel.children = [body];
+    root.children = [trigger, panel];
+    return root;
+}
+
+/** Behaviour ▸ Open by default (a disclosure: on or off). */
+export function disclosureOpenByDefault(root: CompositeNode): boolean {
+    return accordionBehaviour(root).defaultOn !== AccordionDefaultOn.None;
+}

package/src/composite-core/public-api.ts

@@ -3,12 +3,15 @@
  * plan §3a). FRAMEWORK-FREE: the builder, the SSR engine and iox-cms (generation-core's composer, the site
  * build) read the same recipes, roles and structure rules. Card v2 + Badge / Chip (T23 / T25) are the
  * first; the Accordion (CC2) adds the first composite RUNTIME (accordion-runtime.ts — DOM only, no
- * framework); Tabs join with their own phase.
+ * framework), which the Disclosure (CC2.1) runs too — a one-item accordion whose root is its item; Tabs join with
+ * their own phase.
  * ⚠️ Consumers wire the usual trio — ng-package raw-ts assets, jest moduleNameMapper, tsconfig paths.
  */
 export * from './composite-node';
+export * from './composite-kinds';
 export * from './accordion';
 export * from './accordion-runtime';
+export * from './disclosure';
 export * from './badge';
 export * from './card';
 export * from './structure';

package/src/composite-core/structure.ts

@@ -1,4 +1,4 @@
-import { AccordionRole } from './accordion';
+import { AccordionRole, DisclosureRole } from './composite-kinds';
 import { CardPart, CardRole } from './card';
 
 /**
@@ -29,6 +29,13 @@ export const COMPOSITE_ROLE_SPECS: Readonly<Record<string, CompositeRoleSpec>> =
     [AccordionRole.Trigger]: { parent: AccordionRole.Item, locked: true },
     [AccordionRole.Panel]: { parent: AccordionRole.Item, locked: true },
     [AccordionRole.Icon]: { parent: AccordionRole.Trigger },
+    // CC2.1 — a disclosure always keeps its toggle and its panel; the words and the icon are the author's.
+    [DisclosureRole.Disclosure]: { parent: null },
+    [DisclosureRole.Trigger]: { parent: DisclosureRole.Disclosure, locked: true },
+    [DisclosureRole.Panel]: { parent: DisclosureRole.Disclosure, locked: true },
+    [DisclosureRole.More]: { parent: DisclosureRole.Trigger },
+    [DisclosureRole.Less]: { parent: DisclosureRole.Trigger },
+    [DisclosureRole.Icon]: { parent: DisclosureRole.Trigger },
 };
 
 export enum StructureEdit {