@kitlangton/knobs 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,423 @@
+import type { StoragePort } from "../core/storage.js";
+import type { MountPanelOptions, SectionFolded } from "../core/store.js";
+import type { Panel } from "./panel.js";
+/** What a folded card's or section's summary is made of (see `MountPageOptions.groupSummary`). */
+export interface FoldSummaryInfo {
+    /** The group preset its values match (its name), "Custom" when none does; null without any. */
+    readonly preset: string | null;
+    /** How many of its rows differ from their defaults (a spring's two keys count once). */
+    readonly changed: number;
+    /** Its value keys. */
+    readonly keys: readonly string[];
+}
+export interface MountPageOptions extends MountPanelOptions {
+    /** Section order; sections not listed follow in the order they first appear. */
+    readonly sections?: readonly string[];
+    /** The narrowest a column may get before the page drops one (px). Default 300. */
+    readonly columnWidth?: number;
+    /** `/` filters rows by label, live. Default true. */
+    readonly filter?: boolean;
+    /**
+     * Sections that start folded to their heading: `true` for all of them, or by section id (over
+     * the store's `sectionFolded` and fields' `sectionFolded`). A section that says either way
+     * folds: its heading toggles it (a click, or Enter where it's focused). What the user last
+     * chose is remembered (see `foldStorage`) and wins over this.
+     */
+    readonly sectionFolded?: SectionFolded;
+    /**
+     * Where the page keeps what the user folds and opens (sections and group cards), under
+     * `knobs:<id>:folds:v1` as `{ sections, groups }`. By default the store's own storage, unless
+     * it has `persist: "none"` (then nothing). Given, it always wins and keeps folds only (never
+     * values, locks or variants), so a store with `storage: null` can still remember its folds.
+     * `null` keeps none. Folds made for context (`remember: false`) and by the filter are never
+     * written.
+     */
+    readonly foldStorage?: StoragePort | null;
+    /**
+     * A strip of section chips in the sticky header: the section in view is marked as the page
+     * scrolls, each chip counts its changed rows, and a chip (or ⌥↑ / ⌥↓) glides to its section,
+     * opening it if it's folded.
+     */
+    readonly nav?: boolean;
+    /**
+     * What a folded group card's header says. By default "<matching preset, or Custom> · N
+     * changed", leaving out what doesn't apply. `null` shows nothing.
+     */
+    readonly groupSummary?: (group: string, info: FoldSummaryInfo) => string | Node | null;
+    /** What a folded section's heading says ("N changed · M cards" by default; `preset` is null). */
+    readonly sectionSummary?: (section: string, info: FoldSummaryInfo) => string | Node | null;
+}
+export interface PageCardOptions {
+    readonly title?: string;
+    /** The section the card sits in; a new one is added after the others. */
+    readonly section?: string;
+    /** Any content, placed in the card's body (more can follow with `card.body.append`). */
+    readonly element?: HTMLElement;
+    /**
+     * Makes the card collapsible, starting folded (`true`) or open (`false`): its header toggles it
+     * (a click, or Enter where it's focused) and shows a caret. What the user last chose comes back
+     * after a reload in the same tab, over this.
+     */
+    readonly collapsed?: boolean;
+    /** One quiet line on the right of a folded card's header, e.g. "iPhone · 0.142.4 · connected". */
+    readonly summary?: string | Node;
+    /** One muted line under the title (the whole of it on hover). */
+    readonly description?: string;
+}
+export interface PageItem {
+    readonly label: string;
+    readonly detail?: string;
+    onSelect?(): void;
+}
+export interface PageAction {
+    readonly label: string;
+    run(): void;
+    readonly disabled?: boolean;
+}
+/** A control in a custom card; `set` shows a value that arrived from elsewhere (no `onChange`). */
+export interface PageControl<T> {
+    readonly element: HTMLElement;
+    get(): T;
+    set(value: T): void;
+}
+export interface PageCard {
+    /** The card itself. */
+    readonly element: HTMLElement;
+    /** Where content goes. */
+    readonly body: HTMLElement;
+    /** Right side of the card's header, for a badge or a small button. */
+    readonly accessory: HTMLElement;
+    /**
+     * A choice row, like a choice field (no `label` spans the card): segmented while the labels fit
+     * and there are at most four, a drop-down menu otherwise; `display` fixes one or the other.
+     */
+    choice<T extends string>(options: {
+        readonly label?: string;
+        readonly options: readonly (T | {
+            readonly value: T;
+            readonly label: string;
+        })[];
+        readonly value: T;
+        readonly display?: "menu" | "segmented";
+        onChange(value: T): void;
+    }): PageControl<T>;
+    /** A switch row. */
+    toggle(options: {
+        readonly label: string;
+        readonly value: boolean;
+        onChange(value: boolean): void;
+    }): PageControl<boolean>;
+    /**
+     * A row of buttons; `set` swaps them, keyed by label: buttons that stay glide to their place,
+     * the rest cross-fade, and the row folds away while it's empty.
+     */
+    actions(items: readonly PageAction[]): {
+        readonly element: HTMLElement;
+        set(items: readonly PageAction[]): void;
+    };
+    /** A list row: a label, a quieter detail and, with `onSelect`, a keyboard stop (Enter). */
+    item(options: PageItem): HTMLElement;
+    /**
+     * Rows kept by key: `set` updates the ones that stay, folds new ones open and removed ones
+     * shut, so the card's height eases and the cards below glide.
+     */
+    list(items?: readonly (PageItem & {
+        readonly key: string;
+    })[]): {
+        readonly element: HTMLElement;
+        set(items: readonly (PageItem & {
+            readonly key: string;
+        })[]): void;
+    };
+    /** Folds a row (or anything in the card) open or shut. */
+    show(element: HTMLElement, visible: boolean): void;
+    /**
+     * Folds the card down to its header (or back open, with `false`); the cards below in its
+     * column glide. Makes a card collapsible if it wasn't.
+     */
+    collapse(collapsed?: boolean): void;
+    /** Whether the card is folded to its header. */
+    readonly collapsed: boolean;
+    /** Replaces the folded header's summary (`null` clears it). */
+    summary(content: string | Node | null): void;
+    /** Empties the body. */
+    clear(): void;
+    remove(): void;
+}
+/**
+ * What's on screen elsewhere (a phone's current screen): group ids (or custom card titles) and
+ * section ids. `null` clears it.
+ */
+export interface PageHighlight {
+    readonly groups?: readonly string[];
+    readonly sections?: readonly string[];
+}
+export interface Page extends Panel {
+    /** A card of your own in the page's grid, styled by the same tokens. */
+    card(options: PageCardOptions): PageCard;
+    /**
+     * Emphasizes what's on screen: highlighted cards and sections keep full strength, with a small
+     * dot by the title of each highlighted section (or of a card highlighted on its own); the rest
+     * dims a little, readable and fully interactive (a dimmed card you focus comes back up). Every
+     * change glides on the panel spring and can be interrupted. `null` clears it.
+     *
+     * `reveal: true` glides the first highlighted card (or its section's heading) into view when
+     * it's off screen, unless the user scrolled, pressed a key or touched the page in the last two
+     * seconds, or is dragging.
+     *
+     * `expand: true` opens the folded sections and cards it highlights. What it opened folds again
+     * once a later highlight moves away from it, unless the user worked in it meanwhile (it's
+     * theirs then). Opening it this way isn't remembered: the user's own folds are.
+     */
+    highlight(target: PageHighlight | null, options?: {
+        readonly reveal?: boolean;
+        readonly expand?: boolean;
+    }): void;
+    /**
+     * Folds a foldable group's card to its header (or opens it, with `false`; toggles without
+     * `folded`). Remembered as the user's choice unless `remember: false`; `reveal` glides the card
+     * into view.
+     */
+    fold(group: string, folded?: boolean, options?: PageFoldOptions): void;
+    /**
+     * Folds a section to its heading (or opens it, with `false`; toggles without `folded`). Its
+     * cards fold away and the columns re-balance, gliding. Remembered as the user's choice unless
+     * `remember: false`; `reveal` glides the heading into view. Makes the section foldable if it
+     * wasn't.
+     */
+    foldSection(section: string, folded?: boolean, options?: PageFoldOptions): void;
+    /** Whether a section is folded to its heading (its own state; the filter's opening aside). */
+    sectionFolded(section: string): boolean;
+    /**
+     * Opens a section, or a group's card and its section, and glides it into view. By default
+     * it's for context (what's on another screen) and isn't remembered; a jump the user asked for
+     * passes `remember: true` so it stays open after a reload.
+     */
+    reveal(target: {
+        readonly section: string;
+    } | {
+        readonly group: string;
+    }, options?: {
+        readonly remember?: boolean;
+    }): void;
+    /** The page's sections in reading order, with their groups, for a navigation of your own. */
+    sections(): readonly PageSectionInfo[];
+    /**
+     * The section filling most of the window below the header, as the page scrolls; after a
+     * `reveal` (or a jump), that section until the user scrolls.
+     */
+    activeSection(): string | undefined;
+    /**
+     * Calls `listener` (after a microtask) whenever `sections()` would say something new: a fold,
+     * a changed count, a label or description, sections and groups coming or going. Returns an
+     * unsubscribe. `source` says what folded or opened something (see `PageFoldSource`); it's null
+     * for the first call and for changes that aren't folds (a value, a label).
+     */
+    onSections(listener: (sections: readonly PageSectionInfo[], source: PageFoldSource | null) => void): () => void;
+    /** Calls `listener` when `activeSection()` changes. Returns an unsubscribe. */
+    onActiveSection(listener: (section: string | undefined) => void): () => void;
+}
+/**
+ * What a change `onSections` reports came from: `"user"` a click or key on a heading or card
+ * header; `"code"` the page's methods (`fold`, `foldSection`, `reveal`, `highlight`'s expand);
+ * `"search"` the filter opening matches while it runs (`folded` keeps the saved state; the list
+ * shows what the filter shows); `"restore"` the filter clearing, everything back as it was.
+ */
+export type PageFoldSource = "user" | "code" | "search" | "restore";
+export interface PageFoldOptions {
+    /**
+     * `true` (the default) keeps it as the user's choice, across reloads (see `MountPageOptions.foldStorage`);
+     * `false` is for context and leaves what's remembered alone.
+     */
+    readonly remember?: boolean;
+    /** Glides the card or heading into view. */
+    readonly reveal?: boolean;
+}
+/** A group's card, as `page.sections()` describes it. */
+export interface PageGroupInfo {
+    readonly id: string;
+    /** Its title as the card shows it. */
+    readonly label: string;
+    /** Folded to its header (false for a group that doesn't fold). */
+    readonly folded: boolean;
+    /** How many of its rows differ from their defaults. */
+    readonly changed: number;
+    /** The group preset its values match, "Custom" when none does; null without presets. */
+    readonly preset: string | null;
+}
+/** A section, as `page.sections()` describes it. */
+export interface PageSectionInfo {
+    readonly id: string;
+    /** Its heading as the page shows it. */
+    readonly label: string;
+    readonly description?: string;
+    /** Folded to its heading (its own state: a running filter's opening doesn't count). */
+    readonly folded: boolean;
+    /** Changed rows across its groups. */
+    readonly changed: number;
+    /** Its group cards in reading order (custom cards aren't listed). */
+    readonly groups: readonly PageGroupInfo[];
+}
+export interface PageLayout {
+    /** Each showing section's label (the overlay draws their text). */
+    readonly sections: readonly PageSectionView[];
+    add(tile: HTMLElement, section: string): void;
+    /**
+     * Folds a section to its heading or opens it (making it foldable): its cards fold away or grow
+     * back, and the columns re-balance, gliding from wherever the last change had them.
+     */
+    foldSection(name: string, folded: boolean, animate?: boolean): void;
+    /** Whether a section is folded to its heading (while folds hold; see `openFolds`). */
+    isFolded(name: string): boolean;
+    /** Whether a section's heading toggles it. */
+    isFoldable(name: string): boolean;
+    /** While on (a filter runs), folded sections show their cards; call inside `change`. */
+    openFolds(open: boolean): void;
+    /** Sections with something in them, in reading order. */
+    sectionList(): readonly {
+        readonly name: string;
+        readonly label: HTMLElement | null;
+        readonly tiles: readonly HTMLElement[];
+        readonly folded: boolean;
+    }[];
+    /** The section a card sits in. */
+    sectionOf(tile: HTMLElement): string | undefined;
+    /** Re-reads each heading's label and description (the schema changed). */
+    relabel(): void;
+    /** Where a node lands once the glide has settled (its rect less its glide offset). */
+    settled(node: HTMLElement): {
+        top: number;
+        bottom: number;
+    };
+    /** Folds the card away, then takes it out of the page. */
+    remove(tile: HTMLElement): void;
+    /** Re-balances the columns when their count changed (or always, with `force`). */
+    pack(force?: boolean): void;
+    /**
+     * Applies a structural change (the filter, cards shown or hidden) and animates the result:
+     * `rows` whose `hidden` changed fold open or shut, cards glide to their new places.
+     */
+    change(mutate: () => void, rows?: readonly HTMLElement[], instant?: boolean): void;
+    /** Steps the motion now, at the start of the overlay's frame (`now` from requestAnimationFrame). */
+    frame(now: number): void;
+    /** A card's content changed at once (it was drawn `from` px tall): its height eases there. */
+    resize(tile: HTMLElement, from: number): void;
+    /** Emphasizes the cards and sections in `target` and dims the rest (see `Page.highlight`). */
+    highlight(target: PageHighlight | null): void;
+    /** Highlighted cards and section headings that show, top to bottom. */
+    highlighted(): HTMLElement[];
+    /**
+     * How a card or section heading is emphasized right now: `dim` (0 full … the token's
+     * `--k-page-dim`) and its dot (`mark` 0…1), as the DOM draws them.
+     */
+    emphasis(node: HTMLElement): {
+        readonly dim: number;
+        readonly mark: number;
+        readonly dot?: HTMLElement;
+    } | undefined;
+    /** While cards glide or change height, or something folds inside them. */
+    readonly moving: boolean;
+    readonly version: number;
+    dispose(): void;
+}
+/**
+ * Splits `heights` into at most `n` contiguous runs whose tallest is as short as possible, so
+ * reading down a column and on to the next follows the original order.
+ */
+export declare function balancedRuns(heights: readonly number[], n: number, gap?: number): number[];
+export interface PageColumnItem {
+    readonly height: number;
+    /** Cards of a section are contiguous; sections are numbered in reading order. */
+    readonly section: number;
+    /**
+     * A folded section's heading, standing for the whole section (whose `label` is 0): it gets
+     * `space` above it when it follows another section in a column.
+     */
+    readonly head?: boolean;
+}
+export type PageColumnEntry = {
+    readonly kind: "label";
+    readonly section: number;
+    readonly continued: boolean;
+} | {
+    readonly kind: "card";
+    readonly index: number;
+};
+export interface PageColumn {
+    /** The column holds items `start` to `end - 1`. */
+    readonly start: number;
+    readonly end: number;
+    readonly height: number;
+    /** Top to bottom: a label over each section's first card here, then the cards. */
+    readonly entries: readonly PageColumnEntry[];
+}
+/**
+ * Lays a page's cards into `n` independent columns that keep their reading order (down a
+ * column, then the next). A column holds part of one section (a long section takes several
+ * adjacent columns) or several whole sections stacked; it never ends one section and starts
+ * another midway. The tallest column is as short as possible, and the rest as even as they can
+ * be. Each column opens with its section's label (`continued` when the section began in the
+ * column before); a section stacked below another gets a label and `space` above it.
+ */
+export declare function pageColumns(items: readonly PageColumnItem[], n: number, options?: {
+    readonly gap?: number;
+    /** A section's label height (0 for none). */
+    readonly label?: (section: number) => number;
+    readonly space?: number;
+}): PageColumn[];
+/** A disclosure chevron: it points right while folded and down while open (see .knobs-caret). */
+export declare function caretIcon(doc: Document): SVGSVGElement;
+/** A section's heading as the GPU overlay draws it. */
+export interface PageSectionView {
+    readonly element: HTMLElement;
+    readonly head: HTMLElement | null;
+    readonly name?: HTMLElement;
+    readonly summary?: HTMLElement;
+    readonly desc?: HTMLElement;
+    readonly caret?: SVGElement;
+}
+export declare function createPageLayout(doc: Document, host: HTMLElement, options: {
+    order: readonly string[];
+    columnWidth: number;
+    /** What a section's heading says (its name by default). */
+    sectionLabel?(name: string): string;
+    /** The muted line under a section's heading, if any. */
+    sectionDescription?(name: string): string | undefined;
+    /** How a section starts: folded or open, or undefined when it doesn't fold. */
+    sectionFold?(name: string): boolean | undefined;
+    /** Cards moved in the DOM (re-sort anything kept in page order). */
+    onLayout(): void;
+    /** Motion started or settled (the overlay re-reads rects). */
+    wake(): void;
+}): PageLayout;
+/**
+ * A card's title without its section's name repeated in front: "Transcript · Arrivals" under
+ * Transcript reads "Arrivals". `prefixes` are what the section is called (its id and label); the
+ * name has to be followed by a separator (· • : / | › » or a dash), and something has to remain.
+ */
+export declare function cardTitle(title: string, prefixes: readonly string[]): string;
+/** Whether a field, group or card answers the filter: every word appears somewhere in `text`. */
+export declare function matchesFilter(query: string, ...text: (string | undefined)[]): boolean;
+/** A custom card's fold, as the page drives it (see `Page.highlight`'s `expand`). */
+export interface CustomCardFold {
+    readonly tile: HTMLElement;
+    readonly folded: boolean;
+    readonly collapsible: boolean;
+    /** Folds or opens it, remembering it as the user's choice only with `remember`. */
+    fold(folded: boolean, remember: boolean): void;
+}
+export declare function createCustomCard(doc: Document, options: PageCardOptions, hooks: {
+    wake(): void;
+    remove(tile: HTMLElement): void;
+    /** What the header shows for `title` (a repeated section prefix dropped). */
+    title?(title: string): string;
+    /** The card's content changed at once (it was `from` px tall): its height eases there. */
+    resize?(tile: HTMLElement, from: number): void;
+    /** Where a collapsible card's state is remembered, by title. */
+    folded?: {
+        get(title: string): boolean | undefined;
+        set(title: string, folded: boolean): void;
+    };
+    /** Hands the page a way to fold the card without remembering it (a highlight's expand). */
+    register?(card: CustomCardFold): void;
+}): PageCard;

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

