@vectoriox/iox-ui 5.30.0 → 5.31.0

package/src/composite-core/card.ts

@@ -0,0 +1,524 @@
+import { elementStyleById, LinkType, switchElementStyle } from '@vectoriox/iox-ui/design-core';
+
+import { BadgeTone, buildBadge } from './badge';
+import {
+    clearLayerStyles, CompositeNode, CompositeNodeFactory, findByRole, parentInComposite, readLayerStyle, readProp, readStyle,
+    removeFromComposite, writeLayerStyles, writeProp, writeStyles,
+} from './composite-node';
+
+/**
+ * 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.
+ */
+
+export 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. */
+export enum CardPart {
+    Media = 'media',
+    Badge = 'badge',
+    Eyebrow = 'eyebrow',
+    Text = 'text',
+    Actions = 'actions',
+}
+
+export const CARD_PARTS: ReadonlyArray<CardPart> = [CardPart.Media, CardPart.Badge, CardPart.Eyebrow, CardPart.Text, CardPart.Actions];
+
+export const CARD_PART_ROLE: Readonly<Record<CardPart, CardRole>> = {
+    [CardPart.Media]: CardRole.Media,
+    [CardPart.Badge]: CardRole.Badge,
+    [CardPart.Eyebrow]: CardRole.Eyebrow,
+    [CardPart.Text]: CardRole.Text,
+    [CardPart.Actions]: CardRole.Actions,
+};
+
+/** Card ▸ Layout — a preset, never a stored trait: `applyCardLayout` writes the card's layout styles. */
+export enum CardLayout {
+    Top = 'top',
+    Side = 'side',
+    Overlay = 'overlay',
+    Compact = 'compact',
+}
+
+export const CARD_LAYOUTS: ReadonlyArray<CardLayout> = [CardLayout.Top, CardLayout.Side, CardLayout.Overlay, CardLayout.Compact];
+/** What Card ▸ Layout shows once the author has changed the layout styles by hand. */
+export const CARD_LAYOUT_CUSTOM = 'custom';
+export type CardLayoutState = CardLayout | typeof CARD_LAYOUT_CUSTOM;
+
+/** The words a fresh card starts with — the author's to replace (or a bound field's). */
+export interface CardWords {
+    eyebrow: string;
+    title: string;
+    text: string;
+    primary: string;
+    secondary: string;
+    badge: string;
+}
+
+export const CARD_WORDS: Readonly<CardWords> = {
+    eyebrow: 'Category',
+    title: 'Card title',
+    text: 'One or two sentences about this item.',
+    primary: 'Learn more',
+    secondary: 'Save',
+    badge: 'New',
+};
+
+/** The breakpoint whose layer stacks an "Image side" card (Breakpoint.Mobile, ≤767px). */
+export const CARD_STACK_BREAKPOINT = 'mobile';
+
+enum Type {
+    Container = 'Container',
+    Image = 'Image',
+    Heading = 'Heading',
+    Text = 'Text',
+    Icon = 'Icon',
+    ButtonBlock = 'ButtonBlock',
+}
+
+enum Style {
+    Card = 'card',
+    Box = 'box',
+    Media = 'media',
+    Eyebrow = 'eyebrow',
+    Title = 'h3',
+    Body = 'body',
+    Label = 'button-label',
+    Primary = 'button-primary',
+    Ghost = 'button-ghost',
+    Icon = 'icon',
+    Scrim = 'media-scrim',
+}
+
+enum Scheme {
+    Default = 'default',
+    Inverse = 'inverse',
+}
+
+const COLOR_SCHEME = 'colorScheme';
+const LINK_TYPE = 'linkType';
+const SAVE_ICON = 'ph ph-bookmark-simple';
+
+/** A value an element style writes — read from the contract, never retyped. */
+const styleValue = (style: string, trait: string): string => String(elementStyleById(style)?.base[trait] ?? '');
+const CARD_PAD = styleValue(Style.Card, 'padding');
+const IMAGE_RADIUS = styleValue(Style.Media, 'borderRadius');
+const TITLE_SIZE = styleValue(Style.Title, 'fontSize');
+const LEAD_SIZE = 'var(--iox-size-lead)';
+const ZERO_BOX = '0px 0px 0px 0px';
+
+/** What every card part holds in every layout — the recipe's box. */
+const CARD_BASE: Readonly<Record<string, Readonly<Record<string, string>>>> = {
+    [CardRole.Card]: { display: 'flex', gap: '14px', width: '100%', height: '100%', minWidth: '0px', overflow: 'hidden', position: 'relative' },
+    [CardRole.Media]: { display: 'block', width: '100%', minHeight: 'auto', flexGrow: '0', flexShrink: '0' },
+    [CardRole.Content]: { display: 'flex', flexDirection: 'column', gap: '8px', width: '100%', minWidth: '0px', minHeight: 'auto' },
+    [CardRole.Eyebrow]: { margin: ZERO_BOX, padding: ZERO_BOX, minHeight: 'auto' },
+    [CardRole.Title]: { margin: ZERO_BOX },
+    [CardRole.Text]: { margin: ZERO_BOX, padding: ZERO_BOX, minHeight: 'auto' },
+    // Buttons pinned to the bottom (board 8 Q: equal heights + buttons pinned): the content column grows,
+    // and the row's auto top margin takes the slack.
+    [CardRole.Actions]: { display: 'flex', flexWrap: 'wrap', alignItems: 'center', gap: '8px', margin: 'auto 0px 0px 0px', padding: '6px 0px 0px 0px', width: '100%', minHeight: 'auto' },
+};
+const IMAGE_BASE: Readonly<Record<string, string>> = { display: 'block', width: '100%', maxWidth: '100%' };
+/** A button's label and a pill's words: inherit the type and ink of what holds them. */
+const LABEL_BASE: Readonly<Record<string, string>> = { width: 'auto', minHeight: 'auto', padding: ZERO_BOX, margin: ZERO_BOX };
+const INLINE_ICON: Readonly<Record<string, string>> = { fontSize: '1em' };
+
+/** One layout preset: the style values it writes per role (every layout writes the same keys, so
+ *  switching is clean and detection exact), where the badge sits, and what it switches off. */
+interface CardLayoutSpec {
+    card: Readonly<Record<string, string>>;
+    media: Readonly<Record<string, string>>;
+    image: Readonly<Record<string, string>>;
+    content: Readonly<Record<string, string>>;
+    contentStyle: Style;
+    contentScheme: Scheme;
+    title: Readonly<Record<string, string>>;
+    badgeOnMedia: boolean;
+    /** The stacking layer (Image side only); every other layout clears these keys from it. */
+    stack?: { card: Readonly<Record<string, string>>; media: Readonly<Record<string, string>>; image: Readonly<Record<string, string>> };
+    partsOff?: ReadonlyArray<CardPart>;
+}
+
+const IN_FLOW = { position: 'relative', top: 'auto', right: 'auto', bottom: 'auto', left: 'auto' };
+const GROWING_CONTENT = { position: 'static', flexGrow: '1', flexShrink: '1', flexBasis: '0%', padding: ZERO_BOX };
+
+const LAYOUTS: Readonly<Record<CardLayout, CardLayoutSpec>> = {
+    [CardLayout.Top]: {
+        card: { flexDirection: 'column', alignItems: 'stretch', justifyContent: 'flex-start', minHeight: 'auto', padding: CARD_PAD },
+        media: { ...IN_FLOW, flexBasis: 'auto' },
+        image: { aspectRatio: '4 / 3', height: 'auto', minHeight: 'auto', borderRadius: IMAGE_RADIUS },
+        content: GROWING_CONTENT, contentStyle: Style.Box, contentScheme: Scheme.Default,
+        title: { fontSize: TITLE_SIZE },
+        badgeOnMedia: true,
+    },
+    [CardLayout.Side]: {
+        card: { flexDirection: 'row', alignItems: 'stretch', justifyContent: 'flex-start', minHeight: 'auto', padding: CARD_PAD },
+        media: { ...IN_FLOW, flexBasis: '42%' },
+        image: { aspectRatio: 'auto', height: '100%', minHeight: '180px', borderRadius: IMAGE_RADIUS },
+        content: GROWING_CONTENT, contentStyle: Style.Box, contentScheme: Scheme.Default,
+        title: { fontSize: TITLE_SIZE },
+        badgeOnMedia: true,
+        stack: {
+            card: { flexDirection: 'column' },
+            media: { flexBasis: 'auto' },
+            image: { aspectRatio: '4 / 3', height: 'auto', minHeight: 'auto' },
+        },
+    },
+    [CardLayout.Overlay]: {
+        card: { flexDirection: 'column', alignItems: 'stretch', justifyContent: 'flex-end', minHeight: '340px', padding: ZERO_BOX },
+        media: { position: 'absolute', top: '0px', right: '0px', bottom: '0px', left: '0px', flexBasis: 'auto' },
+        image: { aspectRatio: 'auto', height: '100%', minHeight: 'auto', borderRadius: '0px' },
+        content: { position: 'relative', flexGrow: '0', flexShrink: '0', flexBasis: 'auto', padding: `72px ${CARD_PAD} ${CARD_PAD} ${CARD_PAD}` },
+        contentStyle: Style.Scrim, contentScheme: Scheme.Inverse,
+        title: { fontSize: TITLE_SIZE },
+        badgeOnMedia: false,
+    },
+    [CardLayout.Compact]: {
+        card: { flexDirection: 'row', alignItems: 'center', justifyContent: 'flex-start', minHeight: 'auto', padding: CARD_PAD },
+        media: { ...IN_FLOW, flexBasis: '72px' },
+        image: { aspectRatio: '1 / 1', height: 'auto', minHeight: 'auto', borderRadius: IMAGE_RADIUS },
+        content: GROWING_CONTENT, contentStyle: Style.Box, contentScheme: Scheme.Default,
+        title: { fontSize: LEAD_SIZE },
+        badgeOnMedia: false,
+        partsOff: [CardPart.Text, CardPart.Actions],
+    },
+};
+
+const STACK_KEYS = {
+    card: Object.keys(LAYOUTS[CardLayout.Side].stack!.card),
+    media: Object.keys(LAYOUTS[CardLayout.Side].stack!.media),
+    image: Object.keys(LAYOUTS[CardLayout.Side].stack!.image),
+};
+
+/** 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`. */
+export type BaselineStyles = (type: string) => Readonly<Record<string, unknown>>;
+
+export interface CardEditOptions {
+    baselineStyles?: BaselineStyles;
+}
+
+export 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;
+}
+
+
+function make(create: CompositeNodeFactory, key: string, type: string, role: CardRole | null, elementStyle: string | null,
+    props: Record<string, unknown> = {}, label?: string): CompositeNode {
+    const node = create({ key, type, props, elementStyle });
+    if (role) node.role = role;
+    if (label) node.label = label;
+    writeStyles(node, role ? CARD_BASE[role] ?? {} : {});
+    return node;
+}
+
+function buttonLabel(create: CompositeNodeFactory, key: string, words: string): CompositeNode {
+    const label = make(create, key, Type.Text, null, Style.Label, { content: words, tag: 'span' });
+    writeStyles(label, LABEL_BASE);
+    return label;
+}
+
+/** Each optional part (and the locked title) as the recipe builds it. */
+const PART_BUILDERS: Readonly<Record<CardPart, (create: CompositeNodeFactory, words: CardWords, tone: BadgeTone) => CompositeNode>> = {
+    [CardPart.Media]: (create) => {
+        const media = make(create, 'media', Type.Container, CardRole.Media, Style.Box, {}, 'Media');
+        const image = make(create, 'image', Type.Image, null, Style.Media, { src: '', alt: '' });
+        writeStyles(image, IMAGE_BASE);
+        media.children = [image];
+        return media;
+    },
+    [CardPart.Badge]: (create, words, tone) => {
+        const badge = buildBadge(create, { tone, text: words.badge, key: 'badge' });
+        badge.role = CardRole.Badge;
+        badge.label = 'Badge';
+        return badge;
+    },
+    [CardPart.Eyebrow]: (create, words) => make(create, 'eyebrow', Type.Text, CardRole.Eyebrow, Style.Eyebrow, { content: words.eyebrow, tag: 'p' }, 'Eyebrow'),
+    [CardPart.Text]: (create, words) => make(create, 'text', Type.Text, CardRole.Text, Style.Body, { content: words.text, tag: 'p' }, 'Text'),
+    [CardPart.Actions]: (create, words) => {
+        const actions = make(create, 'actions', Type.Container, CardRole.Actions, Style.Box, {}, 'Buttons');
+        const primary = make(create, 'primary', Type.ButtonBlock, null, Style.Primary);
+        primary.children = [buttonLabel(create, 'primary-label', words.primary)];
+        const ghost = make(create, 'secondary', Type.ButtonBlock, null, Style.Ghost);
+        const icon = make(create, 'secondary-icon', Type.Icon, null, Style.Icon, { iconClass: SAVE_ICON });
+        writeStyles(icon, INLINE_ICON);
+        ghost.children = [icon, buttonLabel(create, 'secondary-label', words.secondary)];
+        actions.children = [primary, ghost];
+        return actions;
+    },
+};
+
+function buildTitle(create: CompositeNodeFactory, words: CardWords): CompositeNode {
+    return make(create, 'title', Type.Heading, CardRole.Title, Style.Title, { content: words.title, level: 'h3', [LINK_TYPE]: LinkType.None }, 'Title');
+}
+
+/** A fresh Card v2: every part a node with its role and element style, laid out by `options.layout`. */
+export function buildCardRecipe(create: CompositeNodeFactory, options: CardOptions = {}): CompositeNode {
+    const words: CardWords = { ...CARD_WORDS, ...(options.words ?? {}) };
+    const tone = options.badgeTone ?? BadgeTone.Accent;
+    const on = (part: CardPart) => options.parts?.[part] !== false;
+    const card = make(create, 'card', Type.Container, CardRole.Card, Style.Card, {}, 'Card');
+    const content = make(create, 'content', Type.Container, CardRole.Content, Style.Box, {}, 'Content');
+    content.children = [
+        ...(on(CardPart.Eyebrow) ? [PART_BUILDERS[CardPart.Eyebrow](create, words, tone)] : []),
+        buildTitle(create, words),
+        ...(on(CardPart.Text) ? [PART_BUILDERS[CardPart.Text](create, words, tone)] : []),
+        ...(on(CardPart.Actions) ? [PART_BUILDERS[CardPart.Actions](create, words, tone)] : []),
+    ];
+    card.children = [...(on(CardPart.Media) ? [PART_BUILDERS[CardPart.Media](create, words, tone)] : []), content];
+    if (on(CardPart.Badge)) placeBadge(card, PART_BUILDERS[CardPart.Badge](create, words, tone), true);
+    applyCardLayout(card, options.layout ?? CardLayout.Top, options);
+    return card;
+}
+
+/** True when `node` is a Card v2 root. */
+export function isCardRoot(node: CompositeNode | null | undefined): boolean {
+    return node?.role === CardRole.Card;
+}
+
+/** The Card a part belongs to: the nearest ancestor (or the node itself) playing `card`. `path` = the
+ *  node's ancestors, root first. */
+export function cardRootOf(node: CompositeNode, path: ReadonlyArray<CompositeNode>): CompositeNode | null {
+    if (isCardRoot(node)) return node;
+    for (let i = path.length - 1; i >= 0; i--) if (isCardRoot(path[i])) return path[i];
+    return null;
+}
+
+/** Card ▸ Parts: which optional parts the card holds now. */
+export function cardPartsOf(card: CompositeNode): Record<CardPart, boolean> {
+    return Object.fromEntries(CARD_PARTS.map(part => [part, !!findByRole(card, CARD_PART_ROLE[part])])) as Record<CardPart, boolean>;
+}
+
+const imageOf = (media: CompositeNode | undefined): CompositeNode | undefined => media?.children?.find(c => c.type === Type.Image);
+
+/** Put the badge where the layout says: the Media's top corner, or the head of the content column
+ *  (Image behind text, Compact, or no Media at all). */
+function placeBadge(card: CompositeNode, badge: CompositeNode, onMedia: boolean): void {
+    const media = findByRole(card, CardRole.Media);
+    const content = findByRole(card, CardRole.Content);
+    removeFromComposite(card, badge);
+    if (onMedia && media) media.children = [...(media.children ?? []), badge];
+    else if (content) content.children = [badge, ...(content.children ?? [])];
+}
+
+function writeScheme(node: CompositeNode, scheme: Scheme): void {
+    writeProp(node, COLOR_SCHEME, scheme);
+}
+
+/** Write one role's layout values from a spec (base + layers). */
+function applyPartLayout(card: CompositeNode, spec: CardLayoutSpec, part: CompositeNode, baseline: BaselineStyles): void {
+    switch (part.role) {
+        case CardRole.Card:
+            writeStyles(part, { ...CARD_BASE[CardRole.Card], ...spec.card });
+            setStack(part, spec.stack?.card, STACK_KEYS.card);
+            return;
+        case CardRole.Media: {
+            writeStyles(part, { ...CARD_BASE[CardRole.Media], ...spec.media });
+            setStack(part, spec.stack?.media, STACK_KEYS.media);
+            const image = imageOf(part);
+            if (image) {
+                writeStyles(image, { ...IMAGE_BASE, ...spec.image });
+                setStack(image, spec.stack?.image, STACK_KEYS.image);
+            }
+            return;
+        }
+        case CardRole.Content: {
+            const current = part.elementStyle;
+            if (current !== spec.contentStyle) {
+                switchElementStyle(part, current, spec.contentStyle, baseline(part.type));
+                part.elementStyle = spec.contentStyle;
+            }
+            writeStyles(part, { ...CARD_BASE[CardRole.Content], ...spec.content });
+            writeScheme(part, spec.contentScheme);
+            return;
+        }
+        case CardRole.Title:
+            writeStyles(part, spec.title);
+            return;
+        default:
+            return;
+    }
+}
+
+function setStack(node: CompositeNode, values: Readonly<Record<string, string>> | undefined, keys: ReadonlyArray<string>): void {
+    if (values) writeLayerStyles(node, CARD_STACK_BREAKPOINT, values);
+    else clearLayerStyles(node, CARD_STACK_BREAKPOINT, keys);
+}
+
+export 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.
+ */
+export function applyCardLayout(card: CompositeNode, layout: CardLayout, options: CardEditOptions = {}): CardLayoutResult {
+    const spec = LAYOUTS[layout];
+    const baseline = options.baselineStyles ?? (() => ({}));
+    const removed: CardPart[] = [];
+    for (const part of spec.partsOff ?? []) if (setCardPart(card, part, false)) removed.push(part);
+    applyPartLayout(card, spec, card, baseline);
+    for (const role of [CardRole.Media, CardRole.Content, CardRole.Title]) {
+        const part = findByRole(card, role);
+        if (part) applyPartLayout(card, spec, part, baseline);
+    }
+    const badge = findByRole(card, CardRole.Badge);
+    if (badge) placeBadge(card, badge, spec.badgeOnMedia);
+    return { layout, removed };
+}
+
+const same = (a: unknown, b: unknown) => String(a ?? '').trim() === String(b ?? '').trim();
+const holds = (node: CompositeNode, values: Readonly<Record<string, string>>) => Object.entries(values).every(([k, v]) => same(readStyle(node, k), v));
+const holdsLayer = (node: CompositeNode, values: Readonly<Record<string, string>> | undefined, keys: ReadonlyArray<string>) =>
+    values ? Object.entries(values).every(([k, v]) => same(readLayerStyle(node, CARD_STACK_BREAKPOINT, k), v))
+        : keys.every(k => readLayerStyle(node, CARD_STACK_BREAKPOINT, k) === undefined);
+
+function matches(card: CompositeNode, spec: CardLayoutSpec): boolean {
+    if (!holds(card, spec.card) || !holdsLayer(card, spec.stack?.card, STACK_KEYS.card)) return false;
+    const media = findByRole(card, CardRole.Media);
+    if (media) {
+        if (!holds(media, spec.media) || !holdsLayer(media, spec.stack?.media, STACK_KEYS.media)) return false;
+        const image = imageOf(media);
+        if (image && (!holds(image, spec.image) || !holdsLayer(image, spec.stack?.image, STACK_KEYS.image))) return false;
+    }
+    const content = findByRole(card, CardRole.Content);
+    if (content) {
+        if (content.elementStyle !== spec.contentStyle || !holds(content, spec.content)) return false;
+        if (!same(readProp(content, COLOR_SCHEME) ?? Scheme.Default, spec.contentScheme)) return false;
+    }
+    const title = findByRole(card, CardRole.Title);
+    if (title && !holds(title, spec.title)) return false;
+    const badge = findByRole(card, CardRole.Badge);
+    if (badge && media) {
+        const onMedia = parentInComposite(card, badge) === media;
+        if (onMedia !== spec.badgeOnMedia) return false;
+    }
+    return true;
+}
+
+/** The layout the card's styles hold now, or `custom` once they were changed by hand (Card ▸ Layout). */
+export function detectCardLayout(card: CompositeNode): CardLayoutState {
+    return CARD_LAYOUTS.find(layout => matches(card, LAYOUTS[layout])) ?? CARD_LAYOUT_CUSTOM;
+}
+
+export 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).
+ */
+export function setCardPart(card: CompositeNode, part: CardPart, on: boolean, create?: CompositeNodeFactory, options: CardOptions = {}): CompositeNode | null {
+    const role = CARD_PART_ROLE[part];
+    const existing = findByRole(card, role);
+    if (!on) {
+        if (!existing) return null;
+        if (part === CardPart.Media) {
+            const badge = findByRole(existing, CardRole.Badge);
+            if (badge) placeBadge(card, badge, false);
+        }
+        removeFromComposite(card, existing);
+        return existing;
+    }
+    if (existing || !create) return null;
+    const layout = detectCardLayout(card);
+    const spec = LAYOUTS[layout === CARD_LAYOUT_CUSTOM ? CardLayout.Top : layout];
+    const words: CardWords = { ...CARD_WORDS, ...(options.words ?? {}) };
+    const node = PART_BUILDERS[part](create, words, options.badgeTone ?? BadgeTone.Accent);
+    const content = findByRole(card, CardRole.Content);
+    switch (part) {
+        case CardPart.Media: {
+            card.children = [node, ...(card.children ?? [])];
+            applyPartLayout(card, spec, node, () => ({}));
+            const badge = findByRole(card, CardRole.Badge);
+            if (badge) placeBadge(card, badge, spec.badgeOnMedia);
+            break;
+        }
+        case CardPart.Badge:
+            placeBadge(card, node, spec.badgeOnMedia);
+            break;
+        default:
+            if (content) insertInContent(content, part, node);
+            break;
+    }
+    return node;
+}
+
+/** The content column's order: [badge], eyebrow, title, text, buttons. */
+const CONTENT_ORDER: ReadonlyArray<string> = [CardRole.Badge, CardRole.Eyebrow, CardRole.Title, CardRole.Text, CardRole.Actions];
+
+function insertInContent(content: CompositeNode, part: CardPart, node: CompositeNode): void {
+    const rank = (n: CompositeNode) => { const i = CONTENT_ORDER.indexOf(n.role ?? ''); return i < 0 ? CONTENT_ORDER.length : i; };
+    const children = [...(content.children ?? [])];
+    const own = rank(node);
+    const at = children.findIndex(c => rank(c) > own);
+    children.splice(at < 0 ? children.length : at, 0, node);
+    content.children = children;
+}
+
+// ── Link the whole card ──────────────────────────────────────────────────────────────────────
+
+/** The card's title — what "Link the whole card" makes the link (its words are the link's name). */
+export function cardTitleOf(card: CompositeNode): CompositeNode | undefined {
+    return findByRole(card, CardRole.Title);
+}
+
+/** True when the card links as a whole: its title carries a link (the stretched link renders from it). */
+export function isCardLinked(card: CompositeNode): boolean {
+    const title = cardTitleOf(card);
+    if (!title) return false;
+    const type = readProp(title, LINK_TYPE);
+    return type === LinkType.Page || type === LinkType.External;
+}
+
+/**
+ * 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.
+ */
+export function setCardLinked(card: CompositeNode, on: boolean): boolean {
+    const title = cardTitleOf(card);
+    if (!title) return false;
+    const current = readProp(title, LINK_TYPE);
+    const next = on ? (current === LinkType.External ? LinkType.External : LinkType.Page) : LinkType.None;
+    return writeProp(title, LINK_TYPE, next);
+}

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

