@vectoriox/iox-ui 5.19.0 → 5.21.0

package/design-core/index.d.ts

@@ -8600,8 +8600,14 @@ declare function deriveAccentTokens(seed: string, against: AccentBackgrounds, pa
 
 /** The pack's own defaults as a full set of choices — what Apply means with nothing changed. */
 declare function defaultDesignChoices(pack: FlavorPackV2): DesignChoices;
-/** `'<Family>', system-ui, sans-serif` — the value a font role holds once the author picks a face. */
-declare function userFontStack(family: string): string;
+/**
+ * The value a font role holds once the author picks a face: `'<Family>', <the look's own stack>` —
+ * e.g. `'Rubik', 'Inter Tight', system-ui, -apple-system, 'Segoe UI', sans-serif`. The look's font
+ * follows the author's, so a family that later stops existing (deleted outside the delete guard, a
+ * bucket emptied by hand) renders in the pack's font — Board 8's promise — in every renderer, with no
+ * runtime check. With no look stack: `system-ui, sans-serif`.
+ */
+declare function userFontStack(family: string, packStack?: string | null): string;
 declare function buildFlavorTokens(pack: FlavorPackV2, choices: DesignChoices): DesignTokenRow[];
 
 /** One row's fate in a seed/re-seed pass (the §10 C2 merge semantics). */
@@ -8685,23 +8691,82 @@ declare function springToLinear(stiffness: number, damping: number): LinearSprin
 declare const FONT_CATALOG: Readonly<Record<string, string>>;
 type FontFormat = 'woff2' | 'woff' | 'truetype' | 'opentype';
 type FontStyle = 'normal' | 'italic';
+/**
+ * A face's weight (spec `fontDescriptor.weight`): 100–900 for a static cut (OS/2 `usWeightClass`), or
+ * the RANGE string `'<min> <max>'` a variable font's `fvar` wght axis covers — emitted as
+ * `font-weight: <min> <max>`, so every weight inside it renders from the one file.
+ */
+type FontWeight = number | string;
 /** One uploaded font FILE (spec `fontDescriptor`) — a family is all descriptors sharing `family`. */
 interface FontDescriptor {
     family: string;
-    /** 100–900, from the file's OS/2 `usWeightClass`. */
-    weight: number;
+    weight: FontWeight;
     style: FontStyle;
     url: string;
     format: FontFormat;
 }
+/**
+ * Why iox-cms refused a font upload. The server answers `{ code }` beside its message; the admin
+ * translates the code (`filebox.fontUpload.<code>`), so the author reads why in their language.
+ */
+declare enum FontUploadError {
+    NotAFont = "not_a_font",
+    Empty = "empty",
+    Unreadable = "unreadable",
+    TooLarge = "too_large"
+}
+/**
+ * The largest font FILE a studio may upload: 10 MB. A full static or variable Latin/Hebrew/Arabic
+ * family is well under it (Inter's variable TTF is 0.9 MB); an unsubsetted CJK family is not, and
+ * must be subset first. iox-cms stops reading the request at this size; the admin checks it before
+ * sending.
+ */
+declare const MAX_FONT_FILE_BYTES: number;
 /** The token roles whose values name the families a page renders in. */
 declare const FONT_FAMILY_TOKENS: readonly ["font-display", "font-body", "font-label", "font-mono"];
 /**
  * A CSS string literal, single-quoted: `\` and `'` escaped, line breaks and NUL dropped, and `<` /
  * `>` hex-escaped (`\3c `) — the face CSS is inlined into a `<style>` by the SSR engine, where an
- * uploaded family named `</style><script>` would otherwise close the element.
+ * uploaded family named `</style><script>` would otherwise close the element. `parseFontFamilies` is
+ * its exact inverse (escapes included), which is what keeps a family's name one value everywhere.
  */
 declare function cssString(value: string): string;
+/** ONE family as a `font-family` entry — always quoted, so a family named `Acme, Serif` or `serif` is
+ *  that family, never a list or a generic. */
+declare function formatFontFamily(family: string): string;
+/** Families → a `font-family` stack, each quoted (`formatFontFamily`); `parseFontFamilies` reverses it. */
+declare function formatFontFamilies(families: ReadonlyArray<string>): string;
+/** The entries of `stack` that do NOT name `family`, as written — what a fallback list keeps. */
+declare function fontStackWithout(stack: string | null | undefined, family: string | null | undefined): string;
+/** A weight as a closed range — a static cut is `{ min: w, max: w }`. */
+interface FontWeightRange {
+    min: number;
+    max: number;
+}
+/**
+ * Anything a file, a descriptor or an author may hold as a weight → its range, or null when it is
+ * not one: `700`, `'700'`, `'100 900'`, `'100-900'`, `'100–900'` (the tile's own spelling). A static
+ * weight clamps to 100–900 (as before); range ends clamp to CSS's 1–1000.
+ */
+declare function parseFontWeight(value: unknown): FontWeightRange | null;
+/** A range in the stored / descriptor / CSS form: a number for one weight, `'<min> <max>'` for a span. */
+declare function fontWeightValue(range: FontWeightRange): FontWeight;
+/** Any weight → the stored form; a bad value → 400 (as `normalizeFontWeight`). */
+declare function normalizeFontWeightValue(value: unknown): FontWeight;
+/** Any weight → its range; a bad value → 400–400. */
+declare function fontWeightRange(value: unknown): FontWeightRange;
+/** True when the weight spans more than one value (a variable font's wght axis). */
+declare function isFontWeightRange(value: unknown): boolean;
+/** How a weight reads on screen: `700`, or `100–900` for a range. */
+declare function formatFontWeight(value: unknown): string;
+/**
+ * A weight an author or a client SENT, held to what a face can be — or null: a whole number 100–900,
+ * or a range of whole numbers 1 ≤ min < max ≤ 1000. Nothing is clamped or rounded here; a value that
+ * would need it is refused (the PUT correction's rule).
+ */
+declare function checkFontWeight(value: unknown): FontWeight | null;
+/** True when a face of `weight` renders `wanted` from its own file (inside its range). */
+declare function fontWeightCovers(weight: unknown, wanted: number): boolean;
 /** The file extensions a studio may upload as a font, and the descriptor format each one IS (§5b). */
 declare const FONT_FILE_FORMATS: Readonly<Record<string, FontFormat>>;
 declare const FONT_FILE_EXTENSIONS: ReadonlyArray<string>;
@@ -8717,7 +8782,8 @@ declare function fontFormatOf(fileNameOrKey: string | null | undefined): FontFor
 /** 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). */
 declare function fontFileStem(key: string | null | undefined): string;
-/** A weight as CSS can use it: 100–900, a bad value → 400. */
+/** A single weight as CSS can use it: 100–900, a bad value → 400. A range is not a single weight —
+ *  use `normalizeFontWeightValue` for a face. */
 declare function normalizeFontWeight(w: unknown): number;
 declare function normalizeFontStyle(style: unknown): FontStyle;
 /** CSS family names match case-insensitively; this is the one comparison key. */
@@ -8731,16 +8797,25 @@ declare function buildFontFaceCss(descriptors: ReadonlyArray<FontDescriptor> | n
 /** An uploaded family: every file sharing a family name (case-insensitively), with its real cuts. */
 interface FontFamilyGroup {
     family: string;
-    /** Distinct weights, ascending. */
-    weights: number[];
+    /** Distinct weights, ascending by their lower end — a variable file's is its `'<min> <max>'` range. */
+    weights: FontWeight[];
     styles: FontStyle[];
     /** Every file of the family, lightest first. */
     faces: FontDescriptor[];
 }
+/** Lighter first: by the range's lower end, then its upper end (a static 100 before a 100–900 file). */
+declare function compareFontWeights(a: unknown, b: unknown): number;
+/** The weight a family's preview renders at: 400 when a face covers it, else its lightest. */
+declare function previewFontWeight(weights: ReadonlyArray<FontWeight>): number;
 /** Files → families (§5b "Group into families"): the Files tile, the typeface dropdown and Design ▸ Type. */
 declare function groupFontFamilies(descriptors: ReadonlyArray<FontDescriptor> | null | undefined): FontFamilyGroup[];
-/** The family names in a CSS `font-family` stack, unquoted, in order. */
-declare function parseFontFamilies(stack: string): string[];
+/**
+ * The family names in a CSS `font-family` stack, in order — the exact inverse of `formatFontFamily` /
+ * `formatFontFamilies`: quotes removed, CSS escapes decoded (`\'`, `\\`, `\3c `), a comma INSIDE
+ * quotes kept, an unquoted name's words joined by one space. Every reader of a font token goes
+ * through this; a naive split on `,` is how `O'Neil Sans` stopped matching its own token.
+ */
+declare function parseFontFamilies(stack: string | null | undefined): string[];
 /** Where Google serves the stylesheets, and the origin the font FILES come from (preconnect). */
 declare const GOOGLE_FONTS_CSS_ORIGIN = "https://fonts.googleapis.com";
 declare const GOOGLE_FONTS_FILE_ORIGIN = "https://fonts.gstatic.com";
@@ -8755,6 +8830,13 @@ interface FontsForTokensOptions {
      * would otherwise download a monospace face for a site with no code on it.
      */
     usedCss?: string;
+    /**
+     * The families the org UPLOADED. An uploaded family renders from the org's own files, so it is
+     * never fetched from Google — even when the catalog has a family of that name (an org that uploads
+     * Inter's variable file means THAT Inter: linking Google's too put its static cuts beside the
+     * upload, and the browser picked Google's — DS5.1).
+     */
+    uploaded?: ReadonlyArray<string>;
 }
 /**
  * The Google css2 ids to load for a token set: every catalog family named by the display / body /
@@ -8766,17 +8848,21 @@ type FontFamilyToken = (typeof FONT_FAMILY_TOKENS)[number];
 /** True when `stack` (a CSS `font-family` value) names `family` anywhere in it. */
 declare function stackNamesFamily(stack: string | null | undefined, family: string | null | undefined): boolean;
 /**
- * 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.
+ * The font tokens that render in `family` — their stack LEADS with it — what the delete guard asks
+ * before an uploaded family's last file goes (§5b): deleting it would drop those roles to their
+ * fallback. A role naming it further down (the look's font behind the author's, `userFontStack`) does
+ * not render in it, and rewriting that role would throw the author's own choice away.
  */
 declare function fontRoleReferences(tokens: ReadonlyArray<DesignTokenLike> | null | undefined, family: string | null | undefined): FontFamilyToken[];
 /**
- * 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.
+ * The face CSS font matching picks for `weight` from `faces` (CSS Fonts §5.2): a face whose range
+ * holds the weight is exact (a variable file covers every weight on its axis); otherwise 400 tries
+ * 500 next, 500 tries 400; lighter weights look down first, heavier ones up — each face measured at
+ * its nearest end. So an `h1` at 600 over a family uploaded at 400 + 700 renders the real 700 cut —
+ * the one worth preloading.
  */
 declare function matchFontWeight<T extends {
-    weight: number;
+    weight: FontWeight;
 }>(faces: ReadonlyArray<T>, weight: number): T | null;
 /**
  * The uploaded files the SSR head preloads (§5b — no flash of the fallback face): for the display and
@@ -8784,6 +8870,22 @@ declare function matchFontWeight<T extends {
  * matching would pick for that role's weights. One file per weight that renders, never the family.
  */
 declare function fontPreloads(descriptors: ReadonlyArray<FontDescriptor> | null | undefined, tokens: ReadonlyArray<DesignTokenLike> | null | undefined): FontDescriptor[];
+/** A font role naming a family that is neither uploaded nor in the catalog, and what renders instead. */
+interface MissingFontRole {
+    role: FontFamilyToken;
+    /** The family the role names first, which no file and no catalog entry serves. */
+    family: string;
+    /** The next family in the role's stack that does render — the look's own font for a stack written
+     *  by `userFontStack`, `system-ui` for an older one. */
+    fallback: string;
+}
+/**
+ * Board 8's "the same check runs when a font token points at a missing family": the font roles whose
+ * FIRST family is not uploaded (`uploaded` — the org's families), not in the catalog and not a system
+ * face. Only meaningful over a listing that SUCCEEDED — an empty bucket because storage is down would
+ * otherwise report every uploaded family missing.
+ */
+declare function missingFontRoles(tokens: ReadonlyArray<DesignTokenLike> | null | undefined, uploaded: ReadonlyArray<string> | null | undefined): MissingFontRole[];
 
 /**
  * Which `--iox-<name>` a piece of COMPONENT CSS may reference (design-system §3b-bis: "component CSS
@@ -8943,5 +9045,5 @@ interface FontFamilyRemoval {
  */
 declare function planFontFamilyRemoval(existing: ReadonlyArray<StoredDesignTokenRow>, previous: StoredDesign, family: string): FontFamilyRemoval;
 
-export { ACCENT_TOKEN_NAMES, BUTTON_VARIANT_TO_STYLE, COLOR_SCHEMES, COLOR_SCHEME_TRAIT, COLOR_SCHEME_TYPES, ColorScheme, DEFAULT_FLAVOR_ID, DESIGN_TOKEN_GROUPS, DESIGN_TOKEN_TIERS, DESIGN_TOKEN_TYPES, DesignConfigKey, ELEMENT_STYLES, ELEMENT_STYLE_MARKER_CLASS, ELEMENT_STYLE_STATES, EMPTY_IMAGE_ATTRIBUTE, EMPTY_IMAGE_SRC, ElementStyleState, FLAVOR_SPEC_VERSION, FONT_CATALOG, FONT_FAMILY_TOKENS, FONT_FILE_ACCEPT, FONT_FILE_EXTENSIONS, FONT_FILE_FORMATS, FONT_STYLES, FONT_WEIGHTS, GOOGLE_FONTS_CSS_ORIGIN, GOOGLE_FONTS_FILE_ORIGIN, OwnedTraitLink, PALETTE_PRESETS, REDUCED_MOTION_OVERRIDES, REDUCED_TRANSPARENCY_OVERRIDES, REVERT_WINDOW_MS, SPEC_A11Y, SPEC_AXES, SPEC_BUTTON_VARIANT_TO_STYLE, SPEC_CONTRAST, SPEC_DEFAULT_ELEMENT_STYLE, SPEC_ELEMENT_STYLES, SPEC_FIELD_CLASS_BASELINE, SPEC_FLAVORS, SPEC_FLAVOR_PACKS, SPEC_FONTS, SPEC_FONT_ROLES, SPEC_LEGACY_ALIASES, SPEC_PALETTE_PRESETS, SPEC_SCHEMES, SPEC_SPRINGS, SPEC_TIERS, SPEC_TIER_IDS, SPEC_TOKEN_TYPES, SWISS_FLAVOR, USER_TOKEN_SOURCE, WCAG_AA_TEXT, apcaLc, applyElementStyle, applyHeadingLevelRule, buildFlavorTokens, buildFontFaceCss, catalogFontId, choicesForPack, colorSchemeClass, colorSchemeOf, compileSchemeCss, compileTokenCss, compileTokenCssBlocks, cssString, defaultDesignChoices, defaultElementStyleFor, deriveAccentTokens, deriveBrandTokens, designBaseline, designConfigEntries, designModeOf, designTokenRepairs, designTokenRows, elementStyleById, elementStyleClass, elementStylesFor, emptyImageLabelSrc, emptyImagePlaceholder, emptyImageSrc, flavorPackById, flavorSourceStamp, fontFamilyKey, fontFileName, fontFileStem, fontFormatOf, fontPreloads, fontRoleReferences, fontsForTokens, googleFontHref, groupFontFamilies, hasElementStyleMarker, isDesignTokenGroup, isDesignTokenTier, isDesignTokenType, isRetiredFlavorId, legacyRuleTokenReferences, matchFontWeight, missingDesignRows, nodeDesignClasses, normalizeFontStyle, normalizeFontWeight, oklabToRgb, ownedTraitStatus, packDesignChoices, parseFontFamilies, parseHexColor, planDesignApply, planFlavorRevert, planFlavorSeed, planFontFamilyRemoval, planSwissMigration, readDesignConfig, relativeLuminance, resolveDesignChoices, resolveTokenReferences, resolveTokenValues, revertAvailable, rgbToOklab, sameDesignChoices, specTokenNames, springToLinear, stackNamesFamily, styleKeyToKebab, switchElementStyle, syncNodeDesignClasses, toHexColor, tokenReferences, tokensToDarkVarMap, tokensToVarMap, unknownTokenReferences, userFontStack, validateFlavorPack, wcagContrastRatio };
-export type { AccentBackgrounds, AccentTokenName, ApplyElementStyleResult, DensityId, DesignChoices, DesignClassSource, DesignConfigEntry, DesignMode, DesignTokenGroup, DesignTokenLike, DesignTokenRow, DesignTokenTier, DesignTokenType, ElementStyle, ElementStyleTarget, ElementStyleTraitLike, FlavorPack, FlavorPackV2, FlavorRevertPlan, FlavorRevertSnapshot, FlavorSeedPlan, FlavorSpecToken, FlavorTokenDef, FontDescriptor, FontFamilyGroup, FontFamilyRemoval, FontFamilyToken, FontFormat, FontPair, FontRoleToken, FontStyle, FontsForTokensOptions, LinearSpring, MotionId, OkLab, OwnedTrait, OwnedTraitStatus, PalettePreset, ResolvedMode, Rgb, SchemeId, SeedBaseline, SeedExpectation, ShapeId, StoredDesign, StoredDesignTokenRow, SwissMigration, SwitchElementStyleResult, TokenCssBlocks, TokenCssOptions };
+export { ACCENT_TOKEN_NAMES, BUTTON_VARIANT_TO_STYLE, COLOR_SCHEMES, COLOR_SCHEME_TRAIT, COLOR_SCHEME_TYPES, ColorScheme, DEFAULT_FLAVOR_ID, DESIGN_TOKEN_GROUPS, DESIGN_TOKEN_TIERS, DESIGN_TOKEN_TYPES, DesignConfigKey, ELEMENT_STYLES, ELEMENT_STYLE_MARKER_CLASS, ELEMENT_STYLE_STATES, EMPTY_IMAGE_ATTRIBUTE, EMPTY_IMAGE_SRC, ElementStyleState, FLAVOR_SPEC_VERSION, FONT_CATALOG, FONT_FAMILY_TOKENS, FONT_FILE_ACCEPT, FONT_FILE_EXTENSIONS, FONT_FILE_FORMATS, FONT_STYLES, FONT_WEIGHTS, FontUploadError, GOOGLE_FONTS_CSS_ORIGIN, GOOGLE_FONTS_FILE_ORIGIN, MAX_FONT_FILE_BYTES, OwnedTraitLink, PALETTE_PRESETS, REDUCED_MOTION_OVERRIDES, REDUCED_TRANSPARENCY_OVERRIDES, REVERT_WINDOW_MS, SPEC_A11Y, SPEC_AXES, SPEC_BUTTON_VARIANT_TO_STYLE, SPEC_CONTRAST, SPEC_DEFAULT_ELEMENT_STYLE, SPEC_ELEMENT_STYLES, SPEC_FIELD_CLASS_BASELINE, SPEC_FLAVORS, SPEC_FLAVOR_PACKS, SPEC_FONTS, SPEC_FONT_ROLES, SPEC_LEGACY_ALIASES, SPEC_PALETTE_PRESETS, SPEC_SCHEMES, SPEC_SPRINGS, SPEC_TIERS, SPEC_TIER_IDS, SPEC_TOKEN_TYPES, SWISS_FLAVOR, USER_TOKEN_SOURCE, WCAG_AA_TEXT, apcaLc, applyElementStyle, applyHeadingLevelRule, buildFlavorTokens, buildFontFaceCss, catalogFontId, checkFontWeight, choicesForPack, colorSchemeClass, colorSchemeOf, compareFontWeights, compileSchemeCss, compileTokenCss, compileTokenCssBlocks, cssString, defaultDesignChoices, defaultElementStyleFor, deriveAccentTokens, deriveBrandTokens, designBaseline, designConfigEntries, designModeOf, designTokenRepairs, designTokenRows, elementStyleById, elementStyleClass, elementStylesFor, emptyImageLabelSrc, emptyImagePlaceholder, emptyImageSrc, flavorPackById, flavorSourceStamp, fontFamilyKey, fontFileName, fontFileStem, fontFormatOf, fontPreloads, fontRoleReferences, fontStackWithout, fontWeightCovers, fontWeightRange, fontWeightValue, fontsForTokens, formatFontFamilies, formatFontFamily, formatFontWeight, googleFontHref, groupFontFamilies, hasElementStyleMarker, isDesignTokenGroup, isDesignTokenTier, isDesignTokenType, isFontWeightRange, isRetiredFlavorId, legacyRuleTokenReferences, matchFontWeight, missingDesignRows, missingFontRoles, nodeDesignClasses, normalizeFontStyle, normalizeFontWeight, normalizeFontWeightValue, oklabToRgb, ownedTraitStatus, packDesignChoices, parseFontFamilies, parseFontWeight, parseHexColor, planDesignApply, planFlavorRevert, planFlavorSeed, planFontFamilyRemoval, planSwissMigration, previewFontWeight, readDesignConfig, relativeLuminance, resolveDesignChoices, resolveTokenReferences, resolveTokenValues, revertAvailable, rgbToOklab, sameDesignChoices, specTokenNames, springToLinear, stackNamesFamily, styleKeyToKebab, switchElementStyle, syncNodeDesignClasses, toHexColor, tokenReferences, tokensToDarkVarMap, tokensToVarMap, unknownTokenReferences, userFontStack, validateFlavorPack, wcagContrastRatio };
+export type { AccentBackgrounds, AccentTokenName, ApplyElementStyleResult, DensityId, DesignChoices, DesignClassSource, DesignConfigEntry, DesignMode, DesignTokenGroup, DesignTokenLike, DesignTokenRow, DesignTokenTier, DesignTokenType, ElementStyle, ElementStyleTarget, ElementStyleTraitLike, FlavorPack, FlavorPackV2, FlavorRevertPlan, FlavorRevertSnapshot, FlavorSeedPlan, FlavorSpecToken, FlavorTokenDef, FontDescriptor, FontFamilyGroup, FontFamilyRemoval, FontFamilyToken, FontFormat, FontPair, FontRoleToken, FontStyle, FontWeight, FontWeightRange, FontsForTokensOptions, LinearSpring, MissingFontRole, MotionId, OkLab, OwnedTrait, OwnedTraitStatus, PalettePreset, ResolvedMode, Rgb, SchemeId, SeedBaseline, SeedExpectation, ShapeId, StoredDesign, StoredDesignTokenRow, SwissMigration, SwitchElementStyleResult, TokenCssBlocks, TokenCssOptions };