@@ -0,0 +1,43 @@
+import { type Schema } from "../core/schema.js";
+import type { Controls, MountPanelOptions } from "../core/store.js";
+import { type MountPageOptions, type Page } from "./page.js";
+import { type PresetStrip } from "./presets.js";
+export interface Panel {
+    element: HTMLElement;
+    presetStrip: PresetStrip;
+    focus(): void;
+    /** Collapses the panel into its chip (or fades it out), then disposes it. */
+    dismiss(): void;
+    /** Reverses a collapse still in flight; false once there's none to reverse. */
+    reopen(): boolean;
+    /** Asks `rowAccessory` again for every row, e.g. after a pin changed elsewhere. */
+    updateAccessories(): void;
+    /** Folds (`true`) or opens a foldable group's card; toggles without `folded`. */
+    fold(group: string, folded?: boolean): void;
+    /** Shows tab `id` (when given) and returns the tab shown, if the panel has tabs. */
+    tab(id?: string): string | undefined;
+    /**
+     * Searches for `query` (when given) with exactly `chips` on (when given), as typing and clicking
+     * would, and returns what the search holds now; undefined without `search`.
+     */
+    search(query?: string, chips?: readonly string[]): PanelSearch | undefined;
+    dispose(): void;
+}
+/** A panel's search: the query as typed and the chips that are on. */
+export interface PanelSearch {
+    readonly query: string;
+    readonly chips: readonly string[];
+}
+/** "synth-voice" → "Synth voice", "knobsTokens" → "Knobs tokens"; titles with spaces are kept. */
+export declare function readableTitle(id: string): string;
+export declare function createPanel<S extends Schema>(controls: Controls<S>, anchor: HTMLElement, close: () => void, options?: MountPanelOptions & {
+    readonly restored?: boolean;
+    readonly chip?: HTMLElement;
+}): Panel;
+export declare function mountPanel<S extends Schema>(controls: Controls<S>, container: HTMLElement, options?: MountPanelOptions): Panel;
+/**
+ * A full page of controls: sections of group cards in balanced columns under a sticky header
+ * (title, presets, Random, Reset, Copy, undo and redo). Groups show their numbered presets;
+ * `page.card()` adds cards of your own.
+ */
+export declare function mountPage<S extends Schema>(controls: Controls<S>, container: HTMLElement, options?: MountPageOptions): Page;

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

