@kitlangton/knobs 0.0.0-stage → 0.2.0

package/dist/types/ui/react.d.ts

@@ -0,0 +1,72 @@
+import { type CSSProperties, type ReactNode } from "react";
+import { type Activity as ActivityHandle, type ActivityOptions } from "./activity.js";
+import { type Bento as BentoHandle, type BentoOptions } from "./bento.js";
+import { type OptionPicker as OptionPickerHandle, type OptionPickerOptions, type PickerOption } from "./picker.js";
+import { type Split as SplitHandle, type SplitOptions } from "./split.js";
+import { type Timeline as TimelineHandle, type TimelineOptions } from "./timeline.js";
+import { type Tree as TreeHandle, type TreeOptions } from "./tree.js";
+export type SplitProps = SplitOptions & {
+    /** One child per pane, in the panes' order; each renders into its pane's body. */
+    children?: ReactNode;
+    className?: string;
+    style?: CSSProperties;
+    onReady?: (split: SplitHandle) => void;
+};
+/** `split()` as a component: its children portal into the panes. */
+export declare function Split(props: SplitProps): import("react").JSX.Element;
+export type TreeProps<T> = TreeOptions<T> & {
+    className?: string;
+    style?: CSSProperties;
+    onReady?: (tree: TreeHandle<T>) => void;
+};
+/**
+ * `tree()` as a component. New `items` update it in place (rows glide); `selection` and
+ * `filter` follow their props; callbacks always call the latest props.
+ */
+export declare function Tree<T>(props: TreeProps<T>): import("react").JSX.Element;
+export type TimelineProps = TimelineOptions & {
+    className?: string;
+    style?: CSSProperties;
+    onReady?: (timeline: TimelineHandle) => void;
+};
+/**
+ * `timeline()` as a component. `time`, `playing`, `markers`, `ranges`, `duration`, `fps`,
+ * `units` and `speed` follow their props (a `time` it reported itself is left alone); callbacks
+ * always call the latest props.
+ */
+export declare function Timeline(props: TimelineProps): import("react").JSX.Element;
+export type BentoProps = BentoOptions & {
+    className?: string;
+    style?: CSSProperties;
+    onReady?: (bento: BentoHandle) => void;
+};
+/**
+ * `bento()` as a component. New `items` update it in place (tiles glide); `picks` follows its
+ * prop; callbacks always call the latest props.
+ */
+export declare function Bento(props: BentoProps): import("react").JSX.Element;
+export type ActivityProps = ActivityOptions & {
+    className?: string;
+    style?: CSSProperties;
+    onReady?: (activity: ActivityHandle) => void;
+};
+/**
+ * `activity()` as a component. New `events` update it in place (rows keep their identity and
+ * glide); `selected` follows its prop; callbacks always call the latest props.
+ */
+export declare function Activity(props: ActivityProps): import("react").JSX.Element;
+export type OptionPickerProps = Omit<OptionPickerOptions, "body"> & {
+    /** An option's parameters, portalled under it the first time it opens (a `<Knobs>` panel, say). */
+    children?: (option: PickerOption) => ReactNode;
+    className?: string;
+    style?: CSSProperties;
+    onReady?: (picker: OptionPickerHandle) => void;
+};
+/**
+ * `optionPicker()` as a component: `children` renders each opened option's parameters into its
+ * place through a portal, so context and state carry through. `options`, `selected` and
+ * `chosen` follow their props; callbacks always call the latest props.
+ */
+export declare function OptionPicker(props: OptionPickerProps): import("react").JSX.Element;
+export type { ActivityEvent } from "./activity-model.js";
+export type { PickerOption } from "./picker.js";

package/dist/types/ui/readout-css.d.ts

