@vectoriox/iox-ui 5.15.0 → 5.17.0

package/index.d.ts

@@ -184,9 +184,11 @@ declare class BuilderImageComponent {
     alt: string;
     nodeId: string;
     /**
-     * What a MARKED image shows while it has no source (design-system DS3) — set by each renderer from
-     * the shared `emptyImageSrc` (`@vectoriox/iox-ui/design-core`): the "Add image" label on the canvas,
-     * the blank on the live site, `null` for an unmarked image, which therefore renders as before.
+     * What a MARKED image shows WHENEVER it has no source (design-system DS3) — set by each renderer
+     * from the shared `emptyImagePlaceholder` (`@vectoriox/iox-ui/design-core`): the "Add image" label
+     * on the canvas, the blank on the live site, `null` for an unmarked image, which therefore renders
+     * as before. It does not depend on `src`, so clearing the source (a binding emptied, a context slot
+     * not yet filled) shows it with no re-render; a renderer re-sets it only when the MARKER changes.
      */
     emptySrc: string | null;
     /**
@@ -200,8 +202,16 @@ declare class BuilderImageComponent {
      * filled when the visitor interacts (see element-context-state-plan.md).
      */
     get srcAttr(): string | null;
+    private get showsPlaceholder();
     /** `data-iox-empty` while the placeholder stands in — the hook the shared fill rule keys on. */
     get emptyAttr(): '' | null;
+    /**
+     * The placeholder is not the author's picture, so it never carries the author's alt: it is
+     * decorative (`alt=""`) and hidden from assistive technology — on the live site, in Preview and on
+     * the canvas alike (the canvas label is painted inside the placeholder, not announced as content).
+     */
+    get altAttr(): string;
+    get ariaHiddenAttr(): 'true' | null;
     static ɵfac: i0.ɵɵFactoryDeclaration<BuilderImageComponent, never>;
     static ɵcmp: i0.ɵɵComponentDeclaration<BuilderImageComponent, "img[iox-img]", never, { "src": { "alias": "src"; "required": false; }; "alt": { "alias": "alt"; "required": false; }; "nodeId": { "alias": "nodeId"; "required": false; }; "emptySrc": { "alias": "emptySrc"; "required": false; }; }, {}, never, never, false, never>;
 }