@@ -0,0 +1,5 @@
+import { type StoragePort } from "../core/storage.js";
+export declare function positionPanel(panel: HTMLElement, header: HTMLElement, anchor: HTMLElement, id: string, storage: () => StoragePort | null): {
+    constrain: () => void;
+    dispose(): void;
+};

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

@@ -0,0 +1,28 @@
+import type { PanelCommand, PanelKeys } from "../core/store.js";
+/** How a panel reads keys that aren't commands (see `PanelKeys`): resolved once per panel. */
+export interface KeyPrefs {
+    /** j/k and h/l as aliases for the arrows. */
+    readonly vim: boolean;
+    /** Digits, `.`, `-` and Enter on a slider open its inline number editor. */
+    readonly edit: boolean;
+    /** What ⇧ multiplies a step by. */
+    readonly bigStep: number;
+    /** ↑/↓ wrap from the last row to the first. */
+    readonly wrap: boolean;
+}
+export declare const DEFAULT_PREFS: KeyPrefs;
+export declare const setKeyPrefs: (root: Element, prefs: KeyPrefs) => WeakMap<Element, KeyPrefs>;
+/** The preferences of the panel `node` sits in. */
+export declare function keyPrefs(node: EventTarget | null): KeyPrefs;
+/** -1, 1 or 0 for ←/→ (and h/l unless the panel turned the letter aliases off). */
+export declare function arrowOf(event: KeyboardEvent): -1 | 0 | 1;
+/** ⇧'s multiplier for this event (1 without ⇧). */
+export declare const bigOf: (event: KeyboardEvent) => number;
+/**
+ * The keys each command answers to. An explicit binding wins: a default that collides with one
+ * is dropped (`{ hint: "f" }` takes `f` from "first row"). `presets` takes two characters, back
+ * then forward (`"[]"`).
+ */
+export declare function resolveKeys(given: PanelKeys | undefined, page?: boolean): Record<PanelCommand, string[]>;
+/** How a key reads in the shortcuts popover. */
+export declare function keyLabel(key: string, alt?: boolean): string;

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

