@vectoriox/iox-ui 5.29.1 → 5.31.0

package/src/composite-core/structure.ts

@@ -0,0 +1,58 @@
+import { CardPart, CardRole } from './card';
+
+/**
+ * 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.
+ */
+export interface CompositeRoleSpec {
+    /** The role of the part's parent; null for a composite root. */
+    readonly parent: string | null;
+    readonly locked?: boolean;
+    readonly part?: CardPart;
+}
+
+export const COMPOSITE_ROLE_SPECS: Readonly<Record<string, CompositeRoleSpec>> = {
+    [CardRole.Card]: { parent: null },
+    [CardRole.Media]: { parent: CardRole.Card, part: CardPart.Media },
+    [CardRole.Badge]: { parent: null, part: CardPart.Badge },
+    [CardRole.Content]: { parent: CardRole.Card, locked: true },
+    [CardRole.Eyebrow]: { parent: CardRole.Content, part: CardPart.Eyebrow },
+    [CardRole.Title]: { parent: CardRole.Content, locked: true },
+    [CardRole.Text]: { parent: CardRole.Content, part: CardPart.Text },
+    [CardRole.Actions]: { parent: CardRole.Content, part: CardPart.Actions },
+};
+
+export enum StructureEdit {
+    Delete = 'delete',
+    /** A drop, paste or wrap that would put the node somewhere new. */
+    Move = 'move',
+}
+
+export 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.
+ */
+export function structureRefusal(node: RoleLike | null | undefined, edit: StructureEdit, ancestors: ReadonlyArray<RoleLike> = []): StructureRefusal | null {
+    const spec = node?.role ? COMPOSITE_ROLE_SPECS[node.role] : undefined;
+    if (!spec?.locked) return null;
+    if (edit === StructureEdit.Delete) return StructureRefusal.LockedPart;
+    const parent = ancestors[ancestors.length - 1];
+    return parent?.role === spec.parent ? null : StructureRefusal.LockedPlacement;
+}
+
+/** 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. */
+export function isLockedPart(node: RoleLike | null | undefined): boolean {
+    return !!(node?.role && COMPOSITE_ROLE_SPECS[node.role]?.locked);
+}

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

