@kitlangton/knobs 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,474 @@
+import { type CodeFormat } from "./code.js";
+import type { TokenPreset } from "./theme.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 DensityMode = "compact" | "default" | "comfortable";
+export type RendererMode = "gpu" | "dom" | "auto";
+/** When a store's chip shows; see `ChipOptions.reveal`. */
+export type RevealMode = "hover" | "shortcut" | "always";
+/** The floating chip `attach` puts on an element, which grows into its panel. */
+export interface ChipOptions {
+    /** Text beside the cog, e.g. `"knobs"`. Just the cog by default. */
+    readonly label?: string;
+    /**
+     * When the chip shows. `"hover"`: while the element is hovered or focused. `"shortcut"`: hidden
+     * until `shortcut` turns on knobs mode (remembered for the tab), then on hover. `"always"`:
+     * whenever its panel is closed. `"hover"` in development, `"shortcut"` in production builds.
+     */
+    readonly reveal?: RevealMode;
+    /** The key that toggles knobs mode for `"shortcut"` chips: `"Alt+Shift+D"` (⌥⇧D) by default. */
+    readonly shortcut?: string;
+}
+export type ChangeSource = "local" | "remote" | "reset" | "preset" | "variant" | "undo" | "redo" | "randomize" | "mutate" | "compare";
+/**
+ * A key going into the hand and out of it: a drag or a press on its row, an inline edit, or a
+ * burst of arrow keys. Changes between a key's `start` and `end` are one gesture, so a host can
+ * open one undo entry at `start` and close it at `end`.
+ */
+export interface GestureEvent {
+    readonly key: string;
+    readonly phase: "start" | "end";
+}
+export interface ChangeMeta {
+    readonly source: ChangeSource;
+    readonly coalesce?: boolean;
+    readonly key?: string;
+    readonly group?: string;
+}
+export interface ControlAction<V = State> {
+    readonly id?: string;
+    readonly label: string;
+    readonly group?: string;
+    readonly shortcut?: string;
+    run(values: V, controls: Controls<any>): void | string | Promise<void | string>;
+}
+/** One of a group's numbered presets; keys it leaves out sit at their defaults (see `groupPresets`). */
+export interface GroupPreset<V = State> {
+    readonly name: string;
+    readonly values: Partial<V>;
+}
+/**
+ * How a page card shows its group presets: `names` as segments ("Native · Tight · Airy"), `menu`
+ * as a compact drop-down showing the selected one's name, `numbers` as 1, 2, 3…; `auto` (the
+ * default) shows names while they fit beside the title, else the menu.
+ */
+export type GroupPresetDisplay = "auto" | "names" | "numbers" | "menu";
+/** Display labels, kept apart from the ids that identify groups, sections and presets. */
+export interface LabelOptions {
+    /** By group id: what its header shows (verbatim). Ids stay identity everywhere else. */
+    readonly groupLabels?: Readonly<Record<string, string>>;
+    /** By section id: what its heading shows. */
+    readonly sectionLabels?: Readonly<Record<string, string>>;
+    /** By preset id: what the preset strip shows, e.g. `{ default: "Native" }`. */
+    readonly presetLabels?: Readonly<Record<string, string>>;
+    /** Shorthand for `presetLabels.default`. */
+    readonly defaultLabel?: string;
+    /** How a page card shows its group presets (see `GroupPresetDisplay`). */
+    readonly groupPresetDisplay?: GroupPresetDisplay;
+    /** By group id: one muted line under its card's title on a page, over fields' `groupDescription`. */
+    readonly groupDescriptions?: Readonly<Record<string, string>>;
+    /** By section id: one muted line under its heading on a page, over fields' `sectionDescription`. */
+    readonly sectionDescriptions?: Readonly<Record<string, string>>;
+}
+/**
+ * How a page's sections start: `true` folds every section to its heading, or by section id. A
+ * section neither names keeps its fields' `sectionFolded`, else starts open.
+ */
+export type SectionFolded = boolean | Readonly<Record<string, boolean>>;
+/** Panel commands with a key binding; see `MountPanelOptions.keys`. */
+export type PanelCommand = "random" | "mutate" | "reset" | "resetAll" | "compare" | "hint" | "undo" | "redo" | "copy" | "save" | "lock" | "presets" | "group" | "first" | "help" | "menu" | "leave";
+/**
+ * Remaps (a single character, or a key name such as `"F2"`) or turns off (`false`) a panel's key
+ * bindings. Unlisted commands keep their default key. `true` keeps the default.
+ */
+export type PanelKeys = {
+    readonly [C in PanelCommand]?: string | boolean;
+} & {
+    /** `false` drops the j/k and h/l aliases: only the arrows move and adjust; the letters reach the page. */
+    readonly vim?: boolean;
+    /**
+     * `false` stops digits, `.`, `-` and Enter from opening a slider's inline number editor (they
+     * reach the page); clicking the readout still edits.
+     */
+    readonly edit?: boolean;
+    /** What ⇧ multiplies an arrow's step by; 10 by default. */
+    readonly bigStep?: number;
+    /** `false` stops ↑/↓ at the first and last rows instead of wrapping around. */
+    readonly wrap?: boolean;
+};
+/** A header button (see `MountPanelOptions.header`). */
+export type HeaderButton = "random" | "reset" | "copy" | "undo" | "redo" | "help" | "close";
+export interface HeaderOptions {
+    /** `false` hides the title; the buttons stay at the right. */
+    readonly title?: boolean;
+    /**
+     * Which buttons show (of those that are on). All but `help` by default: its `?` key opens the
+     * shortcuts either way, and the title's tooltip says so. List `"help"` to bring the button back.
+     */
+    readonly buttons?: readonly HeaderButton[];
+}
+export interface MountPanelOptions extends LabelOptions {
+    readonly title?: string | false;
+    /**
+     * Key bindings. An inline panel only ever hears keys while focus is inside it; pass this to remap
+     * or turn off commands so they don't shadow the host's own keys, e.g.
+     * `{ random: false, mutate: false, compare: false, hint: false, undo: false }` or `{ hint: "f" }`.
+     * The `?` popover and hint badges list only what's enabled.
+     */
+    readonly keys?: PanelKeys;
+    /**
+     * Hint mode's reach. `"page"` (the default): `s` labels every visible control in every panel
+     * and knobs/ui piece on the page (and the host's `data-hint` elements), so pressed here or
+     * anywhere outside a text field it jumps across all of them; with nothing else on the page it's
+     * this panel's alone, as always. `"panel"`: `s` here labels only this panel's controls, and they
+     * don't join the page's. `keys: { hint: false }` turns hint mode off here either way.
+     */
+    readonly hints?: "page" | "panel";
+    /**
+     * `false` hides what says a value differs from its default: modified dots and readout marks,
+     * group reset icons and the header's Reset. For panels whose values belong to someone else
+     * (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`). */
+    readonly preset?: TokenPreset;
+    /**
+     * `false` drops the header (title and buttons) for a host that draws its own. An object keeps
+     * it and chooses what shows: `{ title: false, buttons: ["random", "undo", "redo"] }`. A button
+     * left out keeps its key; a command that's off (`keys`) loses its button either way. Without a
+     * list, every button but `help` shows (see `HeaderOptions`).
+     */
+    readonly header?: boolean | HeaderOptions;
+    /**
+     * `false`: no per-tab session, so a rebuilt panel doesn't take focus back to the row it last
+     * had or reopen editors and folded groups. On while the store has storage.
+     */
+    readonly session?: boolean;
+    /** Groups folded (`true`) or open (`false`) at first, over their fields' `folded`. */
+    readonly groupFolded?: Readonly<Record<string, boolean>>;
+    /** Sub-headings (fields' `subsection`) that start folded (`true`), by name. */
+    readonly subsectionFolded?: Readonly<Record<string, boolean>>;
+    /**
+     * The tab strip's order and labels: tab ids, or `{ id, label }`. Tabs the fields name that
+     * aren't listed follow in the order they first appear.
+     */
+    readonly tabs?: readonly (string | {
+        readonly id: string;
+        readonly label?: string;
+    })[];
+    /** The tab shown first; otherwise the one last shown for these controls, else the first. */
+    readonly tab?: string;
+    /** Called when the shown tab changes (by a click, a key or `panel.tab()`). */
+    readonly onTab?: (tab: string) => void;
+    /**
+     * A search field under the header that filters rows by label, key or group as you type, with
+     * filter chips (`"modified"`, with its count, by default). `/` focuses it.
+     */
+    readonly search?: boolean | SearchOptions;
+    /**
+     * A group's Random (its die, `g`, ⌥ for Mutate) asks the host first: returning `true` means the
+     * host rolled the group itself (its own seeded "Randomize <group>"), and the panel only tumbles
+     * the die.
+     */
+    readonly groupRandom?: (group: string, mode: "random" | "mutate") => boolean | void;
+    /**
+     * A node for a row's accessory slot, just after its label (a pin, a marker), or null. Called
+     * with the row's key when the row is built; `panel.updateAccessories()` asks again. The node
+     * stays the host's: style it, listen on it. With the WebGPU renderer it stays DOM (see README).
+     */
+    readonly rowAccessory?: (key: string) => Node | null;
+    /**
+     * Light haptic ticks on phones (a stepped slider crossing a stop, the default's magnet, a
+     * choice changing mid-pan, a switch flipping); on by default, `false` turns them off.
+     * Reduced motion turns them off too.
+     */
+    readonly haptics?: boolean;
+    /** Called once the panel is mounted, with a handle to focus it (a host's "Tune" key). */
+    readonly onReady?: (panel: PanelHandle) => void;
+    /** What Copy (and ⇧C) puts on the clipboard; `controls.code()` by default. */
+    readonly copy?: () => string;
+    readonly theme?: ThemeMode;
+    readonly density?: DensityMode;
+    readonly renderer?: RendererMode;
+    readonly variants?: boolean;
+    readonly history?: boolean;
+    readonly footer?: boolean;
+    readonly actions?: readonly ControlAction<any>[];
+    readonly onClose?: () => void;
+}
+/** A search field's filter chip: it narrows the rows to those `test` accepts. */
+export interface SearchChip {
+    readonly id: string;
+    readonly label: string;
+    /** Shows how many rows it would keep beside its label. */
+    readonly count?: boolean;
+    test(key: string, controls: Controls<any>): boolean;
+}
+export interface SearchOptions {
+    readonly placeholder?: string;
+    /** `"modified"` (rows off their defaults) or chips of your own; `["modified"]` by default. */
+    readonly chips?: readonly ("modified" | SearchChip)[];
+}
+/**
+ * An undo stack the host owns (an editor's ⌘Z that covers more than these values). The panel's
+ * undo and redo buttons and keys call it; compare (hold `\`) still previews knobs' own last entry.
+ */
+export interface HostHistory {
+    undo(): void;
+    redo(): void;
+    canUndo(): boolean;
+    canRedo(): boolean;
+    /** Called when `canUndo` or `canRedo` may have changed; returns an unsubscribe. */
+    subscribe?(cb: () => void): () => void;
+}
+/**
+ * What `storage` keeps: `"all"` (values, locks and saved variants; the default), `"variants"`
+ * (only saved variants, for values the host owns) or `"none"`.
+ */
+export type PersistMode = "all" | "variants" | "none";
+export interface SyncOptions {
+    /** Keys missing from `values` return to their defaults. */
+    readonly replace?: boolean;
+    /**
+     * Keys whose values differ across what the host is showing (a multi-selection): they show an
+     * indeterminate "—" until edited. Replaces the store's mixed keys (see `Controls.setMixed`).
+     */
+    readonly mixed?: readonly string[];
+    /**
+     * A different item arrived: panels place the values without springing or rolling, and undo
+     * history starts over (it belonged to the previous item).
+     */
+    readonly land?: boolean;
+}
+/** A mounted panel: what `mount` hands `onReady`. */
+export interface PanelHandle {
+    readonly element: HTMLElement;
+    focus(): void;
+    dispose(): void;
+}
+/**
+ * The panel module a shipped store mounts with: `() => import("knobs/panel")`. Structural, so the
+ * core never imports the panel itself.
+ */
+export interface PanelModule {
+    mountPanel(controls: Controls<any>, container: HTMLElement, options?: MountPanelOptions): PanelHandle;
+    attach(controls: Controls<any>, element: HTMLElement, chip?: ChipOptions): () => void;
+}
+export interface ControlsOptions<S extends Schema> extends LabelOptions {
+    enabled?: boolean | (() => boolean);
+    /**
+     * Ships this store as product UI: it stays live in production builds (where stores are
+     * otherwise locked to their defaults) and mounts panels from the module this loads, e.g.
+     * `ship: () => import("knobs/panel")`. `enabled` defaults to true. Stores without it stay
+     * dev-only and ship constants.
+     */
+    ship?: () => Promise<PanelModule>;
+    /** The chip `attach` shows: its label, when it shows and the knobs-mode key (see `ChipOptions`). */
+    chip?: ChipOptions;
+    /**
+     * The longest (ms) a key changed here outranks incoming values for it (see `sync`), so an echo
+     * of an older value still in flight can't pull it back. The hold ends early once the remote
+     * reports the value that was sent (for numbers, within half a step). 0 by default; remote
+     * controls use 600. Raise it for peers that acknowledge slowly.
+     */
+    echo?: number;
+    storage?: StoragePort | null;
+    /** What `storage` keeps: everything, only saved variants, or nothing (see `PersistMode`). */
+    persist?: PersistMode;
+    /**
+     * The source Random and Mutate draw from, `[0, 1)` like `Math.random` (the default). Pass a
+     * seeded generator to make a roll reproducible.
+     */
+    random?: () => number;
+    /**
+     * Whether Random and Mutate may change a key, beside locks and each field's `random: false`
+     * (e.g. never seeds or structural pickers).
+     */
+    tunable?: (key: keyof S & string, values: Values<S>) => boolean;
+    /** An undo stack the host owns; undo and redo call it (see `HostHistory`). */
+    history?: HostHistory;
+    presets?: Readonly<Record<string, Partial<Values<S>>>>;
+    /**
+     * Numbered presets per group, shown as 1, 2, 3… on the group's card in a page. A group's
+     * presets cover every key any of them names; keys a preset leaves out are at their defaults,
+     * so `{ name: "Today", values: {} }` is the shipped look.
+     */
+    groupPresets?: Readonly<Record<string, readonly GroupPreset<Values<S>>[]>>;
+    actions?: readonly ControlAction<Values<S>>[];
+    theme?: ThemeMode;
+    density?: DensityMode;
+    renderer?: RendererMode;
+    /** Default key bindings for this store's panels (see `MountPanelOptions.keys`). */
+    keys?: PanelKeys;
+    /** `false`: its panels show no modified marks or resets (see `MountPanelOptions.marks`). */
+    marks?: boolean;
+    /** How its groups start, folded or open, under the mount's `groupFolded` (see there). */
+    groupFolded?: Readonly<Record<string, boolean>>;
+    /** How a page's sections start, under the mount's `sectionFolded` (see `SectionFolded`). */
+    sectionFolded?: SectionFolded;
+    onChange?: (patch: Partial<Values<S>>, values: Values<S>, meta: ChangeMeta) => void;
+    /** A key went into the hand or out of it (see `GestureEvent`). */
+    onGesture?: (event: GestureEvent) => void;
+    onReset?: (target: {
+        key?: keyof S & string;
+        group?: string;
+    }) => void;
+    /** An action row was pressed (after its own `run`), or a toolbar button (with its item's id). */
+    onAction?: (key: string) => void;
+    /** A group's numbered preset was applied (after its values are set). */
+    onPreset?: (target: {
+        group: string;
+        index: number;
+        name: string;
+    }) => void;
+}
+export interface Controls<S extends Schema = Schema> {
+    readonly id: string;
+    readonly schema: S;
+    readonly locked: Values<S>;
+    readonly enabled: boolean;
+    readonly storage: StoragePort | null;
+    /** What `storage` keeps (see `PersistMode`). */
+    readonly persist: PersistMode;
+    readonly presets: Readonly<Record<string, Values<S>>>;
+    readonly variants: Variants<Values<S>>;
+    readonly actions: readonly ControlAction<Values<S>>[];
+    readonly theme: ThemeMode;
+    readonly density: DensityMode;
+    readonly renderer: RendererMode;
+    readonly keys: PanelKeys | undefined;
+    readonly marks: boolean;
+    /** The chip's options, with `reveal` and `shortcut` resolved. */
+    readonly chip: ChipOptions & {
+        readonly reveal: RevealMode;
+        readonly shortcut: string;
+    };
+    /** How page cards show group presets (`groupPresetDisplay`, `auto` by default). */
+    readonly groupPresetDisplay: GroupPresetDisplay;
+    /** A group's display label (`groupLabels`, else its fields' `groupLabel`), if it has one. */
+    groupLabel(group: string): string | undefined;
+    /** A section's display label (`sectionLabels`, else its fields' `sectionLabel`), if it has one. */
+    sectionLabel(section: string): string | undefined;
+    /** A group's description (`groupDescriptions`, else its fields' `groupDescription`), if any. */
+    groupDescription(group: string): string | undefined;
+    /** A section's description (`sectionDescriptions`, else its fields' `sectionDescription`), if any. */
+    sectionDescription(section: string): string | undefined;
+    /** How groups start (`groupFolded`), as given; panels read it under their own `groupFolded`. */
+    readonly groupFolded: Readonly<Record<string, boolean>> | undefined;
+    /** How a page's sections start (`sectionFolded`), as given. */
+    readonly sectionFolded: SectionFolded | undefined;
+    /** A preset's display label (`presetLabels`, `defaultLabel`), else its id. */
+    presetLabel(id: string): string;
+    readonly error: string | null;
+    get(): Values<S>;
+    getServerSnapshot(): Values<S>;
+    /** Apply a change. `coalesce` folds it into the previous history entry (used while dragging). */
+    set(patch: Partial<Values<S>>, options?: {
+        coalesce?: boolean;
+        source?: ChangeSource;
+        key?: string;
+        group?: string;
+    }): void;
+    /**
+     * Apply external state (props, a server, a peer) without recording undo history or emitting a
+     * local change. A key that is held (in hand, or changed here within `echo` ms) keeps its value;
+     * the newest incoming value for it lands when the hold ends.
+     */
+    sync(values: Partial<Values<S>>, options?: SyncOptions): void;
+    /**
+     * Marks a key as in hand (a drag, an inline edit) or lets it go. While held, `sync` doesn't
+     * touch it; letting go applies the newest value that arrived meanwhile. Panels call this.
+     */
+    hold(key: string, held?: boolean): void;
+    /** Whether incoming values for `key` are held back right now (see `sync`). */
+    isHeld(key: string): boolean;
+    /**
+     * Presses an action row: its `run`, then `onAction(key)`. For a toolbar, `item` names the
+     * button (its id, else its label) and `onAction` gets the item's id.
+     */
+    action(key: keyof S & string, item?: string): void;
+    /**
+     * Shows a live value in a readout row (`watch`, `sparkline`, `graph`, `meter`, `table`, `log`):
+     * a number or text, a sample for a history, `{ [series]: number }` for a graph, rows for a
+     * table, an entry for a log. `null` clears it. Rows redraw at most once a frame and sleep
+     * when nothing arrives; nothing is recorded in the values, history or storage.
+     */
+    watch<K extends ReadoutKeys<S>>(key: K, value: ReadoutInput<S[K]>): void;
+    /** The latest value pushed to a readout (`undefined` before any). */
+    watched(key: ReadoutKeys<S>): unknown;
+    /** True while the change being notified landed (`sync(…, { land: true })`): place, don't animate. */
+    readonly landing: boolean;
+    undo(): void;
+    redo(): void;
+    readonly canUndo: boolean;
+    readonly canRedo: boolean;
+    subscribe(cb: () => void): () => void;
+    /**
+     * Back to the defaults: every field, or only `keys`. Locks don't apply; disabled and read-only
+     * fields keep their values.
+     */
+    reset(keys?: readonly (keyof S & string)[]): void;
+    resetKey(key: keyof S & string): void;
+    resetGroup(group: string): void;
+    isModified(key?: keyof S & string): boolean;
+    modified(): Partial<Values<S>>;
+    /**
+     * Random values for every field that can roll (see `canRoll`), or those among `keys`, drawn
+     * from `random`. One undo step.
+     */
+    randomize(keys?: readonly (keyof S & string)[]): void;
+    /** Small changes around the current values instead of a re-roll; skips what can't roll. */
+    mutate(keys?: readonly (keyof S & string)[]): void;
+    /** Keeps fields out of Random and Mutate (or lets them back in). Saved with the values. */
+    lock(keys: (keyof S & string) | readonly (keyof S & string)[], locked?: boolean): void;
+    isLocked(key: keyof S & string): boolean;
+    /**
+     * Whether Random and Mutate may change `key`: it holds a value and isn't locked, `random:
+     * false`, refused by `tunable`, disabled or read-only.
+     */
+    canRoll(key: keyof S & string): boolean;
+    /** Whether the field is disabled now (`disabled`, static or from the values). */
+    isDisabled(key: keyof S & string): boolean;
+    /** Whether the field is read-only now (`readOnly`, static or from the values). */
+    isReadOnly(key: keyof S & string): boolean;
+    /**
+     * Asks panels to read again what they derive without new values: function `disabled` and
+     * `readOnly` flags (which may read state elsewhere, another store's say) and row accessories.
+     */
+    refresh(): void;
+    /**
+     * Marks keys as mixed (a multi-selection whose items differ): panels show "—" until the key is
+     * edited, and the first edit reaches `onChange` even when it picks the value shown.
+     */
+    setMixed(keys: (keyof S & string) | readonly (keyof S & string)[], mixed?: boolean): void;
+    isMixed(key: keyof S & string): boolean;
+    /**
+     * While held, `get()` shows the values from before the last change (the previous undo entry);
+     * releasing restores the current ones. Nothing is recorded or stored; `onChange` reports
+     * `source: "compare"` both ways.
+     */
+    compare(hold: boolean): void;
+    readonly comparing: boolean;
+    preset(id: string): void;
+    matchingPreset(): string;
+    /** Each group's numbered presets, complete over the keys they cover. */
+    readonly groupPresets: Readonly<Record<string, readonly GroupPreset<Values<S>>[]>>;
+    /**
+     * Applies a group's preset (0-based), one undo step; `coalesce` folds it into the previous
+     * one (a pan across a card's presets).
+     */
+    groupPreset(group: string, index: number, options?: {
+        coalesce?: boolean;
+    }): void;
+    /** The group preset the current values match, or -1. */
+    matchingGroupPreset(group: string): number;
+    code(format?: CodeFormat, values?: Values<S>): string;
+    /** Shows the floating chip on `element`; `chip` overrides the store's chip options. */
+    attach(element: HTMLElement, chip?: ChipOptions): () => void;
+    mount(container: HTMLElement, options?: MountPanelOptions): () => void;
+}
+/** Whether two fields draw and behave the same (a reshape keeps such a key's value). */
+export declare function sameField(a: unknown, b: unknown): boolean;
+export declare function defineControls<const S extends Schema>(id: string, input: S, options?: ControlsOptions<S>): Controls<S>;

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

