@weasel-js/theme 1.5.2 → 1.6.1

package/dist/engine.d.ts

@@ -1,6 +1,6 @@
 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';
+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';
 
 /** A color in OKLCH: lightness 0–1, chroma, hue in degrees. paint's own type,
  *  under the name this engine has always called it. */
@@ -218,6 +218,10 @@ interface LightnessParams {
 /**
  * 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.
+ *
+ * An anchored step emits its anchor exactly, and the anchor replaces `hue` and `peak`: its OKLCH hue becomes the hue and
+ * its chroma becomes the peak, unscaled by the envelope. With several anchors, both blend linearly by step between
+ * 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>;
 declare function categoricalRamp(steps: readonly string[], gates: Partial<Constraints>, anchors: readonly Anchor[]): {
@@ -243,6 +247,28 @@ interface EmitInput {
 declare function cssValue(name: string, token: RawToken): string;
 declare function emitCss(themes: readonly EmitInput[]): string;
 
+/** The `$extensions` key on a DTCG export's root that carries every axis besides mode. */
+declare const AXES_EXT = "com.weasel.axes";
+/** The token groups of one layer: plain values, and values per mode. */
+interface DtcgLayer {
+    readonly primitives: Record<string, Record<string, unknown>>;
+    readonly modes: Record<string, Record<string, Record<string, unknown>>>;
+}
+/**
+ * What `toDTCG` writes under `$extensions["com.weasel.axes"]`.
+ *
+ * - `axes`: every axis the theme resolves with, mode included.
+ * - `varies`: token name → the non-mode axes its value depends on.
+ * - `overrides`: a layer per combination of non-default values, keyed like
+ *   `selectionKey` but naming only the axes off their default
+ *   (`density=compact`, `contrast=high,density=roomy` in axis order).
+ */
+interface DtcgAxesExtension {
+    readonly axes: AxisDefs;
+    readonly varies: Record<string, readonly string[]>;
+    readonly overrides: Record<string, DtcgLayer>;
+}
+
 type Group = Record<string, unknown> & {
     $type: string;
 };
@@ -251,17 +277,21 @@ interface DtcgExport {
     readonly defaultMode?: string;
     readonly primitives: Record<string, Group>;
     readonly modes: Record<string, Record<string, Group>>;
+    readonly $extensions?: {
+        readonly [AXES_EXT]?: DtcgAxesExtension;
+    };
 }
 /**
  * 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.
+ * DTCG has one variant dimension, so the plain groups hold mode, with every
+ * other axis at its default value: what a tool that ignores extensions reads.
+ * The other values travel under `$extensions["com.weasel.axes"]` (see
+ * `DtcgAxesExtension`), one override layer per combination of non-default values
+ * some token actually varies by — axes that vary independently cost one layer
+ * per value, not their cross-product.
  */
 declare function toDTCG(theme: Theme): DtcgExport;
 
@@ -290,4 +320,42 @@ type GeneratedTokens = {
 /** 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 };
+/** A theme definition file as a theme store serves it: the dev-server endpoint at `__theme/<name>`. */
+interface StoredTheme {
+    readonly name: string;
+    /** sha-256 of the file's bytes: what a save sends back to prove it saw the file as it is. */
+    readonly hash: string;
+    /** Saving it regenerates `packages/theme/src/generated/`. */
+    readonly emits: boolean;
+    readonly definition: ThemeDefinition;
+}
+interface IssueReport {
+    readonly selection: Selection;
+    readonly issue: Issue;
+}
+type PutResult = {
+    readonly status: 'saved';
+    readonly hash: string;
+    readonly issues: readonly IssueReport[];
+    readonly regenerated: boolean;
+    /** Why the generated files were left alone, when the definition emits and they were. */
+    readonly problems: readonly string[];
+} | {
+    readonly status: 'conflict';
+    readonly hash: string | null;
+} | {
+    readonly status: 'invalid';
+    readonly message: string;
+};
+/** Record order is emission order, so keys are never sorted. */
+declare const serializeDefinition: (definition: ThemeDefinition) => string;
+interface ThemeApi {
+    list(): Promise<StoredTheme[]>;
+    get(name: string): Promise<StoredTheme>;
+    put(name: string, definition: ThemeDefinition, baseHash: string | null): Promise<PutResult>;
+}
+type Fetch = (input: string, init?: RequestInit) => Promise<Response>;
+/** The dev server's theme store, addressed relative to the page so the app's base path carries over. */
+declare function httpThemeApi(base?: string, fetchImpl?: Fetch): ThemeApi;
+
+export { type Anchor, type AxisDependency, BakedTheme, CHROMA_WEIGHT, type Constraints, DEFAULT_CONSTRAINTS, type DeriveResult, type DtcgExport, type EmitInput, type GeneratedTokens, type Issue, type IssueReport, type Layer, type Lch, type LightnessParams, Lookup, type Palette, type Provenance, type PutResult, type ScaleParams, type Stats, type StoredTheme, type Swatch, type ThemeApi, ThemeDefinition, type ThemesInput, anchorFromHex, axisDependencies, categoricalRamp, chromaCap, contrast, cssValue, declaredSteps, deltaE, derive, emitCss, emitManifest, emitThemes, floorDegrees, generate, generateTokens, hexToRgb, httpThemeApi, hueGap, hueName, lightnessRamp, luminance, scale, serializeDefinition, toDTCG, toHex, toHexPreview, toLab, toLch, vividAt };