@vectoriox/iox-ui 5.30.0 → 5.31.0

package/src/design-core/node-classes.ts

@@ -9,9 +9,12 @@ import { SPEC_SCHEMES } from './flavor-spec.generated';
  * - the element-style MARKER `iox-es iox-es-<id>` (design-system §3b-bis) — component CSS carrying
  *   the system look is scoped to it, so a node saved before DS2 keeps its pre-DS2 look;
  * - the section colour scheme `iox-scheme-<id>` (§3c) for a non-default `colorScheme` — the class
- *   `compileSchemeCss` re-declares tokens on, so everything inside re-resolves.
+ *   `compileSchemeCss` re-declares tokens on, so everything inside re-resolves;
+ * - the composite ROLE `iox-role-<role>` (`card.media` → `iox-role-card-media`; composite-components
+ *   plan §3, Card v2) — what the shared CSS keys a part's structural rules on (the badge's corner, the
+ *   card's stretched link), so a role is never a renderer's private knowledge.
  *
- * Renderers read `elementStyle` and `colorScheme` for exactly this and nothing else.
+ * Renderers read `elementStyle`, `colorScheme` and `role` for exactly this and nothing else.
  */
 
 /** The section colour schemes — the contract's `schemes` keys. */
@@ -34,6 +37,9 @@ export const COLOR_SCHEMES: ReadonlyArray<{ readonly id: ColorScheme; readonly l
 
 const SCHEME_IDS = new Set<string>(Object.keys(SPEC_SCHEMES));
 const SCHEME_PREFIX = 'iox-scheme-';
+const ROLE_PREFIX = 'iox-role-';
+/** A role is dot-separated lowercase words (`card`, `card.title`) — anything else never reaches a class. */
+const ROLE_SHAPE = /^[a-z][a-z0-9-]*(\.[a-z][a-z0-9-]*)*$/;
 const MARKER_PREFIX = `${ELEMENT_STYLE_MARKER_CLASS}-`;
 
 /** `iox-scheme-<id>` for a known NON-default scheme, else null — an unknown id never reaches a class attribute. */
@@ -41,9 +47,15 @@ export function colorSchemeClass(id: unknown): string | null {
     return typeof id === 'string' && id !== ColorScheme.Default && SCHEME_IDS.has(id) ? `${SCHEME_PREFIX}${id}` : null;
 }
 
+/** `iox-role-<role>` for a well-formed composite role, else null. */
+export function roleClass(role: unknown): string | null {
+    return typeof role === 'string' && ROLE_SHAPE.test(role) ? `${ROLE_PREFIX}${role.replace(/\./g, '-')}` : null;
+}
+
 /** The node shapes this module reads: a serialized node (`props`) or a builder node (`traits[]`). */
 export interface DesignClassSource {
     elementStyle?: string | null;
+    role?: string | null;
     props?: Readonly<Record<string, unknown>> | null;
     traits?: ReadonlyArray<{ name?: string; default?: unknown }> | null;
 }
@@ -65,12 +77,12 @@ export function hasElementStyleMarker(node: { elementStyle?: string | null } | n
 /** The classes a node renders: `'iox-es iox-es-card iox-scheme-inverse'`, or `''` for none. */
 export function nodeDesignClasses(node: DesignClassSource | null | undefined): string {
     const marker = elementStyleClass(node?.elementStyle);
-    return [marker ? `${ELEMENT_STYLE_MARKER_CLASS} ${marker}` : '', colorSchemeClass(colorSchemeOf(node)) ?? '']
+    return [marker ? `${ELEMENT_STYLE_MARKER_CLASS} ${marker}` : '', colorSchemeClass(colorSchemeOf(node)) ?? '', roleClass(node?.role) ?? '']
         .filter(Boolean).join(' ');
 }
 
 const isDesignClass = (c: string) =>
-    c === ELEMENT_STYLE_MARKER_CLASS || c.startsWith(MARKER_PREFIX) || c.startsWith(SCHEME_PREFIX);
+    c === ELEMENT_STYLE_MARKER_CLASS || c.startsWith(MARKER_PREFIX) || c.startsWith(SCHEME_PREFIX) || c.startsWith(ROLE_PREFIX);
 
 /** Make an element's design classes match the node — the live switch on the canvas and the
  *  component path's one-time stamp. Removes stale ones; touches no other class. */

package/src/design-core/node-links.ts

@@ -6,6 +6,8 @@
  */
 
 export enum LinkType {
+    /** Links nowhere — a Heading's default; "Link the whole card" (Card v2) turns its title's link on. */
+    None = 'none',
     External = 'external',
     Page = 'page',
 }
@@ -30,3 +32,30 @@ export function buttonBlockHref(props: ButtonBlockLinkProps, pageHref: (route: s
     const href = props.linkType === LinkType.Page ? pageHref(String(props.pageRoute ?? '')) : String(props.href ?? '');
     return href || null;
 }
+
+export interface NodeLinkProps {
+    linkType?: unknown;
+    url?: unknown;
+    pageRoute?: unknown;
+}
+
+/** The class of the `<a>` a linked Heading renders — the Card v2 stretched link keys on it (iox-design.css:
+ *  the card is the click target, its buttons sit above, the focus ring is drawn on the card). */
+export const CARD_LINK_CLASS = 'iox-card-link';
+/** On the editing canvas the anchor carries this, so the stretched `::after` is off and every part of the
+ *  card stays clickable (board 8). */
+export const CANVAS_LINK_ATTRIBUTE = 'data-iox-canvas';
+
+/**
+ * The href a linked Heading renders (Card v2: the card's title IS its link), or `null` when it links
+ * nowhere — `none`, or a link with no target yet (the title then renders as plain words). A page link goes
+ * through `pageHref` exactly as a ButtonBlock's does.
+ */
+export function headingHref(props: NodeLinkProps, pageHref: (route: string) => string = route => route): string | null {
+    if (props.linkType === LinkType.Page) {
+        const route = String(props.pageRoute ?? '');
+        return route ? pageHref(route) || null : null;
+    }
+    if (props.linkType === LinkType.External) return String(props.url ?? '').trim() || null;
+    return null;
+}

package/src/generation-core/compose-site.ts

@@ -1,8 +1,9 @@
 import { DesignChoices, LinkType, resolveDesignChoices } from '@vectoriox/iox-ui/design-core';
 import { FormPresetDef, FormPresetField, formPresetById } from '@vectoriox/iox-ui/forms-core';
+import { buildCardRecipe, CardLayout, CardPart, CardRole, CARD_LAYOUTS, CARD_PARTS, CompositeNode, CompositeNodeSpec, findByRole } from '@vectoriox/iox-ui/composite-core';
 
 import { NODE_BASELINES } from './node-baselines.generated';
-import { BindScope, PatternDirective, PatternNode, PatternPlaceholder, SitePattern, patternById } from './patterns';
+import { BindScope, CardBindTarget, PatternDirective, PatternNode, PatternPlaceholder, PatternRecipe, SitePattern, patternById } from './patterns';
 import { assertStyleSlots, ComposeError, createSerializedNode, SerializedBinding, SerializedNode, setStyleProps } from './serialized-node';
 import {
     ContentTypePlan, DataSourcePlan, FactKey, FACT_KEYS, GlobalSlot, PagePlan, PageSectionPlan, PlanDataSourceMode, PlanDataSourceType,
@@ -159,6 +160,8 @@ const LINK_SLOTS: Readonly<Record<string, LinkSlots>> = {
     Link: { url: 'url' },
     LinkedContainer: { url: 'url' },
     ButtonBlock: { url: 'href', fixed: { tag: 'a' } },
+    // A Card v2 links as a whole through its TITLE (the stretched link): the Heading carries the link.
+    Heading: { url: 'url' },
 };
 /** What a linked box becomes when its link has nowhere to go: the same box, unlinked. */
 const UNLINKED_TYPE: Readonly<Record<string, string>> = { LinkedContainer: 'Container' };
@@ -433,6 +436,7 @@ function composeChildren(pn: PatternNode, id: string, repeater: RepeaterScope |
  *  dangling link is removed. */
 function composeNode(pn: PatternNode, id: string, repeater: RepeaterScope | null, ctx: Ctx): SerializedNode | null {
     if (pn.optional && ctx.section?.without?.includes(pn.optional)) return null;
+    if (pn.recipe) return composeRecipe(pn, id, repeater, ctx);
 
     const words = chooseText(pn, ctx);
     const fate = danglingFate(pn, ctx);
@@ -537,6 +541,56 @@ function composeNode(pn: PatternNode, id: string, repeater: RepeaterScope | null
     return node;
 }
 
+/** A Card v2 `binds` key → the part it binds and that part's bound prop. */
+const CARD_BINDS: Readonly<Record<CardBindTarget, { role: CardRole; prop: string }>> = {
+    [CardBindTarget.Image]: { role: CardRole.Media, prop: 'src' },
+    [CardBindTarget.Eyebrow]: { role: CardRole.Eyebrow, prop: 'content' },
+    [CardBindTarget.Title]: { role: CardRole.Title, prop: 'content' },
+    [CardBindTarget.Text]: { role: CardRole.Text, prop: 'content' },
+};
+
+/**
+ * A `recipe` node: the composite-core recipe, stamped whole with THIS composer's node factory — the same
+ * recipe the builder's palette stamps with its own — then bound part by part, and linked as a whole card
+ * through its title (`href` + `param`, the stretched link). Ids derive from the recipe's keys.
+ */
+function composeRecipe(pn: PatternNode, id: string, repeater: RepeaterScope | null, ctx: Ctx): SerializedNode {
+    if (pn.recipe !== PatternRecipe.Card) throw new ComposeError(`${id}: no recipe "${pn.recipe}" in composite-core`);
+    const layout = (pn.layout ?? CardLayout.Top) as CardLayout;
+    if (!CARD_LAYOUTS.includes(layout)) throw new ComposeError(`${id}: a card has no layout "${pn.layout}"`);
+    for (const part of Object.keys(pn.parts ?? {})) {
+        if (!CARD_PARTS.includes(part as CardPart)) throw new ComposeError(`${id}: a card has no part "${part}"`);
+    }
+    const factory = (spec: CompositeNodeSpec): CompositeNode =>
+        create(spec.key === CardRole.Card ? id : `${id}-${spec.key}`, spec.type, { ...(spec.props ?? {}) }, spec.elementStyle ?? null) as CompositeNode;
+    const card = buildCardRecipe(factory, { layout, parts: pn.parts as Partial<Record<CardPart, boolean>> }) as SerializedNode;
+
+    for (const [key, path] of Object.entries(pn.binds ?? {})) {
+        const target = CARD_BINDS[key as CardBindTarget];
+        if (!target) throw new ComposeError(`${id}: a card cannot bind "${key}"`);
+        const part = findByRole(card as CompositeNode, target.role) as SerializedNode | undefined;
+        if (!part) throw new ComposeError(`${id}: "${key}" binds a part the card leaves out`);
+        const node = target.role === CardRole.Media ? part.children?.find(c => c.type === IMAGE) : part;
+        if (!node) throw new ComposeError(`${id}: the card's media holds no image`);
+        addBinding(node, { prop: target.prop, ...resolveScoped(path, repeater, ctx, id) });
+        if (node.type === IMAGE) addBinding(node, { prop: 'alt', ...altBinding({ ...pn, t: IMAGE, bind: path, alt: undefined }, repeater, ctx, id) });
+    }
+
+    const fate = danglingFate({ ...pn, t: 'Heading' }, ctx);
+    const title = findByRole(card as CompositeNode, CardRole.Title) as SerializedNode;
+    if (pn.href && !fate) writePageLink(title, pn.href);
+    else if (fate) {
+        if (fate === DanglingFate.Email) writeExternalLink(title, `${MAILTO}${ctx.email}`);
+        reportDangling(fate === DanglingFate.Remove ? DanglingFate.Unlink : fate, pn, id, undefined, ctx);
+    }
+    if (pn.param && !fate) {
+        const names = pn.href ? routeParams(pn.href) : [];
+        if (names.length !== 1) throw new ComposeError(`${id}: "param" needs an href with one :param`);
+        addBinding(title, { prop: `routeParam:${names[0]}`, ...resolveScoped(pn.param, repeater, ctx, id) });
+    }
+    return card;
+}
+
 function composePattern(pattern: SitePattern, id: string, ctx: Ctx): SerializedNode {
     if (pattern.node.each) throw new ComposeError(`${id}: a pattern's root cannot be stamped per page`);
     const node = composeNode(pattern.node, id, null, ctx);

package/src/generation-core/node-baselines.generated.ts

@@ -764,7 +764,11 @@ export const NODE_BASELINES: Readonly<Record<string, NodeBaseline>> = {
   "Heading": {
     "props": {
       "content": "Heading",
-      "level": "h2"
+      "level": "h2",
+      "linkType": "none",
+      "url": "",
+      "pageRoute": "",
+      "target": "_self"
     },
     "styleProps": {
       "position": "static",
@@ -813,6 +817,7 @@ export const NODE_BASELINES: Readonly<Record<string, NodeBaseline>> = {
       "textDecoration": "none",
       "WebkitTextStrokeWidth": "0px",
       "WebkitTextStrokeColor": "transparent",
+      "maxLines": "none",
       "margin": "0px 0px 0px 0px",
       "padding": "0px 0px 0px 0px",
       "borderWidth": "0px",
@@ -852,7 +857,11 @@ export const NODE_BASELINES: Readonly<Record<string, NodeBaseline>> = {
     },
     "traits": [
       "content",
-      "level"
+      "level",
+      "linkType",
+      "url",
+      "pageRoute",
+      "target"
     ],
     "styleTraits": [
       "position",
@@ -902,6 +911,7 @@ export const NODE_BASELINES: Readonly<Record<string, NodeBaseline>> = {
       "_sep_stroke",
       "WebkitTextStrokeWidth",
       "WebkitTextStrokeColor",
+      "maxLines",
       "margin",
       "padding",
       "borderWidth",
@@ -999,6 +1009,7 @@ export const NODE_BASELINES: Readonly<Record<string, NodeBaseline>> = {
       "textDecoration": "none",
       "WebkitTextStrokeWidth": "0px",
       "WebkitTextStrokeColor": "transparent",
+      "maxLines": "none",
       "margin": "0px 0px 0px 0px",
       "padding": "10px",
       "borderWidth": "0px",
@@ -1088,6 +1099,7 @@ export const NODE_BASELINES: Readonly<Record<string, NodeBaseline>> = {
       "_sep_stroke",
       "WebkitTextStrokeWidth",
       "WebkitTextStrokeColor",
+      "maxLines",
       "margin",
       "padding",
       "borderWidth",

package/src/generation-core/patterns.ts

@@ -16,7 +16,9 @@ import { SPEC_SITE_PATTERNS } from './site-spec.generated';
  * per page in the navigation (`$navPages`) · `href` a page route (`$page.route` = the stamped page's) ·
  * `param` the value of the route's `:param` · `optional` a part a page may leave out (`without`) ·
  * `preset` a forms-core form preset (its fields, submit and Success/Error words) · `control` / `label` /
- * `required` a Field's · `c` children.
+ * `required` a Field's · `c` children · `recipe` a composite-core recipe stamped whole (`card`: Card v2 —
+ * its `layout`, the optional `parts` it leaves out, and `binds`, a binding path per part: `image`,
+ * `eyebrow`, `title`, `text`; `href` + `param` link the whole card through its title).
  */
 export interface PatternNode {
     readonly t: string;
@@ -43,6 +45,28 @@ export interface PatternNode {
     readonly label?: string;
     readonly required?: boolean;
     readonly c?: ReadonlyArray<PatternNode>;
+    readonly recipe?: string;
+    readonly layout?: string;
+    readonly parts?: Readonly<Record<string, boolean>>;
+    readonly binds?: Readonly<Record<string, string>>;
+}
+
+/** The composite-core recipes a pattern may stamp (`recipe`). */
+export enum PatternRecipe {
+    Card = 'card',
+}
+
+/** A recipe node's `binds` keys → the part each binds (Card v2). */
+export enum CardBindTarget {
+    Image = 'image',
+    Eyebrow = 'eyebrow',
+    Title = 'title',
+    Text = 'text',
+}
+
+/** Every binding path a node reads: its own `bind`, and a recipe's `binds`. */
+export function nodeBindPaths(node: PatternNode): string[] {
+    return [node.bind, ...Object.values(node.binds ?? {})].filter((p): p is string => !!p);
 }
 
 export enum PatternGlobalPosition {
@@ -129,6 +153,9 @@ export function altSourceScopes(pattern: SitePattern): Set<string> {
     const scopes = new Set<string>();
     const visit = (n: PatternNode) => {
         if (n.t === IMAGE_TYPE && n.bind && n.alt === undefined) scopes.add(n.bind.split('.')[0]);
+        // A Card v2's bound image takes its alt from the same item.
+        const cardImage = n.recipe === PatternRecipe.Card ? n.binds?.[CardBindTarget.Image] : undefined;
+        if (cardImage) scopes.add(cardImage.split('.')[0]);
         for (const child of n.c ?? []) visit(child);
     };
     visit(pattern.node);
@@ -139,7 +166,7 @@ export function altSourceScopes(pattern: SitePattern): Set<string> {
 export function patternScopes(pattern: SitePattern): Set<string> {
     const scopes = new Set<string>();
     for (const n of patternNodes(pattern)) {
-        for (const path of [n.bind, n.alt, n.param, n.src]) {
+        for (const path of [...nodeBindPaths(n), n.alt, n.param, n.src]) {
             if (path && !path.startsWith('$')) scopes.add(path.split('.')[0]);
         }
     }

package/src/generation-core/serialized-node.ts

@@ -27,6 +27,8 @@ export interface SerializedNode {
     stateStyles?: Partial<Record<string, Record<string, unknown>>>;
     responsive?: SerializedResponsive;
     elementStyle?: string;
+    /** The part this node plays in a composite (composite-core: `card.title`). */
+    role?: string;
     bindings: SerializedBinding[];
     interactions: unknown[];
     isGlobal?: boolean;

package/src/generation-core/site-spec.generated.ts

@@ -428,34 +428,21 @@ export const SPEC_SITE_PATTERNS = {
           },
           "c": [
             {
-              "t": "LinkedContainer",
-              "es": "card",
+              "t": "Container",
+              "recipe": "card",
+              "layout": "top",
+              "parts": {
+                "badge": false,
+                "actions": false
+              },
               "href": "/work/:slug",
               "param": "item.slug",
-              "lay": {
-                "display": "flex",
-                "flexDirection": "column",
-                "gap": "12px"
-              },
-              "c": [
-                {
-                  "t": "Image",
-                  "es": "media",
-                  "bind": "item.cover",
-                  "aspect": "4 / 3"
-                },
-                {
-                  "t": "Heading",
-                  "es": "h3",
-                  "level": "h3",
-                  "bind": "item.title"
-                },
-                {
-                  "t": "Text",
-                  "es": "small",
-                  "bind": "item.summary"
-                }
-              ]
+              "binds": {
+                "image": "item.cover",
+                "eyebrow": "item.year",
+                "title": "item.title",
+                "text": "item.summary"
+              }
             }
           ]
         }

package/styles/iox-design.css

@@ -44,3 +44,65 @@ iox-gallery.iox-es-media[data-iox-empty] > .iox-gallery {
     --iox-link-hover-color: currentColor;
     --iox-text-muted: currentColor;
 }
+
+/* A Badge's or a Chip's Icon reads the pill's own ink (Card v2 / T25 — the contract's `inkScopes`). */
+.iox-es-badge-neutral,
+.iox-es-badge-success,
+.iox-es-badge-warning,
+.iox-es-badge-accent,
+.iox-es-chip {
+    --iox-icon-color: currentColor;
+}
+
+/* Text over an image (Card v2 "Image behind text"): everything the scrim block holds reads the scrim's
+   fixed ink. Declared on the CHILDREN (the contract's `children: true`): the block also wears the Inverse
+   scheme, which re-declares these tokens on the block itself — a scope there would tie with it. */
+.iox-es-media-scrim > * {
+    --iox-heading-color: currentColor;
+    --iox-eyebrow-color: currentColor;
+    --iox-text-muted: currentColor;
+    --iox-link-color: currentColor;
+    --iox-link-hover-color: currentColor;
+    --iox-icon-color: currentColor;
+    --iox-button-ghost-ink: currentColor;
+}
+
+/* ── Card v2 (composite T23; complex-components board 8) ──────────────────────────────────────────
+   The parts are ordinary nodes; `nodeDesignClasses` writes `iox-role-<role>` on each, so these rules are
+   the same in every renderer. Zero-specificity where an author's own value must win. */
+
+/* A Badge on the Media sits in the Media's top inline-start corner (mirrored in RTL), over the image. */
+:where(.iox-role-card-media) > :where(.iox-role-card-badge) {
+    position: absolute;
+    inset-block-start: 10px;
+    inset-inline-start: 10px;
+    z-index: 1;
+}
+
+/* Link the whole card — the stretched link. The title's <a> is the card's ONE link (its words are the
+   link's name); its ::after covers the card, so a click anywhere on it navigates. The Buttons sit above
+   it and keep their own actions; the focus ring is drawn on the card. Never a link inside a link. On the
+   editing canvas the anchor carries data-iox-canvas and the ::after is off: every part stays clickable. */
+.iox-card-link {
+    color: inherit;
+    text-decoration: none;
+}
+:where(.iox-role-card):has(.iox-card-link) {
+    position: relative;
+}
+.iox-role-card .iox-card-link:not([data-iox-canvas])::after {
+    content: '';
+    position: absolute;
+    inset: 0;
+    z-index: 1;
+}
+.iox-role-card:has(.iox-card-link) .iox-role-card-actions {
+    position: relative;
+    z-index: 2;
+}
+.iox-role-card .iox-card-link:focus-visible {
+    outline: none;
+}
+.iox-role-card:has(.iox-card-link:focus-visible) {
+    box-shadow: var(--iox-focus-ring);
+}