@loworbitstudio/visor-theme-engine 0.18.0 → 0.20.0

package/dist/index.d.ts

@@ -1,5 +1,5 @@
-import { F as FontResolveOptions, a as FontResolution, V as VisorTypography, b as FontDisplayStrategy, T as ThemeFontResult, G as GoogleFontEntry, c as VisorBrand, B as BrandSlot, d as BrandSource, e as BrandResolution, C as ColorScheme, f as ThemeBrandResult, g as BrandStrategy, h as BrandStrategyContext, i as BrandStrategyIssue, j as BrandStrategyValidationResult, S as SerializedBrandStrategy, R as ResolvedThemeConfig, k as GeneratedPrimitives, l as ThemeOutput, m as ThemeData, n as VisorThemeConfig, o as FullShadeScale, p as ColorRole, q as SelectiveShadeScale, r as RGB, P as ParsedColor, O as OKLCH, s as SemanticTokens, t as ShadeStep } from './types-Cvm7vFwe.js';
-export { u as BRAND_VARIANTS, v as BRAND_VISIBILITIES, w as BrandAccessibility, x as BrandArchetype, y as BrandBoilerplate, z as BrandColorPairing, A as BrandColorUsage, D as BrandContrastTarget, E as BrandGoverns, H as BrandLexiconEntry, I as BrandMessaging, J as BrandPersonalityTrait, K as BrandPillar, L as BrandPositioning, M as BrandStrategyIssueSeverity, N as BrandToneEntry, Q as BrandVariant, U as BrandVisibility, W as BrandVoice, X as BrandVoiceTrait, Y as ColorFormat, Z as DEFAULT_BRAND_STRATEGY_SURFACES, _ as DEFAULT_BRAND_STRATEGY_TONE_STATES, $ as FontSource, a0 as GOVERNS_WILDCARD, a1 as RGBA, a2 as SemanticTokenValue } from './types-Cvm7vFwe.js';
+import { F as FontResolveOptions, a as FontResolution, V as VisorTypography, b as FontDisplayStrategy, T as ThemeFontResult, G as GoogleFontEntry, c as VisorBrand, B as BrandSlot, d as BrandSource, e as BrandResolution, C as ColorScheme, f as ThemeBrandResult, g as BrandStrategy, h as BrandStrategyContext, i as BrandStrategyIssue, j as BrandStrategyValidationResult, S as SerializedBrandStrategy, R as ResolvedThemeConfig, k as GeneratedPrimitives, l as ThemeOutput, m as ThemeData, n as VisorThemeConfig, o as FullShadeScale, p as ColorRole, q as SelectiveShadeScale, r as RGB, P as ParsedColor, O as OKLCH, s as SemanticTokens, t as ShadeStep } from './types-BG-YT4JW.js';
+export { u as BRAND_VARIANTS, v as BRAND_VISIBILITIES, w as BrandAccessibility, x as BrandArchetype, y as BrandBoilerplate, z as BrandColorPairing, A as BrandColorUsage, D as BrandContrastTarget, E as BrandGoverns, H as BrandLexiconEntry, I as BrandMessaging, J as BrandPersonalityTrait, K as BrandPillar, L as BrandPositioning, M as BrandStrategyIssueSeverity, N as BrandToneEntry, Q as BrandVariant, U as BrandVisibility, W as BrandVoice, X as BrandVoiceTrait, Y as COMPONENT_TOKEN_FAMILIES, Z as COMPONENT_TOKEN_FAMILY_BY_NAME, _ as ColorFormat, $ as ComponentTokenBinding, a0 as ComponentTokenBindings, a1 as ComponentTokenConsumer, a2 as ComponentTokenFamily, a3 as ComponentTokenSpec, a4 as DEFAULT_BRAND_STRATEGY_SURFACES, a5 as DEFAULT_BRAND_STRATEGY_TONE_STATES, a6 as FontSource, a7 as GOVERNS_WILDCARD, a8 as RGBA, a9 as ResolvedComponentTokens, aa as SemanticTokenValue, ab as allComponentTokenNames, ac as componentTokenName, ad as hasComponentBindings, ae as resolveComponentBindings, af as validateComponentBindings } from './types-BG-YT4JW.js';
 
 /**
  * Font resolver — maps font family names to loadable font resources.
@@ -585,7 +585,7 @@ var properties = {
 			},
 			scale: {
 				type: "number",
-				description: "Type scale multiplier applied to the font-size ramp. Default: 1."
+				description: "Type scale multiplier applied to the font-size ramp: every --font-size-* step is multiplied by it, and the page inherits the scaled --font-size-base. Default: 1. CSS adapters only — the Flutter adapter emits Material 3 slot sizes verbatim and ignores this field."
 			},
 			"text-on-light": {
 				type: "string",
@@ -1025,6 +1025,125 @@ var properties = {
 			}
 		}
 	},
+	components: {
+		type: "object",
+		description: "Component-scoped theme bindings for the admin-UI families (VI-625). Keyed by family, then by token key; the value is a string (both modes) or { light, dark }. Every token falls back to its Tier-1 expression, so omitting this block renders exactly as before. Key names are validated against the contract in component-tokens.ts.",
+		additionalProperties: false,
+		properties: {
+			table: {
+				type: "object",
+				description: "Table head, row and cell treatment. The retro measured the same header cell rendered four ways across one admin app; binding this family pins it once. Keys: font-size, text-color, head-height, head-padding-x, head-font-family, head-font-size, head-font-weight, head-letter-spacing, head-text-transform, head-color, head-bg, row-border, row-hover-bg, row-selected-bg, cell-padding, cell-font-size, cell-color, cell-bg, cell-border-top, footer-bg, caption-color.",
+				additionalProperties: {
+					$ref: "#/$defs/componentTokenBinding"
+				}
+			},
+			"data-table": {
+				type: "object",
+				description: "The admin-ui Tier-2 data-table surface stack (D3). Shared between the Table primitive and the DataTable shell so a list page and its table read as one surface. Keys: header-bg, row-bg, container-radius, container-shadow, row-py, cell-px, header-font-size.",
+				additionalProperties: {
+					$ref: "#/$defs/componentTokenBinding"
+				}
+			},
+			chip: {
+				type: "object",
+				description: "Chip / filter-pill treatment. The retro found the same mono status chip at 8.5 / 9 / 9.5 / 10 / 11px with tracking .03–.14em across nine implementations; this family is the single dial. Keys: radius, border, bg, text-color, font-family, font-weight, letter-spacing, text-transform, sm-height, sm-padding-x, sm-font-size, md-height, md-padding-x, md-font-size, lg-height, lg-padding-x, lg-font-size, selected-bg, selected-border-color, selected-text-color.",
+				additionalProperties: {
+					$ref: "#/$defs/componentTokenBinding"
+				}
+			},
+			badge: {
+				type: "object",
+				description: "Badge treatment — the D3 Tier-2 `--badge-text-transform` / `-letter-spacing` / `-font-size` / `-font-weight` set, promoted from the admin-ui audit to a bindable contract. Keys: radius, border, font-family, font-weight, text-transform, letter-spacing, font-size, md-padding, md-gap.",
+				additionalProperties: {
+					$ref: "#/$defs/componentTokenBinding"
+				}
+			},
+			"status-badge": {
+				type: "object",
+				description: "Status-badge indicator dot and the mono readout label. Chrome is inherited from the Badge family. Keys: dot-size, dot-radius, mono-font-family, mono-font-size, mono-letter-spacing.",
+				additionalProperties: {
+					$ref: "#/$defs/componentTokenBinding"
+				}
+			},
+			"filter-bar": {
+				type: "object",
+				description: "The operator's named case: \"the filter bar above the table in many admin pages was pretty different from one to the next; that should be streamlined.\" Keys: bg, border, radius, padding, gap, text-color, dense-padding, dense-gap, control-radius, results-font-size, results-color.",
+				additionalProperties: {
+					$ref: "#/$defs/componentTokenBinding"
+				}
+			},
+			"page-header": {
+				type: "object",
+				description: "Page-header lockup. The retro found the page title rendered five ways across one app. Keys: gap, text-color, leading-gap, eyebrow-font-size, eyebrow-font-weight, eyebrow-letter-spacing, eyebrow-text-transform, eyebrow-color, title-family, title-size, title-leading, title-font-size, title-font-weight, title-letter-spacing, title-color, description-font-size, description-color, actions-gap.",
+				additionalProperties: {
+					$ref: "#/$defs/componentTokenBinding"
+				}
+			},
+			"empty-state": {
+				type: "object",
+				description: "Empty-state placard — surface, icon chip and copy scale. Keys: radius, text-color, gap, padding, bg, border, icon-size, icon-radius, icon-bg, icon-color, heading-font-family, heading-font-size, heading-font-weight, heading-color, description-font-size, description-color, actions-gap.",
+				additionalProperties: {
+					$ref: "#/$defs/componentTokenBinding"
+				}
+			},
+			banner: {
+				type: "object",
+				description: "Full-width notice bar. The retro found six separate banner systems across ~180 instances in one app; binding this family collapses them to one. Keys: padding, gap, font-size, radius, border-width, shadow, title-font-weight, description-font-size, info-bg, info-text-color, info-border-color, warning-bg, warning-text-color, warning-border-color, error-bg, error-text-color, error-border-color, success-bg, success-text-color, success-border-color.",
+				additionalProperties: {
+					$ref: "#/$defs/componentTokenBinding"
+				}
+			},
+			sidebar: {
+				type: "object",
+				description: "Sidebar chrome and nav-item treatment. The palette roles (`bg`, `text`, `border`, `accent-*`) already ship defaults from visor-core's `visor-semantic` layer and are read bare; the structural roles below are new in VI-625. Keys: bg, text, text-muted, border, accent-bg, accent-text, header-padding, footer-padding, content-padding, menu-gap, group-label-height, group-label-font-size, group-label-font-weight, group-label-letter-spacing, group-label-text-transform, item-radius, item-gap, item-font-size, item-font-weight, item-letter-spacing, item-text-transform, item-height, item-padding, item-active-font-weight.",
+				additionalProperties: {
+					$ref: "#/$defs/componentTokenBinding"
+				}
+			},
+			tabs: {
+				type: "object",
+				description: "Tab rail and trigger treatment, for both the segmented (`default`) and underlined (`line`) variants. Keys: list-radius, list-height, list-padding, list-color, list-bg, line-border-bottom, trigger-radius, trigger-padding, trigger-font-size, trigger-font-weight, trigger-letter-spacing, trigger-text-transform, trigger-color, trigger-active-bg, trigger-active-color, trigger-active-shadow, indicator-height, indicator-color.",
+				additionalProperties: {
+					$ref: "#/$defs/componentTokenBinding"
+				}
+			},
+			skeleton: {
+				type: "object",
+				description: "Loading-placeholder shimmer and the content-shape geometry the admin list/table/detail skeletons use. Keys: from, to, radius, duration, logo-width, logo-height, pill-width, pill-height, line-h1-height, line-heading-height, line-body-height, avatar-size, avatar-lg-size, badge-width, badge-height, row-gap, row-padding, row-border-bottom.",
+				additionalProperties: {
+					$ref: "#/$defs/componentTokenBinding"
+				}
+			},
+			spinner: {
+				type: "object",
+				description: "Inline loading ring — track, leading edge, per-size geometry and cycle length. Keys: track-color, edge-color, primary-edge-color, radius, duration, xs-size, xs-border-width, sm-size, sm-border-width, md-size, md-border-width.",
+				additionalProperties: {
+					$ref: "#/$defs/componentTokenBinding"
+				}
+			},
+			checkbox: {
+				type: "object",
+				description: "Control sizing — the D3 Tier-2 `--checkbox-size` / `-radius` / `-bg` / `-border` set, promoted from the admin-ui audit to a bindable contract. Keys: size, radius, bg, border, bg-checked, border-checked.",
+				additionalProperties: {
+					$ref: "#/$defs/componentTokenBinding"
+				}
+			},
+			surface: {
+				type: "object",
+				description: "The D3 Tier-2 surface-scale extremes. `elev` is the elevated control tier the chip family already reads; `screen` is the deepest chrome tier consumed by admin pattern shells (`design-prototypes/admin-ui/tokens.css`) rather than by a Visor component. Keys: elev, screen.",
+				additionalProperties: {
+					$ref: "#/$defs/componentTokenBinding"
+				}
+			},
+			"admin-ui": {
+				type: "object",
+				description: "Structural roles the admin-ui pattern owns. `marquee-family` is the display face for KPI hero figures and marquee page titles — the role the admin-ui portability audit named as the one piece of ENTR brand coupling a new theme must rebind. Keys: marquee-family.",
+				additionalProperties: {
+					$ref: "#/$defs/componentTokenBinding"
+				}
+			}
+		}
+	},
 	migrate: {
 		type: "object",
 		description: "Migration metadata consumed by `visor migrate` commands. Does not affect CSS generation or theme application.",
@@ -1041,6 +1160,26 @@ var properties = {
 	}
 };
 var $defs = {
+	componentTokenBinding: {
+		description: "A component-token binding: one string for both modes, or per-mode values.",
+		oneOf: [
+			{
+				type: "string"
+			},
+			{
+				type: "object",
+				additionalProperties: false,
+				properties: {
+					light: {
+						type: "string"
+					},
+					dark: {
+						type: "string"
+					}
+				}
+			}
+		]
+	},
 	cssColor: {
 		type: "string",
 		description: "CSS color value. Accepts hex (#RGB, #RRGGBB, #RRGGBBAA), rgb()/rgba(), hsl()/hsla(), or oklch() formats.",
@@ -1783,6 +1922,135 @@ declare function generateDarkCss(tokens: SemanticTokens, options?: {
 }): string;
 declare function generateFullBundleCss(primitives: GeneratedPrimitives, tokens: SemanticTokens, config: ResolvedThemeConfig): string;
 
+/**
+ * Font-weight resolution (VI-639).
+ *
+ * The named weight ramp used to be three literals and one role leak:
+ *
+ * ```
+ * --font-weight-normal:   <body.weight>
+ * --font-weight-medium:   500                 // literal
+ * --font-weight-semibold: <heading.weight>    // a different concept entirely
+ * --font-weight-bold:     700                 // literal
+ * ```
+ *
+ * `semibold` is not a heading. Pinning it there collapsed it onto `medium` on
+ * every theme whose heading weight is 500 (the Blacklight family), onto
+ * `normal` where it is 400 (knowmentum), and inverted the ramp where it is
+ * above `bold` (strata emitted `semibold: 800` over `bold: 700`). Meanwhile the
+ * literals ignored the `weights` array a theme actually loaded, so a theme
+ * declaring `[200, 400, 600, 900]` got tokens pointing at faces it never
+ * fetched — which the browser then silently substituted.
+ *
+ * Resolution here follows the CSS font-matching algorithm's weight-selection
+ * order (CSS Fonts 4 §5.2) rather than naive nearest-numeric. The browser is
+ * already performing exactly this substitution at render time, so an emitted
+ * token becomes the weight that was *already rendering* — which is what makes
+ * this change visually neutral everywhere except where the token was wrong.
+ */
+/** Canonical targets for the named ramp above `normal`. */
+declare const WEIGHT_RAMP_TARGETS: {
+    readonly medium: 500;
+    readonly semibold: 600;
+    readonly bold: 700;
+};
+/** The typography slots that can declare a family, weight and weights array. */
+declare const SLOTS: readonly ["heading", "display", "body", "mono"];
+type WeightedSlot = {
+    weight?: number;
+    weights?: number[];
+} | undefined;
+type SlottedTypography = Partial<Record<(typeof SLOTS)[number], WeightedSlot>>;
+/**
+ * The weights a theme actually loads: each slot's explicit `weights` array, or
+ * its single `weight` when it declares none — mirroring how the font pipeline
+ * resolves the set it fetches.
+ */
+declare function loadedWeights(typography: SlottedTypography): number[];
+/**
+ * Whether any slot declares an explicit `weights` array.
+ *
+ * Resolution is gated on this. A theme that declares one has told us what it
+ * loads, so we can hold every emitted token to that set. A theme that hasn't
+ * keeps the historical emission untouched — snapping against a set inferred
+ * from three `weight` fields would move tokens on a claim the theme never made
+ * (and says nothing at all about a system font stack, which has whatever the OS
+ * has). `validateFontWeights` warns about those instead.
+ */
+declare function declaresWeights(typography: SlottedTypography): boolean;
+/**
+ * Pick the weight a browser would actually use for `desired`, given the faces
+ * the theme loaded — CSS Fonts 4 §5.2 weight-matching order:
+ *
+ * - exact match wins;
+ * - desired 400–500: heavier faces up to 500 ascending, then lighter descending,
+ *   then heavier than 500 ascending;
+ * - desired below 400: lighter descending, then heavier ascending;
+ * - desired above 500: heavier ascending, then lighter descending.
+ *
+ * Returns `desired` unchanged when the theme loads nothing (nothing to match
+ * against, and the system font has its own ideas).
+ */
+declare function matchLoadedWeight(desired: number, loaded: readonly number[]): number;
+/** The four named ramp steps a theme emits, resolved against what it loaded. */
+interface ResolvedWeightRamp {
+    normal: number;
+    medium: number;
+    semibold: number;
+    bold: number;
+}
+/**
+ * Resolve the named ramp.
+ *
+ * `normal` tracks the theme's body weight rather than a hard 400 — it is the
+ * ramp's zero point, and Blacklight's `body.weight: 300` is a deliberate
+ * choice, not a rounding error. It is still coerced to a loaded face (strata
+ * declares `body.weight: 450` and loads `[400, 700, 900]`).
+ *
+ * `medium / semibold / bold` resolve the canonical 500 / 600 / 700 targets.
+ * Names can still share a value on a family that cannot separate them — two
+ * loaded faces cannot back four distinct names — but the result is now the
+ * truth about what renders rather than a number nothing will honour.
+ */
+declare function resolveWeightRamp(typography: SlottedTypography & {
+    body?: WeightedSlot;
+}): ResolvedWeightRamp;
+/**
+ * Resolve a role weight (`--weight-heading`, `--weight-body`,
+ * `--weight-display`) to a loaded face. Roles carry theme intent — what this
+ * theme's headings weigh — and are the channel components should read when they
+ * mean "the heading weight" rather than "a step above medium".
+ */
+declare function resolveRoleWeight(declared: number, typography: SlottedTypography): number;
+/**
+ * Emit the shared weight declarations: the named ramp, the role tokens, and the
+ * discrete ladder.
+ *
+ * The ladder (`--font-weight-300` … `--font-weight-800`, one per loaded face)
+ * is what makes the `weights` array authoritative instead of decorative. Before
+ * it, a theme could load five faces and reach four of them by name at best —
+ * Blacklight's 800 was unreachable from CSS, so BL-987 had to write a literal.
+ * It follows the `--text-N` / `--space-N` discrete-alias precedent from VI-451.
+ */
+declare function generateFontWeightDecls(typography: {
+    heading: {
+        weight: number;
+        weights?: number[];
+    };
+    display: {
+        weight: number;
+        weights?: number[];
+    };
+    body: {
+        weight: number;
+        weights?: number[];
+    };
+    mono: {
+        weight?: number;
+        weights?: number[];
+    };
+}): string[];
+
 /**
  * Theme Extraction Engine
  *
@@ -1858,4 +2126,4 @@ declare function cleanFontValue(val: string): string;
  */
 declare function extractFromCSS(files: CSSFile[], name?: string): ExtractionResult;
 
