@vectoriox/iox-ui 5.30.0 → 5.31.1

package/composite-core/index.d.ts

@@ -0,0 +1,270 @@
+import { ElementStyleTarget } from '@vectoriox/iox-ui/design-core';
+
+/**
+ * The node shape composite-core reads and writes — both a builder `ComponentNode` (values in
+ * `traits[].default` / `styleTraits`) and a saved layout node (flat `props` / `styleProps`), the same
+ * dual shape design-core's element styles already speak. A composite is a tree of ORDINARY nodes
+ * (composite-components plan §1): this module only adds the `role` each part carries.
+ */
+interface CompositeTrait {
+    name: string;
+    default?: unknown;
+}
+interface CompositeLayer {
+    styleProps?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+interface CompositeNode extends ElementStyleTarget {
+    id?: string;
+    /** The part this node plays in its composite (`card.title`). Additive; saved; read by the shared CSS
+     *  (`iox-role-<role>`), the structure guard and the composite's own editors. */
+    role?: string;
+    label?: string;
+    props?: Record<string, unknown>;
+    traits?: CompositeTrait[];
+    responsive?: Partial<Record<string, CompositeLayer>>;
+    children?: CompositeNode[];
+}
+/** What a recipe asks its consumer to create: a NEW node of `type`, the way that consumer creates one
+ *  (the builder's `createConfig`, generation-core's `createSerializedNode`), with these props and this
+ *  element style. `key` is stable per recipe node — a consumer that needs deterministic ids builds them
+ *  from it (generation-core: `<root id>-<key>`). */
+interface CompositeNodeSpec {
+    key: string;
+    type: string;
+    props?: Readonly<Record<string, unknown>>;
+    elementStyle?: string | null;
+}
+type CompositeNodeFactory = (spec: CompositeNodeSpec) => 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). */
+declare function writeProp(node: CompositeNode, name: string, value: unknown): boolean;
+/** A base style value (the node's own, either shape). */
+declare function readStyle(node: CompositeNode, name: string): unknown;
+/** Write base style values; returns the names the node has no slot for (a builder node drops them). */
+declare function writeStyles(node: CompositeNode, values: Readonly<Record<string, string>>): string[];
+/** Set style values in one breakpoint layer (`responsive[bp].styleProps`, the shape both renderers'
+ *  shared `planResponsiveRules` reads). */
+declare function writeLayerStyles(node: CompositeNode, breakpoint: string, values: Readonly<Record<string, string>>): void;
+/** Remove style keys from one breakpoint layer; an emptied layer (and an emptied map) is dropped. */
+declare function clearLayerStyles(node: CompositeNode, breakpoint: string, names: ReadonlyArray<string>): void;
+/** A breakpoint layer's own value for one style key. */
+declare function readLayerStyle(node: CompositeNode, breakpoint: string, name: string): unknown;
+/** Depth-first: `node`, then every descendant. */
+declare function walkComposite(node: CompositeNode, visit: (node: CompositeNode, parent: CompositeNode | null) => void, parent?: CompositeNode | null): void;
+/**
+ * The first descendant of `root` playing `role`. Never descends into a NESTED composite of the same
+ * root role (a card inside a card's content keeps its own parts).
+ */
+declare function findByRole(root: CompositeNode, role: string): CompositeNode | undefined;
+/** The node's parent inside `root`, or null. */
+declare function parentInComposite(root: CompositeNode, node: CompositeNode): CompositeNode | null;
+/** Detach `node` from its parent inside `root`. True when it was found. */
+declare function removeFromComposite(root: CompositeNode, node: CompositeNode): boolean;
+
+/**
+ * BADGE + CHIP (composite T25; complex-components board 8). A Badge is a Container wearing
+ * `badge-<tone>` › Icon + Text; its TONE is its element style, so Badge ▸ Tone writes the style and
+ * nothing else, and a re-theme restyles every badge. A Chip is the outlined static style only (no
+ * behaviour until the K5 Data view). Inside a card the badge plays `card.badge`; anywhere else it is
+ * recognised by its style.
+ */
+declare enum BadgeTone {
+    Neutral = "neutral",
+    Success = "success",
+    Warning = "warning",
+    Accent = "accent"
+}
+declare const BADGE_TONES: ReadonlyArray<BadgeTone>;
+/** The tone's element style (`badge-<tone>`, the contract's). */
+declare function badgeStyleId(tone: BadgeTone): string;
+declare const CHIP_STYLE = "chip";
+/** The glyph a fresh badge of each tone shows (the board's tone grid). */
+declare const BADGE_TONE_ICONS: Readonly<Record<BadgeTone, string>>;
+declare const CHIP_ICON = "ph ph-tag";
+/** The badge tone a node wears, or null when it is no badge. */
+declare function badgeToneOf(node: {
+    elementStyle?: string | null;
+} | null | undefined): BadgeTone | null;
+/** True for a node wearing a badge tone or the chip style — the pills (their Icon reads their ink). */
+declare function isPillNode(node: {
+    elementStyle?: string | null;
+} | null | undefined): boolean;
+/**
+ * Badge ▸ Tone: move the badge to another tone's element style (an edit the author made to the old
+ * tone's look is kept, design-core's switch rule). Nothing else changes — not the icon, not the words.
+ */
+declare function setBadgeTone(node: CompositeNode, tone: BadgeTone, baseline?: Readonly<Record<string, unknown>>): boolean;
+interface PillOptions {
+    text?: string;
+    icon?: string;
+    /** Key prefix for the consumer's ids (`badge` → `badge`, `badge-icon`, `badge-text`). */
+    key?: string;
+}
+/** A fresh Badge: Container `badge-<tone>` › Icon + Text. */
+declare function buildBadge(create: CompositeNodeFactory, options?: PillOptions & {
+    tone?: BadgeTone;
+}): CompositeNode;
+/** A fresh Chip: Container `chip` › Icon + Text (outlined, static). */
+declare function buildChip(create: CompositeNodeFactory, options?: PillOptions): CompositeNode;
+
+/**
+ * CARD v2 (composite T23; complex-components board 8, APPROVED 2026-10-20). Not a component: a recipe of
+ * ordinary nodes, each part carrying a role, so every part is selectable on the canvas, in the layer tree
+ * and the breadcrumb, wears its own element style and is edited on its own (R2). No runtime and no design
+ * state — nothing is hidden at rest.
+ *
+ *   Container `card`                    role card
+ *   ├─ Container `box`                  role card.media      (optional: Image)
+ *   │   ├─ Image `media`
+ *   │   └─ Container `badge-accent`     role card.badge      (optional) › Icon + Text
+ *   └─ Container `box`                  role card.content    (locked)
+ *       ├─ Text `eyebrow`               role card.eyebrow    (optional)
+ *       ├─ Heading h3 `h3`              role card.title      (locked — the card's link when linked)
+ *       ├─ Text `body`                  role card.text       (optional)
+ *       └─ Container `box`              role card.actions    (optional) › ButtonBlock primary + ghost
+ *
+ * One recipe for every consumer: the builder's palette (its `createConfig`), generation-core's composer
+ * (its `createSerializedNode`) and the site build — each passes its own node factory.
+ */
+declare enum CardRole {
+    Card = "card",
+    Media = "card.media",
+    Badge = "card.badge",
+    Content = "card.content",
+    Eyebrow = "card.eyebrow",
+    Title = "card.title",
+    Text = "card.text",
+    Actions = "card.actions"
+}
+/** The optional parts — Card ▸ Parts, one switch each, in the board's order. Title and Content are locked. */
+declare enum CardPart {
+    Media = "media",
+    Badge = "badge",
+    Eyebrow = "eyebrow",
+    Text = "text",
+    Actions = "actions"
+}
+declare const CARD_PARTS: ReadonlyArray<CardPart>;
+declare const CARD_PART_ROLE: Readonly<Record<CardPart, CardRole>>;
+/** Card ▸ Layout — a preset, never a stored trait: `applyCardLayout` writes the card's layout styles. */
+declare enum CardLayout {
+    Top = "top",
+    Side = "side",
+    Overlay = "overlay",
+    Compact = "compact"
+}
+declare const CARD_LAYOUTS: ReadonlyArray<CardLayout>;
+/** What Card ▸ Layout shows once the author has changed the layout styles by hand. */
+declare const CARD_LAYOUT_CUSTOM = "custom";
+type CardLayoutState = CardLayout | typeof CARD_LAYOUT_CUSTOM;
+/** The words a fresh card starts with — the author's to replace (or a bound field's). */
+interface CardWords {
+    eyebrow: string;
+    title: string;
+    text: string;
+    primary: string;
+    secondary: string;
+    badge: string;
+}
+declare const CARD_WORDS: Readonly<CardWords>;
+/** The breakpoint whose layer stacks an "Image side" card (Breakpoint.Mobile, ≤767px). */
+declare const CARD_STACK_BREAKPOINT = "mobile";
+/** What a type's UNSTYLED node holds — passed so a style switch (Content ⇄ the scrim) hands the old
+ *  style's values back to the type, never to `undefined`. */
+type BaselineStyles = (type: string) => Readonly<Record<string, unknown>>;
+interface CardEditOptions {
+    baselineStyles?: BaselineStyles;
+}
+interface CardOptions extends CardEditOptions {
+    layout?: CardLayout;
+    /** Which optional parts the card starts with (all, by default). */
+    parts?: Partial<Record<CardPart, boolean>>;
+    words?: Partial<CardWords>;
+    badgeTone?: BadgeTone;
+}
+/** A fresh Card v2: every part a node with its role and element style, laid out by `options.layout`. */
+declare function buildCardRecipe(create: CompositeNodeFactory, options?: CardOptions): CompositeNode;
+/** True when `node` is a Card v2 root. */
+declare function isCardRoot(node: CompositeNode | null | undefined): boolean;
+/** The Card a part belongs to: the nearest ancestor (or the node itself) playing `card`. `path` = the
+ *  node's ancestors, root first. */
+declare function cardRootOf(node: CompositeNode, path: ReadonlyArray<CompositeNode>): CompositeNode | null;
+/** Card ▸ Parts: which optional parts the card holds now. */
+declare function cardPartsOf(card: CompositeNode): Record<CardPart, boolean>;
+interface CardLayoutResult {
+    layout: CardLayout;
+    /** Parts the preset switched off (Compact: Text and Buttons). */
+    removed: CardPart[];
+}
+/**
+ * Card ▸ Layout. Rewrites the card's LAYOUT styles for `layout` — the card's direction and box, the
+ * Media's placement, the Image's aspect, the content block (Image behind text: the `media-scrim` style +
+ * the Inverse scheme), the title size (Compact) and, for Image side, a Mobile layer that stacks it — and
+ * moves the badge to where the layout puts it. Nothing else on any part. One undo step for the caller.
+ */
+declare function applyCardLayout(card: CompositeNode, layout: CardLayout, options?: CardEditOptions): CardLayoutResult;
+/** The layout the card's styles hold now, or `custom` once they were changed by hand (Card ▸ Layout). */
+declare function detectCardLayout(card: CompositeNode): CardLayoutState;
+interface CardPartChange {
+    part: CardPart;
+    /** The node removed (off) or stamped (on); null when there was nothing to do. */
+    node: CompositeNode | null;
+}
+/**
+ * Card ▸ Parts. Off removes the part (the badge first moves out of a removed Media); on stamps it back
+ * from the recipe into its role's slot, wearing its element style and laid out like the rest of the card
+ * (the card's current layout; Image top when it is Custom). Returns the node touched, or null when the
+ * card already was that way. Title and Content are not parts: they are locked (structure guard).
+ */
+declare function setCardPart(card: CompositeNode, part: CardPart, on: boolean, create?: CompositeNodeFactory, options?: CardOptions): CompositeNode | null;
+/** The card's title — what "Link the whole card" makes the link (its words are the link's name). */
+declare function cardTitleOf(card: CompositeNode): CompositeNode | undefined;
+/** True when the card links as a whole: its title carries a link (the stretched link renders from it). */
+declare function isCardLinked(card: CompositeNode): boolean;
+/**
+ * Card ▸ Link ▸ "Link the whole card". On: the title links (to a website page, unless it already pointed
+ * at a URL — the target it held is kept); off: the title links nowhere (its target is kept for the next
+ * time). The stretched link itself is the shared CSS (iox-design.css), keyed on the title's anchor.
+ */
+declare function setCardLinked(card: CompositeNode, on: boolean): boolean;
+
+/**
+ * The structure every composite declares (composite-components plan §3a `RoleSpec`): where a role may
+ * live and whether it is LOCKED (a structural part that cannot be deleted or moved out — a card always
+ * has its content column and its title). Optional parts carry the Parts switch that re-adds them.
+ * The builder's delete paths and its drop/paste rule ask `structureRefusal` — ONE answer for all of them.
+ */
+interface CompositeRoleSpec {
+    /** The role of the part's parent; null for a composite root. */
+    readonly parent: string | null;
+    readonly locked?: boolean;
+    readonly part?: CardPart;
+}
+declare const COMPOSITE_ROLE_SPECS: Readonly<Record<string, CompositeRoleSpec>>;
+declare enum StructureEdit {
+    Delete = "delete",
+    /** A drop, paste or wrap that would put the node somewhere new. */
+    Move = "move"
+}
+declare enum StructureRefusal {
+    /** A locked part cannot be deleted (the card's Content and Title). */
+    LockedPart = "locked-part",
+    /** A locked part can only live directly inside its own parent role. */
+    LockedPlacement = "locked-placement"
+}
+interface RoleLike {
+    role?: string | null;
+}
+/**
+ * Why the structure guard refuses `edit` on `node`, or null when it is allowed. `ancestors` (Move only) =
+ * the new parent chain, root first, the direct parent last.
+ */
+declare function structureRefusal(node: RoleLike | null | undefined, edit: StructureEdit, ancestors?: ReadonlyArray<RoleLike>): StructureRefusal | null;
+/** True when `node` is a locked part (shown with a lock and no delete in the layer tree). Deleting a whole
+ *  composite is always allowed — only its locked parts are refused. */
+declare function isLockedPart(node: RoleLike | null | undefined): boolean;
+
+export { 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_ROLE_SPECS, CardLayout, CardPart, CardRole, StructureEdit, StructureRefusal, applyCardLayout, badgeStyleId, badgeToneOf, buildBadge, buildCardRecipe, buildChip, cardPartsOf, cardRootOf, cardTitleOf, clearLayerStyles, detectCardLayout, findByRole, isCardLinked, isCardRoot, isLockedPart, isPillNode, parentInComposite, readLayerStyle, readProp, readStyle, removeFromComposite, setBadgeTone, setCardLinked, setCardPart, structureRefusal, walkComposite, writeLayerStyles, writeProp, writeStyles };
+export type { BaselineStyles, CardEditOptions, CardLayoutResult, CardLayoutState, CardOptions, CardPartChange, CardWords, CompositeLayer, CompositeNode, CompositeNodeFactory, CompositeNodeSpec, CompositeRoleSpec, CompositeTrait, PillOptions };

package/composite-core/package.json

@@ -0,0 +1,3 @@
+{
+  "module": "../fesm2022/vectoriox-iox-ui-composite-core.mjs"
+}