@@ -0,0 +1 @@
+export declare const readoutCss = "\n/* Readouts: live values, sparklines, graphs, meters, tables and logs. */\n:where(.knobs-ui) :is(.knobs-rd-chip,.knobs-rd-copy,.knobs-rd-jump,.knobs-rd-find,.knobs-rd-match){all:revert;box-sizing:border-box;\n  font:inherit;color:inherit;letter-spacing:inherit;background:transparent;border:0;border-radius:0;margin:0;padding:0;min-width:0;box-shadow:none;outline:none}\n.knobs-ui.knobs-rd,.knobs-rd *{box-sizing:border-box}\n.knobs-ui.knobs-rd{display:flex;align-items:center;gap:8px;min-width:0;color:var(--ku-text);letter-spacing:normal}\n.knobs-rd .knobs-rd-v{font:var(--ku-font-weight) var(--ku-value-size)/1.25 var(--ku-value-font);font-variant-numeric:tabular-nums;font-feature-settings:\"tnum\";white-space:nowrap}\n.knobs-rd .knobs-rd-mono{font:400 var(--ku-text-meta)/1.25 var(--ku-mono);font-variant-numeric:tabular-nums;white-space:pre}\n.knobs-rd .knobs-rd-meta{font:var(--ku-font-weight) var(--ku-text-meta)/1.25 var(--ku-font);white-space:nowrap}\n.knobs-rd .knobs-rd-value{display:inline-flex;justify-content:flex-end;align-items:baseline;flex:none;margin-left:auto;contain:layout paint style}\n.knobs-rd .knobs-rd-num{color:var(--ku-text);text-align:right;transition:color .15s}\n.knobs-rd .knobs-rd-unit{margin-left:var(--k-unit-gap,.28em);color:var(--ku-dim)}\n.knobs-rd .knobs-rd-unit[hidden]{display:none}\n.knobs-rd.knobs-rd-watch{flex:1 1 auto;justify-content:flex-end}\n.knobs-rd.knobs-rd-spark,.knobs-rd.knobs-rd-meter{flex:0 1 64%;margin-left:auto}\n.knobs-rd .knobs-rd-plot{display:block;flex:1 1 0;min-width:24px;height:max(12px,calc(var(--ku-control-h) - 2px))}\n.knobs-rd.knobs-rd-meter>.knobs-rd-plot{height:8px}\n.knobs-rd.knobs-rd-spark[data-hover] .knobs-rd-num{color:var(--ku-label)}\n.knobs-rd .knobs-rd-cap,.knobs-rd .knobs-rd-head>span:first-child{min-width:0;overflow:hidden;text-overflow:ellipsis;white-space:nowrap;color:var(--ku-label);font-weight:var(--ku-label-weight)}\n\n/* Blocks: a head line (the label and what goes with it) over a body. In a panel the row grows to fit. */\n.knobs-panel .knobs-row.knobs-rd-rowblock{display:block;height:auto}\n.knobs-rd.knobs-rd-block{display:flex;flex-direction:column;align-items:stretch;gap:2px;width:100%}\n.knobs-rd .knobs-rd-head{display:flex;align-items:center;gap:0 10px;min-height:var(--ku-row);min-width:0}\n/* The title keeps its words; the legend or tools beside it give way (see fitHead). */\n.knobs-rd .knobs-rd-head>span:first-child{flex:0 0 auto;max-width:100%}\n.knobs-rd .knobs-rd-legend{display:flex;align-items:center;gap:12px;margin-left:auto;min-width:0;overflow:hidden}\n.knobs-rd .knobs-rd-tools{display:flex;align-items:center;gap:10px;margin-left:auto;min-width:0}\n.knobs-rd .knobs-rd-tools>.knobs-rd-find{flex:1 1 56px;min-width:56px;max-width:84px}\n.knobs-rd .knobs-rd-head[data-short] .knobs-rd-legend .knobs-rd-unit{display:none}\n.knobs-rd .knobs-rd-head[data-wrap]{flex-wrap:wrap;padding-bottom:4px}\n.knobs-rd .knobs-rd-head[data-wrap]>span:first-child{display:flex;align-items:center;min-height:var(--ku-row)}\n.knobs-rd .knobs-rd-head[data-wrap]>:is(.knobs-rd-legend,.knobs-rd-tools){flex:1 0 100%;margin-left:0}\n.knobs-rd .knobs-rd-head[data-wrap]>.knobs-rd-tools{flex-wrap:wrap;row-gap:4px}\n.knobs-rd .knobs-rd-key{display:inline-flex;align-items:center;gap:5px;white-space:nowrap}\n.knobs-rd .knobs-rd-swatch{flex:none;width:8px;height:2px;border-radius:1px}\n.knobs-rd .knobs-rd-name{color:var(--ku-label)}\n.knobs-rd .knobs-rd-key>.knobs-rd-value{margin-left:2px}\n.knobs-rd .knobs-rd-plotbox{position:relative;outline:none;margin-bottom:6px}\n.knobs-rd .knobs-rd-plotbox>.knobs-rd-plot{position:absolute;inset:0;width:100%;height:100%;min-width:0}\n.knobs-rd .knobs-rd-tick,.knobs-rd .knobs-rd-mark{position:absolute;color:var(--ku-dim);pointer-events:none;line-height:14px;height:14px}\n.knobs-rd .knobs-rd-tick{left:0}\n.knobs-rd .knobs-rd-tick[data-at=\"top\"]{top:-2px}\n.knobs-rd .knobs-rd-tick[data-at=\"bottom\"]{bottom:0}\n.knobs-rd .knobs-rd-mark{right:0;top:0}\n.knobs-rd .knobs-rd-mark[hidden]{display:none}\n\n.knobs-rd .knobs-rd-grid{display:grid;column-gap:14px;align-items:center;outline:none;margin-bottom:4px}\n.knobs-rd .knobs-rd-tr{display:contents}\n.knobs-rd .knobs-rd-tr>*{height:calc(var(--ku-row) * .72);line-height:calc(var(--ku-row) * .72);min-width:0;overflow:hidden;text-overflow:ellipsis;white-space:nowrap}\n.knobs-rd .knobs-rd-thead>*{height:var(--ku-row);line-height:var(--ku-row)}\n.knobs-rd .knobs-rd-th{color:var(--ku-dim);text-align:right}\n.knobs-rd .knobs-rd-td{color:var(--ku-text)}\n.knobs-rd .knobs-rd-td:first-child{color:var(--ku-label)}\n.knobs-rd .knobs-rd-td[data-num]{text-align:right}\n\n.knobs-rd.knobs-rd-log{--rd-lh:18px}\n.knobs-rd .knobs-rd-chips{display:inline-flex;align-items:center;gap:2px;margin-right:auto}\n.knobs-ui .knobs-rd-chip,.knobs-ui .knobs-rd-copy{height:calc(var(--ku-control-h) - 2px);padding:0 7px;border-radius:min(var(--ku-radius),5px);color:var(--ku-label);cursor:pointer;transition:background .15s,color .15s}\n.knobs-ui .knobs-rd-chip:hover,.knobs-ui .knobs-rd-copy:hover{background:var(--ku-wash);color:var(--ku-text)}\n.knobs-ui .knobs-rd-chip[aria-checked=\"true\"]{background:var(--ku-wash-hi);color:var(--ku-text)}\n.knobs-ui .knobs-rd-find{width:84px;height:calc(var(--ku-control-h) - 2px);padding:0 7px;border-radius:min(var(--ku-radius),5px);\n  background:color-mix(in srgb,var(--ku-surface-hi) 60%,transparent);color:var(--ku-text);caret-color:var(--ku-accent)}\n.knobs-rd .knobs-rd-find::placeholder{color:var(--ku-dim)}\n.knobs-rd .knobs-rd-find::-webkit-search-cancel-button{display:none}\n.knobs-rd .knobs-rd-logbody{position:relative;margin-bottom:6px}\n.knobs-rd .knobs-rd-scroll{position:relative;overflow-x:hidden;overflow-y:auto;height:calc(var(--knobs-rd-lines,8) * var(--rd-lh));outline:none;\n  background:color-mix(in srgb,var(--ku-surface-hi) 45%,transparent);border-radius:min(var(--ku-radius),6px);scrollbar-width:thin;overscroll-behavior:contain}\n.knobs-rd .knobs-rd-space{position:relative;width:100%}\n.knobs-rd .knobs-rd-line{position:absolute;left:0;right:0;top:0;display:flex;gap:10px;height:var(--rd-lh);line-height:var(--rd-lh);padding:0 8px;contain:layout style;will-change:transform}\n.knobs-rd .knobs-rd-line[hidden]{display:none}\n.knobs-rd .knobs-rd-time{flex:none;color:var(--ku-dim)}\n.knobs-rd .knobs-rd-text{min-width:0;overflow:hidden;text-overflow:ellipsis;color:var(--ku-text)}\n.knobs-rd .knobs-rd-line[data-level=\"warn\"]>.knobs-rd-text{color:var(--ku-warn)}\n.knobs-rd .knobs-rd-line[data-level=\"error\"]>.knobs-rd-text{color:var(--ku-critical)}\n.knobs-rd .knobs-rd-line[data-level=\"debug\"]>.knobs-rd-text{color:var(--ku-dim)}\n.knobs-ui .knobs-rd-match{color:var(--ku-accent)}\n.knobs-ui .knobs-rd-jump{position:absolute;left:50%;bottom:6px;height:20px;padding:0 10px;border-radius:calc(var(--ku-radius) * 999);\n  background:var(--ku-accent);color:var(--ku-bg);opacity:0;transform:translate(-50%,6px);cursor:pointer;white-space:nowrap}\n\n/* Under the GPU overlay the readouts' DOM stays for focus, hit-testing and screen readers; the\n   overlay draws them. Their filter field sits above it. */\n.knobs-panel[data-gpu-active=\"true\"] .knobs-rd :where(*:not(.knobs-rd-find)),.knobs-panel[data-gpu-active=\"true\"] .knobs-rd{color:transparent!important;background:transparent!important;border-color:transparent!important;box-shadow:none!important}\n.knobs-panel[data-gpu-active=\"true\"] .knobs-rd-plot{visibility:hidden}\n.knobs-panel[data-gpu-active=\"true\"] .knobs-rd-find{position:relative;z-index:2147480003}\n@media(prefers-reduced-motion:reduce){.knobs-rd :where(*){transition:none!important}}\n";