@@ -0,0 +1,48 @@
+import { type Schema } from "../core/schema.js";
+import type { Controls } from "../core/store.js";
+import { Edges, Spring } from "./motion.js";
+export interface PresetEntry<V = Record<string, unknown>> {
+    readonly id: string;
+    readonly kind: "preset" | "variant";
+    readonly rawId: string;
+    readonly label: string;
+    readonly values: V;
+    apply(): void;
+}
+export interface ActivePresetState {
+    readonly activeId: string;
+    readonly activeIndex: number;
+    readonly isCustom: boolean;
+}
+/**
+ * Resolves which preset or variant is currently active.
+ * Honors `lastAppliedId` when its values still match `currentValues`, so cycling never gets
+ * stuck when a saved variant has the exact same values as a built-in preset.
+ */
+export declare function resolveActivePresetEntry<V extends Record<string, any>>(entries: readonly PresetEntry<V>[], currentValues: V, lastAppliedId: string | null): ActivePresetState;
+export declare function nextPresetIndex(count: number, activeIndex: number, direction: number): number;
+export interface PresetStrip {
+    readonly element: HTMLElement;
+    readonly track: HTMLElement;
+    readonly pill: HTMLElement;
+    /** Trailing "+" chip that saves the current values as a new variant (absent when variants are off). */
+    readonly saveButton: HTMLButtonElement | null;
+    /** The selected pill's left and right edges (track px); the edge facing the move leads. */
+    readonly pillEdges: Edges;
+    readonly pillY: Spring;
+    readonly pillAlpha: Spring;
+    getEntries(): readonly PresetEntry<any>[];
+    getButtons(): readonly HTMLButtonElement[];
+    getActiveState(): ActivePresetState;
+    cycle(direction: -1 | 1): void;
+    selectById(id: string): void;
+    /** Saves the current values as "Variant N"; returns a status message. */
+    save(): string;
+    /** Deletes the selected chip when it's a saved variant; returns a status message. */
+    deleteActive(): string | undefined;
+    update(): void;
+    dispose(): void;
+}
+export declare function createPresetStrip<S extends Schema>(doc: Document, controls: Controls<S>, showVariants: boolean, run: (action: () => unknown) => void, onAfterChange?: () => void, 
+/** What a preset's chip says (its id stays its identity); `controls.presetLabel` by default. */
+presetLabel?: (id: string) => string): PresetStrip;

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

