@kitlangton/knobs 0.3.0 → 0.4.0-next.1

package/dist/types/core/adapter.d.ts

@@ -1,6 +1,7 @@
 import type { ControlDescriptor } from "./remote.js";
 import type { Choice, Schema, State } from "./schema.js";
-import type { Controls, DensityMode, MountPanelOptions, ThemeMode } from "./store.js";
+import type { Controls, DensityMode, MountPanelOptions } from "./store.js";
+import { type LookOptions } from "./appearance.js";
 export type ChoiceKey<S extends Schema> = {
     [K in keyof S]: S[K] extends Choice ? K : never;
 }[keyof S] & string;
@@ -16,6 +17,9 @@ export type KnobsPanelProps<S extends Schema = Schema> = MountPanelOptions & {
     /** While true, a different item is arriving: values land without springing or rolling. */
     land?: boolean;
 };
-export declare function syncPanelLook<S extends Schema>(host: HTMLElement | null | undefined, controls: Controls<S>, theme?: ThemeMode, density?: DensityMode): void;
+/** The look a panel takes: its props' over its store's. */
+export declare const panelLook: <S extends Schema>(controls: Controls<S>, look?: LookOptions) => import("./appearance.js").Look;
+/** Restyles the mounted panel in place (theme, appearance, preset, density), so its tokens glide. */
+export declare function syncPanelLook<S extends Schema>(host: HTMLElement | null | undefined, controls: Controls<S>, look?: LookOptions, density?: DensityMode): void;
 export declare function syncPanelValues<S extends Schema>(controls: Controls<S>, descriptors?: readonly ControlDescriptor[], values?: State, land?: boolean): void;
 export declare function mountPanelAdapter<S extends Schema>(host: HTMLElement, controls: Controls<S>, getProps: () => KnobsPanelProps<S>): () => void;

package/dist/types/core/appearance.d.ts

@@ -0,0 +1,44 @@
+import type { Theme } from "../themes/define.js";
+import { type TokenPreset } from "./theme.js";
+/**
+ * Light or dark: `dark` and `light` fix it, `system` follows the OS, and `inherit` (the default)
+ * follows the page: a `color-scheme`, a `.dark`/`.light` class, `[data-theme]` or
+ * `[data-appearance]` on an ancestor, or an outer knobs element, else the OS.
+ */
+export type Appearance = "dark" | "light" | "system" | "inherit";
+/** @deprecated The old name for an appearance: `auto` is `system`. Use `appearance`. */
+export type ThemeMode = "dark" | "light" | "auto";
+/** How a panel, chip or knobs/ui piece looks: its theme, its appearance (and an old preset). */
+export interface LookOptions {
+    /**
+     * A theme from `defineTheme` (or `themes.knobs`, `themes.void`). Knobs' own when unset.
+     * `"dark" | "light" | "auto"` is the old spelling of `appearance` and still works.
+     */
+    readonly theme?: Theme | ThemeMode;
+    readonly appearance?: Appearance;
+    /** @deprecated A `TokenPreset` (`labPreset`): its tokens over the theme's. */
+    readonly preset?: TokenPreset;
+}
+/** A look with every part decided. */
+export interface Look {
+    readonly theme?: Theme;
+    readonly appearance: Appearance;
+    readonly preset?: TokenPreset;
+}
+/** `options` over `base`: a theme object, an appearance (or an old mode), a preset. */
+export declare function resolveLook(options?: LookOptions, base?: Partial<Look>): Look;
+/** The theme an element shows: the nearest themed knobs element's, else knobs' own (undefined). */
+export declare function themeOf(el: Element): Theme | undefined;
+/** The selector a theme's tokens sit under: any knobs element marked with its name. */
+export declare const themeSelector: (name: string) => string;
+/** Adds a theme's tokens once per document, under `[data-knobs-theme="<name>"]`. */
+export declare function injectTheme(doc: Document, theme: Theme): void;
+/** Adds a preset's tokens once per document, for any knobs element marked `data-preset`. */
+export declare function injectPreset(doc: Document, preset: TokenPreset): void;
+/** Marks `el` (a knobs root) with `look`: its theme's tokens, its appearance and its preset. */
+export declare function applyLook(el: HTMLElement, look: Look): void;
+/**
+ * The look `el` shows, fixed: its theme and preset, and the appearance it shows now. For something
+ * floated out of it (a drag ghost, a menu) to match it wherever it lands.
+ */
+export declare function lookAt(el: Element): Look;