@@ -247,6 +257,11 @@ declare class BuilderIconComponent {
 /**
  * Directive-host link: the `<a>` IS the host — no wrapper. Content is the label; styles come from
  * `.iox-node` (the legacy `style` input is kept for builder compat but no longer inline-applied).
+ *
+ * Outside a preview (`IS_PREVIEW` unprovided — the editing canvas, the design sampler) the link keeps
+ * its real `href` so it LOOKS like the live site's (the UA link styles key on it) and stays clickable
+ * so the canvas can select it, but no click navigates: plain, modified (cmd/ctrl/shift) and middle
+ * clicks all have their default cancelled here.
  */
 declare class BuilderLinkComponent {
     isPreview: boolean;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vectoriox/iox-ui",
-  "version": "5.15.0",
+  "version": "5.17.0",
   "peerDependencies": {
     "@angular/common": ">=20.0.0",
     "@angular/core": ">=20.0.0",

package/src/design-core/design-apply.ts

@@ -70,6 +70,29 @@ export function missingDesignRows(existing: ReadonlyArray<{ name: string }>, cho
     return designTokenRows(choices).filter(r => !have.has(r.name));
 }
 
+/**
+ * The builder-load REPAIR (DS4.1): rows the design owns and nobody touched — stamped by the current
+ * pack, light value exactly the pack's — whose dark override differs from the pack's are rewritten.
+ * iox-cms dropped `values.dark` on every write from F0 to DS4 (`values` was an implicit relation),
+ * and a revert could leave the previous apply's dark behind; both leave a row whose light half is the
+ * design's and whose dark half is not. No author edit can produce that shape — the Tokens panel edits
+ * the light value only — so rewriting it heals existing orgs without the author doing anything.
+ */
+export function designTokenRepairs(existing: ReadonlyArray<StoredDesignTokenRow>, choices: DesignChoices): FlavorSeedPlan['update'] {
+    const pack = flavorPackById(choices.flavorId);
+    if (!pack) return [];
+    const stamp = flavorSourceStamp(pack.id);
+    const desired = new Map(designTokenRows(choices).map(r => [r.name, r]));
+    const out: FlavorSeedPlan['update'] = [];
+    for (const row of existing ?? []) {
+        const want = desired.get(row.name);
+        if (!want || !row._id || row.source !== stamp || want.source !== stamp || row.value !== want.value) continue;
+        if ((row.values?.dark ?? '') === (want.values?.dark ?? '')) continue;
+        out.push({ id: row._id, data: { value: want.value, values: want.values ?? {}, source: stamp, ...(want.group ? { group: want.group } : {}), ...(want.tier ? { tier: want.tier } : {}) } });
+    }
+    return out;
+}
+
 export interface SwissMigration {
     /** The design the org now wears: Crisp, carrying the stored brand seed when it is a colour. */
     choices: DesignChoices;
@@ -87,9 +110,11 @@ const LEGACY_ALIASES: Readonly<Record<string, string>> = SPEC_LEGACY_ALIASES;
  *
  * - The look: `planDesignApply` from Swiss to Crisp — Swiss-stamped rows untouched since Swiss seeded
  *   them (incl. F2's `surface` / `line` / `accent`) become Crisp's; edited ones are kept.
- * - The aliases: `radius-control` / `radius-surface` / `space-control` / `space-stack` are rewritten to
- *   their alias reference ONLY while still machine-owned and untouched, so a node saved since F1 that
- *   reads `var(--iox-radius-control)` keeps resolving — now to Crisp's button radius.
+ * - The aliases (`SPEC_LEGACY_ALIASES`: `radius-control` / `radius-surface` / `space-stack`) are rewritten
+ *   to their alias reference ONLY while still machine-owned and untouched, so a node saved since F1 that
+ *   reads `var(--iox-radius-control)` keeps resolving — now to Crisp's button radius. `space-control` is
+ *   NOT an alias: it is a v2 semantic token (`button-pad` reads it), and aliasing it closed a `var()`
+ *   cycle; it migrates like any other Swiss row.
  */
 export function planSwissMigration(existing: ReadonlyArray<StoredDesignTokenRow>, stored: StoredDesign): SwissMigration | null {
     const swissAliasRows = (existing ?? []).filter(r => r.name in LEGACY_ALIASES && SEED_STAMP.exec(r.source ?? '')?.[1] === SWISS_FLAVOR.id);

package/src/design-core/design-settings.ts

@@ -130,6 +130,17 @@ export function packDesignChoices(flavorId: string): DesignChoices {
     return resolveDesignChoices({ flavorId });
 }
 
+/**
+ * What picking a pack card means, given the design the studio wears: the applied pack → the applied
+ * choices; another pack → that pack's defaults, CARRYING the author's chosen fonts (§5b — a font the
+ * author chose survives a pack switch unless the author changes it). Both picker homes call this.
+ */
+export function choicesForPack(flavorId: string, applied: DesignChoices | null | undefined): DesignChoices {
+    const pack = flavorPackById(flavorId) ?? defaultPack();
+    if (applied && resolveDesignChoices(applied).flavorId === pack.id) return resolveDesignChoices(applied);
+    return resolveDesignChoices({ flavorId: pack.id, fonts: applied?.fonts });
+}
+
 /** A stored `settings.design` config → the resolved design. No row (or no config) → Crisp's defaults. */
 export function readDesignConfig(config: ReadonlyArray<DesignConfigEntry> | null | undefined, hasRow = !!config): StoredDesign {
     const map = configMap(config);

package/src/design-core/empty-image.ts

@@ -41,12 +41,21 @@ export function emptyImageLabelSrc(label: string): string {
 }
 
 /**
- * The `src` a node's Image renders when its own source is empty: the canvas label (when `label` is
- * given) or the live blank for a MARKED node; `null` — render exactly as before — for an unmarked
- * node or one that has a source.
+ * What a node's Image shows WHENEVER its source is empty: the canvas label (when `label` is given) or
+ * the live blank for a MARKED node; `null` — render exactly as before — for an unmarked node. It does
+ * not look at the source, so a renderer computes it once per marker/label and the component falls
+ * back to it the moment its source is cleared (a binding emptied, a context slot not yet filled).
  */
-export function emptyImageSrc(node: { elementStyle?: string | null } | null | undefined, src: unknown, label?: string | null): string | null {
-    if (src != null && src !== '') return null;
+export function emptyImagePlaceholder(node: { elementStyle?: string | null } | null | undefined, label?: string | null): string | null {
     if (!hasElementStyleMarker(node)) return null;
     return label ? emptyImageLabelSrc(label) : EMPTY_IMAGE_SRC;
 }
+
+/**
+ * The `src` a node's Image renders for a given source: its placeholder while the source is empty,
+ * `null` once it has one (the source itself renders) or when the node is unmarked.
+ */
+export function emptyImageSrc(node: { elementStyle?: string | null } | null | undefined, src: unknown, label?: string | null): string | null {
+    if (src != null && src !== '') return null;
+    return emptyImagePlaceholder(node, label);
+}

package/src/design-core/flavor-seed.ts

@@ -66,14 +66,16 @@ export function planFlavorRevert(
         snapNames.add(snap.name);
         const live = byName.get(snap.name);
         if (!live) {
-            plan.create.push({ name: snap.name, type: snap.type, value: snap.value, values: snap.values, source: snap.source, ...classification(snap) });
+            plan.create.push({ name: snap.name, type: snap.type, value: snap.value, ...(snap.values?.dark ? { values: snap.values } : {}), source: snap.source, ...classification(snap) });
             continue;
         }
         const differs = live.value !== snap.value
             || (live.values?.dark ?? null) !== (snap.values?.dark ?? null)
             || (live.source ?? null) !== (snap.source ?? null);
+        // `values` is ALWAYS sent: an absent key is dropped by JSON and a `$set` then keeps the
+        // apply's dark override — a snapshot row with no dark must clear it, so it sends `{}`.
         if (differs && live._id) {
-            plan.update.push({ id: live._id, data: { value: snap.value, values: snap.values, source: snap.source } });
+            plan.update.push({ id: live._id, data: { value: snap.value, values: snap.values ?? {}, source: snap.source } });
         }
     }
     for (const row of current ?? []) {
@@ -110,7 +112,9 @@ const sameValue = (row: { value: string; values?: { dark?: string } }, e: SeedEx
  * write is never touched: no `flavor:` stamp, unless it is a `user` row (a font the author CHOSE in
  * the design) whose value is exactly what the previous design wrote — that row is the design's own
  * choice, so a new choice may replace it. `group`/`tier` ride every write; a desired row's own
- * `source` (a chosen font's `user`) wins over the pack stamp.
+ * `source` (a chosen font's `user`) wins over the pack stamp. A machine-owned row that already holds
+ * the desired value but another pack's stamp is RE-STAMPED (§10 C2 provenance: the stamp names the
+ * design that owns the row, so the next switch judges it against the right baseline).
  */
 export function planFlavorSeed(
     desired: ReadonlyArray<FlavorTokenDef & { source?: string }>,
@@ -140,7 +144,6 @@ export function planFlavorSeed(
         if (!designOwned) { plan.kept.push(def.name); continue; }
         const sameAsDesired = row.value === def.value && (row.values?.dark ?? '') === (def.values?.dark ?? '');
         if (sameAsDesired && (row.source ?? '') === source) continue; // already exactly this
-        if (sameAsDesired && isSeeded(row) && source !== USER_TOKEN_SOURCE) continue; // same value, another pack's stamp — nothing to write
         const untouched = !!old && sameValue(row, old);
         if ((untouched || sameAsDesired) && row._id) {
             plan.update.push({ id: row._id, data: { value: def.value, values: def.values ?? {}, source, ...classification(def) } });

package/src/design-core/flavor-spec.generated.ts

@@ -1419,7 +1419,7 @@ export const SPEC_ELEMENT_STYLES = [
       "fontSize": "var(--iox-size-lead)",
       "fontWeight": "var(--iox-weight-body)",
       "lineHeight": "var(--iox-leading-body)",
-      "color": "var(--iox-text)"
+      "color": "inherit"
     }
   },
   {
@@ -1434,7 +1434,7 @@ export const SPEC_ELEMENT_STYLES = [
       "fontSize": "var(--iox-size-body)",
       "fontWeight": "var(--iox-weight-body)",
       "lineHeight": "var(--iox-leading-body)",
-      "color": "var(--iox-text)"
+      "color": "inherit"
     }
   },
   {

package/src/design-core/token-names.ts

@@ -32,22 +32,64 @@ export function unknownTokenReferences(css: string, alsoAllowed: Iterable<string
 }
 
 const LEGACY_SCOPE = /:not\(\s*\.iox-es\s*\)/;
-const RULE = /([^{}]+)\{([^{}]*)\}/g;
+
+/** Comments out: block comments, and SCSS `//` line comments (never the `//` of a `url(https://…)`). */
+const stripComments = (css: string) => String(css ?? '')
+    .replace(/\/\*[\s\S]*?\*\//g, '')
+    .replace(/(^|[^:\\])\/\/[^\n]*/g, '$1');
+
+/** A nested SCSS selector against its parent's: `&` is the parent; no `&` means a descendant. */
+function resolveNested(parent: string, selector: string): string {
+    if (!parent) return selector;
+    return selector.split(',').map(part => {
+        const own = part.trim();
+        return own.includes('&') ? own.replace(/&/g, parent) : `${parent} ${own}`;
+    }).join(', ');
+}
 
 /**
  * Tokens read by a LEGACY rule — any rule whose selector is scoped `:not(.iox-es)` (the pre-DS2 look
  * of a node that wears no element style, design-system §3b-bis). Such a rule must read NO token at
  * all: a token it reads repaints a pre-DS2 page the moment the org's rows are seeded or a flavor is
- * applied (D5). Returns `selector → names` for each offending rule; comments are ignored.
+ * applied (D5). Returns `selector → names` for each offending rule; comments are ignored. SCSS
+ * nesting is resolved (DS4.1): `.x:where(:not(.iox-es)) { &:hover { … } }` is the legacy rule
+ * `.x:where(:not(.iox-es)):hover`, and an at-rule (`@media`) between them does not break the chain.
  */
 export function legacyRuleTokenReferences(css: string): Array<{ selector: string; tokens: string[] }> {
-    const text = String(css ?? '').replace(/\/\*[\s\S]*?\*\//g, '');
+    const text = stripComments(css);
     const out: Array<{ selector: string; tokens: string[] }> = [];
-    for (const m of text.matchAll(RULE)) {
-        const selector = m[1].trim().replace(/\s+/g, ' ');
-        if (!LEGACY_SCOPE.test(selector)) continue;
-        const tokens = tokenReferences(m[2]);
-        if (tokens.length) out.push({ selector, tokens });
+    const stack: Array<{ selector: string; body: string }> = [];
+    const report = (frame: { selector: string; body: string }) => {
+        if (!LEGACY_SCOPE.test(frame.selector)) return;
+        const tokens = tokenReferences(frame.body);
+        if (tokens.length) out.push({ selector: frame.selector, tokens });
+    };
+    let buffer = '';
+    for (const ch of text) {
+        if (ch === '{') {
+            const head = buffer.trim().replace(/\s+/g, ' ');
+            buffer = '';
+            // Declarations before a nested block belong to the parent (`color: x; &:hover {`).
+            const cut = head.lastIndexOf(';');
+            const prelude = cut >= 0 ? head.slice(cut + 1).trim() : head;
+            const parent = stack[stack.length - 1];
+            if (parent && cut >= 0) parent.body += head.slice(0, cut + 1);
+            const inherited = parent?.selector ?? '';
+            const selector = prelude.startsWith('@') ? inherited : resolveNested(inherited, prelude);
+            stack.push({ selector, body: '' });
+        } else if (ch === '}') {
+            const frame = stack.pop();
+            if (frame) {
+                frame.body += buffer;
+                report(frame);
+            }
+            buffer = '';
+        } else if (ch === ';' && stack.length) {
+            stack[stack.length - 1].body += buffer + ch;
+            buffer = '';
+        } else {
+            buffer += ch;
+        }
     }
     return out;
 }