@@ -0,0 +1,143 @@
+import { ElementStyleTarget, readOwnedTrait, writeOwnedTrait } 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.
+ */
+export interface CompositeTrait {
+    name: string;
+    default?: unknown;
+}
+
+export interface CompositeLayer {
+    styleProps?: Record<string, unknown>;
+    [key: string]: unknown;
+}
+
+export 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>`). */
+export interface CompositeNodeSpec {
+    key: string;
+    type: string;
+    props?: Readonly<Record<string, unknown>>;
+    elementStyle?: string | null;
+}
+
+export type CompositeNodeFactory = (spec: CompositeNodeSpec) => CompositeNode;
+
+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. */
+export function readProp(node: CompositeNode, name: string): unknown {
+    return usesTraits(node) ? node.traits!.find(t => t.name === name)?.default : node.props?.[name];
+}
+
+/** Write a content trait. False when a builder node has no such trait (the value would be dropped). */
+export function writeProp(node: CompositeNode, name: string, value: unknown): boolean {
+    if (usesTraits(node)) {
+        const trait = node.traits!.find(t => t.name === name);
+        if (!trait) return false;
+        trait.default = value;
+        return true;
+    }
+    node.props = { ...(node.props ?? {}), [name]: value };
+    return true;
+}
+
+/** A base style value (the node's own, either shape). */
+export function readStyle(node: CompositeNode, name: string): unknown {
+    return readOwnedTrait(node, { trait: name });
+}
+
+/** Write base style values; returns the names the node has no slot for (a builder node drops them). */
+export function writeStyles(node: CompositeNode, values: Readonly<Record<string, string>>): string[] {
+    const missing: string[] = [];
+    for (const [name, value] of Object.entries(values)) {
+        if (!writeOwnedTrait(node, { trait: name }, value)) missing.push(name);
+    }
+    return missing;
+}
+
+/** Set style values in one breakpoint layer (`responsive[bp].styleProps`, the shape both renderers'
+ *  shared `planResponsiveRules` reads). */
+export function writeLayerStyles(node: CompositeNode, breakpoint: string, values: Readonly<Record<string, string>>): void {
+    const responsive = { ...(node.responsive ?? {}) };
+    const layer: CompositeLayer = { ...(responsive[breakpoint] ?? {}) };
+    layer.styleProps = { ...(layer.styleProps ?? {}), ...values };
+    responsive[breakpoint] = layer;
+    node.responsive = responsive;
+}
+
+/** Remove style keys from one breakpoint layer; an emptied layer (and an emptied map) is dropped. */
+export function clearLayerStyles(node: CompositeNode, breakpoint: string, names: ReadonlyArray<string>): void {
+    const layer = node.responsive?.[breakpoint];
+    if (!layer?.styleProps) return;
+    const styleProps = { ...layer.styleProps };
+    for (const name of names) delete styleProps[name];
+    const next: CompositeLayer = { ...layer };
+    if (Object.keys(styleProps).length) next.styleProps = styleProps;
+    else delete next.styleProps;
+    const responsive = { ...(node.responsive ?? {}) };
+    if (Object.keys(next).length) responsive[breakpoint] = next;
+    else delete responsive[breakpoint];
+    node.responsive = Object.keys(responsive).length ? responsive : undefined;
+}
+
+/** A breakpoint layer's own value for one style key. */
+export function readLayerStyle(node: CompositeNode, breakpoint: string, name: string): unknown {
+    return node.responsive?.[breakpoint]?.styleProps?.[name];
+}
+
+/** Depth-first: `node`, then every descendant. */
+export function walkComposite(node: CompositeNode, visit: (node: CompositeNode, parent: CompositeNode | null) => void, parent: CompositeNode | null = null): void {
+    visit(node, parent);
+    for (const child of node.children ?? []) walkComposite(child, visit, node);
+}
+
+/**
+ * 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).
+ */
+export function findByRole(root: CompositeNode, role: string): CompositeNode | undefined {
+    for (const child of root.children ?? []) {
+        if (child.role === role) return child;
+        if (child.role === root.role && root.role) continue;
+        const hit = findByRole(child, role);
+        if (hit) return hit;
+    }
+    return undefined;
+}
+
+/** The node's parent inside `root`, or null. */
+export function parentInComposite(root: CompositeNode, node: CompositeNode): CompositeNode | null {
+    for (const child of root.children ?? []) {
+        if (child === node) return root;
+        const hit = parentInComposite(child, node);
+        if (hit) return hit;
+    }
+    return null;
+}
+
+/** Detach `node` from its parent inside `root`. True when it was found. */
+export function removeFromComposite(root: CompositeNode, node: CompositeNode): boolean {
+    const parent = parentInComposite(root, node);
+    if (!parent?.children) return false;
+    parent.children.splice(parent.children.indexOf(node), 1);
+    return true;
+}

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

@@ -0,0 +1,11 @@
+/**
+ * @vectoriox/iox-ui/composite-core — composites built from the builder's own parts (composite-components
+ * 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; Accordion and Tabs join with their own phases.
+ * ⚠️ Consumers wire the usual trio — ng-package raw-ts assets, jest moduleNameMapper, tsconfig paths.
+ */
+export * from './composite-node';
+export * from './badge';
+export * from './card';
+export * from './structure';