package/dist/types/core/glide.d.ts

@@ -0,0 +1,7 @@
+/** The transitions that glide every driver, for a root that also transitions its own properties. */
+export declare const TOKEN_TRANSITIONS: string;
+/** Elements whose tokens glide: each declares the drivers. */
+export declare const GLIDING = ".knobs-panel,.knobs-chip,.knobs-notice,.knobs-ui";
+export declare const DRIVERS: string;
+/** Rules read the gliding aliases of what glides, and what the knobs root resolved otherwise. */
+export declare const aliased: (css: string) => string;

package/dist/types/core/motion.d.ts

@@ -0,0 +1,66 @@
+import { type SpringValue } from "./spring.js";
+/**
+ * The five named springs (SwiftUI duration and bounce), all without bounce. Every motion in knobs
+ * uses one of these unless it's tuned for one feature.
+ */
+export declare const SPRINGS: {
+    /** Press feedback, focus, selection, pointer-tied moves. */
+    readonly instant: {
+        readonly duration: 0.1;
+        readonly bounce: 0;
+    };
+    /** Value fills, thumbs, toggles, small controls, menus, exits. */
+    readonly snappy: {
+        readonly duration: 0.25;
+        readonly bounce: 0;
+    };
+    /** Most state changes: popovers, panel open and close, restyle glides (`--k-spring`). */
+    readonly default: {
+        readonly duration: 0.3;
+        readonly bounce: 0;
+    };
+    /** Layout reflow, split panes, list reorders. */
+    readonly calm: {
+        readonly duration: 0.4;
+        readonly bounce: 0;
+    };
+    /** Appearance and theme changes, drawers, page-scale moves. */
+    readonly smooth: {
+        readonly duration: 0.45;
+        readonly bounce: 0;
+    };
+};
+export type SpringName = keyof typeof SPRINGS;
+/** A quick fade that isn't travel (and what any fade becomes under reduced motion). */
+export declare const FADE: SpringValue;
+/** A popover or menu closing: a little shorter than snappy. */
+export declare const CLOSE: SpringValue;
+/** The named springs as ω/ζ, for `new Spring(x, omega, zeta)`. */
+export declare const MOTION: { readonly [K in SpringName]: {
+    readonly omega: number;
+    readonly zeta: number;
+}; };
+export declare const reducedMotion: (win: Window | null | undefined) => boolean;
+/**
+ * The reduced-motion policy: movement doesn't travel (`null`: go straight to the end), and a fade
+ * keeps a short fade (at most `FADE`).
+ */
+export declare function reducedSpring(spring: SpringValue, kind: "move" | "fade", reduced: boolean): SpringValue | null;
+/** A spring as a CSS `linear()` easing and its settle time (ms). */
+export declare const springLinear: (spring: SpringValue) => {
+    easing: string;
+    ms: number;
+};
+/** `--k-spring`'s default: the default spring as "duration bounce". */
+export declare const SPRING_TOKEN: string;
+/** The default spring as CSS, for `--k-fill-ease` and `--k-fill-ms`. */
+export declare const DEFAULT_LINEAR: {
+    easing: string;
+    ms: number;
+};
+/**
+ * Each named spring as CSS on :root: `--_k-motion-<name>` (a `linear()` easing) and
+ * `--_k-motion-<name>-ms` (its settle time, a number of ms). Under reduced motion they take 0 ms:
+ * movement doesn't travel.
+ */
+export declare const motionCss: string;

package/dist/types/core/root.d.ts

@@ -0,0 +1,13 @@
+/**
+ * The class every knobs top-level element carries: panels, chips, menus, the status notice, and
+ * every knobs/ui piece's root. Each resolves the design tokens for itself (see tokens/css.ts), so
+ * a theme, an appearance or a host's token on any ancestor reaches what's derived from it.
+ */
+export declare const ROOT_CLASS = "knobs-root";
+/**
+ * The token sheet: the Knobs theme's defaults, every root's resolution and appearance, the
+ * drivers that make tokens glide, and the motion tokens.
+ */
+export declare const rootCss: string;
+/** Adds the token sheet once per document. */
+export declare function injectTokens(doc: Document): void;

package/dist/types/core/store.d.ts

@@ -1,9 +1,11 @@
 import { type CodeFormat } from "./code.js";
 import type { TokenPreset } from "./theme.js";