@@ -17,7 +17,9 @@ import { DesignTokenLike, ResolvedMode, resolveSchemeTokenValues } from './token
  *   a gradient ground (Glass's mesh, Midnight's glow) checked at its worst stop;
  * - base and hover; a button's icon read through the contract's `inkScopes` (it takes the button's ink),
  *   its focus ring; the form parts the field baseline paints (`contrastAudit.formParts`); the form's
- *   Success / Error notices, in every scheme and container.
+ *   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`).
  *
  * 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
@@ -45,16 +47,20 @@ interface FormPart {
     readonly thumb?: string;
     readonly min: number;
 }
-interface InkScope { readonly styles: ReadonlyArray<string>; readonly set: Readonly<Record<string, string>>; }
+interface InkScope { readonly styles: ReadonlyArray<string>; readonly set: Readonly<Record<string, string>>; readonly children?: boolean; }
+interface Scrim { readonly style: string; readonly token: string; readonly scheme: string; readonly image: string; }
 
 const FORM_PARTS: ReadonlyArray<FormPart> = SPEC_CONTRAST_AUDIT.formParts;
 const INK_SCOPES: ReadonlyArray<InkScope> = SPEC_INK_SCOPES;
+const SCRIMS: ReadonlyArray<Scrim> = SPEC_CONTRAST_AUDIT.scrims;
+const SCRIM_STYLES: ReadonlySet<string> = new Set(SCRIMS.map(s => s.style));
+/** What a scrim block's children read, beside its own ink (each pinned to it by the block's ink scope). */
+const SCRIM_HELD_TOKENS: ReadonlyArray<string> = ['heading-color', 'eyebrow-color', 'text-muted'];
 const SCHEME_IDS: ReadonlyArray<string> = Object.keys(SPEC_SCHEMES);
 const CONTAINER_GROUPS: ReadonlySet<string> = new Set(['Layout', 'Overlays']);
 const NOT_CONTENT: ReadonlySet<string> = new Set(['rule', 'media']);
 const SECTION_STYLE = 'section';
 const ICON_STYLE = 'icon';
-const BUTTON_GROUP = 'Buttons';
 const GLYPH_GROUP = 'Media';
 const FORMS_GROUP = 'Forms';
 const DEFAULT_SCHEME = 'default';
@@ -95,7 +101,7 @@ export function auditDesignContrast(rows: ReadonlyArray<DesignTokenLike>, mode:
         ...styles.filter(e => CONTAINER_GROUPS.has(e.group) && ownStyle(e)['backgroundColor'] && e.id !== SECTION_STYLE),
     ];
     const content = styles.filter(e => !CONTAINER_GROUPS.has(e.group) && (ownStyle(e)['color'] || ownStyle(e)['backgroundColor'])
-        && e.group !== FORMS_GROUP && !NOT_CONTENT.has(e.id));
+        && e.group !== FORMS_GROUP && !NOT_CONTENT.has(e.id) && !SCRIM_STYLES.has(e.id));
     const notices = styles.filter(e => e.group === FORMS_GROUP && ownStyle(e)['color']);
     const section = ownStyle(byId.get(SECTION_STYLE) as ElementStyle);
     const iconColour = ownStyle(byId.get(ICON_STYLE) as ElementStyle)['color'];
@@ -136,7 +142,8 @@ export function auditDesignContrast(rows: ReadonlyArray<DesignTokenLike>, mode:
                     const under = fill.length && opaque(fill) ? overAll(fill, bgs) : bgs;
                     const ink = s['color'] ? parseCssColour(resolveIn(values, s['color']), boxInk) : boxInk;
                     check(e.id, state === 'base' ? (glyph ? 'glyph' : 'text') : `${state} text`, ink, under, glyph ? WCAG_AA_UI : WCAG_AA_TEXT);
-                    if (state === 'base' && e.group === BUTTON_GROUP) {
+                    // What a filled element HOLDS (inkScopes): a button's or a badge's icon reads its ink.
+                    if (state === 'base' && INK_SCOPES.some(sc => sc.styles.includes(e.id))) {
                         check(e.id, 'icon', parseCssColour(resolveIn(inkScoped(values, e.id), iconColour), ink), under, WCAG_AA_UI);
                         const focus = (e.focus as StyleMap | undefined)?.['boxShadow'];
                         if (focus) check(e.id, 'focus ring', ringColour(resolveIn(values, focus), ink), bgs, WCAG_AA_UI);
@@ -171,9 +178,35 @@ export function auditDesignContrast(rows: ReadonlyArray<DesignTokenLike>, mode:
             }
         }
     }
+    for (const scrim of SCRIMS) findings.push(...scrimFindings(rows, mode, scrim, byId.get(scrim.style)));
     return findings;
 }
 
+/** 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. */
+function scrimFindings(rows: ReadonlyArray<DesignTokenLike>, mode: ResolvedMode, scrim: Scrim, style: ElementStyle | undefined): ContrastFinding[] {
+    const values = resolveSchemeTokenValues(rows, mode, scrim.scheme);
+    const layer = parseCssColour(values[scrim.token]);
+    const image = parseCssColour(scrim.image);
+    if (!style || !layer || !image) return [];
+    const bg = quantizeRgb(compositeOver(layer, image));
+    const ink = parseCssColour(resolveIn(values, ownStyle(style)['color']));
+    const held = inkScoped(values, scrim.style);
+    const parts: Array<[string, Rgba | null]> = [['text', ink], ...SCRIM_HELD_TOKENS.map((t): [string, Rgba | null] => [t, parseCssColour(held[t], ink)])];
+    const out: ContrastFinding[] = [];
+    for (const [part, fg] of parts) {
+        if (!fg) continue;
+        const f = quantizeRgb(fg.a < 1 ? compositeOver(fg, bg) : fg);
+        const ratio = wcagContrastRatio(f, bg);
+        out.push({
+            scheme: scrim.scheme, container: scrim.style, element: scrim.style, part: `${part} over a ${scrim.image} image`,
+            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;
+}
+
 /** The pairs the Design ▸ Colour tab lists for the CURRENT brand (Board 6 + DS9): what a filled button
  *  shows, and the link on every section scheme — each the worst case on the section itself. */
 export enum ColourCheckId {