@kitlangton/knobs 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,258 @@
+import type { CurveInterp, CurvePoint, GradientSpace, GradientStop } from "./ramp.js";
+import { type Field, type FieldMeta, type GraphSeries, type GraphThreshold, type ToolbarShortcut, type Schema, type State, type Value } from "./schema.js";
+import type { SpringValue } from "./spring.js";
+import type { StoragePort } from "./storage.js";
+import { type ChangeMeta, type GestureEvent, type ControlAction, type GroupPreset, type Controls, type DensityMode, type GroupPresetDisplay, type HostHistory, type PanelKeys, type PersistMode, type PanelModule, type RendererMode, type SectionFolded, type ThemeMode } from "./store.js";
+/** A choice option with its own label: `{ id: "md", label: "Medium" }` (`value` works for `id`). */
+export interface ChoiceOption {
+    readonly id?: string;
+    readonly value?: string;
+    readonly label?: string;
+}
+interface DescriptorMeta extends FieldMeta {
+    readonly key: string;
+}
+/**
+ * Two flat number keys drawn as one spring card (a curve and two sliders). Values stay flat:
+ * `onSet("duration", 0.4)`, `values.bounce`. When the bound keys have number descriptors of their
+ * own, their ranges, labels and defaults are used (and they aren't drawn again); otherwise the
+ * spring's `default` and the standard spring ranges are.
+ */
+export interface SpringBindingDescriptor extends DescriptorMeta {
+    readonly kind: "spring";
+    readonly bind: {
+        readonly duration: string;
+        readonly bounce: string;
+    };
+    readonly default?: SpringValue;
+}
+/** A button row: pressing it calls `onAction(key)`. */
+export interface ActionDescriptor extends DescriptorMeta {
+    readonly kind: "action";
+    readonly default?: undefined;
+    readonly bind?: undefined;
+}
+/** A row of buttons; pressing one calls `onAction(item.key)`. */
+export interface ToolbarDescriptor extends DescriptorMeta {
+    readonly kind: "toolbar";
+    readonly items: readonly {
+        readonly key: string;
+        readonly label: string;
+        readonly icon?: string;
+        readonly shortcut?: string | ToolbarShortcut;
+        readonly global?: boolean;
+        readonly disabled?: boolean;
+    }[];
+    readonly default?: undefined;
+    readonly bind?: undefined;
+}
+/**
+ * A readout row (`watch`, `sparkline`, `graph`, `meter`, `table`, `log`): it shows what
+ * `controls.watch(key, value)` pushes and holds no value. Options as their field constructors take.
+ */
+export interface ReadoutDescriptor extends DescriptorMeta {
+    readonly kind: "watch" | "sparkline" | "graph" | "meter" | "table" | "log";
+    readonly unit?: string;
+    readonly decimals?: number;
+    readonly hz?: number;
+    readonly min?: number;
+    readonly max?: number;
+    readonly history?: number;
+    readonly height?: number;
+    readonly color?: string;
+    readonly series?: readonly (GraphSeries | string)[];
+    readonly thresholds?: readonly (GraphThreshold | number)[];
+    readonly segments?: number;
+    readonly warn?: number;
+    readonly critical?: number;
+    readonly columns?: readonly string[];
+    readonly lines?: number;
+    readonly get?: () => unknown;
+    readonly format?: (value: number) => string;
+    readonly default?: undefined;
+    readonly bind?: undefined;
+}
+export type ControlDescriptor = ValueDescriptor | SpringBindingDescriptor | ActionDescriptor | ToolbarDescriptor | ReadoutDescriptor;
+export interface ValueDescriptor extends DescriptorMeta {
+    readonly bind?: undefined;
+    readonly kind: "knob" | "number" | "choice" | "toggle" | "bool" | "spring" | "color" | "point" | "easing" | "vec2" | "vec3" | "range" | "angle" | "seed" | "keybind" | "gradient" | "curve";
+    /**
+     * Springs take `{ duration, bounce }`, colours a CSS string, points and vec2 `{ x, y }`, vec3
+     * `{ x, y, z }`, easings `[x1, y1, x2, y2]`, ranges `[low, high]`, keybinds a combination
+     * string (`"Meta+K"`), gradients `[{ at, color }]` and curves `[{ x, y }]`.
+     */
+    readonly default: Value;
+    readonly min?: number;
+    readonly max?: number;
+    readonly step?: number;
+    readonly unit?: string;
+    /** Readout digits after the point (the step's own by default). */
+    readonly decimals?: number;
+    /** Choices: segments or a drop-down menu (see `Choice.display`); automatic by default. */
+    readonly display?: "menu" | "segmented";
+    /** Strings, or `{ id, label }` options; past four, or when they don't fit, a menu. */
+    readonly choices?: readonly (string | ChoiceOption)[];
+    readonly options?: readonly (string | ChoiceOption)[];
+    readonly swiftType?: string;
+    /** Vectors: show the link toggle for uniform scaling (`linked` starts it on). */
+    readonly link?: boolean;
+    readonly linked?: boolean;
+    /** Vectors: what the cells are called (`["x", "z"]`), their letters and accessible names. */
+    readonly axes?: readonly string[];
+    /** Angles: carry past the ends a whole turn (on for a full turn by default). */
+    readonly wrap?: boolean;
+    /** Gradients: blend in `oklab` (default) or `srgb`. */
+    readonly space?: GradientSpace;
+    /** Curves: the y range, `[0, 1]` by default (`min` and `max` work too). */
+    readonly range?: readonly [number, number];
+    /** Curves: `smooth` (monotone cubic, default), `linear` or `step`. */
+    readonly interp?: CurveInterp;
+    /** Curves: `false` hides the built-in shape chips. */
+    readonly shapes?: boolean;
+    /** Gradients and curves: named ramps or shapes offered as chips. */
+    readonly presets?: Readonly<Record<string, readonly GradientStop[] | readonly CurvePoint[]>>;
+}
+export interface RemoteControlsOptions {
+    readonly enabled?: boolean | (() => boolean);
+    /** Ships the panel as product UI, live in production: `() => import("knobs/panel")` (see `ControlsOptions.ship`). */
+    readonly ship?: () => Promise<PanelModule>;
+    /** How long (ms) a key changed here outranks incoming values for it; 600 by default. */
+    readonly echo?: number;
+    /**
+     * `onSet` sends `null` when a key returns to its default (and a key's reset is an `onSet` of
+     * `null` too), as the socket protocol expects. `false` sends the value itself, and resets reach
+     * only `onReset`.
+     */
+    readonly nullDefaults?: boolean;
+    readonly values?: State;
+    readonly presets?: Readonly<Record<string, State>>;
+    /** Numbered presets per group, e.g. the phone's preset sets (see `ControlsOptions.groupPresets`). */
+    readonly groupPresets?: Readonly<Record<string, readonly GroupPreset[]>>;
+    /** Display labels by group id, section id and preset id (see `ControlsOptions.groupLabels`). */
+    readonly groupLabels?: Readonly<Record<string, string>>;
+    readonly sectionLabels?: Readonly<Record<string, string>>;
+    readonly presetLabels?: Readonly<Record<string, string>>;
+    /** Shorthand for `presetLabels.default`, e.g. "Native". */
+    readonly defaultLabel?: string;
+    /** How a page card shows its group presets (see `ControlsOptions.groupPresetDisplay`). */
+    readonly groupPresetDisplay?: GroupPresetDisplay;
+    /** One muted line under a group's card title or a section's heading on a page, by id. */
+    readonly groupDescriptions?: Readonly<Record<string, string>>;
+    readonly sectionDescriptions?: Readonly<Record<string, string>>;
+    /** How groups and a page's sections start, folded or open (see `ControlsOptions.groupFolded`). */
+    readonly groupFolded?: Readonly<Record<string, boolean>>;
+    readonly sectionFolded?: SectionFolded;
+    readonly actions?: readonly ControlAction<State>[];
+    readonly storage?: StoragePort | null;
+    /** What `storage` keeps (see `ControlsOptions.persist`). */
+    readonly persist?: PersistMode;
+    /** What Random and Mutate draw from (see `ControlsOptions.random`). */
+    readonly random?: () => number;
+    /** Whether Random and Mutate may change a key (see `ControlsOptions.tunable`). */
+    readonly tunable?: (key: string, values: State) => boolean;
+    /** An undo stack the host owns (see `HostHistory`). */
+    readonly history?: HostHistory;
+    readonly theme?: ThemeMode;
+    readonly density?: DensityMode;
+    readonly renderer?: RendererMode;
+    /** Default key bindings for its panels (see `MountPanelOptions.keys`). */
+    readonly keys?: PanelKeys;
+    /** `false`: its panels show no modified marks or resets (see `MountPanelOptions.marks`). */
+    readonly marks?: boolean;
+    readonly onSet?: (key: string, value: Value | null, meta: ChangeMeta) => void;
+    /**
+     * A change of several keys at once (a preset, Random, Mutate, resetting a selection, undoing or
+     * redoing any of them), in one call instead of an `onSet` per key. The entries are what `onSet`
+     * would have received, `null` again meaning back to the default. A change of one key still goes
+     * to `onSet`, or here as a single entry when there's no `onSet`. Resetting everything or a
+     * group stays `onReset`'s, as with `onSet`.
+     */
+    readonly onSetBatch?: (changes: Array<{
+        key: string;
+        value: Value | null;
+    }>, meta: ChangeMeta) => void;
+    /** A key went into the hand or out of it: a drag, an inline edit, a burst of arrow keys. */
+    readonly onGesture?: (event: GestureEvent) => void;
+    /** A key, a group, or (`{}`) everything was reset. */
+    readonly onReset?: (target: {
+        key?: string;
+        group?: string;
+    }) => void;
+    /** An action row was pressed. */
+    readonly onAction?: (key: string) => void;
+    /**
+     * A group preset was chosen. When given, the peer applies its own preset (and sends back its
+     * state) instead of receiving `onSet` for each key.
+     */
+    readonly onPreset?: (target: {
+        group: string;
+        index: number;
+        name: string;
+    }) => void;
+}
+export interface RemoteControls extends Controls<Schema> {
+    readonly descriptors: readonly ControlDescriptor[];
+    /**
+     * Swaps in another set of descriptors (another variation, another item) without tearing the
+     * panel down. Rows with the same key keep their DOM and spring to their new value; new rows
+     * enter and missing ones leave. `values` are the complete values (missing keys sit at their
+     * defaults), held back for any key in hand as `sync` does.
+     *
+     * Undo history starts over when the descriptors change shape or `land` is set: it belonged to
+     * the previous set. `land: true` (a different item arrived) also places every value at once,
+     * without springing or rolling. `mixed` names the keys whose values differ across a
+     * multi-selection (see `SyncOptions.mixed`).
+     */
+    update(descriptors: readonly ControlDescriptor[], values?: State, options?: {
+        land?: boolean;
+        mixed?: readonly string[];
+    }): void;
+    swift(group?: string): string;
+}
+export declare function descriptorToField(d: ControlDescriptor): Field;
+/**
+ * Converts descriptors into a schema. A spring binding becomes its two flat number fields, at the
+ * binding's place (their own descriptors, if any, give their ranges and labels).
+ */
+export declare function fromDescriptors(descriptors: readonly ControlDescriptor[]): Schema;
+export declare function formatSwift(descriptors: readonly ControlDescriptor[], values: State, group?: string): string;
+export declare function createRemoteControls(id: string, descriptors: readonly ControlDescriptor[], options?: RemoteControlsOptions): RemoteControls;
+/** A titled section of settings, as a hosted prototype reports them (viewer.js `pv:settings`). */
+export interface SettingsGroup {
+    readonly title?: string;
+    readonly items: readonly SettingsItem[];
+}
+export type SettingsItem = {
+    readonly id: string;
+    readonly label: string;
+    readonly kind: "choice";
+    readonly choices: readonly {
+        readonly id: string;
+        readonly label?: string;
+    }[];
+    readonly value?: string | null;
+} | {
+    readonly id: string;
+    readonly label: string;
+    readonly kind: "toggle";
+    readonly value?: boolean;
+} | {
+    readonly id: string;
+    readonly label: string;
+    readonly kind: "action";
+    readonly value?: boolean;
+};
+/**
+ * Settings sections as descriptors and values, one row per item: choices (a menu past four
+ * options), switches and buttons, each section's title its group.
+ *
+ * The prototype owns these values, so each setting's default is its `home`: the value the
+ * prototype first reported. Pass the first call's `values` back as `home` (merging in settings
+ * that appear later) so the shape stays put while the values move; without it, the values
+ * reported now are the defaults.
+ */
+export declare function fromSettings(groups: readonly SettingsGroup[], home?: State): {
+    descriptors: ControlDescriptor[];
+    values: State;
+};
+export {};