@weasel-js/theme 1.5.0 → 1.5.2

package/dist/theme-DAZcQi_L.d.ts

@@ -0,0 +1,191 @@
+/** One value of an axis. `scheme` becomes `color-scheme` in that value's CSS blocks. */
+interface AxisValue {
+    readonly scheme?: 'dark' | 'light';
+}
+interface AxisDef {
+    readonly default: string;
+    readonly values: Readonly<Record<string, AxisValue>>;
+}
+/** Key order is declaration order, which selectors and selection keys follow. */
+type AxisDefs = Readonly<Record<string, AxisDef>>;
+/** A partial choice of axis values, e.g. `{ mode: 'light' }`. */
+type Selection = Readonly<Record<string, string>>;
+/** `{ by: 'mode', dark: …, light: … }`: a value that differs per axis value. */
+interface ByAxis<T> {
+    readonly by: string;
+    readonly [axisValue: string]: Varying<T> | string;
+}
+type Varying<T> = T | ByAxis<T>;
+declare function isByAxis(v: unknown): v is ByAxis<unknown>;
+/** Every axis given a known value; anything missing or unknown takes its default. */
+declare function fullSelection(axes: AxisDefs, selection?: Selection): Selection;
+declare function enumerateSelections(axes: AxisDefs): Selection[];
+/** `mode=dark,density=compact`, axes in declaration order. */
+declare function selectionKey(axes: AxisDefs, selection: Selection): string;
+
+type TokenValue = string | number | readonly (string | number)[];
+/**
+ * A single design token as authored, before aliases are resolved: a DTCG-shaped
+ * `{ type, value }` pair where `value` may still be a `{ref}` to another token.
+ */
+interface RawToken {
+    readonly type: string;
+    readonly value: TokenValue;
+    /** Render the referenced color at this alpha, 0–1. */
+    readonly alpha?: number | undefined;
+    readonly description?: string | undefined;
+}
+/** A token graph flattened to one level, keyed by token name (no `--wzl-`
+ *  prefix). Still unresolved — see `ResolvedTokenMap` for the output side. */
+type FlatTokens = Record<string, RawToken>;
+
+/** A number, or `{seeds.name}`. */
+type NumberParam = Varying<number | string>;
+interface PinObject {
+    readonly value: TokenValue;
+    readonly type?: string;
+    readonly description?: string;
+    readonly alpha?: number;
+}
+/** A bare value or `{ value, type?, description?, alpha? }`. The value may be a `{token}` reference. */
+type PinValue = TokenValue | PinObject;
+interface LightnessRampDef {
+    readonly kind: 'lightness';
+    readonly steps: Varying<readonly string[]>;
+    /** First and last step's OKLCH lightness. */
+    readonly lightness: Varying<readonly [NumberParam, NumberParam]>;
+    /** 0 walks evenly; 1 follows a smoothstep S. */
+    readonly curve?: NumberParam;
+    /** Degrees. Ignored when an anchor is given. */
+    readonly hue?: NumberParam;
+    readonly chroma?: Varying<{
+        readonly peak: NumberParam;
+        readonly lightBias?: NumberParam;
+        readonly darkBias?: NumberParam;
+    }>;
+    /** Step name → exact hex (or `{seeds.name}`). The first anchor supplies hue and chroma. */
+    readonly anchor?: Varying<Readonly<Record<string, Varying<string>>>>;
+    readonly description?: string;
+    readonly describe?: Readonly<Record<string, string>>;
+}
+interface CategoricalRampDef {
+    readonly kind: 'categorical';
+    readonly steps: Varying<readonly string[]>;
+    /** Any of the palette generator's `Constraints` except `count` and `anchors`. */
+    readonly gates?: Varying<Readonly<Record<string, Varying<number | string>>>>;
+    readonly anchors?: readonly {
+        readonly name: string;
+        readonly hue: number;
+        readonly lightness: number;
+        readonly chroma?: number;
+    }[];
+    readonly description?: string;
+    readonly describe?: Readonly<Record<string, string>>;
+}
+type RampDef = LightnessRampDef | CategoricalRampDef;
+interface ScaleDef {
+    readonly steps: Varying<readonly string[]>;
+    readonly base: NumberParam;
+    /** Linear: `base + step × i`. */
+    readonly step?: NumberParam;
+    /** Geometric: `base × ratio^i`. */
+    readonly ratio?: NumberParam;
+    /** Explicit: `base × factors[i]`, one per step. For a ramp no single rule fits. */
+    readonly factors?: Varying<readonly NumberParam[]>;
+    readonly description?: string;
+    readonly describe?: Readonly<Record<string, string>>;
+}
+interface SemanticCommon {
+    readonly type?: string;
+    readonly description?: string;
+    /** Audited, never applied. */
+    readonly check?: {
+        readonly contrast: number;
+        readonly against: readonly string[];
+    };
+}
+type StepRule = SemanticCommon & {
+    readonly ramp: string;
+    readonly step: Varying<string>;
+};
+type OffsetRule = SemanticCommon & {
+    readonly from: string;
+    readonly offset: number;
+    readonly dir: 'lighter' | 'darker' | 'away';
+};
+type ContrastRule = SemanticCommon & {
+    readonly ramp: string;
+    readonly contrast: {
+        readonly min: number;
+        readonly against: readonly string[];
+    };
+};
+type RefRule = SemanticCommon & {
+    readonly ref: string;
+    readonly alpha?: number;
+};
+type LiteralRule = SemanticCommon & {
+    readonly value: TokenValue;
+};
+type SemanticRule = StepRule | OffsetRule | ContrastRule | RefRule | LiteralRule;
+interface ThemeDefinition {
+    readonly name: string;
+    /** Another definition's name. Absent or null: extends nothing. */
+    readonly extends?: string | null;
+    readonly description?: string;
+    readonly axes?: AxisDefs;
+    readonly seeds?: Readonly<Record<string, Varying<number | string>>>;
+    readonly ramps?: Readonly<Record<string, RampDef>>;
+    readonly scales?: Readonly<Record<string, ScaleDef>>;
+    readonly semantics?: Readonly<Record<string, Varying<SemanticRule>>>;
+    readonly components?: Readonly<Record<string, Varying<PinValue>>>;
+    readonly pins?: Readonly<Record<string, Varying<PinValue>>>;
+}
+
+type Lookup = (name: string) => ThemeDefinition | undefined;
+/** The definition with its whole `extends` chain folded in, child entries winning. */
+declare function mergeChain(def: ThemeDefinition, lookup?: Lookup, seen?: ReadonlySet<string>): ThemeDefinition;
+
+/**
+ * A definition with every rule run: plain or `by`-varying tokens, references intact.
+ * A branch `derive` could not produce is left out, so at runtime it falls through to the parent; definitions with
+ * issues still bake, because the editor bakes mid-edit and the build refuses them before baking. Cycles and dangling
+ * references still throw, as they do in `derive`.
+ */
+interface BakedTheme {
+    readonly name: string;
+    readonly extends: string | null;
+    readonly axes: AxisDefs;
+    /** In layer order, then definition order. */
+    readonly tokens: Readonly<Record<string, Varying<RawToken>>>;
+}
+/** Derive `definition` at every selection and fold the results into one record of tokens with no rules left. */
+declare function bake(definition: ThemeDefinition, lookup?: Lookup): BakedTheme;
+/** `definition` and every theme it extends, baked, root first. */
+declare function bakeChain(definition: ThemeDefinition, lookup?: Lookup): BakedTheme[];
+
+/**
+ * A theme ready to resolve: its axes and its tokens, each plain or varying by
+ * axis, references intact. A `by` that leaves a value out contributes nothing
+ * for that selection, so the theme it extends supplies it.
+ */
+interface Theme {
+    readonly name: string;
+    readonly extends: Theme | null;
+    readonly axes: AxisDefs;
+    readonly tokens: Readonly<Record<string, Varying<RawToken>>>;
+}
+/** What `defineTheme` accepts: a definition whose `extends` is a `Theme`, holding pins and components only. */
+type ThemeInput = Omit<ThemeDefinition, 'extends'> & {
+    readonly extends?: Theme | null;
+};
+/** The built-in theme, from the baked output of themes/weasel.json. */
+declare const weaselTheme: Theme;
+/**
+ * Build a theme from pins. Unless `extends` says otherwise the result layers
+ * onto `weaselTheme`, so a theme only names what it changes. A definition with
+ * seeds, ramps, scales or semantics needs deriving first.
+ */
+declare function defineTheme(input: ThemeInput): Theme;
+
+export { type AxisDef as A, type BakedTheme as B, type CategoricalRampDef as C, type FlatTokens as F, type Lookup as L, type NumberParam as N, type OffsetRule as O, type PinObject as P, type RawToken as R, type Selection as S, type Theme as T, type Varying as V, type TokenValue as a, type AxisDefs as b, type AxisValue as c, type ByAxis as d, type PinValue as e, type ThemeDefinition as f, type ThemeInput as g, defineTheme as h, enumerateSelections as i, fullSelection as j, isByAxis as k, type ContrastRule as l, type LightnessRampDef as m, type LiteralRule as n, type RampDef as o, type RefRule as p, type ScaleDef as q, type SemanticRule as r, selectionKey as s, type StepRule as t, bake as u, bakeChain as v, weaselTheme as w, mergeChain as x };

