@vectoriox/iox-ui 5.17.0 → 5.18.0

package/package.json

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

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

@@ -4,6 +4,7 @@ import { SWISS_FLAVOR } from './flavor';
 import { buildFlavorTokens } from './flavor-tokens';
 import { FlavorSeedPlan, planFlavorSeed, SeedBaseline, SeedExpectation } from './flavor-seed';
 import { DesignChoices, DesignTokenRow, flavorSourceStamp, StoredDesignTokenRow } from './design-token.model';
+import { fontFamilyKey, FontFamilyToken, fontRoleReferences, parseFontFamilies } from './fonts';
 import { flavorPackById, isRetiredFlavorId, packDesignChoices, StoredDesign } from './design-settings';
 
 /**
@@ -139,3 +140,45 @@ export function planSwissMigration(existing: ReadonlyArray<StoredDesignTokenRow>
     }
     return { choices, plan };
 }
+
+/** What deleting an uploaded family does to the look (§5b delete guard). */
+export interface FontFamilyRemoval {
+    /** The font tokens that name the family — empty means nothing references it and nothing changes. */
+    roles: FontFamilyToken[];
+    /** The design without the family: every font role it held goes back to the pack's pairing. */
+    choices: DesignChoices;
+    /** The token writes: the look's own merge, plus any OTHER row still naming the family (one typed
+     *  in the Tokens panel), rewritten to the pack's value too — a deleted face must not stay named. */
+    plan: FlavorSeedPlan;
+    /** Per role, the family it falls back to — what the guard tells the author before they confirm. */
+    fallbacks: Array<{ role: FontFamilyToken; family: string }>;
+}
+
+/**
+ * Plan the removal of an uploaded family from the look: the roles naming it fall back to the pack's
+ * own font (the design's pairing), as the guard promises — "Nothing else changes".
+ */
+export function planFontFamilyRemoval(
+    existing: ReadonlyArray<StoredDesignTokenRow>,
+    previous: StoredDesign,
+    family: string,
+): FontFamilyRemoval {
+    const roles = fontRoleReferences(existing, family);
+    const fonts = Object.fromEntries(Object.entries(previous.choices.fonts ?? {})
+        .filter(([, chosen]) => fontFamilyKey(chosen) !== fontFamilyKey(family)));
+    const choices: DesignChoices = { ...previous.choices };
+    if (Object.keys(fonts).length) choices.fonts = fonts; else delete choices.fonts;
+    if (!roles.length) return { roles, choices: previous.choices, plan: { create: [], update: [], kept: [] }, fallbacks: [] };
+
+    const plan = planDesignApply(existing, previous, choices);
+    const desired = new Map(designTokenRows(choices).map(r => [r.name, r]));
+    const planned = new Set(plan.update.map(u => u.id));
+    for (const row of existing ?? []) {
+        const want = desired.get(row.name);
+        if (!row._id || !want || planned.has(row._id) || !(roles as string[]).includes(row.name)) continue;
+        plan.update.push({ id: row._id, data: { value: want.value, values: want.values ?? {}, source: want.source } });
+        plan.kept = plan.kept.filter(name => name !== row.name);
+    }
+    const fallbacks = roles.map(role => ({ role, family: parseFontFamilies(desired.get(role)?.value ?? '')[0] ?? '' }));
+    return { roles, choices, plan, fallbacks };
+}

package/src/design-core/fonts.ts

@@ -1,5 +1,5 @@
 import { SPEC_FONTS } from './flavor-spec.generated';
