@vectoriox/iox-ui 5.45.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);