@@ -0,0 +1,27 @@
+/**
+ * A named set of `--k-*` token values for dark and light, applied to panels 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.
+ */
+export interface TokenPreset {
+    readonly name: string;
+    readonly dark: Readonly<Record<string, string | number>>;
+    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. */
+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
+ * plain sections split by hairlines, no cards, and no panel card when inline), the Lab's greys
+ * and one blue accent, small type with monospaced readouts, and no glass, glow or lift. Mount it
+ * inside the host's own card or column.
+ */
+export declare const labPreset: TokenPreset;
+/**
+ * The Problems viewer's parameter panel: separate 34 px bars 4 px apart, its blue fill and
+ * labels, a spring card that stacks its curve over two sliders, washes that arrive at once and
+ * leave over 100 ms, and Problems' own slider spring (ω 34, ζ 0.86). An inline panel sheds its
+ * chrome to sit in the host's column. Every difference from the defaults is a token.
+ */
+export declare const problemsPreset: TokenPreset;

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

@@ -0,0 +1,17 @@
+import { type Schema, type Values } from "./schema.js";
+import type { StoragePort } from "./storage.js";
+export interface Variant<V> {
+    readonly id: string;
+    readonly name?: string;
+    readonly values: V;
+}
+export interface Variants<V> {
+    readonly ready: boolean;
+    list(): readonly Variant<V>[];
+    save(name?: string): Variant<V>;
+    load(id: string): void;
+    remove(id: string): void;
+    export(): string;
+    import(json: string): void;
+}
+export declare function createVariants<S extends Schema>(schema: () => S, id: string, key: string, storage: () => StoragePort | null, get: () => Values<S>, set: (v: Values<S>) => void, notify: () => void, enabled: () => boolean): Variants<Values<S>>;