package/dist/tokens.css

@@ -1,5 +1,5 @@
 /* GENERATED by packages/theme/scripts/build-tokens.ts — do not edit.
- * Source: packages/theme/tokens/<theme>/
+ * Source: packages/theme/themes/<theme>.json
  */
 
 :root {
@@ -18,6 +18,52 @@
   /* Midnight blue-violet. Deep and saturated; anchors primary actions on light and dark surfaces alike. */
   --wzl-accent-base: #2e1f7a;
   --wzl-accent-strong: #5841b8;
+  /* First of ten categorical spot colors for plotting, status and data viz. Take them in sequence: the order is farthest-point over hue, so the first N are as separated as N colors can be (first three 87° apart, all ten 32°). Mode-invariant on purpose — a series keeps its color when the mode flips, which is why they are tuned for a dark surface and clear only 1.5:1 on a light one. */
+  --wzl-swatch-fuchsia: #f641f7;
+  --wzl-swatch-green: #48e628;
+  --wzl-swatch-sky: #36bff2;
+  --wzl-swatch-amber: #e69628;
+  --wzl-swatch-teal: #3ee1cb;
+  --wzl-swatch-red: #f75034;
+  --wzl-swatch-blue: #407ef7;
+  --wzl-swatch-citron: #d5d23a;
+  --wzl-swatch-rose: #fa4590;
+  --wzl-swatch-violet: #955cf9;
+  /* Shortcut keys and index badges. The floor for chrome text. */
+  --wzl-font-size-2xs: 9px;
+  /* Tool-button labels under an icon. */
+  --wzl-font-size-xs: 10px;
+  /* Chrome labels, status readouts, section headings. */
+  --wzl-font-size-sm: 11px;
+  /* Controls and body text. */
+  --wzl-font-size-md: 13px;
+  /* Panel and dialog titles. */
+  --wzl-font-size-lg: 16px;
+  /* The largest chrome text — a lab or app title. */
+  --wzl-font-size-xl: 20px;
+  --wzl-space-1: 2px;
+  --wzl-space-2: 4px;
+  --wzl-space-3: 6px;
+  --wzl-space-4: 8px;
+  --wzl-space-5: 10px;
+  --wzl-space-6: 12px;
+  --wzl-space-7: 14px;
+  --wzl-space-8: 16px;
+  --wzl-surface: var(--wzl-gray-800);
+  --wzl-surface-raised: var(--wzl-gray-700);
+  --wzl-surface-sunken: var(--wzl-gray-900);
+  --wzl-fg: var(--wzl-gray-100);
+  --wzl-fg-muted: var(--wzl-gray-300);
+  --wzl-fg-subtle: var(--wzl-gray-400);
+  --wzl-border: var(--wzl-gray-700);
+  /* The line that has to be seen: a control's edge, a raised surface's outline. Clears WCAG 1.4.11's 3:1 against every surface in both modes. */
+  --wzl-border-strong: var(--wzl-gray-400);
+  /* Accent for foreground use — text, icons, selected labels drawn on a surface. accent is a fill; the midnight base is too dim to read as text on dark surfaces. */
+  --wzl-accent-fg: var(--wzl-accent-strong);
+  /* Text drawn on a filled foreground-colored element (e.g. a slider thumb). Flips with the mode, so it is a semantic, not an alias to a primitive. */
+  --wzl-fg-inverse: var(--wzl-gray-900);
+  /* Elevation. Always darker than any surface — never derived from fg, which is near-white on dark. */
+  --wzl-shadow: rgba(0, 0, 0, 0.6);
   --wzl-danger-base: #d94a3f;
   --wzl-warning-base: #d99a3f;
   --wzl-success-base: #2ec27e;
@@ -42,17 +88,6 @@
   --wzl-surface-hover: color-mix(in srgb, var(--wzl-fg) 10%, transparent);
   /* Pressed wash over a raised surface. */
   --wzl-surface-pressed: color-mix(in srgb, var(--wzl-fg) 18%, transparent);
-  /* First of ten categorical spot colors for plotting, status and data viz. Take them in sequence: the order is farthest-point over hue, so the first N are as separated as N colors can be (first three 87° apart, all ten 32°). Mode-invariant on purpose — a series keeps its color when the mode flips, which is why they are tuned for a dark surface and clear only 1.5:1 on a light one. */
-  --wzl-swatch-fuchsia: #f641f7;
-  --wzl-swatch-green: #48e628;
-  --wzl-swatch-sky: #36bff2;
-  --wzl-swatch-amber: #e69628;
-  --wzl-swatch-teal: #3ee1cb;
-  --wzl-swatch-red: #f75034;
-  --wzl-swatch-blue: #407ef7;
-  --wzl-swatch-citron: #d5d23a;
-  --wzl-swatch-rose: #fa4590;
-  --wzl-swatch-violet: #955cf9;
   --wzl-radius-sm: 3px;
   --wzl-radius-md: 5px;
   --wzl-radius-lg: 14px;
@@ -65,8 +100,14 @@
   --wzl-curve-width: 3px;
   /* Height of a horizontal toolbar strip (ActionsBar, OptionsBar, ToolOptionsBar). Taller than control-h so the controls inside a strip are not flush with its edges. */
   --wzl-tb-height: 28px;
+  /* Height of the smallest interactive control -- a stepper, a keycap, a swatch button in a dense row. The rank below control-h-sm. */
+  --wzl-control-h-xs: 18px;
+  /* Height of a control in a dense inspector -- a Properties field, a small Button. The rank below control-h, which sizes a standalone control. */
+  --wzl-control-h-sm: 20px;
   /* Height of an interactive control — button, input, select, segmented control. Distinct from tb-height, which sizes the strip a row of them sits in. */
   --wzl-control-h: 24px;
+  /* Side of a square icon button -- a dialog close, a row remove, a field clear. Smaller than control-h because it carries a glyph rather than a label, and square, so it sizes both axes. */
+  --wzl-icon-button-size: 22px;
   /* Height of a linear range track. The kit's single-thumb ranges all wear this; Slider's default 24px canvas track does not. */
   --wzl-slider-track-h: 4px;
   /* Diameter of a linear range thumb. */
@@ -75,26 +116,18 @@
   --wzl-slider-track-mix: 18%;
   /* Accent proportion in a range thumb, as a color-mix percentage — not a color. */
   --wzl-slider-thumb-mix: 70%;
+  /* Edge of a draggable handle on a plot or timeline — a keyframe diamond, a timeline key, an event mark. The default rank; -sm and -lg are the two deliberate departures from it. */
+  --wzl-handle-size: 9px;
+  /* A handle that is drawn but not draggable — a locked or pinned point. Smaller so it reads as inert next to a live one. */
+  --wzl-handle-size-sm: 7px;
+  /* A handle that is a category of its own rather than one of a row — a curve's endpoint. Larger so it separates from the handles it sits in line with. */
+  --wzl-handle-size-lg: 10px;
   /* Horizontal padding inside a boxed field. Pairs with --wzl-field-h, which is a container override and has no :root default. */
   --wzl-field-pad-x: 8px;
   /* Backdrop blur radius for frosted surfaces. Pairs with glass-tint. */
   --wzl-glass-blur: 3px;
-  /* Shortcut keys and index badges. The floor for chrome text. */
-  --wzl-font-size-2xs: 9px;
-  /* Tool-button labels under an icon. */
-  --wzl-font-size-xs: 10px;
-  /* Chrome labels, status readouts, section headings. */
-  --wzl-font-size-sm: 11px;
   /* Controls and body text. */
-  --wzl-font-size: 13px;
-  /* Panel and dialog titles. */
-  --wzl-font-size-lg: 16px;
-  /* The largest chrome text — a lab or app title. */
-  --wzl-font-size-xl: 20px;
-  --wzl-space-xs: 4px;
-  --wzl-space-sm: 8px;
-  --wzl-space-md: 12px;
-  --wzl-space-lg: 16px;
+  --wzl-font-size: var(--wzl-font-size-md);
   --wzl-tracking-none: 0;
   /* Uppercase section headings. */
   --wzl-tracking-wide: 0.06em;
@@ -128,21 +161,14 @@
   --wzl-font-weight-normal: 300;
   --wzl-font-weight-medium: 350;
   --wzl-font-weight-bold: 400;
-  --wzl-surface: var(--wzl-gray-800);
-  --wzl-surface-raised: var(--wzl-gray-700);
-  --wzl-surface-sunken: var(--wzl-gray-900);
-  --wzl-fg: var(--wzl-gray-100);
-  --wzl-fg-muted: var(--wzl-gray-300);
-  --wzl-fg-subtle: var(--wzl-gray-400);
-  --wzl-border: var(--wzl-gray-700);
-  /* The line that has to be seen: a control's edge, a raised surface's outline. Clears WCAG 1.4.11's 3:1 against every surface in both modes. */
-  --wzl-border-strong: var(--wzl-gray-400);
-  /* Accent for foreground use — text, icons, selected labels drawn on a surface. accent is a fill; the midnight base is too dim to read as text on dark surfaces. */
-  --wzl-accent-fg: var(--wzl-accent-strong);
-  /* Text drawn on a filled foreground-colored element (e.g. a slider thumb). Flips with the mode, so it is a semantic, not an alias to a primitive. */
-  --wzl-fg-inverse: var(--wzl-gray-900);
-  /* Elevation. Always darker than any surface — never derived from fg, which is near-white on dark. */
-  --wzl-shadow: rgba(0, 0, 0, 0.6);
+  /* Alias for space-2. The t-shirt names name every other rung of the ladder. */
+  --wzl-space-xs: var(--wzl-space-2);
+  /* Alias for space-4. The t-shirt names name every other rung of the ladder. */
+  --wzl-space-sm: var(--wzl-space-4);
+  /* Alias for space-6. The t-shirt names name every other rung of the ladder. */
+  --wzl-space-md: var(--wzl-space-6);
+  /* Alias for space-8. The t-shirt names name every other rung of the ladder. */
+  --wzl-space-lg: var(--wzl-space-8);
 }
 
 [data-wzl-theme='weasel'][data-wzl-mode='dark'],
