@vectoriox/iox-ui 5.33.0 → 5.34.0

package/package.json

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

package/src/composite-core/badge.ts

@@ -66,8 +66,9 @@ const PILL_BASE: Readonly<Record<string, string>> = {
 };
 const PILL_ICON: Readonly<Record<string, string>> = { fontSize: '1em' };
 const PILL_WORDS: Readonly<Record<string, string>> = { width: 'auto', minHeight: 'auto', padding: '0px 0px 0px 0px', margin: '0px 0px 0px 0px' };
-/** The pill's words inherit the pill's type and ink (the contract's inherit-everything text style). */
-const PILL_WORDS_STYLE = 'button-label';
+/** The pill's words wear the pill's OWN label style (Card v2.1): its type from the badge tokens, its leading,
+ *  tracking, case and ink inherited from the pill — never the button's label style. */
+export const PILL_LABEL_STYLE = 'badge-label';
 
 export interface PillOptions {
     text?: string;
@@ -81,7 +82,7 @@ function buildPill(create: CompositeNodeFactory, elementStyle: string, text: str
     writeStyles(pill, PILL_BASE);
     const glyph = create({ key: `${key}-icon`, type: 'Icon', props: { iconClass: icon }, elementStyle: 'icon' });
     writeStyles(glyph, PILL_ICON);
-    const words = create({ key: `${key}-text`, type: 'Text', props: { content: text, tag: 'span' }, elementStyle: PILL_WORDS_STYLE });
+    const words = create({ key: `${key}-text`, type: 'Text', props: { content: text, tag: 'span' }, elementStyle: PILL_LABEL_STYLE });
     writeStyles(words, PILL_WORDS);
     pill.children = [glyph, words];
     return pill;

package/src/composite-core/card.ts

@@ -1,4 +1,4 @@
-import { elementStyleById, LinkType, switchElementStyle } from '@vectoriox/iox-ui/design-core';
+import { COLOR_SCHEME_TRAIT, elementStyleById, LinkType, setColorScheme, switchElementStyle } from '@vectoriox/iox-ui/design-core';
 
 import { BadgeTone, buildBadge } from './badge';
 import {
@@ -119,7 +119,6 @@ enum Scheme {
     Inverse = 'inverse',
 }
 
-const COLOR_SCHEME = 'colorScheme';
 const LINK_TYPE = 'linkType';
 const SAVE_ICON = 'ph ph-bookmark-simple';
 
@@ -336,8 +335,9 @@ function placeBadge(card: CompositeNode, badge: CompositeNode, onMedia: boolean)
     writeStyles(badge, { position: overMedia ? 'absolute' : 'static' });
 }
 
+/** Through design-core's ONE scheme writer — the same setting Section colours edits everywhere. */
 function writeScheme(node: CompositeNode, scheme: Scheme): void {
-    writeProp(node, COLOR_SCHEME, scheme);
+    setColorScheme(node, scheme);
 }
 
 /** Write one role's layout values from a spec (base + layers). */
@@ -424,7 +424,7 @@ function matches(card: CompositeNode, spec: CardLayoutSpec): boolean {
     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;
+        if (!same(readProp(content, COLOR_SCHEME_TRAIT) ?? Scheme.Default, spec.contentScheme)) return false;
     }
     const title = findByRole(card, CardRole.Title);
     if (title && !holds(title, spec.title)) return false;

package/src/design-core/contrast-audit.ts

@@ -3,6 +3,7 @@ import { WCAG_AA_UI } from './brand-neutrals';
 import { compositeOver, paintColours, parseCssColour, quantizeRgb, Rgba, ringColour } from './colour-eval';
 import { ElementStyle, ELEMENT_STYLES } from './element-styles';
 import { SPEC_CONTRAST_AUDIT, SPEC_INK_SCOPES, SPEC_SCHEMES } from './flavor-spec.generated';
+import { SCHEME_INK } from './node-classes';
 import { DesignTokenLike, ResolvedMode, resolveSchemeTokenValues } from './token-css';
 
 /**
@@ -19,7 +20,10 @@ import { DesignTokenLike, ResolvedMode, resolveSchemeTokenValues } from './token
  *   its focus ring; the form parts the field baseline paints (`contrastAudit.formParts`); the form's
  *   Success / Error notices, in every scheme and container;
  * - a Badge's or Chip's icon through the same `inkScopes`, and text over an image (Card v2's "Image behind
- *   text"): the block's ink over its scrim composited on the WORST-CASE image (`contrastAudit.scrims`).
+ *   text"): the block's ink over its scrim composited on the WORST-CASE image (`contrastAudit.scrims`);
+ * - a container that WEARS a scheme inside a section of any scheme (a Featured card on a plain page): the
+ *   text it holds inherits the scheme's ink (`SCHEME_INK`, iox-ui#15) on the inner scheme's fill, composited
+ *   over the OUTER section — the pairing the token pairs cannot see.
  *
  * WCAG 2: 4.5:1 for text, 3:1 for glyphs, UI boundaries and focus indicators (1.4.11), judged on 8-bit
  * colours. The same audit gates the contract (`colour.mjs auditContrast`, every flavor × tint × a seed
@@ -65,6 +69,8 @@ const GLYPH_GROUP = 'Media';
 const FORMS_GROUP = 'Forms';
 const DEFAULT_SCHEME = 'default';
 const SECTION = 'section';
+/** The element a scheme'd container's running text is reported as (iox-ui#15). */
+export const INHERITED_TEXT = 'inherited text';
 const FIELD = 'field';
 const WHITE: Rgba = { r: 1, g: 1, b: 1, a: 1 };
 const SINGLE_REF = /^var\(--iox-([\w-]+)\)$/;
@@ -187,10 +193,53 @@ export function auditDesignContrast(rows: ReadonlyArray<DesignTokenLike>, mode:
             }
         }
     }