package/dist/types/ui/readout-model.d.ts

@@ -0,0 +1,137 @@
+import type { Ring } from "../core/readout.js";
+import { type Rgba } from "./rgba.js";
+export type PlotOp = {
+    readonly t: "line";
+    readonly pts: readonly number[];
+    readonly color: Rgba;
+    readonly width: number;
+}
+/** The area between a line and `base` (a y), fading to `fade` × its alpha at the base. */
+ | {
+    readonly t: "area";
+    readonly pts: readonly number[];
+    readonly base: number;
+    readonly color: Rgba;
+    readonly fade: number;
+} | {
+    readonly t: "rect";
+    readonly x: number;
+    readonly y: number;
+    readonly w: number;
+    readonly h: number;
+    readonly color: Rgba;
+    readonly r?: number;
+} | {
+    readonly t: "dot";
+    readonly x: number;
+    readonly y: number;
+    readonly r: number;
+    readonly color: Rgba;
+};
+/** The colours readouts draw with, read from the tokens. */
+export interface Palette {
+    readonly accent: Rgba;
+    readonly text: Rgba;
+    readonly label: Rgba;
+    readonly dim: Rgba;
+    readonly line: Rgba;
+    readonly surfaceHi: Rgba;
+    readonly warn: Rgba;
+    readonly critical: Rgba;
+    /** Corner radius (px); 0 squares the bars. */
+    readonly radius: number;
+}
+/** Series colours after the first (the accent). */
+export declare const SERIES: string[];
+/** A number as text: `decimals` places, else fewer as it grows (2 under 10, 1 under 100, 0 past). */
+export declare function formatNumber(v: number, decimals?: number): string;
+/** A step of 1, 2 or 5 × 10ⁿ near `span / 4`: a scale snaps to these, so it moves rarely. */
+export declare function niceStep(span: number): number;
+/**
+ * The range a history is drawn on: its samples' extent (and `keep`, such as thresholds), snapped
+ * out to a nice step, with fixed bounds where given. A flat history gets room around it.
+ */
+export declare function fitRange(lo: number, hi: number, fixed?: {
+    min?: number;
+    max?: number;
+}, keep?: readonly number[]): [number, number];
+/**
+ * A scale that eases to each new range on a spring, interruptibly, instead of jumping. The span
+ * eases in log space, so a line rescaling by 5× moves at an even pace rather than mostly at once.
+ */
+export declare class EasedRange {
+    private readonly lo;
+    private readonly span;
+    private placed;
+    private goal;
+    /** Sets where it's headed; `snap` places it there at once (the first range, reduced motion). */
+    to(lo: number, hi: number, snap?: boolean): void;
+    /** Steps both bounds; true while they're still moving. */
+    step(dt: number): boolean;
+    get value(): [number, number];
+    get target(): [number, number];
+}
+/**
+ * A history's samples as points across `w`, newest at the right edge; a history that isn't full
+ * yet starts part way across. NaN samples break the line: each run is its own list.
+ */
+export declare function historyRuns(ring: Ring, capacity: number, range: readonly [number, number], w: number, top: number, bottom: number): number[][];
+/** The sample index under `x` (local px), or -1. */
+export declare function sampleAt(x: number, w: number, capacity: number, length: number): number;
+export interface SparkScene {
+    readonly ops: PlotOp[];
+}
+/** A sparkline: a soft area under its line, the newest sample dotted; hovered, its min and max. */
+export declare function sparkScene(o: {
+    ring: Ring;
+    capacity: number;
+    range: readonly [number, number];
+    w: number;
+    h: number;
+    color: Rgba;
+    palette: Palette;
+    hover: boolean;
+}): PlotOp[];
+/** Dashes along a horizontal line at `y`: 4 px on, 3 off. */
+export declare function dashes(y: number, x0: number, x1: number, color: Rgba, on?: number, off?: number): PlotOp[];
+export interface GraphLine {
+    readonly ring: Ring;
+    readonly color: Rgba;
+    readonly area: boolean;
+}
+/** A graph: thresholds dashed, each series' area and line, a baseline; hovered, a crosshair. */
+export declare function graphScene(o: {
+    lines: readonly GraphLine[];
+    capacity: number;
+    range: readonly [number, number];
+    thresholds: readonly {
+        value: number;
+        color: Rgba;
+    }[];
+    w: number;
+    h: number;
+    palette: Palette;
+    hover: number;
+}): PlotOp[];
+/** The colour a meter's value takes: the accent, the warning colour from `warn`, critical past `critical`. */
+export declare function levelOf(v: number, warn?: number, critical?: number, prev?: number, band?: number): 0 | 1 | 2;
+export declare function levelColor(p: Palette, level: number): Rgba;
+/** A meter: a slim track with its fill (eased), or cells; indeterminate, a band that sweeps across. */
+export declare function meterScene(o: {
+    /** 0–1, as eased. */
+    fraction: number;
+    /** 0 (ok) to 2 (critical), as eased, for a continuous bar's colour. */
+    level: number;
+    min: number;
+    max: number;
+    warn?: number;
+    critical?: number;
+    segments?: number;
+    /** 0–1 through the sweep, or undefined when the value is known. */
+    sweep?: number;
+    w: number;
+    h: number;
+    palette: Palette;
+}): PlotOp[];
+/** Paints ops on a 2D canvas (already scaled to CSS px). */
+export declare function paintOps(ctx: CanvasRenderingContext2D, ops: readonly PlotOp[]): void;