-import { DesignTokenLike } from './token-css';
+import { DesignTokenLike, resolveTokenValues } from './token-css';
 
 /**
  * Fonts (design-system plan §5b, D7): ONE Google catalog for both renderers, and ONE face builder
@@ -45,23 +45,90 @@ export function cssString(value: string): string {
     return `'${body}'`;
 }
 
-const clampWeight = (w: unknown): number => {
+/** The file extensions a studio may upload as a font, and the descriptor format each one IS (§5b). */
+export const FONT_FILE_FORMATS: Readonly<Record<string, FontFormat>> = Object.freeze({
+    woff2: 'woff2', woff: 'woff', ttf: 'truetype', otf: 'opentype',
+});
+export const FONT_FILE_EXTENSIONS: ReadonlyArray<string> = Object.keys(FONT_FILE_FORMATS);
+/** For a file input's `accept` — the same list the server validates against. */
+export const FONT_FILE_ACCEPT = FONT_FILE_EXTENSIONS.map(ext => `.${ext}`).join(',');
+/** The CSS weights a face can be declared at, for an editor that offers them. */
+export const FONT_WEIGHTS: ReadonlyArray<number> = [100, 200, 300, 400, 500, 600, 700, 800, 900];
+export const FONT_STYLES: ReadonlyArray<FontStyle> = ['normal', 'italic'];
+
+/** When two files declare the same face, the browser should try the smallest, best-supported first. */
+const FORMAT_PREFERENCE: ReadonlyArray<FontFormat> = ['woff2', 'woff', 'opentype', 'truetype'];
+const UPLOAD_SUFFIX = /-\d+$/;
+
+/** A stored key's original file name: the folder prefix and the `-<timestamp>` upload suffix removed. */
+export function fontFileName(key: string | null | undefined): string {
+    const name = String(key ?? '');
+    return name.substring(name.lastIndexOf('/') + 1).replace(UPLOAD_SUFFIX, '');
+}
+
+/** The descriptor format of a font file, from its extension — null for anything we do not serve. */
+export function fontFormatOf(fileNameOrKey: string | null | undefined): FontFormat | null {
+    const ext = /\.([a-z0-9]+)$/i.exec(fontFileName(fileNameOrKey))?.[1]?.toLowerCase() ?? '';
+    return FONT_FILE_FORMATS[ext] ?? null;
+}
+
+/** The family a file had before DS5 — its name without the extension. Legacy files with no parsed
+ *  name table keep it, so a page saved with `font-family: 'Rubik-Regular'` keeps its face (D5). */
+export function fontFileStem(key: string | null | undefined): string {
+    return fontFileName(key).replace(/\.[^.]+$/, '');
+}
+
+/** A weight as CSS can use it: 100–900, a bad value → 400. */
+export function normalizeFontWeight(w: unknown): number {
     const n = Math.round(Number(w));
     return Number.isFinite(n) && n > 0 ? Math.min(MAX_WEIGHT, Math.max(MIN_WEIGHT, n)) : DEFAULT_WEIGHT;
+}
+
+export function normalizeFontStyle(style: unknown): FontStyle {
+    return style === 'italic' ? 'italic' : 'normal';
+}
+
+/** CSS family names match case-insensitively; this is the one comparison key. */
+export function fontFamilyKey(family: string | null | undefined): string {
+    return String(family ?? '').trim().toLowerCase();
+}
+
+const usableDescriptor = (d: FontDescriptor | null | undefined): d is FontDescriptor =>
+    !!d && typeof d.family === 'string' && d.family.trim() !== '' && typeof d.url === 'string' && d.url !== '';
+
+const preference = (format: FontFormat) => {
+    const i = FORMAT_PREFERENCE.indexOf(format);
+    return i < 0 ? FORMAT_PREFERENCE.length : i;
 };
 
