@weasel-js/theme 1.5.0 → 1.5.2

package/dist/engine.d.ts

@@ -0,0 +1,293 @@
+import { OklchDeg, oklchDegToHex } from '@weasel-js/paint';
+import { f as ThemeDefinition, L as Lookup, F as FlatTokens, R as RawToken, S as Selection, B as BakedTheme, T as Theme } from './theme-DAZcQi_L.js';
+export { C as CategoricalRampDef, l as ContrastRule, m as LightnessRampDef, n as LiteralRule, N as NumberParam, O as OffsetRule, P as PinObject, e as PinValue, o as RampDef, p as RefRule, q as ScaleDef, r as SemanticRule, t as StepRule, u as bake, v as bakeChain, x as mergeChain } from './theme-DAZcQi_L.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;
+declare function hexToRgb(hex: string): [number, number, number];
+declare const toHex: typeof oklchDegToHex;
+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;
+declare function contrast(a: string, b: string): number;
+/** Shortest angular distance between two hues, in degrees. */
+declare function hueGap(a: number, b: number): number;
+/** OKLab coordinates, for distance work. */
+declare function toLab(hex: string): [number, number, number];
+/**
+ * How far apart two colors look, with chroma weighted up.
+ *
+ * Two things this is not. It is not WCAG contrast, which reads lightness only
+ * and so scores a vivid yellow on white at 1.2:1 and calls it illegible when
+ * what separates them is chroma. And it is not plain euclidean OKLab distance:
+ * OKLab's chroma range is small beside its lightness range, so an unweighted
+ * distance is almost all lightness, and it ranks a mid-gray as further from
+ * white than a pale blue is. Measured against CIELAB dE on the same colors,
+ * unweighted OKLab put `#c1c1c1` at 0.160 and `#abd9ff` at 0.126 while CIELAB
+ * put them at 21.9 and 28.5 — opposite orders.
+ *
+ * `CHROMA_WEIGHT` restores CIELAB's ordering. It is a weight, not a unit
+ * conversion, so these numbers do not transfer to or from CIELAB dE.
+ *
+ * Rough calibration in the weighted space: 0.17 is a pale wash against paper,
+ * 0.25 is a real color, 0.5 is unmistakable.
+ */
+declare const CHROMA_WEIGHT = 3;
+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;
+
+/**
+ * A hue pinned into the palette with its own lightness.
+ *
+ * Anchors exist because the lightness law excludes some colors entirely. Yellow
+ * is the case that forces it: its chroma peaks at L 0.95 — higher than any other
+ * hue — so a law that picks lightness for legibility silently yields gold, then
+ * olive, and never reports that yellow was dropped.
+ */
+interface Anchor {
+    readonly name: string;
+    readonly hue: number;
+    readonly lightness: number;
+    /**
+     * Absolute chroma. Omitted means "as much as the gamut allows here", which is
+     * what a bright color wants. A muted color has to say so: hue and lightness
+     * alone can only describe vivid colors, so a tan asked for at max chroma
+     * comes back as an amber.
+     */
+    readonly chroma?: number;
+}
+/** Every constraint the generator honors. A zero disables the ones that gate. */
+interface Constraints {
+    readonly count: number;
+    /**
+     * Minimum hue separation, as a share of the even `360 / count` spacing an
+     * ideal set would have. 0 disables the check.
+     *
+     * A share rather than degrees, because absolute degrees mean different things
+     * at different cardinalities: 30 degrees is generous for 8 colors and
+     * impossible for 16, so a floor in degrees silently becomes unsatisfiable as
+     * the set grows.
+     */
+    readonly hueFloor: number;
+    /** Minimum WCAG contrast every swatch must clear against `surface`. 0 disables. */
+    readonly minContrast: number;
+    /**
+     * Minimum perceptual distance from `surface`. 0 disables.
+     *
+     * The gate WCAG contrast cannot express. Contrast reads only lightness, so it
+     * scores a vivid yellow on white at 1.2:1 and calls it illegible, when what
+     * separates them is chroma. Gate on this instead of on lightness and a yellow
+     * can be a yellow; gate on contrast alone and the search quietly returns gold.
+     */
+    readonly minSurfaceDistance: number;
+    /** Minimum perceptual distance between any two swatches. 0 disables. */
+    readonly minDistance: number;
+    readonly surface: string;
+    /** Where `lightnessPull` drags each hue, away from its own chroma peak. */
+    readonly lightnessTarget: number;
+    /** 0 leaves every hue at its chroma peak; 1 puts them all at the target. */
+    readonly lightnessPull: number;
+    /** Fraction of the in-gamut chroma ceiling to take. */
+    readonly chromaFraction: number;
+    /** 0 leaves chroma alone; 1 pulls every hue to the set mean. */
+    readonly equalize: number;
+    readonly anchors: readonly Anchor[];
+    readonly order: 'hue' | 'farthest';
+}
+interface Swatch {
+    readonly name: string;
+    readonly hex: string;
+    readonly lch: Lch;
+    readonly anchored: boolean;
+    readonly contrast: number;
+}
+interface Stats {
+    readonly meanChroma: number;
+    readonly chromaSpread: number;
+    readonly lightnessSpread: number;
+    readonly minHueGap: number;
+    /** The realized floor as a share of even spacing, comparable across sizes. */
+    readonly hueFloorShare: number;
+    readonly minContrast: number;
+    readonly minSurfaceDistance: number;
+    readonly minDistance: number;
+}
+interface Palette {
+    readonly swatches: readonly Swatch[];
+    readonly stats: Stats;
+    /** False when no hue arrangement satisfied the gates; `swatches` is then the
+     *  best unconstrained attempt, so the lab still has something to draw. */
+    readonly feasible: boolean;
+}
+declare function hueName(H: number): string;
+/**
+ * Search hue positions that maximize mean chroma subject to the gates.
+ *
+ * Seeds matter: a uniform 360/n ring can never open a `2 * minHueGap` hole
+ * around a pinned hue, so with anchors the seeds spread across the arc the
+ * anchors leave free instead.
+ */
+/** The share-of-even floor, in degrees, for a set of this size. */
+declare function floorDegrees(c: Pick<Constraints, 'hueFloor' | 'count'>): number;
+declare function generate(c: Constraints): Palette;
+/** What the lab opens with: the set this palette work landed on. */
+declare const DEFAULT_CONSTRAINTS: Constraints;
+/**
+ * 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.
+ */
+/** 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;
+
+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[];
+}
+declare function axisDependencies(definition: ThemeDefinition, lookup?: Lookup): Record<string, AxisDependency>;
+
+type Layer = 'ramps' | 'scales' | 'semantics' | 'components' | 'pins';
+interface Provenance {
+    readonly layer: Layer;
+    /** `lightness`, `categorical`, `linear`, `geometric`, `step`, `offset`, `contrast`, `ref`, `value`. */
+    readonly rule: string;
+    /** A pin replaced what the rule produced. Only these count as overridden. */
+    readonly pinned: boolean;
+    /** What the rule alone produced, when `pinned`. */
+    readonly generated?: RawToken;
+}
+type Issue = {
+    readonly kind: 'missing-axis-value';
+    readonly path: string;
+    readonly axis: string;
+    readonly value: string;
+} | {
+    readonly kind: 'untyped-pin';
+    readonly token: string;
+} | {
+    readonly kind: 'infeasible-ramp';
+    readonly ramp: string;
+} | {
+    readonly kind: 'contrast-unmet';
+    readonly token: string;
+    readonly min: number;
+    readonly against: readonly string[];
+    /** The step used anyway: the one with the best worst-case ratio across the whole ramp. */
+    readonly picked: string;
+    readonly ratio: number;
+} | {
+    readonly kind: 'check-failed';
+    readonly token: string;
+    readonly against: string;
+    readonly min: number;
+    readonly ratio: number;
+} | {
+    readonly kind: 'invalid';
+    readonly path: string;
+    readonly message: string;
+};
+interface DeriveResult {
+    /** In layer order, then definition order within a layer. */
+    readonly tokens: FlatTokens;
+    readonly provenance: Readonly<Record<string, Provenance>>;
+    readonly issues: readonly Issue[];
+}
+
+/** 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;
+
+interface LightnessParams {
+    readonly steps: readonly string[];
+    readonly lightness: readonly [number, number];
+    readonly curve: number;
+    readonly hue: number;
+    readonly peak: number;
+    /** Lifts the first step's chroma off zero, as `darkBias` lifts the last. Default 0. */
+    readonly lightBias?: number;
+    readonly darkBias: number;
+    readonly anchor?: Readonly<Record<string, string>>;
+}
+/**
+ * Step name → hex. Lightness walks from `lightness[0]` to `lightness[1]`, `curve` blending an even walk toward a
+ * smoothstep; chroma is `peak` scaled by the envelope `sin(πt) + lightBias·(1−t) + darkBias·t` normalized to a maximum of 1.
+ */
+declare function lightnessRamp(p: LightnessParams): Record<string, string>;
+declare function categoricalRamp(steps: readonly string[], gates: Partial<Constraints>, anchors: readonly Anchor[]): {
+    colors: Record<string, string>;
+    feasible: boolean;
+};
+
+interface ScaleParams {
+    readonly base: number;
+    readonly step?: number;
+    readonly ratio?: number;
+    readonly factors?: readonly number[];
+}
+declare function scale(steps: readonly string[], p: ScaleParams): Record<string, string>;
+
+interface EmitInput {
+    readonly baked: BakedTheme;
+    readonly deps: Readonly<Record<string, AxisDependency>>;
+    /** The default theme alone gets `:root` and the unscoped selectors. */
+    readonly isDefault: boolean;
+}
+/** A reference becomes `var()` (or `color-mix()` with an alpha); a literal is resolved. */
+declare function cssValue(name: string, token: RawToken): string;
+declare function emitCss(themes: readonly EmitInput[]): string;
+
+type Group = Record<string, unknown> & {
+    $type: string;
+};
+interface DtcgExport {
+    readonly name: string;
+    readonly defaultMode?: string;
+    readonly primitives: Record<string, Group>;
+    readonly modes: Record<string, Record<string, Group>>;
+}
+/**
+ * A theme's own tokens as a DTCG document `loadDTCG` reads back. `extends` is
+ * not carried; pass it to `loadDTCG`. Every mode the chain declares is written,
+ * so a token that leaves one out still falls through to the parent on the way back.
+ *
+ * DTCG has one variant dimension and no standard way to name a second, so mode
+ * is the only axis exported: a token varying by any other axis is written at
+ * that axis's default value and its other branches are dropped. Round-tripping
+ * a theme through DTCG therefore flattens it to the default selection of every
+ * non-mode axis.
+ */
+declare function toDTCG(theme: Theme): DtcgExport;
+
+declare function emitManifest({ baked }: EmitInput): string;
+
+interface ThemesInput {
+    readonly definition: ThemeDefinition;
+    readonly baked: BakedTheme;
+}
+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[];
+
+type GeneratedTokens = {
+    readonly ok: true;
+    readonly files: {
+        readonly 'tokens.css': string;
+        readonly 'themes.ts': string;
+        readonly 'manifest.ts': string;
+    };
+} | {
+    readonly ok: false;
+    readonly problems: readonly string[];
+};
+/** Every generated token file for a set of definitions, the one that extends nothing being the default. Any derive issue refuses the whole set. */
+declare function generateTokens(definitions: readonly ThemeDefinition[]): GeneratedTokens;
+
+export { type Anchor, type AxisDependency, BakedTheme, CHROMA_WEIGHT, type Constraints, DEFAULT_CONSTRAINTS, type DeriveResult, type DtcgExport, type EmitInput, type GeneratedTokens, type Issue, type Layer, type Lch, type LightnessParams, Lookup, type Palette, type Provenance, type ScaleParams, type Stats, type Swatch, ThemeDefinition, type ThemesInput, anchorFromHex, axisDependencies, categoricalRamp, chromaCap, contrast, cssValue, declaredSteps, deltaE, derive, emitCss, emitManifest, emitThemes, floorDegrees, generate, generateTokens, hexToRgb, hueGap, hueName, lightnessRamp, luminance, scale, toDTCG, toHex, toHexPreview, toLab, toLch, vividAt };