@@ -0,0 +1,14 @@
+import type { CurveField, GradientField } from "../core/schema.js";
+import { type EditorRow, type RowContext } from "./editors.js";
+/** The custom properties a gradient strip's samples ride on (registered, so they transition). */
+export declare const GRADIENT_VARS: string[];
+/**
+ * A gradient: a swatch strip with stop ticks in the head; a wide strip with a handle per stop, the
+ * selected stop's colour strips and any presets in the body.
+ */
+export declare function gradientRow(c: RowContext<GradientField>): EditorRow;
+/**
+ * A curve: its name (when it's a preset) and a mini curve in the head; a graph with a grid,
+ * draggable points and a hover crosshair, and shape chips, in the body.
+ */
+export declare function curveRow(c: RowContext<CurveField>): EditorRow;

package/dist/types/panel/readout-row.d.ts

@@ -0,0 +1,21 @@
+import type { ReadoutState } from "../core/readout.js";
+import type { ReadoutField } from "../core/schema.js";
+import { type ReadoutView } from "../ui/readouts.js";
+import type { EditorRow } from "./editors.js";
+import type { RowWave } from "./gpu/renderer.js";
+export interface ReadoutRow extends EditorRow {
+    readonly view: ReadoutView;
+    /** Something new arrived for this key. */
+    notify(): void;
+    swap(field: ReadoutField, display: string): void;
+}
+export declare function readoutRow(c: {
+    doc: Document;
+    key: string;
+    display: string;
+    field: ReadoutField;
+    state: ReadoutState;
+    wave: RowWave;
+    wake(): void;
+    gpu(): boolean;
+}): ReadoutRow;

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

