@weasel-js/theme 1.6.1 → 1.7.1

package/dist/engine.d.ts

@@ -1,17 +1,21 @@
 import { OklchDeg, oklchDegToHex } from '@weasel-js/paint';
-import { T as ThemeDefinition, L as Lookup, F as FlatTokens, R as RawToken, S as Selection, B as BakedTheme, A as AxisDefs, a as Theme } from './definition-DLdTdFWs.js';
-export { C as CategoricalRampDef, b as ContrastRule, c as LightnessRampDef, d as LiteralRule, N as NumberParam, O as OffsetRule, P as PinObject, e as PinValue, f as RampDef, g as RefRule, h as ScaleDef, i as SemanticRule, j as StepRule, k as bake, l as bakeChain, m as mergeChain } from './definition-DLdTdFWs.js';
+import { T as ThemeDefinition, L as Lookup, F as FlatTokens, R as RawToken, S as Selection, B as BakedTheme, A as AxisDefs, a as Theme } from './definition-ChUj0lSz.js';
+export { C as CategoricalRampDef, b as ContrastRule, c as LightnessRampDef, d as LiteralRule, N as NumberParam, O as OffsetRule, P as PinObject, e as PinValue, f as RampDef, g as RefRule, h as ScaleDef, i as SemanticRule, j as StepRule, k as bake, l as bakeChain, m as mergeChain } from './definition-ChUj0lSz.js';
 
 /** A color in OKLCH: lightness 0–1, chroma, hue in degrees. paint's own type,
  *  under the name this engine has always called it. */
 type Lch = OklchDeg;
+/** `#rrggbb` to 0–255 channels. */
 declare function hexToRgb(hex: string): [number, number, number];
+/** OKLCH (lightness 0–1, chroma, hue in degrees) to `#rrggbb`. Chroma past the gamut is clipped at constant lightness. */
 declare const toHex: typeof oklchDegToHex;
+/** `#rrggbb` to OKLCH, hue in 0–360. */
 declare const toLch: (hex: string) => Lch;
 /** The most chroma this hue can carry at this lightness, inside sRGB. */
 declare function chromaCap(L: number, H: number): number;
 /** WCAG relative luminance. */
 declare function luminance(hex: string): number;
+/** WCAG contrast ratio between two hex colors, 1–21, in either order. */
 declare function contrast(a: string, b: string): number;
 /** Shortest angular distance between two hues, in degrees. */
 declare function hueGap(a: number, b: number): number;
@@ -36,6 +40,7 @@ declare function toLab(hex: string): [number, number, number];
  * 0.25 is a real color, 0.5 is unmistakable.
  */
 declare const CHROMA_WEIGHT = 3;
+/** Perceptual distance between two hex colors: OKLab with chroma weighted by {@link CHROMA_WEIGHT}. */
 declare function deltaE(a: string, b: string): number;
 /** The most chroma this hue can carry at this lightness, as a hex. */
 declare function vividAt(L: number, H: number): string;
@@ -98,13 +103,17 @@ interface Constraints {
     readonly anchors: readonly Anchor[];
     readonly order: 'hue' | 'farthest';
 }
+/** One color of a generated {@link Palette}. */
 interface Swatch {
     readonly name: string;
     readonly hex: string;
     readonly lch: Lch;
+    /** Came from one of the constraints' anchors. */
     readonly anchored: boolean;
+    /** WCAG contrast against the constraints' `surface`. */
     readonly contrast: number;
 }