package/dist/types/ui/readouts.d.ts

@@ -0,0 +1,85 @@
+import type { ReadoutState, Ring } from "../core/readout.js";
+import type { ReadoutField } from "../core/schema.js";
+import { type UiLook } from "./look.js";
+import { type Palette, type PlotOp } from "./readout-model.js";
+import { type Rgba } from "./rgba.js";
+export type ReadoutFont = "value" | "mono" | "meta";
+/** A piece of text the GPU overlay draws in place of the DOM's (which it hides). */
+export interface TextItem {
+    readonly el: HTMLElement;
+    /** Drawn left to right from the element's left edge, or right-aligned at its right edge. */
+    readonly parts: readonly {
+        readonly text: string;
+        readonly color: Rgba;
+    }[];
+    readonly font: ReadoutFont;
+    readonly align: "left" | "right";
+    /** Clipped to this element (a scroller). */
+    readonly clip?: HTMLElement;
+}
+/** Ops in px from `el`'s top-left corner. */
+export interface PlotLayer {
+    readonly el: HTMLElement;
+    readonly ops: readonly PlotOp[];
+}
+export interface ButtonItem {
+    readonly el: HTMLButtonElement;
+    /** `chip`: a filter chip (pressed shows a wash); `pill`: a filled pill (jump to latest). */
+    readonly look: "chip" | "plain" | "pill";
+    readonly alpha: number;
+}
+export interface ReadoutView {
+    readonly element: HTMLElement;
+    readonly field: ReadoutField;
+    /** Where the row's ↑↓ stop lands. */
+    readonly focusTarget: HTMLElement;
+    /** Graphics, text and buttons as the last frame drew them (the GPU overlay draws these). */
+    layers(): readonly PlotLayer[];
+    texts(): readonly TextItem[];
+    buttons(): readonly ButtonItem[];
+    /** Something arrived in the readout's state. */
+    notify(): void;
+    /** A new field of the same kind (a descriptor swap). */
+    retune(field: ReadoutField): void;
+    /** Paints its canvas again (after a GPU overlay stopped drawing it). */
+    refresh(): void;
+    dispose(): void;
+}
+export interface ReadoutEnv {
+    readonly doc: Document;
+    readonly field: ReadoutField;
+    readonly state: ReadoutState;
+    /** The row's label; block readouts (graph, table, log) put it in their head. */
+    readonly label?: HTMLElement;
+    /** True while a GPU overlay draws this readout: the canvas stays blank. */
+    gpu?(): boolean;
+    /** Called after a frame changed what the readout shows. */
+    wake?(): void;
+}
+export declare function paletteOf(el: HTMLElement, now?: number): Palette;
+/** A value's text and unit, as the field formats it. */
+export declare function readoutText(field: ReadoutField, v: unknown): {
+    num: string;
+    unit: string;
+};
+/** A time as the log shows it: a clock for epoch times, else seconds (a `performance.now()`). */
+export declare function logTime(t: number): string;
+/** Builds the view for a readout field. */
+export declare function createReadout(env: ReadoutEnv): ReadoutView;
+export type { Ring };
+export interface Readout {
+    readonly element: HTMLElement;
+    /** A value, a sample or rows, as `controls.watch` takes them; `null` clears it. */
+    push(value: unknown): void;
+    /** The latest value pushed. */
+    readonly value: unknown;
+    dispose(): void;
+}
+/**
+ * A readout on its own, outside a panel: `readout(sparkline({ unit: "ms" }))`, put its element
+ * anywhere and `push` values to it. It sleeps when nothing arrives, as it does in a panel.
+ */
+export declare function readout(field: ReadoutField, options?: UiLook & {
+    readonly doc?: Document;
+    readonly label?: string;
+}): Readout;