package/dist/types/index.d.ts

@@ -0,0 +1,13 @@
+export { knob, choice, toggle, spring, color, point, easing, action, flatSpring, vec2, vec3, range, angle, seed, keybind, gradient, curve, toolbar, toolbarShortcut, 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 { 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 { defineControls, type ChangeMeta, type GestureEvent, type ChangeSource, type ChipOptions, type ControlAction, type Controls, type ControlsOptions, type DensityMode, type GroupPreset, type GroupPresetDisplay, 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 ThemeMode, } 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";
+export type { TokenPreset } from "./core/theme.js";
+export { formatCode, type CodeFormat } from "./core/code.js";
+export { comboFromEvent, letterOf, comboLabel, comboParts, matchesCombo, normalizeCombo, } from "./core/keys.js";
+export type { Variant, Variants } from "./core/variants.js";

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

@@ -0,0 +1,5 @@
+import type { ChipOptions, Controls } from "../core/store.js";
+import type { Schema } from "../core/schema.js";
+export declare function attach<S extends Schema>(controls: Controls<S>, element: HTMLElement, options?: ChipOptions): () => void;
+/** Parses `"Alt+Shift+D"` into a test for keydown events. Letters and digits match by key position. */
+export declare function matchShortcut(shortcut: string): (event: KeyboardEvent) => boolean;

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

@@ -0,0 +1,56 @@
+export interface ChoiceItem {
+    readonly value: string;
+    readonly label: string;
+}
+/** `auto` is segmented while it fits and has at most `COMPACT_CHOICES` options; else a menu. */
+export type ChoiceDisplay = "auto" | "menu" | "segmented";
+/** More options than this always drop down a menu (unless `display: "segmented"`). */
+export declare const COMPACT_CHOICES = 4;
+/** A menu of more options than this opens with a search field. */
+export declare const SEARCH_CHOICES = 8;
+export interface ChoiceControl {
+    /** The segmented control and the menu button; one is hidden at a time. */
+    readonly seg: HTMLElement;
+    readonly buttons: readonly HTMLButtonElement[];
+    readonly menu: HTMLButtonElement;
+    readonly menuValue: HTMLElement;
+    /** Whichever of the two is showing: the row's ↑↓ stop. */
+    focusTarget(): HTMLElement;
+    isMenu(): boolean;
+    /**
+     * Shows `value` (the pill under its segment and the menu's label); `mixed` shows none of them
+     * (no pill, "—"), for a multi-selection whose items differ.
+     */
+    show(value: string, instant?: boolean, mixed?: boolean): void;
+    /** New labels for the same options. */
+    relabel(items: readonly ChoiceItem[]): void;
+    /** Steps one option (←/→), stopping at the ends unless `wrap`. */
+    step(direction: number, wrap: boolean): void;
+    dispose(): void;
+}
+/**
+ * One choice control for every segmented row (fields and custom cards): segments while their
+ * labels fit with room to spare, a compact button that drops down a menu when they don't or when
+ * there are many. It measures on resize, so it switches both ways as the width changes. ←/→ on
+ * either steps through the options; Enter or Space opens the menu.
+ */
+export declare function createChoice(doc: Document, row: HTMLElement, o: {
+    readonly label?: string;
+    readonly items: readonly ChoiceItem[];
+    readonly display?: ChoiceDisplay;
+    /** The current value (the store's, or the card's own). */
+    value(): string;
+    /** `coalesce`: a later change in the same pan, folded into its undo step. */
+    choose(value: string, coalesce?: boolean): void;
+    wake?(): void;
+    /** The width (px) the segments may take; the row's, less its label, by default. */
+    room?(): number;
+    /** What a resize is watched on, when not the row (the room depends on more than it). */
+    observe?: HTMLElement;
+    /** Most options shown as segments under `auto`; `COMPACT_CHOICES` by default. */
+    compact?: number;
+    /** Menu items show their 1-based number as a key equivalent. */
+    numbered?: boolean;
+    /** The menu's label when no option matches the value. */
+    none?: string;
+}): ChoiceControl;