+/** Measurements of a generated palette as a whole: the minimums are over every swatch, or every pair. */
 interface Stats {
     readonly meanChroma: number;
     readonly chromaSpread: number;
@@ -116,6 +125,7 @@ interface Stats {
     readonly minSurfaceDistance: number;
     readonly minDistance: number;
 }
+/** What {@link generate} returns. */
 interface Palette {
     readonly swatches: readonly Swatch[];
     readonly stats: Stats;
@@ -123,6 +133,7 @@ interface Palette {
      *  best unconstrained attempt, so the lab still has something to draw. */
     readonly feasible: boolean;
 }
+/** A plain color name for a hue in degrees: `red`, `teal`, `violet`. */
 declare function hueName(H: number): string;
 /**
  * Search hue positions that maximize mean chroma subject to the gates.
@@ -133,28 +144,36 @@ declare function hueName(H: number): string;
  */
 /** The share-of-even floor, in degrees, for a set of this size. */
 declare function floorDegrees(c: Pick<Constraints, 'hueFloor' | 'count'>): number;
+/**
+ * A categorical palette of `count` swatches, anchors included, satisfying the gates. When no hue arrangement
+ * satisfies them the result is still a full palette, with `feasible` false.
+ */
 declare function generate(c: Constraints): Palette;
 /** What the lab opens with: the set this palette work landed on. */
 declare const DEFAULT_CONSTRAINTS: Constraints;
+/** The color an anchor will actually contribute, for a swatch beside its controls. */
+declare function toHexPreview(a: Pick<Anchor, 'hue' | 'lightness' | 'chroma'>): string;
 /**
  * An anchor taken from an existing color — a brand hex, or a color lifted from
  * somewhere else in the theme. Lightness comes along with the hue, which is the
  * point: the reason to pin a color is usually that the lightness law would not
- * have chosen its lightness.
+ * have chosen its lightness. `name` defaults to the hue's {@link hueName}.
  */
-/** The color an anchor will actually contribute, for a swatch beside its controls. */
-declare function toHexPreview(a: Pick<Anchor, 'hue' | 'lightness' | 'chroma'>): string;
 declare function anchorFromHex(hex: string, name?: string): Anchor;
 
+/** The axes one token's value can change with. */
 interface AxisDependency {
     /** Axes this token's own entry varies on. */
     readonly own: readonly string[];
     /** `own` plus everything reachable through references and rule inputs. */
     readonly all: readonly string[];
 }
+/** Every token of the definition, `extends` chain included, mapped to the axes it depends on, in axis declaration order. */
 declare function axisDependencies(definition: ThemeDefinition, lookup?: Lookup): Record<string, AxisDependency>;
 
+/** The definition layer that produced a token. */
 type Layer = 'ramps' | 'scales' | 'semantics' | 'components' | 'pins';
+/** Where one derived token came from. */
 interface Provenance {
     readonly layer: Layer;
     /** `lightness`, `categorical`, `linear`, `geometric`, `step`, `offset`, `contrast`, `ref`, `value`. */
@@ -164,6 +183,7 @@ interface Provenance {
     /** What the rule alone produced, when `pinned`. */
     readonly generated?: RawToken;
 }
+/** A problem `derive` found. Every one is reported, never thrown; the tokens still come back without what failed. */
 type Issue = {
     readonly kind: 'missing-axis-value';
     readonly path: string;
@@ -194,6 +214,7 @@ type Issue = {
     readonly path: string;
     readonly message: string;
 };
+/** What `derive` produces for one selection. */
 interface DeriveResult {
     /** In layer order, then definition order within a layer. */
     readonly tokens: FlatTokens;
@@ -204,6 +225,7 @@ interface DeriveResult {
 /** Derive every token of `definition` for one selection. Unmet rules are reported in `issues`; cycles and dangling references throw. */
 declare function derive(definition: ThemeDefinition, selection?: Selection, lookup?: Lookup): DeriveResult;
 
+/** A lightness ramp with every `by` and seed already settled. See {@link lightnessRamp}. */
 interface LightnessParams {
     readonly steps: readonly string[];
     readonly lightness: readonly [number, number];
@@ -224,19 +246,29 @@ interface LightnessParams {
  * consecutive anchors, hue along the shorter arc; steps before the first anchor or after the last take that anchor's.
  */
 declare function lightnessRamp(p: LightnessParams): Record<string, string>;
+/**
+ * Step name → hex from the palette generator, one swatch per step in step order. `feasible` is false when no palette
+ * met the gates; the colors are then its best unconstrained attempt.
+ */
 declare function categoricalRamp(steps: readonly string[], gates: Partial<Constraints>, anchors: readonly Anchor[]): {
     colors: Record<string, string>;
     feasible: boolean;
 };
 
+/** A scale's base and exactly one of `step`, `ratio` or `factors`. */
 interface ScaleParams {
     readonly base: number;
     readonly step?: number;
     readonly ratio?: number;
     readonly factors?: readonly number[];
 }
+/**
+ * Step name → `<n>px`, rounded to whole pixels. Throws unless exactly one rule is given, or when `factors` has a
+ * length other than `steps`'.
+ */
 declare function scale(steps: readonly string[], p: ScaleParams): Record<string, string>;
 
+/** One theme to write as CSS: its baked tokens and the axes each token depends on. */
 interface EmitInput {
     readonly baked: BakedTheme;
     readonly deps: Readonly<Record<string, AxisDependency>>;
@@ -245,6 +277,10 @@ interface EmitInput {
 }
 /** A reference becomes `var()` (or `color-mix()` with an alpha); a literal is resolved. */
 declare function cssValue(name: string, token: RawToken): string;
+/**
+ * The `tokens.css` text for a set of themes. Each non-default theme is written as its difference from the default,
+ * scoped to `[data-wzl-theme]`. Throws unless exactly one theme is the default.
+ */
 declare function emitCss(themes: readonly EmitInput[]): string;
 
 /** The `$extensions` key on a DTCG export's root that carries every axis besides mode. */
@@ -272,6 +308,7 @@ interface DtcgAxesExtension {
 type Group = Record<string, unknown> & {
     $type: string;
 };
+/** A DTCG document as {@link toDTCG} writes it. */
 interface DtcgExport {
     readonly name: string;
     readonly defaultMode?: string;
@@ -295,17 +332,21 @@ interface DtcgExport {
  */
 declare function toDTCG(theme: Theme): DtcgExport;
 
+/** The `manifest.ts` source: `TOKEN_MANIFEST` for this theme at its default selection, then every override hook. */
 declare function emitManifest({ baked }: EmitInput): string;
 
+/** One theme to write into `themes.ts`: its definition and what it bakes to. */
 interface ThemesInput {
     readonly definition: ThemeDefinition;
     readonly baked: BakedTheme;
 }
+/** The `themes.ts` source: every theme's resolved tokens at every selection, plus the definitions and baked themes. */
 declare function emitThemes(themes: readonly ThemesInput[]): string;
 
 /** Every step name a ramp or scale entry declares, across every `by` branch of the entry and of its `steps`, first seen first. */
 declare function declaredSteps(entry: unknown): string[];
 
+/** The files {@link generateTokens} produces, or every derive issue that stopped it. */
 type GeneratedTokens = {
     readonly ok: true;
     readonly files: {
@@ -329,10 +370,15 @@ interface StoredTheme {
     readonly emits: boolean;
     readonly definition: ThemeDefinition;
 }
+/** A derive issue and the selection it occurred at. */
 interface IssueReport {
     readonly selection: Selection;
     readonly issue: Issue;
 }
+/**
+ * The outcome of a save. `conflict` means the file changed since `baseHash`, and carries its current hash (null when
+ * it does not exist); `invalid` means the definition was refused and nothing was written.
+ */
 type PutResult = {
     readonly status: 'saved';
     readonly hash: string;
@@ -349,6 +395,7 @@ type PutResult = {
 };
 /** Record order is emission order, so keys are never sorted. */
 declare const serializeDefinition: (definition: ThemeDefinition) => string;
+/** Reads and writes theme definition files. `put` sends the hash it last read, or null to create a new file. */
 interface ThemeApi {
     list(): Promise<StoredTheme[]>;
     get(name: string): Promise<StoredTheme>;

package/dist/engine.js

@@ -1,6 +1,6 @@
-import { overrideKey, AXES_EXT, ALPHA_EXT } from './chunk-EINHFDWI.js';
-import { mergeAxes, toLch, toHex, generate, DEFAULT_CONSTRAINTS, fullSelection, pick, enumerateSelections, resolveTokens, pickAll, themeAxes, selectionKey, isByAxis, contrast } from './chunk-C3S4A65R.js';
-export { CHROMA_WEIGHT, DEFAULT_CONSTRAINTS, anchorFromHex, chromaCap, contrast, deltaE, floorDegrees, generate, hexToRgb, hueGap, hueName, luminance, toHex, toHexPreview, toLab, toLch, vividAt } from './chunk-C3S4A65R.js';
+import { overrideKey, AXES_EXT, ALPHA_EXT } from './chunk-Z675UQ26.js';
+import { mergeAxes, toLch, toHex, generate, DEFAULT_CONSTRAINTS, fullSelection, pick, enumerateSelections, resolveTokens, pickAll, themeAxes, selectionKey, isByAxis, contrast } from './chunk-AN5JVL2S.js';
+export { CHROMA_WEIGHT, DEFAULT_CONSTRAINTS, anchorFromHex, chromaCap, contrast, deltaE, floorDegrees, generate, hexToRgb, hueGap, hueName, luminance, toHex, toHexPreview, toLab, toLch, vividAt } from './chunk-AN5JVL2S.js';
 
 // src/engine/steps.ts
 var stepList = (x) => Array.isArray(x) ? [...new Set(x.filter((s) => typeof s === "string"))] : [];
@@ -1249,6 +1249,12 @@ function toDTCG(theme) {
 
 // src/hooks.ts
 var TOKEN_HOOKS = [
+  {
+    name: "detail-figure-min-width",
+    type: "dimension",
+    value: "8ch",
+    description: 'Least width of a value cell in a `values="figures"` DetailList.'
+  },
   {
     name: "disclosure-gap",
     type: "dimension",
@@ -1271,7 +1277,7 @@ var TOKEN_HOOKS = [
     name: "input-surface",
     type: "color",
     value: "var(--wzl-surface-sunken)",
-    description: "Surface a text Input\u2019s frame sits on. Set it on any container whose own background is the default \u2014 a sunken rail or panel \u2014 where an unset field is the same color as what is behind it."
+    description: "Surface a field\u2019s frame sits on \u2014 Input, NumberField, ComboBox, Select, MenuButton, ListEditor and the property rows. Set it on any container whose own background is the default \u2014 a sunken rail or panel \u2014 where an unset field is the same color as what is behind it."
   },
   {
     name: "number-field-width",