-export { type BrandPassthrough, BrandResolution, BrandSlot, BrandSource, BrandStrategy, BrandStrategyContext, BrandStrategyIssue, BrandStrategyValidationResult, type CSSFile, ColorRole, type Confidence, DEFAULT_VISOR_BRAND, type ExtractedToken, type ExtractionResult, FONT_WEIGHT_ALIASES, type FontCoverageError, type FontCoverageResult, FontDisplayStrategy, type FontFaceDeclaration, FontResolution, FontResolveOptions, FullShadeScale, GeneratedPrimitives, GoogleFontEntry, OKLCH, ParsedColor, RGB, ResolvedThemeConfig, SEMANTIC_MAP, SelectiveShadeScale, SemanticTokens, SerializedBrandStrategy, ShadeStep, TAILWIND_GRAY, ThemeBrandResult, ThemeData, ThemeFontResult, ThemeOutput, type ThemeValidationResult, VISOR_BRANDS_CDN, VISOR_DEFAULT_BRAND_PATH, VISOR_FONTS_CDN, type ValidateOptions, type ValidationIssue, type ValidationSeverity, VisorBrand, VisorThemeConfig, VisorTypography, applyOverrides, assignSemanticTokens, buildVisorBrandUrl, buildVisorFontUrl, checkBrandStrategyCoherence, checkBrandStrategyStructure, clampToSrgb, cleanFontValue, collectBrandPassthrough, compositeOverBackground, exportTheme, extractFromCSS, formatFontCoverageError, generateDarkCss, generateFullBundleCss, generateLightCss, generatePreloadLinks, generatePrimitives, generatePrimitivesCss, generateSemanticCss, generateShadeScale, generateStylesheetLinks, generateTheme, generateThemeData, generateThemeDataFromConfig, generateThemeFromConfig, getContrastRatio, getKnownTokenRefs, getLuminance, googleFontsCatalog, hasBrandPassthrough, hexToOklch, hexToRgb, isValidColor, isValidHex, isVisorThemeConfig, lookupFontWeightAlias, lookupGoogleFont, normalizeHex, oklchToHex, parseCSSDeclarations, parseColor, parseConfig, parseFontFaceDeclarations, parseHex, parseHsla, parseOklch, parseRgba, resolveBrandSlot, resolveBrandSource, resolveConfig, resolveFont, resolveThemeBrand, resolveThemeFonts, rgbToHex, serializeBrandStrategy, serializeColor, validate, validateBrandStrategy, validateConfig, validateFontCoverage, visorTheme_schema as visorThemeSchema };
+export { type BrandPassthrough, BrandResolution, BrandSlot, BrandSource, BrandStrategy, BrandStrategyContext, BrandStrategyIssue, BrandStrategyValidationResult, type CSSFile, ColorRole, type Confidence, DEFAULT_VISOR_BRAND, type ExtractedToken, type ExtractionResult, FONT_WEIGHT_ALIASES, type FontCoverageError, type FontCoverageResult, FontDisplayStrategy, type FontFaceDeclaration, FontResolution, FontResolveOptions, FullShadeScale, GeneratedPrimitives, GoogleFontEntry, OKLCH, ParsedColor, RGB, ResolvedThemeConfig, type ResolvedWeightRamp, SEMANTIC_MAP, SelectiveShadeScale, SemanticTokens, SerializedBrandStrategy, ShadeStep, TAILWIND_GRAY, ThemeBrandResult, ThemeData, ThemeFontResult, ThemeOutput, type ThemeValidationResult, VISOR_BRANDS_CDN, VISOR_DEFAULT_BRAND_PATH, VISOR_FONTS_CDN, type ValidateOptions, type ValidationIssue, type ValidationSeverity, VisorBrand, VisorThemeConfig, VisorTypography, WEIGHT_RAMP_TARGETS, applyOverrides, assignSemanticTokens, buildVisorBrandUrl, buildVisorFontUrl, checkBrandStrategyCoherence, checkBrandStrategyStructure, clampToSrgb, cleanFontValue, collectBrandPassthrough, compositeOverBackground, declaresWeights, exportTheme, extractFromCSS, formatFontCoverageError, generateDarkCss, generateFontWeightDecls, generateFullBundleCss, generateLightCss, generatePreloadLinks, generatePrimitives, generatePrimitivesCss, generateSemanticCss, generateShadeScale, generateStylesheetLinks, generateTheme, generateThemeData, generateThemeDataFromConfig, generateThemeFromConfig, getContrastRatio, getKnownTokenRefs, getLuminance, googleFontsCatalog, hasBrandPassthrough, hexToOklch, hexToRgb, isValidColor, isValidHex, isVisorThemeConfig, loadedWeights, lookupFontWeightAlias, lookupGoogleFont, matchLoadedWeight, normalizeHex, oklchToHex, parseCSSDeclarations, parseColor, parseConfig, parseFontFaceDeclarations, parseHex, parseHsla, parseOklch, parseRgba, resolveBrandSlot, resolveBrandSource, resolveConfig, resolveFont, resolveRoleWeight, resolveThemeBrand, resolveThemeFonts, resolveWeightRamp, rgbToHex, serializeBrandStrategy, serializeColor, validate, validateBrandStrategy, validateConfig, validateFontCoverage, visorTheme_schema as visorThemeSchema };