package/dist/types/ui/rgba.d.ts

@@ -0,0 +1,6 @@
+export type Rgba = readonly [number, number, number, number];
+/** Any CSS colour (hex, rgb(), oklch(), color-mix(), calc() inside) as RGBA; `fallback` if not one. */
+export declare function parseCssColor(raw: string, fallback?: Rgba): Rgba;
+export declare const withAlpha: (c: Rgba, k: number) => Rgba;
+export declare const mixRgba: (a: Rgba, b: Rgba, t: number) => Rgba;
+export declare const rgbaCss: (c: Rgba) => string;

package/dist/types/ui/solid.d.ts

@@ -0,0 +1,63 @@
+import { type JSX } from "solid-js";
+import { type Activity as ActivityHandle, type ActivityOptions } from "./activity.js";
+import { type Bento as BentoHandle, type BentoOptions } from "./bento.js";
+import { type OptionPicker as OptionPickerHandle, type OptionPickerOptions, type PickerOption } from "./picker.js";
+import { type Split as SplitHandle, type SplitOptions } from "./split.js";
+import { type Timeline as TimelineHandle, type TimelineOptions } from "./timeline.js";
+import { type Tree as TreeHandle, type TreeOptions } from "./tree.js";
+export type SplitProps = SplitOptions & {
+    /** One element per pane, in the panes' order; each goes into its pane's body. */
+    children?: JSX.Element;
+    onReady?: (split: SplitHandle) => void;
+};
+/**
+ * `split()` as a component: each child goes into its pane. The split is made once; children
+ * that change move into their panes.
+ */
+export declare function Split(props: SplitProps): JSX.Element;
+export type TreeProps<T> = TreeOptions<T> & {
+    onReady?: (tree: TreeHandle<T>) => void;
+};
+/**
+ * `tree()` as a component. New `items` update it in place (rows glide); `selection` and
+ * `filter` follow their props; callbacks always call the latest props.
+ */
+export declare function Tree<T>(props: TreeProps<T>): JSX.Element;
+export type TimelineProps = TimelineOptions & {
+    onReady?: (timeline: TimelineHandle) => void;
+};
+/**
+ * `timeline()` as a component. `time`, `playing`, `markers`, `ranges`, `duration`, `fps`,
+ * `units` and `speed` follow their props (a `time` it reported itself is left alone); callbacks
+ * always call the latest props.
+ */
+export declare function Timeline(props: TimelineProps): JSX.Element;
+export type BentoProps = BentoOptions & {
+    onReady?: (bento: BentoHandle) => void;
+};
+/**
+ * `bento()` as a component. New `items` update it in place (tiles glide); `picks` follows its
+ * prop; callbacks always call the latest props.
+ */
+export declare function Bento(props: BentoProps): JSX.Element;
+export type ActivityProps = ActivityOptions & {
+    onReady?: (activity: ActivityHandle) => void;
+};
+/**
+ * `activity()` as a component. New `events` update it in place (rows keep their identity and
+ * glide); `selected` follows its prop; callbacks always call the latest props.
+ */
+export declare function Activity(props: ActivityProps): JSX.Element;
+export type OptionPickerProps = Omit<OptionPickerOptions, "body"> & {
+    /** An option's parameters, rendered once, the first time it opens (a `KnobsPanel`, say). */
+    children?: (option: PickerOption) => JSX.Element;
+    onReady?: (picker: OptionPickerHandle) => void;
+};
+/**
+ * `optionPicker()` as a component: `children` renders an option's parameters under it, in this
+ * component's context. `options`, `selected` and `chosen` follow their props; callbacks always
+ * call the latest props.
+ */
+export declare function OptionPicker(props: OptionPickerProps): JSX.Element;
+export type { ActivityEvent } from "./activity-model.js";
+export type { PickerOption } from "./picker.js";