@@ -0,0 +1,15 @@
+export declare const isAnyRevealing: () => boolean;
+export declare const isRevealingIn: (root: HTMLElement) => boolean;
+export declare const getRevealVersion: () => number;
+export declare const isRevealing: (node: HTMLElement) => boolean;
+/**
+ * Eases an in-flow element from height `from` to the height it has now, after its content
+ * changed, so what's below glides. Read `from` before the change (mid-flight is fine).
+ */
+export declare function resize(node: HTMLElement, from: number): void;
+/**
+ * Shows or hides an in-flow element by animating its height (and margins/padding) open or shut,
+ * so the content below glides instead of jumping. Interruptible: reversing mid-flight continues
+ * from the current height.
+ */
+export declare function reveal(node: HTMLElement, show: boolean, after?: () => void, delay?: number): void;

package/dist/types/panel/rolling-css.d.ts

@@ -0,0 +1,2 @@
+declare const _default: ".rn-root {\n  display: inline-block;\n  position: relative;\n  white-space: pre;\n  unicode-bidi: isolate;\n  vertical-align: baseline;\n}\n.rn-root > .rn-measure,\n.rn-root > .rn-visual { display: none; }\n.rn-root[data-rn-measuring] > .rn-measure {\n  display: inline-flex;\n  position: relative;\n  visibility: hidden;\n  white-space: pre;\n  padding: 0;\n  border: 0;\n}\n.rn-token { display: inline-block; padding: 0; border: 0; }\n.rn-root[data-rn-measuring] > .rn-value,\n.rn-react[data-rn-hydrated] > .rn-semantic,\n.rn-solid[data-rn-hydrated] > .rn-semantic {\n  position: absolute;\n  inset: 0;\n  padding: 0;\n  margin: 0;\n  color: transparent;\n  z-index: 1;\n}\n/* A single native text layer is selectable; decorative reels never enter a copy. */\n.rn-value::selection, .rn-semantic::selection {\n  color: HighlightText;\n  background: Highlight;\n}\n.rn-root[data-rn-ready] > .rn-visual {\n  display: block;\n  position: absolute;\n  inset: 0;\n  pointer-events: none;\n  user-select: none;\n}\n.rn-slot {\n  position: absolute;\n  left: 0;\n  overflow: hidden;\n  /* Space for italic overhang without changing the measured advance width. */\n  box-sizing: content-box;\n  padding-inline: 0.15em;\n  margin-inline-start: -0.15em;\n  -webkit-mask-image: var(--rn-mask, linear-gradient(\n    to bottom,\n    transparent,\n    #000 var(--rn-edge-fade, 0.12em),\n    #000 calc(100% - var(--rn-edge-fade, 0.12em)),\n    transparent\n  ));\n  mask-image: var(--rn-mask, linear-gradient(\n    to bottom,\n    transparent,\n    #000 var(--rn-edge-fade, 0.12em),\n    #000 calc(100% - var(--rn-edge-fade, 0.12em)),\n    transparent\n  ));\n  -webkit-mask-repeat: no-repeat;\n  mask-repeat: no-repeat;\n}\n@supports (overflow: clip) {\n  .rn-slot { overflow-x: visible; overflow-y: clip; }\n}\n.rn-slot:not([data-rn-wheel]) {\n  overflow: visible;\n  -webkit-mask-image: none;\n  mask-image: none;\n}\n.rn-enter, .rn-reel, .rn-face { display: block; }\n.rn-reel { position: relative; }\n.rn-ink { display: block; position: absolute; inset: 0; will-change: transform; }\n/* Safari's SVG filter must rasterize the smear's descendants into its input. */\n.rn-smear .rn-ink { will-change: auto; }\n/* Each turning half carries its own perspective transform, not a shared 3D scene. */\n/* The slot acts as the bezel: the card stays vertically framed while it hinges. */\n.rn-slot[data-rn-flap] { -webkit-mask-image: none; mask-image: none; }\n/* Hinged faces must occlude the cards behind them, including with default CSS. */\n:where(.rn-slot[data-rn-flap]) .rn-face { background: var(--rn-flap-background, Canvas); }\n.rn-flap { position: absolute; inset: 0; transform-origin: 50% 50%; backface-visibility: hidden; }\n/* --rn-crease is the visible hinge gap between the two halves. */\n.rn-flap-top { clip-path: inset(0 0 calc(50% + var(--rn-crease, 1px) / 2) 0); }\n.rn-flap-bottom { clip-path: inset(calc(50% + var(--rn-crease, 1px) / 2) 0 0 0); }\n.rn-sharp, .rn-smear { display: block; }\n.rn-smear { position: absolute; inset: 0; pointer-events: none; }\n.rn-blur-defs { position: absolute; width: 0; height: 0; overflow: hidden; }\n.rn-face { text-align: center; white-space: pre; }\n.rn-react, .rn-solid { display: inline-block; position: relative; white-space: pre; unicode-bidi: isolate; }\n.rn-mount { display: inline-block; user-select: none; }\n.rn-mount .rn-value { pointer-events: none; }\n.rn-react:not([data-rn-hydrated]) > .rn-mount,\n.rn-solid:not([data-rn-hydrated]) > .rn-mount { display: none; }\n";
+export default _default;

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