+    findings.push(...schemedContainerFindings(rows, mode, section, containers.filter((c): c is ElementStyle => !!c)));
     for (const scrim of SCRIMS) findings.push(...scrimFindings(rows, mode, scrim, byId.get(scrim.style)));
     return findings;
 }
 
+/** What a section in `values` paints under its content: its own fill over the page, or the page. */
+function sectionGround(values: Values): Rgba[] {
+    const pageInk = parseCssColour(values['text']);
+    const page = paintColours(values['page-bg'], pageInk);
+    const sectionPaint = paintColours(values['section-bg'], pageInk);
+    return opaque(sectionPaint) ? sectionPaint.map(c => (c.a < 1 ? compositeOver(c, page[0] ?? WHITE) : c)) : page;
+}
+
+/**
+ * A container that wears a NON-default scheme, inside a section of every scheme (vectoriox/iox-ui#15 — the
+ * Featured card is a Card in Brand on a Default page). Its tokens are its own scheme's laid over the outer
+ * section's (what it does not set, it inherits); a translucent fill composites over the OUTER section; the running text it holds (`body`, `lead`, a label: `color: inherit`)
+ * reads the scheme's ink, which is what the scheme-ink rule and `withSchemeInk` make CSS compute.
+ */
+function schemedContainerFindings(rows: ReadonlyArray<DesignTokenLike>, mode: ResolvedMode, section: StyleMap,
+    containers: ReadonlyArray<ElementStyle>): ContrastFinding[] {
+    const out: ContrastFinding[] = [];
+    for (const outer of SCHEME_IDS) {
+        const ground = sectionGround(resolveSchemeTokenValues(rows, mode, outer));
+        for (const inner of SCHEME_IDS.filter(id => id !== DEFAULT_SCHEME)) {
+            const values = resolveSchemeTokenValues(rows, mode, [outer, inner]);
+            const schemeInk = parseCssColour(resolveIn(values, SCHEME_INK), parseCssColour(resolveIn(values, section['color'])));
+            for (const box of containers) {
+                const style = ownStyle(box);
+                const bgs = overAll(paintColours(resolveIn(values, style['backgroundColor']), schemeInk), ground);
+                const ink = style['color'] && style['color'] !== 'inherit' ? parseCssColour(resolveIn(values, style['color']), schemeInk) : schemeInk;
+                if (!ink) continue;
+                for (const g of bgs) {
+                    const bg = quantizeRgb(g);
+                    const f = quantizeRgb(ink.a < 1 ? compositeOver(ink, bg) : ink);
+                    const ratio = wcagContrastRatio(f, bg);
+                    out.push({
+                        scheme: inner, container: `${box.id} in a ${outer} section`, element: INHERITED_TEXT, part: 'text',
+                        fg: toHexColor(f), bg: toHexColor(bg), ratio: Math.round(ratio * 100) / 100, min: WCAG_AA_TEXT, pass: ratio >= WCAG_AA_TEXT - 1e-9,
+                    });
+                }
+            }
+        }
+    }
+    return out;
+}
+
 /** Text over an image: the block's ink — and every token its ink scope pins to it — over the scrim
  *  composited on the WORST-CASE image, in the scheme the block wears. Never over the section: the image
  *  covers it. */

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