package/dist/types/ui/split-model.d.ts

@@ -0,0 +1,135 @@
+export type SplitDirection = "row" | "column";
+export interface PaneSpec {
+    readonly id: string;
+    /** Pixels. Panes without one share what the sized panes leave, by their last sizes. */
+    readonly size?: number;
+    /** Pixels; 48 unless set. */
+    readonly min?: number;
+    readonly max?: number;
+    /** Collapses to its rail (or header) from its divider, header or `collapse()`. */
+    readonly collapsible?: boolean;
+    /** Starts collapsed (a saved layout wins). */
+    readonly collapsed?: boolean;
+}
+/** What a split saves and reports: each pane's size and whether it's collapsed. */
+export interface SplitLayout {
+    readonly sizes: Readonly<Record<string, number>>;
+    readonly collapsed: Readonly<Record<string, boolean>>;
+}
+export declare const DEFAULT_MIN = 48;
+/** How far past its minimum a collapsible pane is dragged before it collapses. */
+export declare const COLLAPSE_PAST = 40;
+export declare const paneMin: (p: PaneSpec) => number;
+export declare const paneMax: (p: PaneSpec) => number;
+/** Panes that fill: those without a `size`, or else the last one. */
+export declare function flexible(panes: readonly PaneSpec[]): Set<string>;
+/**
+ * Approaches a bound without passing it: 1:1 until `knee` px short of it, then easing in, so a
+ * drag slows into its limit instead of stopping dead (and never bands past it).
+ */
+export declare function softClamp(x: number, min: number, max: number, knee?: number): number;
+export interface SolveInput {
+    readonly panes: readonly PaneSpec[];
+    /** Last sizes (px); flexible panes use theirs as shares. */
+    readonly sizes: Readonly<Record<string, number>>;
+    readonly collapsed: Readonly<Record<string, boolean>>;
+    /** The container's length along the split, dividers included. */
+    readonly total: number;
+    /** Room each divider takes. */
+    readonly divider?: number;
+    /** A collapsed pane's length (its rail or header). */
+    readonly rail?: (id: string) => number;
+    /** Sizes held exactly, whatever else is true (a pane mid-collapse). */
+    readonly fixed?: Readonly<Record<string, number>>;
+}
+/**
+ * Lays panes out along the split. Sized panes keep their size (clamped to min and max) and
+ * flexible ones share the rest by their last sizes; when there isn't room for every flexible
+ * pane's minimum, sized panes give way, the largest first, down to their own minimums.
+ */
+export declare function solve(input: SolveInput): Record<string, number>;
+export interface DragResult {
+    /** New sizes for the two panes beside the divider. */
+    readonly sizes: Record<string, number>;
+    /** A collapsible pane dragged well past its minimum collapses; dragged back, it opens. */
+    readonly collapse?: {
+        readonly id: string;
+        readonly collapsed: boolean;
+    };
+}
+/**
+ * Moves the divider after pane `index` by `delta` px from where the drag began (`start` holds
+ * every pane's size then). The panes on either side trade the distance, each slowing into its
+ * own bounds.
+ */
+export declare function drag(panes: readonly PaneSpec[], start: Readonly<Record<string, number>>, index: number, delta: number, collapsed?: Readonly<Record<string, boolean>>): DragResult;
+/** Steps a divider by keys: the pane before it grows by `delta`, within both panes' bounds. */
+export declare function nudge(panes: readonly PaneSpec[], sizes: Readonly<Record<string, number>>, index: number, delta: number): Record<string, number>;
+/**
+ * Which pane a divider collapses (Enter, its button): the sized one beside it, else the
+ * collapsible one, preferring the pane at the edge.
+ */
+export declare function collapsibleSide(panes: readonly PaneSpec[], index: number): string | undefined;
+/**
+ * Which edge a pane collapses toward: panes before the first flexible pane go to the start,
+ * the rest to the end.
+ */
+export declare function edgeOf(panes: readonly PaneSpec[], id: string): "start" | "end";
+/** How far a folding pane is from its open size (0) to its rail (1), by the size it shows. */
+export declare function foldProgress(size: number, open: number, rail: number): number;
+/** How much of each face a folding pane shows (0…1): its content, open, and its rail, folded. */
+export interface FoldFaces {
+    readonly content: number;
+    readonly rail: number;
+}
+/** A face that's leaving is gone by this far along the fold. */
+export declare const FACE_OUT = 0.4;
+/** A face that's arriving shows only over this last part of the fold. */
+export declare const FACE_IN = 0.3;
+/**
+ * The faces at fold progress `p`, from the last frame's. The content and the rail never show
+ * together: the content is gone before 40% and the rail starts past 70% (folding or opening).
+ */
+export declare function foldFaces(prev: FoldFaces, p: number): FoldFaces;
+/**
+ * The fold's chevron turn (degrees) at progress `p`: half a turn from the open pane's chevron to
+ * the rail's, rolling the way the pane's edge travels.
+ */
+export declare function chevronTurn(p: number, edge: "start" | "end"): number;
+/**
+ * The fold's chevron, flipping: its width (scaleX) against the rail's chevron at flip progress
+ * `f` (0 open, 1 folded). The arms close in to a flat line halfway and open out the other way.
+ */
+export declare function chevronFlip(f: number): number;
+/** How a pane folds: see `SplitOptions.fold`. */
+export interface FoldStyle {
+    readonly chevron: "flip" | "turn";
+    readonly title: "travel" | "fade";
+    /** Seconds, on a spring with no bounce. */
+    readonly duration: number;
+}
+export declare const FOLD_STYLE: FoldStyle;
+export declare function foldStyle(options?: Partial<FoldStyle>): FoldStyle;
+/**
+ * Where a header's title and the rail's label sit, each from its own box's start edge and the
+ * pane's top (`dy` is the title's height less the label's), as measured with the pane open.
+ */
+export interface TitlePlaces {
+    readonly title: number;
+    readonly label: number;
+    readonly dy: number;
+}
+/**
+ * The rail's label travelling as the header's title, at fold progress `p`: the offset that puts it
+ * on the title (the rail holds on to the pane's moving edge, the header to the inner content that
+ * keeps its open size), and its turn from upright (-90°) to the rail's vertical (0°).
+ */
+export declare function titleTravel(at: TitlePlaces, open: number, rail: number, edge: "start" | "end", p: number): {
+    x: number;
+    y: number;
+    turn: number;
+};
+/** A saved layout, kept only where it names known panes with sane values. */
+export declare function parseLayout(raw: unknown, panes: readonly PaneSpec[]): SplitLayout | undefined;
+/** A layout as saved: sizes rounded to a tenth of a pixel. */
+export declare function serializeLayout(layout: SplitLayout): string;