+import type { Appearance, ThemeMode } from "./appearance.js";
+import type { Theme } from "../themes/define.js";
 import { type ReadoutInput, type ReadoutKeys, type Schema, type State, type Values } from "./schema.js";
 import { type StoragePort } from "./storage.js";
 import { type Variants } from "./variants.js";
-export type ThemeMode = "dark" | "light" | "auto";
+export type { Appearance, ThemeMode } from "./appearance.js";
 export type DensityMode = "compact" | "default" | "comfortable";
 export type RendererMode = "gpu" | "dom" | "auto";
 /** When a store's chip shows; see `ChipOptions.reveal`. */
@@ -157,7 +159,7 @@ export interface MountPanelOptions extends LabelOptions {
      * (a prototype's settings), where "default" means nothing. The store's `marks` by default.
      */
     readonly marks?: boolean;
-    /** Token values to style the panel with, e.g. `problemsPreset` (see `TokenPreset`). */
+    /** @deprecated Token values to style the panel with (see `TokenPreset`); use `theme`. */
     readonly preset?: TokenPreset;
     /**
      * `false` drops the header (title and buttons) for a host that draws its own. An object keeps
@@ -231,7 +233,13 @@ export interface MountPanelOptions extends LabelOptions {
     readonly onReady?: (panel: PanelHandle) => void;
     /** What Copy (and ⇧C) puts on the clipboard; `controls.code()` by default. */
     readonly copy?: () => string;
-    readonly theme?: ThemeMode;
+    /**
+     * A theme from `defineTheme` (`themes.knobs`, `themes.void`); the store's by default. The old
+     * `"dark" | "light" | "auto"` still sets the appearance.
+     */
+    readonly theme?: Theme | ThemeMode;
+    /** dark | light | system | inherit (the default: follow the page, else the OS). */
+    readonly appearance?: Appearance;
     readonly density?: DensityMode;
     readonly renderer?: RendererMode;
     readonly variants?: boolean;
@@ -347,7 +355,10 @@ export interface ControlsOptions<S extends Schema> extends LabelOptions {
      */
     groupPresets?: Readonly<Record<string, readonly GroupPreset<Values<S>>[]>>;
     actions?: readonly ControlAction<Values<S>>[];
-    theme?: ThemeMode;
+    /** Its panels' theme (see `MountPanelOptions.theme`). */
+    theme?: Theme | ThemeMode;
+    /** Its panels' appearance (see `MountPanelOptions.appearance`). */
+    appearance?: Appearance;
     density?: DensityMode;
     renderer?: RendererMode;
     /** Default key bindings for this store's panels (see `MountPanelOptions.keys`). */
@@ -385,7 +396,9 @@ export interface Controls<S extends Schema = Schema> {
     readonly presets: Readonly<Record<string, Values<S>>>;
     readonly variants: Variants<Values<S>>;
     readonly actions: readonly ControlAction<Values<S>>[];
-    readonly theme: ThemeMode;
+    /** Its panels' theme, as given (see `ControlsOptions.theme`). */
+    readonly theme: Theme | ThemeMode | undefined;
+    readonly appearance: Appearance | undefined;
     readonly density: DensityMode;
     readonly renderer: RendererMode;
     readonly keys: PanelKeys | undefined;

package/dist/types/core/theme.d.ts

@@ -1,7 +1,10 @@
 /**
- * A named set of `--k-*` token values for dark and light, applied to panels mounted with
+ * A named set of `--k-*` token values for dark and light, applied to knobs elements mounted with
  * `{ preset }` (or with `data-preset="<name>"` and `presetCss(preset)` in your own stylesheet).
- * `css` adds rules for anything tokens don't cover; `&` stands for the panel.
+ * `css` adds rules for anything tokens don't cover; `&` stands for the element.
+ *
+ * @deprecated Use `defineTheme` (from `knobs/themes`), which generates both appearances from a
+ * few dials. Presets keep working; their token names go through the deprecated aliases.
  */
 export interface TokenPreset {
     readonly name: string;
@@ -9,7 +12,11 @@ export interface TokenPreset {
     readonly light?: Readonly<Record<string, string | number>>;
     readonly css?: string;
 }
-/** The stylesheet for a preset: its dark tokens, its light ones wherever a panel is light. */
+/**
+ * The stylesheet for a preset. A token it gives for both appearances becomes `light-dark(light,
+ * dark)`, so it follows the element's appearance (its `color-scheme`) like the theme's colours
+ * do; anything else holds in both.
+ */
 export declare function presetCss(preset: TokenPreset): string;
 /**
  * A dense, square editor (Arcade's Lab): radius 0, compact 26 px rows, the flat frame (groups as

package/dist/types/index.d.ts

@@ -1,10 +1,11 @@
 export { knob, choice, toggle, spring, color, point, easing, action, flatSpring, vec2, vec3, range, angle, seed, keybind, gradient, curve, toolbar, toolbarShortcut, actionShortcut, watch, sparkline, graph, meter, table, log, hasValue, isReadout, wrapAngle, SPRING, type FieldMeta, type ActionField, type SpringPart, type ValueField, type Knob, type Choice, type Toggle, type SpringField, type ColorField, type PointField, type EasingField, type VecField, type Vec3, type RangeField, type AngleField, type SeedField, type KeybindField, type GradientField, type CurveField, type ToolbarField, type ToolbarItem, type ToolbarShortcut, type WatchField, type SparklineField, type GraphField, type GraphSeries, type GraphThreshold, type MeterField, type TableField, type LogField, type ReadoutField, type ReadoutKeys, type ReadoutInput, type Point, type Field, type Schema, type Values, type Value, type State, } from "./core/schema.js";
 export { springCss, springMotion, type SpringValue } from "./core/spring.js";
+export { reducedSpring, SPRINGS, type SpringName } from "./core/motion.js";
 export { colorHex, parseColor, type Oklch } from "./core/color.js";
 export { sampleGradient, sampleCurve, gradientCss, CURVE_SHAPES, type GradientStop, type GradientSpace, type CurvePoint, type CurveInterp, type SampleGradientOptions, type SampleCurveOptions, } from "./core/ramp.js";
 export { bezierCss, bezierPoint, EASINGS, type Bezier, type EasingName } from "./core/easing.js";
 export { AROUND } from "./core/random.js";
-export { defineControls, type ChangeMeta, type GestureEvent, type ChangeSource, type ChipOptions, type ControlAction, type Controls, type ControlsOptions, type DensityMode, type GroupPreset, type GroupPresetDisplay, type PresetRef, type HeaderButton, type HeaderOptions, type HostHistory, type LabelOptions, type MountPanelOptions, type PanelCommand, type PanelHandle, type PanelModule, type PanelKeys, type PersistMode, type SearchChip, type SearchOptions, type SyncOptions, type RendererMode, type RevealMode, type SectionFolded, type SoundOptions, type SoundTheme, type ThemeMode, } from "./core/store.js";
+export { defineControls, type ChangeMeta, type GestureEvent, type ChangeSource, type ChipOptions, type ControlAction, type Controls, type ControlsOptions, type DensityMode, type GroupPreset, type GroupPresetDisplay, type PresetRef, type HeaderButton, type HeaderOptions, type HostHistory, type LabelOptions, type MountPanelOptions, type PanelCommand, type PanelHandle, type PanelModule, type PanelKeys, type PersistMode, type SearchChip, type SearchOptions, type SyncOptions, type RendererMode, type RevealMode, type SectionFolded, type SoundOptions, type SoundTheme, type ThemeMode, type Appearance, } from "./core/store.js";
 export { createRemoteControls, descriptorToField, formatSwift, fromDescriptors, fromSettings, type SettingsGroup, type SettingsItem, type ActionDescriptor, type ChoiceOption, type ControlDescriptor, type SpringBindingDescriptor, type ToolbarDescriptor, type ReadoutDescriptor, type ValueDescriptor, type RemoteControls, type RemoteControlsOptions, } from "./core/remote.js";
 export type { LogEntry, LogLevel, TableRows, WatchValue } from "./core/readout.js";
 export { memoryStorage, urlFlag, type StoragePort } from "./core/storage.js";

package/dist/types/panel/gpu/color.d.ts

@@ -1,4 +1,5 @@
 import { mixRgba as mixColor, parseCssColor, type Rgba, withAlpha } from "../../ui/rgba.js";
+import type { GpuColors, Theme } from "../../themes/define.js";
 export { mixColor, parseCssColor, type Rgba, withAlpha };
 /** CSS `color-mix(in srgb, a p, b)`, interpolated with premultiplied alpha like the browser. */
 export declare function cssMix(a: Rgba, b: Rgba, p: number): Rgba;
@@ -126,3 +127,8 @@ export interface PanelThemeTokens {
     readonly shadowStrength: number;
 }
 export declare function readPanelTokens(panel: HTMLElement, version?: number): PanelThemeTokens;
+/**
+ * A theme's colours for one appearance, as the renderer draws them (sRGB, straight alpha): what
+ * the panel shows where no CSS (a host's override, a preset, a glide) says otherwise.
+ */
+export declare function gpuDefaults(theme: Theme | undefined, light: boolean): GpuColors;

package/dist/types/panel/motion.d.ts

@@ -1,6 +1,6 @@
 import { Spring } from "../core/spring.js";
 export { Spring, springEasing } from "../core/spring.js";
-/** The slider fill, and its rubber band springing back from past an end. */
+/** The slider fill (the default spring, as --k-spring), and its rubber band springing back from past an end. */
 export declare const FILL: {
     omega: number;
     zeta: number;

package/dist/types/panel/styles.d.ts

@@ -1,11 +1,10 @@
-import { type TokenPreset } from "../core/theme.js";
 /**
  * What DELAY times: a row's turn in a preset's cascade is set on these (see `showValues` in
  * panel.ts) rather than on the row, where the custom property would restyle all of the row.
  */
 export declare const DELAYED = ".knobs-fill,.knobs-handle,.knobs-seg-pill,.knobs-toggle,.knobs-toggle i,.knobs-arm,.knobs-curve,.knobs-swatch,.knobs-strip-thumb,.knobs-pad>i,.knobs-ease-handle,.knobs-range-track,.knobs-range-fill,.knobs-range-thumb,.knobs-dial-hand,.knobs-grad,.knobs-grad-mini,.knobs-grad-mini>i,.knobs-grad-stop,.knobs-graph-pt";
-/** Adds a token preset's stylesheet once per document. */
-export declare function injectPreset(doc: Document, preset: TokenPreset): void;
 /** The rules' `:has()` as the attributes has.ts keeps (see there for why). */
 export declare const withoutHas: (css: string) => string;
+/** The panel stylesheet, as `injectStyles` writes it (after the token sheet). */
+export declare const panelCss: () => string;
 export declare function injectStyles(doc: Document): void;

package/dist/types/themes/define.d.ts

@@ -0,0 +1,104 @@
+import { type Rgba } from "../tokens/color.js";
+import { type ColorTokenName, type TokenName } from "../tokens/schema.js";
+export type Appearance = "dark" | "light";
+export type Density = "compact" | "default" | "comfortable";
+export type Material = "glass" | "solid" | "flat";
+export type TokenOverrides = Partial<Record<TokenName, string>>;
+/** What `defineTheme` takes. Everything but `name` is optional and deep-merges over `extends`. */
+export interface ThemeSpec {
+    readonly name: string;
+    readonly extends?: Theme;
+    /** Tint of the neutral ladder. Chroma 0–0.02; 0.004 reads as neutral with a hint of hue. */
+    readonly gray?: {
+        readonly hue?: number;
+        readonly chroma?: number;
+    };
+    /** The accent: one colour (its dark-appearance value; light is derived) or one per appearance. */
+    readonly accent?: string | {
+        readonly dark: string;
+        readonly light: string;
+    };
+    /** 0–100, 50 by default: spreads the surface ladder and text tiers, scales fills and borders. */
+    readonly contrast?: number;
+    /** Control radius in px. */
+    readonly radius?: number;
+    readonly density?: Density;
+    readonly material?: Material;
+    readonly font?: {
+        readonly sans?: string;
+        readonly mono?: string;
+    };
+    /** Escape hatch: any token's value, per appearance. Applied after generation. */
+    readonly tokens?: {
+        readonly dark?: TokenOverrides;
+        readonly light?: TokenOverrides;
+    };
+}
+/** A spec with every dial filled in. */
+export interface ThemeInputs {
+    readonly gray: {
+        readonly hue: number;
+        readonly chroma: number;
+    };
+    readonly accent: string | {
+        readonly dark: string;
+        readonly light: string;
+    };
+    readonly contrast: number;
+    readonly radius: number;
+    readonly density: Density;
+    readonly material: Material;
+    readonly font: {
+        readonly sans: string;
+        readonly mono: string;
+    };
+    readonly tokens: {
+        readonly dark: TokenOverrides;
+        readonly light: TokenOverrides;
+    };
+}
+export type ResolvedTokens = Readonly<Record<TokenName, string>>;
+export type GpuColors = Readonly<Record<ColorTokenName, Rgba>>;
+export interface Theme {
+    readonly name: string;
+    readonly inputs: ThemeInputs;
+    /**
+     * Every token for each appearance. Colours are fully resolved hex (`#rrggbb` or `#rrggbbaa`);
+     * other tokens carry their CSS value or derivation.
+     */
+    readonly dark: ResolvedTokens;
+    readonly light: ResolvedTokens;
+    /** What the theme itself declares (generated values plus overrides); the CSS is built from it. */
+    readonly declared: {
+        readonly dark: TokenOverrides;
+        readonly light: TokenOverrides;
+    };
+    /** Every colour token as linear-light sRGB floats `[r, g, b, a]` (straight alpha), for WebGPU. */
+    readonly gpu: {
+        readonly dark: GpuColors;
+        readonly light: GpuColors;
+    };
+    /**
+     * The theme's CSS in `@layer knobs.tokens`. With no selector, the full default sheet (its values
+     * on `:root`, every token resolved on `.knobs-root`, appearance rules). With a selector, one
+     * block of what this theme declares, to scope it to part of a page.
+     */
+    css(options?: {
+        readonly selector?: string;
+    }): string;
+}
+/** The APCA budget each ink must meet on `bg`. */
+export declare const APCA_BUDGET: {
+    readonly fg: 90;
+    readonly "fg-2": 75;
+    readonly "fg-3": 45;
+    readonly "fg-4": 30;
+    readonly "accent-fg": 60;
+    readonly "border-strong": 15;
+};
+/**
+ * Builds a theme from a few dials: a neutral ladder generated in OKLCH and checked against the
+ * APCA budget, an accent with its text and on-accent colours, a shared status palette, chart
+ * series and material values, resolved for both appearances.
+ */
+export declare function defineTheme(spec: ThemeSpec): Theme;

package/dist/types/themes/index.d.ts

@@ -1 +1,12 @@
+import { knobs } from "./knobs.js";
+import { voidTheme } from "./void.js";
+export { APCA_BUDGET, type Appearance as ThemeAppearance, type Density, defineTheme, type GpuColors, type Material, type ResolvedTokens, type Theme, type ThemeInputs, type ThemeSpec, type TokenOverrides, } from "./define.js";
+export { knobs, voidTheme };
+export type { Appearance } from "../core/appearance.js";
+export type { PublicTokenName, TokenName, TokenProperty } from "../tokens/schema.js";
+/** The shipped themes: Knobs (the default) and Void (true black, flat, for OLED and video). */
+export declare const themes: {
+    readonly knobs: import("./define.js").Theme;
+    readonly void: import("./define.js").Theme;
+};
 export { labPreset, presetCss, problemsPreset, type TokenPreset } from "../core/theme.js";

package/dist/types/themes/knobs.d.ts

@@ -0,0 +1,5 @@
+/**
+ * The main look: a `#1c1c1e`-class panel floating on a near-black page, glass, a white
+ * monochrome accent and alpha hairlines. Its light pair keeps `#f5f5f7` / `#1a1a1c` / `#1c1c1e`.
+ */
+export declare const knobs: import("./define.js").Theme;

package/dist/types/themes/void.d.ts

@@ -0,0 +1,8 @@
+/**
+ * For OLED and video review: true black page and panel with Apple's `#1c1c1e` / `#2c2c2e` raised
+ * surfaces, text capped at `#ededed` to limit halation, a white accent, flat with solid
+ * hairlines, and a black stage behind compared media. Neutral (no tint) so the chrome doesn't
+ * bias colour judgement. The light pair is generated from the same dials, with a neutral
+ * near-black accent.
+ */
+export declare const voidTheme: import("./define.js").Theme;

package/dist/types/tokens/color.d.ts

@@ -0,0 +1,42 @@
+/**
+ * The colour maths the theme generator needs and nothing more: OKLCH ↔ sRGB (Björn Ottosson's
+ * OKLab matrices), hex parsing and formatting with alpha, and APCA 0.0.98G contrast.
+ */
+/** Linear-light sRGB, each channel 0–1, plus straight (not premultiplied) alpha. */
+export type Rgba = readonly [r: number, g: number, b: number, a: number];
+export interface Oklch {
+    /** Perceived lightness, 0–1. */
+    readonly l: number;
+    readonly c: number;
+    /** Hue in degrees. */
+    readonly h: number;
+    readonly alpha?: number;
+}
+export declare const toLinear: (c: number) => number;
+export declare const toGamma: (c: number) => number;
+/** Linear sRGB → OKLCH. */
+export declare function linearToOklch([r, g, b, a]: Rgba): Oklch;
+/** OKLCH → linear sRGB, unclamped (may fall outside the gamut). */
+export declare function oklchToLinear({ l: L, c, h, alpha }: Oklch): Rgba;
+/** OKLCH → linear sRGB inside the gamut, reducing chroma (keeping L and h) when it doesn't fit. */
+export declare function oklchToLinearInGamut(color: Oklch): Rgba;
+/** Parses `#rgb`, `#rgba`, `#rrggbb`, `#rrggbbaa`, `oklch(L% C H / A)` and `rgb()/rgba()`. */
+export declare function parseColor(input: string): Rgba;
+export declare const toOklch: (input: string) => Oklch;
+/** Linear sRGB → `#rrggbb`, or `#rrggbbaa` when not opaque. */
+export declare function formatHex([r, g, b, a]: Rgba): string;
+export declare const oklchToHex: (color: Oklch) => string;
+/** Rounds to the 8-bit hex grid, so values compare and serialise the same everywhere. */
+export declare const normalize: (input: string) => string;
+/** `color` at `alpha` (multiplying any alpha it already has). */
+export declare function withAlpha(input: string, alpha: number): string;
+/** `top` composited over an opaque `bottom` in gamma-encoded sRGB (what browsers paint). */
+export declare function over(top: string, bottom: string): string;
+/** `a` mixed toward `b` by `t` (0–1) in OKLCH, the hue taking the shorter arc. */
+export declare function mixOklch(a: string, b: string, t: number): string;
+/**
+ * APCA 0.0.98G lightness contrast of `text` on `background`, as an absolute Lc (light text on
+ * dark is negative in APCA; this returns its magnitude). A translucent text colour is composited
+ * over the background first.
+ */
+export declare function apca(text: string, background: string): number;

package/dist/types/tokens/css.d.ts

@@ -0,0 +1,13 @@
+import type { Theme } from "../themes/define.js";
+export declare const APPEARANCE_CSS: string;
+/**
+ * The default token sheet for `theme`, in `@layer knobs.tokens` so any host assignment wins: the
+ * theme's values (inputs, generated colours as `light-dark()` pairs, literals) as public tokens on
+ * `:where(:root,:host)`, every token resolved privately (`--_k-*`) on `:where(.knobs-root)`, and
+ * the appearance rules. Component styles read only the private names.
+ */
+export declare function tokensCss(theme: Theme): string;
+/** One block of everything `theme` declares, under `selector`, to theme part of a page. */
+export declare function themeCss(theme: Theme, selector: string): string;
+/** The README token reference: every public token with its values in `theme`, then the renames. */
+export declare function tokensTable(theme: Theme): string;

package/dist/types/tokens/evaluate.d.ts

@@ -0,0 +1,8 @@
+/**
+ * Evaluates the small CSS colour language the token derivations are written in: `var(--k-…)`
+ * (with fallbacks), `color-mix(in oklch, A p, B q)` (premultiplied, shorter hue, as browsers do),
+ * `calc(N% * var(--k-contrast))` percentages, and plain colours. The same strings are emitted as
+ * CSS, so the TypeScript-resolved maps and the browser agree by construction.
+ */
+export type Lookup = (cssName: string) => string | undefined;
+export declare function evaluate(input: string, lookup: Lookup): string;

package/dist/types/tokens/index.d.ts

@@ -0,0 +1,4 @@
+export { apca, formatHex, mixOklch, normalize, type Oklch, oklchToHex, over, parseColor, type Rgba, toOklch, withAlpha, } from "./color.js";
+export { APPEARANCE_CSS, themeCss, tokensCss, tokensTable } from "./css.js";
+export { evaluate } from "./evaluate.js";
+export { type ColorTokenName, cssName, DEPRECATED, type HookName, type PublicTokenName, RETIRED_INTERNAL, type SemanticTokenName, THEME_DIALS, type ThemeTokenName, type Tier, TOKEN_BY_NAME, TOKENS, type TokenDef, type TokenName, type TokenProperty, type TokenSource, type TokenType, tokenForProperty, } from "./schema.js";