@@ -186,3 +212,51 @@
   --wzl-surface-hover: color-mix(in srgb, var(--wzl-fg) 10%, transparent);
   --wzl-surface-pressed: color-mix(in srgb, var(--wzl-fg) 18%, transparent);
 }
+
+[data-wzl-theme='weasel'][data-wzl-density='compact'],
+[data-wzl-density='compact'] {
+  --wzl-font-size-2xs: 7px;
+  --wzl-font-size-xs: 8px;
+  --wzl-font-size-sm: 9px;
+  --wzl-font-size-md: 11px;
+  --wzl-font-size-lg: 14px;
+  --wzl-font-size-xl: 17px;
+  --wzl-tb-height: 24px;
+  --wzl-control-h-xs: 16px;
+  --wzl-control-h-sm: 18px;
+  --wzl-control-h: 20px;
+  --wzl-icon-button-size: 20px;
+  --wzl-font-size: var(--wzl-font-size-md);
+}
+
+[data-wzl-theme='weasel'][data-wzl-density='comfortable'],
+[data-wzl-density='comfortable'] {
+  --wzl-font-size-2xs: 9px;
+  --wzl-font-size-xs: 10px;
+  --wzl-font-size-sm: 11px;
+  --wzl-font-size-md: 13px;
+  --wzl-font-size-lg: 16px;
+  --wzl-font-size-xl: 20px;
+  --wzl-tb-height: 28px;
+  --wzl-control-h-xs: 18px;
+  --wzl-control-h-sm: 20px;
+  --wzl-control-h: 24px;
+  --wzl-icon-button-size: 22px;
+  --wzl-font-size: var(--wzl-font-size-md);
+}
+
+[data-wzl-theme='weasel'][data-wzl-density='roomy'],
+[data-wzl-density='roomy'] {
+  --wzl-font-size-2xs: 10px;
+  --wzl-font-size-xs: 12px;
+  --wzl-font-size-sm: 13px;
+  --wzl-font-size-md: 15px;
+  --wzl-font-size-lg: 18px;
+  --wzl-font-size-xl: 23px;
+  --wzl-tb-height: 32px;
+  --wzl-control-h-xs: 22px;
+  --wzl-control-h-sm: 24px;
+  --wzl-control-h: 28px;
+  --wzl-icon-button-size: 26px;
+  --wzl-font-size: var(--wzl-font-size-md);
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@weasel-js/theme",
-  "version": "1.5.0",
+  "version": "1.5.2",
   "description": "Design tokens shared by weasel-ui and weasel-hud — CSS variables + a parallel TS export.",
   "license": "MIT",
   "type": "module",
@@ -19,10 +19,17 @@
       "import": "./dist/react.js",
       "types": "./dist/react.d.ts"
     },
+    "./engine": {
+      "import": "./dist/engine.js",
+      "types": "./dist/engine.d.ts"
+    },
     "./tokens.css": "./dist/tokens.css",
     "./fonts.css": "./dist/fonts.css",
     "./package.json": "./package.json"
   },
+  "dependencies": {
+    "@weasel-js/paint": "1.5.2"
+  },
   "peerDependencies": {
     "react": ">=18"
   },