@@ -1348,6 +1348,7 @@ export const SPEC_SCHEMES = {
     "set": {
       "section-bg": "{{accent}}",
       "bg": "{{accent}}",
+      "nav-bg": "{{accent}}",
       "surface": "{{accent-hover}}",
       "surface-2": "{{accent-hover}}",
       "surface-glass": "{{accent-hover}}",
@@ -1371,6 +1372,8 @@ export const SPEC_SCHEMES = {
   }
 } as const;
 
+export const SPEC_SCHEME_INK = "var(--iox-text)" as const;
+
 export const SPEC_A11Y = {
   "reducedMotion": {
     "dur-fast": "0ms",
@@ -2012,6 +2015,23 @@ export const SPEC_ELEMENT_STYLES = [
       "fontWeight": "var(--iox-weight-label)"
     }
   },
+  {
+    "id": "badge-label",
+    "label": "Badge label",
+    "group": "Content blocks",
+    "appliesTo": [
+      "Text"
+    ],
+    "base": {
+      "fontFamily": "var(--iox-font-label)",
+      "fontSize": "var(--iox-badge-size)",
+      "fontWeight": "var(--iox-weight-label)",
+      "lineHeight": "inherit",
+      "letterSpacing": "inherit",
+      "textTransform": "inherit",
+      "color": "inherit"
+    }
+  },
   {
     "id": "media-scrim",
     "label": "Text over image",

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

@@ -1,5 +1,5 @@
 import { ELEMENT_STYLE_MARKER_CLASS, elementStyleClass } from './element-styles';
-import { SPEC_SCHEMES } from './flavor-spec.generated';
+import { SPEC_SCHEME_INK, SPEC_SCHEMES } from './flavor-spec.generated';
 
 /**
  * The design-system classes a node renders, in BOTH renderers (builder canvas, engine component
@@ -104,6 +104,54 @@ export function colorSchemeOf(node: DesignClassSource | null | undefined): strin
     return typeof trait === 'string' ? trait : null;
 }
 
+/**
+ * The ink a section colour scheme gives everything inside it (vectoriox/iox-ui#15). A scheme re-declares
+ * tokens only, so without this a Container wearing one kept the colour it INHERITED from the section around
+ * it: a Featured (Brand) card's body text stayed the page's dark ink on the Brand fill, 2.54:1. Two halves,
+ * one rule: `compileSchemeCss` gives every `iox-scheme-*` element `color: var(--iox-text)` (the node rule,
+ * emitted after it at the same specificity, still wins), and {@link withSchemeInk} reads a scheme'd node's
+ * own `inherit` — what the card / box / panel element styles write for "no colour of my own" — as this ink.
+ * The value is the contract's `schemeInk`.
+ */
+export const SCHEME_INK: string = SPEC_SCHEME_INK;
+
+/** The values that mean "no colour of my own" — `color` is inherited, so these equal no declaration. */
+const INHERITED_INK: ReadonlySet<string> = new Set(['inherit', 'unset']);
+
+/**
+ * A node's style map as its renderer compiles it under a section colour scheme: a NON-default scheme turns
+ * an inherited `color` into {@link SCHEME_INK}; anything else — no scheme, an author's own colour, a token —
+ * is returned untouched (the same object). Every render path calls it on every rule it compiles for the
+ * node (base, states, breakpoint layers): the builder's StyleRegistryService and both engine paths.
+ */
+export function withSchemeInk<T extends Record<string, unknown>>(styles: T, scheme: unknown): T {
+    if (!styles || !colorSchemeClass(scheme)) return styles;
+    const color = styles['color'];
+    if (typeof color !== 'string' || !INHERITED_INK.has(color.trim().toLowerCase())) return styles;
+    return { ...styles, color: SCHEME_INK };
+}
+
+/**
+ * Write a node's section colour scheme — THE one writer, so every control that offers Section colours (the
+ * Style panel's Element style block, Card ▸ Card) edits the same setting: the `colorScheme` content trait on
+ * a builder node, `props.colorScheme` on a saved one. False when nothing changed: an unknown id, the value it
+ * already holds, or a builder node with no such trait (a type that offers no scheme).
+ */
+export function setColorScheme(
+    node: { props?: Record<string, unknown> | null; traits?: Array<{ name?: string; default?: unknown }> | null } | null | undefined,
+    id: string,
+): boolean {
+    if (!node || !SCHEME_IDS.has(id) || (colorSchemeOf(node) ?? ColorScheme.Default) === id) return false;
+    if (Array.isArray(node.traits)) {
+        const trait = node.traits.find(t => t?.name === COLOR_SCHEME_TRAIT);
+        if (!trait) return false;
+        trait.default = id;
+        return true;
+    }
+    node.props = { ...(node.props ?? {}), [COLOR_SCHEME_TRAIT]: id };
+    return true;
+}
+
 /** True when the node wears a known element style — the marker is on it. */
 export function hasElementStyleMarker(node: { elementStyle?: string | null } | null | undefined): boolean {
     return elementStyleClass(node?.elementStyle) !== null;

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

@@ -1,5 +1,6 @@
 import { DesignMode } from './design-token.model';
 import { SPEC_A11Y, SPEC_SCHEMES } from './flavor-spec.generated';
+import { SCHEME_INK } from './node-classes';
 import { specTokenNames } from './token-names';
 
 /**
@@ -10,7 +11,8 @@ import { specTokenNames } from './token-names';
  *
  * Block order (design-system plan §3e, T8):
  *   1. base            `:root { --iox-*: … }`
- *   2. schemes         `.iox-scheme-<id> { overrides; every var()-referencing token re-declared }`
+ *   2. schemes         `.iox-scheme-<id> { overrides; every var()-referencing token re-declared }`, then the
+ *                      ONE scheme-ink rule `.iox-scheme-subtle, … { color: var(--iox-text) }` (iox-ui#15)
  *   3. reduced motion  `@media (prefers-reduced-motion: reduce)`
  *   4. reduced transparency `@media (prefers-reduced-transparency: reduce)`
  *   5. dark — LAST     `@media (prefers-color-scheme: dark)`
@@ -167,19 +169,29 @@ export function resolveTokenValues(
  * Every token's value INSIDE a section wearing `schemeId`, in one mode — what CSS computes there: the
  * scheme's overrides (`{{token}}` / `{{~token}}` placeholders substituted from the root), every other
  * row as declared, and `var()` references resolved within the section (the §3c re-declaration rule
- * makes that the section's own resolution). `default` (or an unknown id) is the root.
+ * makes that the section's own resolution). `default` (or an unknown id) is the root. A CHAIN
+ * (`['inverse', 'accent']`, outermost first) is an element wearing the last scheme inside elements wearing
+ * the ones before it: a token the inner scheme does not set is the outer one's (custom properties inherit).
  */
 export function resolveSchemeTokenValues(
     tokens: ReadonlyArray<DesignTokenLike> | null | undefined,
     mode: ResolvedMode,
-    schemeId: string,
+    schemeId: string | ReadonlyArray<string>,
 ): Record<string, string> {
     const rows = usableTokens(tokens);
-    const set = schemeId === DEFAULT_SCHEME ? undefined : (SPEC_SCHEMES as Readonly<Record<string, { set: Readonly<Record<string, string>> }>>)[schemeId]?.set;
-    if (!set) return resolveTokenValues(rows, mode);
+    const sets = (typeof schemeId === 'string' ? [schemeId] : schemeId)
+        .map(id => (id === DEFAULT_SCHEME ? undefined : (SPEC_SCHEMES as Readonly<Record<string, { set: Readonly<Record<string, string>> }>>)[id]?.set));
+    if (!sets.some(Boolean)) return resolveTokenValues(rows, mode);
     const root = resolveTokenValues(rows, mode);
     const other = resolveTokenValues(rows, mode === DARK ? LIGHT : DARK);
-    const overrides = new Map(schemeEntries(set, root, other));
+    // Nested (`[outer, inner]` — a Featured card in an Inverse section): each scheme block re-declares the
+    // rows that reference a token, so at every level those are restored before the block's own set.
+    const overrides = new Map<string, string>();
+    for (const set of sets) {
+        if (!set) continue;
+        for (const t of rows) if (modeValue(t, mode).includes(REFERENCE)) overrides.delete(t.name);
+        for (const [name, value] of schemeEntries(set, root, other)) overrides.set(name, value);
+    }
     return resolveTokenValues(rows.map(t => ({ name: t.name, value: overrides.get(t.name) ?? modeValue(t, mode) })), LIGHT);
 }
 
@@ -243,11 +255,27 @@ export function compileSchemeCss(
     if (!rows.length) return '';
     const resolved = resolveTokenValues(rows, LIGHT);
     const other = opposite ?? resolveTokenValues(rows, DARK);
-    return nonDefaultSchemes().map(([id, set]) => rule(schemeSelector(id, scope), [
-        ...schemeEntries(set, resolved, other),
-        ...rows.filter(t => !(t.name in set) && t.value.includes(REFERENCE))
-            .map((t): [string, string] => [t.name, t.value]),
-    ])).filter(Boolean).join('\n');
+    return [
+        ...nonDefaultSchemes().map(([id, set]) => rule(schemeSelector(id, scope), [
+            ...schemeEntries(set, resolved, other),
+            ...rows.filter(t => !(t.name in set) && t.value.includes(REFERENCE))
+                .map((t): [string, string] => [t.name, t.value]),
+        ])),
+        schemeInkRule(scope),
+    ].filter(Boolean).join('\n');
+}
+
+/**
+ * Every element wearing a scheme takes the scheme's ink (vectoriox/iox-ui#15): the tokens re-resolve inside
+ * it, but `color` is inherited as a COMPUTED value, so without this a scheme'd Container's running text kept
+ * the outer section's ink. One rule, specificity (0,1,0) in every renderer — a builder scope is wrapped in
+ * `:where()` — emitted with the token CSS, BEFORE every node rule: a node's own colour (same specificity,
+ * later) still wins. A node's `color: inherit` is read as this ink by `withSchemeInk`.
+ */
+function schemeInkRule(scope?: string): string {
+    const where = scope ? `:where(${scope}) ` : '';
+    const selectors = nonDefaultSchemes().map(([id]) => `${where}.iox-scheme-${id}`);
+    return selectors.length ? `${selectors.join(', ')} {\n  color: ${SCHEME_INK};\n}` : '';
 }
 
 /** The dark twin of both scheme rules: a re-declared token with a dark value would otherwise pin