@vectoriox/iox-ui 5.44.0 → 5.46.0

package/src/design-core/fonts.ts

@@ -1,4 +1,4 @@
-import { SPEC_FONTS } from './flavor-spec.generated';
+import { SPEC_FONTS, SPEC_SCRIPTS } from './flavor-spec.generated';
 import { DesignTokenLike, resolveTokenValues } from './token-css';
 
 /**
@@ -429,6 +429,40 @@ export interface FontsForTokensOptions {
      * upload, and the browser picked Google's — DS5.1).
      */
     uploaded?: ReadonlyArray<string>;
+    /**
+     * The page's locale (`page.locale`). A locale whose script the Latin families cannot draw (`he` →
+     * Hebrew) also links each role's script PARTNER — the family the stack names after the first that draws
+     * it (H1-2). An English page loads no Hebrew file.
+     */
+    locale?: string | null;
+}
+
+/** A script the catalog's Latin families cannot draw, and the families that can (contract `scripts`). */
+export type ScriptId = keyof typeof SPEC_SCRIPTS;
+const SCRIPT_FAMILIES = new Map<ScriptId, Set<string>>(
+    (Object.entries(SPEC_SCRIPTS) as Array<[ScriptId, { families: ReadonlyArray<string> }]>)
+        .map(([script, def]) => [script, new Set(def.families.map(fontFamilyKey))]));
+
+/** The scripts a page in `locale` needs drawn (`he`, `he-IL` → hebrew); none for a Latin locale. */
+export function scriptsForLocale(locale: string | null | undefined): ScriptId[] {
+    const lang = String(locale ?? '').trim().toLowerCase().split(/[-_]/)[0];
+    return (Object.entries(SPEC_SCRIPTS) as Array<[ScriptId, { locales: ReadonlyArray<string> }]>)
+        .filter(([, def]) => def.locales.includes(lang)).map(([script]) => script);
+}
+
+/** True when `family` is a catalog family that draws `script`. */
+export function drawsScript(family: string | null | undefined, script: ScriptId): boolean {
+    return !!SCRIPT_FAMILIES.get(script)?.has(fontFamilyKey(family));
+}
+
+/**
+ * A stack with its script PARTNERS removed — every family after the first that only stands there to draw
+ * a script. What the contract wrote before H1-2 placed the partners: a row seeded then still holds it, and
+ * is the look's own, not the author's (`designBaseline`).
+ */
+export function withoutScriptPartners(stack: string | null | undefined): string {
+    const partner = (family: string) => [...SCRIPT_FAMILIES.values()].some(set => set.has(fontFamilyKey(family)));
+    return splitFontStack(stack).filter((e, i) => i === 0 || !partner(e.family)).map(e => e.raw).join(', ');
 }
 
 /**
@@ -445,23 +479,35 @@ export function fontsForTokens(
         || rows.some(t => t.name !== MONO_ROLE && MONO_REFERENCE.test(`${t.value ?? ''} ${t.values?.dark ?? ''}`));
     const roles = monoRead ? FONT_FAMILY_TOKENS : ALWAYS_LOADED_ROLES;
     const uploaded = new Set((opts.uploaded ?? []).map(fontFamilyKey));
+    const scripts = scriptsForLocale(opts.locale);
     const seen = new Set<string>();
     const ids: string[] = [];
+    const add = (id: string | null) => {
+        if (id && !seen.has(id)) {
+            seen.add(id);
+            ids.push(id);
+        }
+    };
     for (const role of roles) {
-        const row = rows.find(t => t.name === role);
+        const families = parseFontFamilies(rows.find(t => t.name === role)?.value ?? '');
         // The role's FIRST family that renders decides: an uploaded one needs nothing from Google; the
         // first catalog one is linked (it renders, or stands in for an uploaded family that is missing
         // — `userFontStack` puts the look's font right after the author's). Nothing further down is
-        // ever reached, so nothing further down is loaded.
+        // reached for a Latin glyph, so nothing further down is loaded for one.
+        let lead: string | null = null;
         let id: string | null = null;
-        for (const family of parseFontFamilies(row?.value ?? '')) {
-            if (uploaded.has(fontFamilyKey(family))) break;
+        for (const family of families) {
+            if (uploaded.has(fontFamilyKey(family))) { lead = family; break; }
             id = catalogFontId(family);
-            if (id) break;
+            if (id) { lead = family; break; }
         }
-        if (id && !seen.has(id)) {
-            seen.add(id);
-            ids.push(id);
+        add(id);
+        // …but a Hebrew glyph IS reached further down: the browser falls through the stack, per glyph, to the
+        // first family that draws it — the role's script partner, linked for a page whose locale needs it.
+        for (const script of scripts) {
+            if (lead && drawsScript(lead, script)) continue;
+            const partner = families.find(f => drawsScript(f, script) && !uploaded.has(fontFamilyKey(f)));
+            add(partner ? catalogFontId(partner) : null);
         }
     }
     return ids;
@@ -526,8 +572,10 @@ const PRELOAD_FORMAT: FontFormat = 'woff2';
 
 /**
  * The uploaded files the SSR head preloads (§5b — no flash of the fallback face): for the display and
- * body roles, the family each token names (its first uploaded family), the woff2 normal-style cut CSS
- * matching would pick for that role's weights. One file per weight that renders, never the family.
+ * body roles, the family the role RENDERS in — the stack's first family that is uploaded, in the catalog
+ * or on every system — when it is an uploaded one, the woff2 normal-style cut CSS matching would pick for
+ * that role's weights. One file per weight that renders, never the family. A family further down (a
+ * Hebrew partner, H1-2) draws only the glyphs the lead lacks: never preloaded.
  */
 export function fontPreloads(
     descriptors: ReadonlyArray<FontDescriptor> | null | undefined,
@@ -539,7 +587,9 @@ export function fontPreloads(
     const out = new Map<string, FontDescriptor>();
     for (const { role, weights, fallback } of PRELOAD_ROLES) {
         const named = parseFontFamilies(resolved[role] ?? '').map(fontFamilyKey);
-        const family = named.map(key => families.find(f => fontFamilyKey(f.family) === key)).find(Boolean);
+        const uploadedFamily = (key: string) => families.find(f => fontFamilyKey(f.family) === key);
+        const lead = named.find(key => !!uploadedFamily(key) || !!catalogFontId(key) || ALWAYS_AVAILABLE_FAMILIES.has(key));
+        const family = lead ? uploadedFamily(lead) : undefined;
         const faces = family?.faces.filter(f => f.format === PRELOAD_FORMAT && normalizeFontStyle(f.style) === 'normal') ?? [];
         for (const token of weights) {
             const weight = Number.parseInt(resolved[token] ?? '', 10);

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

@@ -29,3 +29,4 @@ export * from './fonts';
 export * from './token-names';
 export * from './design-settings';
 export * from './design-apply';
+export * from './style-presets';

package/src/design-core/style-presets.ts

@@ -0,0 +1,71 @@
+import { SPEC_MOODS, SPEC_STYLE_PRESETS } from './flavor-spec.generated';
+import { resolveDesignChoices } from './design-settings';
+import {
+    DensityId, DesignChoices, DesignMode, DesignMotion, MotionId, ShapeId, TintId,
+} from './design-token.model';
+
+/**
+ * Style presets (AI plan rev 3 §3f, H1-1) — a style is a preset over what exists, never a stylesheet: a
+ * named `DesignChoices` + the site's motion character + the colour modes it passed the contrast audit in.
+ * Generated 1:1 from the contract (`stylePresets`, AA-gated per preset × mode in build-spec.mjs); Design ▸
+ * Look lists them, ranked by the harness (`@vectoriox/iox-ui/harness-core`).
+ */
+
+/** The closed mood vocabulary a preset carries (≤ 3) and an analysis returns. */
+export type MoodId = keyof typeof SPEC_MOODS;
+export const MOOD_IDS = Object.keys(SPEC_MOODS) as ReadonlyArray<MoodId>;
+export const MOOD_LABELS: Readonly<Record<MoodId, string>> = SPEC_MOODS;
+
+/** A colour mode a preset was audited in (`auto` is offered on top when it passed both). */
+export type PresetMode = Exclude<DesignMode, 'auto'>;
+
+export interface StylePreset {
+    readonly id: string;
+    readonly name: string;
+    readonly blurb: string;
+    readonly flavorId: string;
+    readonly seed: string;
+    readonly tint: TintId;
+    readonly pairId: string;
+    readonly shape: ShapeId;
+    readonly density: DensityId;
+    readonly motion: MotionId;
+    readonly pillButtons: boolean;
+    readonly moves: Readonly<DesignMotion>;
+    /** The modes it PASSED the audit in; the first is its default. */
+    readonly modes: ReadonlyArray<PresetMode>;
+    readonly moods: ReadonlyArray<MoodId>;
+    /** The UI UX Pro Max styles it stands for (attribution and the mapping table). */
+    readonly uupm: ReadonlyArray<string>;
+    /** In the M1-alpha slice. */
+    readonly slice: boolean;
+}
+
+/** The 24, catalogue order (four per flavor). Assignment here proves the generated data fits the type. */
+export const STYLE_PRESETS: ReadonlyArray<StylePreset> = SPEC_STYLE_PRESETS;
+
+export function stylePresetById(id: string | null | undefined): StylePreset | undefined {
+    return id ? STYLE_PRESETS.find(p => p.id === id) : undefined;
+}
+
+const FOLLOW_VISITOR: DesignMode = 'auto';
+
+/** The modes Design offers for a preset: the audited ones, then "Follow visitor" when it passed both (H-D3). */
+export function presetModes(preset: StylePreset): DesignMode[] {
+    return preset.modes.length > 1 ? [...preset.modes, FOLLOW_VISITOR] : [...preset.modes];
+}
+
+/**
+ * What picking a preset means — the complete `DesignChoices`, its motion included — in `mode` (default:
+ * its first). A mode it was not audited in is REFUSED (null): a light-only preset is never worn dark.
+ */
+export function presetChoices(id: string, mode?: DesignMode): DesignChoices | null {
+    const preset = stylePresetById(id);
+    if (!preset) return null;
+    const wear = mode ?? preset.modes[0];
+    if (!presetModes(preset).includes(wear)) return null;
+    return resolveDesignChoices({
+        flavorId: preset.flavorId, seed: preset.seed, pairId: preset.pairId, shape: preset.shape, density: preset.density,
+        motion: preset.motion, pillButtons: preset.pillButtons, mode: wear, tint: preset.tint, ...preset.moves,
+    });
+}