package/dist/types/ui/split.d.ts

@@ -0,0 +1,92 @@
+import { type StoragePort } from "../core/storage.js";
+import { type UiLook } from "./look.js";
+import { type PaneSpec, type SplitDirection, type SplitLayout } from "./split-model.js";
+export interface PaneAction {
+    readonly id?: string;
+    readonly label: string;
+    /** SVG markup, text, or a node of your own. */
+    readonly icon?: string | Node;
+    readonly pressed?: boolean;
+    /** Shown in its tooltip as key chips (the split doesn't bind it). */
+    readonly shortcut?: string;
+    run(event: MouseEvent): void;
+}
+export interface PaneOptions extends PaneSpec {
+    /** A header with this title (a dock); collapsed, it's the rail's label too. */
+    readonly title?: string;
+    /** The collapsed rail's label, when it isn't the title. */
+    readonly rail?: string;
+    /** Beside the title, dimmed: a count or a word. */
+    readonly count?: string | number;
+    /** Icon buttons at the header's end. */
+    readonly actions?: readonly PaneAction[];
+    /** The body scrolls (on by default for panes with a header). */
+    readonly scroll?: boolean;
+    /** Content for the body (or fill `split.pane(id).body` yourself). */
+    readonly element?: Node;
+}
+export interface SplitOptions extends UiLook {
+    readonly direction?: SplitDirection;
+    readonly panes: readonly PaneOptions[];
+    /** Saves sizes and collapsed panes under this id (with `storage`). */
+    readonly id?: string;
+    /** Where layouts are saved: localStorage unless set; `null` saves nothing. */
+    readonly storage?: StoragePort | null;
+    /** After every change of size or collapse, drag frames and springs included. */
+    readonly onLayout?: (layout: SplitLayout) => void;
+    /**
+     * Header actions, collapse buttons and the rails of collapsed panes take codes in the page's
+     * hint mode (`s`), on by default; a code presses its button.
+     */
+    readonly hints?: boolean;
+    /** How collapsible panes fold to their rails and open again. */
+    readonly fold?: SplitFold;
+}
+/** How a pane folds (each part has a default). */
+export interface SplitFold {
+    /**
+     * The collapse chevron: `"flip"` (default) closes it to a flat line and opens it the other way,
+     * quickly, on its own snappy spring; `"turn"` spins it half a turn with the fold.
+     */
+    readonly chevron?: "flip" | "turn";
+    /**
+     * The header's title: `"travel"` (default) turns it and slides it into the rail's label, one
+     * element all the way; `"fade"` fades it out with the header as the rail's label fades in.
+     */
+    readonly title?: "travel" | "fade";
+    /** The fold's spring, in seconds (no bounce): 0.3 unless set. */
+    readonly duration?: number;
+}
+export interface SplitPane {
+    readonly id: string;
+    /** The pane itself. */
+    readonly element: HTMLElement;
+    /** Where content goes. */
+    readonly body: HTMLElement;
+    readonly header: HTMLElement | undefined;
+    /** Its size along the split (px), as shown now. */
+    readonly size: number;
+    readonly collapsed: boolean;
+    collapse(collapsed?: boolean): void;
+    resize(size: number): void;
+    title(text: string, count?: string | number): void;
+}
+export interface Split {
+    readonly element: HTMLElement;
+    pane(id: string): SplitPane;
+    layout(): SplitLayout;
+    /** Collapses or opens a pane (springing, interruptibly); no argument toggles. */
+    collapse(id: string, collapsed?: boolean): void;
+    resize(id: string, size: number): void;
+    /** Back to the panes' own sizes, one pane or all. */
+    reset(id?: string): void;
+    dispose(): void;
+}
+/**
+ * Resizable panes along a row or a column, divided by hairlines with a wider grip. Drag a divider
+ * to resize (each pane slows into its min and max), double-click it to reset, or focus it and use
+ * the arrow keys (⇧ for bigger steps) and Enter to collapse. Collapsing springs the pane down to a
+ * slim rail, or to its header in a column, which opens it again. Sizes persist and restore before
+ * the first paint. Splits nest: call `split` on another split's pane body.
+ */
+export declare function split(container: HTMLElement, options: SplitOptions): Split;