@@ -0,0 +1,36 @@
+export interface SearchChipSpec {
+    readonly id: string;
+    readonly label: string;
+    readonly count?: boolean;
+}
+/**
+ * A panel's search field: a text field that filters rows as you type, and filter chips beside it
+ * ("Modified 3") that narrow them further. It's drawn by the DOM in both renderers.
+ */
+export interface SearchBar {
+    readonly element: HTMLElement;
+    readonly input: HTMLInputElement;
+    readonly chips: readonly HTMLButtonElement[];
+    /** The trimmed query, lower-cased. */
+    query(): string;
+    /** The chips that are on. */
+    active(): ReadonlySet<string>;
+    /** Whether anything narrows the rows (a query or a chip). */
+    filtering(): boolean;
+    /** Shows each counted chip's number. */
+    counts(counts: ReadonlyMap<string, number>): void;
+    /** Empties the query and turns the chips off. */
+    clear(): void;
+    /** Sets the query as typed, and (when given) exactly which chips are on. */
+    set(query: string | undefined, chips?: readonly string[]): void;
+    focus(): void;
+}
+export declare function createSearch(doc: Document, options: {
+    placeholder: string;
+    chips: readonly SearchChipSpec[];
+    change(): void;
+}): SearchBar;
+/** Where `query` matches in `text` (case-insensitive), as [start, end), or undefined. */
+export declare function matchSpan(text: string, query: string): [number, number] | undefined;
+/** Writes `text` into `label`, with the matched span wrapped in `<mark class="knobs-match">`. */
+export declare function markLabel(label: HTMLElement, text: string, span: [number, number] | undefined): void;