-/** One `@font-face` per file, carrying its real weight and style — so bold is never synthesised. */
+/**
+ * One `@font-face` per FACE (family × weight × style), carrying its real weight and style — so bold is
+ * never synthesised. Files that declare the same face (a woff2 and a ttf of one cut) share one rule
+ * whose `src` lists them best format first, which is what the two retired forks did per file stem.
+ */
 export function buildFontFaceCss(descriptors: ReadonlyArray<FontDescriptor> | null | undefined): string {
-    return (descriptors ?? [])
-        .filter(d => !!d && typeof d.family === 'string' && d.family.trim() !== '' && typeof d.url === 'string' && d.url !== '')
-        .map(d => {
-            const format = FONT_FORMATS.includes(d.format) ? ` format(${cssString(d.format)})` : '';
+    const faces = new Map<string, { family: string; weight: number; style: FontStyle; files: FontDescriptor[] }>();
+    for (const d of (descriptors ?? []).filter(usableDescriptor)) {
+        const family = d.family.trim();
+        const weight = normalizeFontWeight(d.weight);
+        const style = normalizeFontStyle(d.style);
+        const id = `${fontFamilyKey(family)}|${weight}|${style}`;
+        const face = faces.get(id) ?? { family, weight, style, files: [] };
+        face.files.push(d);
+        faces.set(id, face);
+    }
+    return [...faces.values()]
+        .map(face => {
+            const src = [...face.files]
+                .sort((a, b) => preference(a.format) - preference(b.format))
+                .map(d => `url(${cssString(d.url)})${FONT_FORMATS.includes(d.format) ? ` format(${cssString(d.format)})` : ''}`)
+                .join(', ');
             return [
                 '@font-face {',
-                `  font-family: ${cssString(d.family.trim())};`,
-                `  src: url(${cssString(d.url)})${format};`,
-                `  font-weight: ${clampWeight(d.weight)};`,
-                `  font-style: ${d.style === 'italic' ? 'italic' : 'normal'};`,
+                `  font-family: ${cssString(face.family)};`,
+                `  src: ${src};`,
+                `  font-weight: ${face.weight};`,
+                `  font-style: ${face.style};`,
                 '  font-display: swap;',
                 '}',
             ].join('\n');
@@ -69,6 +136,39 @@ export function buildFontFaceCss(descriptors: ReadonlyArray<FontDescriptor> | nu
         .join('\n');
 }
 
+/** An uploaded family: every file sharing a family name (case-insensitively), with its real cuts. */
+export interface FontFamilyGroup {
+    family: string;
+    /** Distinct weights, ascending. */
+    weights: number[];
+    styles: FontStyle[];
+    /** Every file of the family, lightest first. */
+    faces: FontDescriptor[];
+}
+
+/** Files → families (§5b "Group into families"): the Files tile, the typeface dropdown and Design ▸ Type. */
+export function groupFontFamilies(descriptors: ReadonlyArray<FontDescriptor> | null | undefined): FontFamilyGroup[] {
+    const groups = new Map<string, FontFamilyGroup>();
+    for (const d of (descriptors ?? []).filter(usableDescriptor)) {
+        const key = fontFamilyKey(d.family);
+        const group = groups.get(key) ?? { family: d.family.trim(), weights: [], styles: [], faces: [] };
+        group.faces.push(d);
+        groups.set(key, group);
+    }
+    return [...groups.values()]
+        .map(g => {
+            const faces = [...g.faces].sort((a, b) => normalizeFontWeight(a.weight) - normalizeFontWeight(b.weight)
+                || normalizeFontStyle(a.style).localeCompare(normalizeFontStyle(b.style)));
+            return {
+                family: g.family,
+                weights: [...new Set(faces.map(f => normalizeFontWeight(f.weight)))].sort((a, b) => a - b),
+                styles: FONT_STYLES.filter(s => faces.some(f => normalizeFontStyle(f.style) === s)),
+                faces,
+            };
+        })
+        .sort((a, b) => a.family.localeCompare(b.family));
+}
+
 /** The family names in a CSS `font-family` stack, unquoted, in order. */
 export function parseFontFamilies(stack: string): string[] {
     return String(stack ?? '')
@@ -133,3 +233,76 @@ export function fontsForTokens(
     }
     return ids;
 }
+
+export type FontFamilyToken = (typeof FONT_FAMILY_TOKENS)[number];
+
+/** True when `stack` (a CSS `font-family` value) names `family` anywhere in it. */
+export function stackNamesFamily(stack: string | null | undefined, family: string | null | undefined): boolean {
+    const key = fontFamilyKey(family);
+    return key !== '' && parseFontFamilies(stack ?? '').some(f => fontFamilyKey(f) === key);
+}
+
+/**
+ * The font tokens whose value names `family` — what the delete guard asks before an uploaded family's
+ * last file goes (§5b): deleting it would silently drop those roles to their fallback.
+ */
+export function fontRoleReferences(
+    tokens: ReadonlyArray<DesignTokenLike> | null | undefined,
+    family: string | null | undefined,
+): FontFamilyToken[] {
+    const rows = (tokens ?? []).filter(t => !!t && typeof t.name === 'string');
+    return FONT_FAMILY_TOKENS.filter(role => rows.some(t => t.name === role && stackNamesFamily(t.value, family)));
+}
+
+/**
+ * The face CSS font matching picks for `weight` from `faces` (CSS Fonts §5.2): 400 tries 500 next,
+ * 500 tries 400; lighter weights look down first, heavier ones up. So an `h1` at 600 over a family
+ * uploaded at 400 + 700 renders the real 700 cut — the one worth preloading.
+ */
+export function matchFontWeight<T extends { weight: number }>(faces: ReadonlyArray<T>, weight: number): T | null {
+    if (!faces?.length) return null;
+    const want = normalizeFontWeight(weight);
+    const exact = faces.find(f => normalizeFontWeight(f.weight) === want);
+    if (exact) return exact;
+    const w = (f: T) => normalizeFontWeight(f.weight);
+    const below = (max: number) => [...faces].filter(f => w(f) < max).sort((a, b) => w(b) - w(a))[0] ?? null;
+    const above = (min: number) => [...faces].filter(f => w(f) > min).sort((a, b) => w(a) - w(b))[0] ?? null;
+    if (want >= 400 && want <= 500) {
+        const within = [...faces].filter(f => w(f) > want && w(f) <= 500).sort((a, b) => w(a) - w(b))[0];
+        return within ?? below(want) ?? above(500);
+    }
+    return want < 400 ? (below(want) ?? above(want)) : (above(want) ?? below(want));
+}
+
+/** The roles a preload serves, and the weight tokens whose cuts render above the fold. */
+const PRELOAD_ROLES: ReadonlyArray<{ role: FontFamilyToken; weights: ReadonlyArray<string>; fallback: number }> = [
+    { role: 'font-display', weights: ['weight-display', 'weight-heading'], fallback: 700 },
+    { role: 'font-body', weights: ['weight-body', 'weight-strong'], fallback: DEFAULT_WEIGHT },
+];
+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.
+ */
+export function fontPreloads(
+    descriptors: ReadonlyArray<FontDescriptor> | null | undefined,
+    tokens: ReadonlyArray<DesignTokenLike> | null | undefined,
+): FontDescriptor[] {
+    const families = groupFontFamilies(descriptors);
+    if (!families.length) return [];
+    const resolved = resolveTokenValues(tokens);
+    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 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);
+            const face = matchFontWeight(faces, Number.isFinite(weight) ? weight : fallback);
+            if (face) out.set(face.url, face);
+        }
+    }
+    return [...out.values()];
+}