@kitlangton/knobs 0.0.0-stage → 0.1.0

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

@@ -0,0 +1,77 @@
+import { type BentoPlan } from "./bento-model.js";
+import { type UiLook } from "./look.js";
+export interface BentoItem {
+    readonly id: string;
+    /** Width / height. Images without one take their natural size. */
+    readonly aspect?: number;
+    /** An image. */
+    readonly src?: string;
+    /** Responsive candidates for the image; the tile's size picks one, and a zoom a larger one. */
+    readonly srcset?: string;
+    readonly alt?: string;
+    /**
+     * Your own content (a live canvas, a prototype), drawn into `el` when the tile comes into view;
+     * return a cleanup for when it leaves. Zoomed, it takes the pointer.
+     */
+    readonly render?: (el: HTMLElement) => void | (() => void);
+    /** Shown as type on hover. */
+    readonly label?: string;
+    /** Items in the same group sit together under its name (the set then scrolls). */
+    readonly group?: string;
+    /** Asks to be the large tile when the set fits one screen. */
+    readonly hero?: boolean;
+}
+export interface BentoOptions extends UiLook {
+    readonly items: readonly BentoItem[];
+    /** Between tiles, px (2). */
+    readonly gap?: number;
+    /** Around the tiles, px (the gap). */
+    readonly padding?: number;
+    /** How far a tile may be cropped to fill a row (.08). */
+    readonly tolerance?: number;
+    /** Scrolling rows' target height, px (about a third of the view). */
+    readonly rowHeight?: number;
+    /** Whether a few items may lay out on one screen (true). */
+    readonly fit?: boolean;
+    /** The most a zooming or sliding tile blurs with its speed, px (2.5; 0 for none). */
+    readonly blur?: number;
+    readonly picks?: Iterable<string>;
+    /** Space toggles a pick; the picks in the items' order. */
+    readonly onPick?: (ids: readonly string[]) => void;
+    readonly onZoom?: (id: string | null) => void;
+    readonly onActive?: (id: string | null) => void;
+    /** The grid's accessible name. */
+    readonly label?: string;
+}
+export interface Bento {
+    readonly element: HTMLElement;
+    /** New items: tiles that stay glide to their places, new ones come in, gone ones soften out. */
+    update(items: readonly BentoItem[]): void;
+    /** Zooms an item to fill the view (`null` zooms back out). */
+    zoom(id: string | null): void;
+    readonly zoomed: string | null;
+    readonly active: string | null;
+    focus(id?: string): void;
+    readonly picks: readonly string[];
+    pick(ids: Iterable<string>): void;
+    readonly plan: BentoPlan;
+    /** Whether anything is moving (the frame loop runs only then). */
+    readonly moving: boolean;
+    /** Frames stepped, and the script time each took (ms), for perf checks. */
+    stats(): {
+        frames: number;
+        p50: number;
+        p95: number;
+        max: number;
+    };
+    dispose(): void;
+}
+/**
+ * An ideas grid: a bento of images and live content, laid out to show as much as possible, that
+ * zooms an item to fill the view. See `planBento` for the layout. Click or Enter zooms; Esc, a
+ * click or a pinch out returns to the exact grid place; ←/→ (or a swipe) step through neighbours
+ * while zoomed; ⌘-scroll or a pinch zooms by hand. Arrows move a wash through the grid by
+ * geometry, Space picks, 1–9 jump. Offscreen tiles aren't in the page, and the frame loop sleeps
+ * when nothing moves.
+ */
+export declare function bento(container: HTMLElement, options: BentoOptions): Bento;

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

@@ -0,0 +1,11 @@
+import type { Controls } from "../core/store.js";
+import type { Command } from "./palette.js";
+export interface CommandsFromOptions {
+    /** Prefix for sections ("Station" → "Station · Presets"); the store id is never shown. */
+    readonly title?: string;
+    /** Leave out fields (only actions and presets). */
+    readonly fields?: boolean;
+    /** A field picked from the palette: show it (scroll a panel to it, focus it). */
+    reveal?(key: string): void;
+}
+export declare function commandsFrom(controls: Controls<any>, options?: CommandsFromOptions): Command[];

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

@@ -0,0 +1,13 @@
+import type { UiLook } from "./look.js";
+export interface ConfirmOptions {
+    readonly title: string;
+    readonly body?: string;
+    /** The confirming button's label ("OK"). */
+    readonly confirm?: string;
+    readonly cancel?: string;
+    /** It deletes or discards: the button reads in the critical colour, and Cancel takes focus. */
+    readonly destructive?: boolean;
+    readonly look?: UiLook;
+    readonly doc?: Document;
+}
+export declare function confirm(options: ConfirmOptions): Promise<boolean>;

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

@@ -0,0 +1,20 @@
+export { injectUiStyles, restyle, type RestyleLook, type UiLook, type UiTheme } from "./look.js";
+export { commandsFrom, type CommandsFromOptions } from "./commands.js";
+export { confirm, type ConfirmOptions } from "./confirm.js";
+export { overlayLook, type Anchor } from "./layer.js";
+export { assignPageCodes, hints, pageHints, type HintPainter, type HintSourceOptions, type PageHints, type PageHintTarget, } from "../panel/page-hints.js";
+export { fuzzy, inTriangle, marks, matchItem, place, safeTriangle, stepItem, rank, type Box, type FuzzyMatch, type Placed, type Placement, type Ranked, type Side, } from "./overlay-model.js";
+export { commandPalette, type Command, type CommandPalette, type CommandPaletteOptions, } from "./palette.js";
+export { contextMenu, menu, type ContextMenu, type ContextMenuOptions, type Menu, type MenuCloseReason, type MenuEntry, type MenuItem, type MenuOptions, } from "./menu.js";
+export { popover, type Popover, type PopoverCloseReason, type PopoverOptions } from "./popover.js";
+export { readout, type Readout } from "./readouts.js";
+export { toast, type Toast, type ToastOptions } from "./toast.js";
+export { tooltip, tooltips, type TooltipContent, type TooltipOptions } from "./tooltip.js";
+export { split, type PaneAction, type PaneOptions, type Split, type SplitOptions, type SplitPane, } from "./split.js";
+export { COLLAPSE_PAST, drag as dragDivider, parseLayout, softClamp, solve as solveSplit, type PaneSpec, type SplitDirection, type SplitLayout, } from "./split-model.js";
+export { timeline, type SeekSource, type Timeline, type TimelineMarker, type TimelineOptions, type TimelineRange, } from "./timeline.js";
+export { adjacentMarker, advance, clampView, followView, frameTime, magnet, rulerTicks, scrubTime, timeLabel, toFrame, zoomView, type Tick, type Ticks, type TimeUnits, type TimeView, } from "./timeline-model.js";
+export { tree, type Tree, type TreeOptions, type TreeRowContext, type TreeToggle } from "./tree.js";
+export { applyMove, plainAccess, dropTarget, flatten, indexTree, matchLabel, navigate, select, stepMove, topmost, typeahead, validMove, virtualWindow, type DropTarget, type FlatRow, type Selection, type TreeAccess, type TreeFilter, type TreeMove, } from "./tree-model.js";
+export { bento, type Bento, type BentoItem, type BentoOptions } from "./bento.js";
+export { fitRect, FIT_MAX, motionBlur, neighbour as bentoNeighbour, planBento, rowTarget, windowOf as bentoWindow, type BentoDirection, type BentoLayout, type BentoMode, type BentoPlan, type BentoRect, } from "./bento-model.js";

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

@@ -0,0 +1,70 @@
+import { type UiLook } from "./look.js";
+/** The look every overlay takes unless given its own (a preset and theme, as panels take). */
+export declare function overlayLook(look: UiLook): void;
+export declare const lookOf: (look?: UiLook) => UiLook;
+/** The document's overlay layer: fixed, above everything, passing the pointer through. */
+export declare function layerRoot(doc: Document): HTMLElement;
+/** A new overlay element in the layer, with the pieces' look. */
+export declare function layerElement(doc: Document, cls: string, look?: UiLook): HTMLDivElement;
+export interface PresenceOptions {
+    /** Scale it grows from (0.94). */
+    readonly scale?: number;
+    /** Blur (px) it sharpens from (6). */
+    readonly blur?: number;
+    /** Where it slides from, px (toward its anchor). */
+    readonly dx?: number;
+    readonly dy?: number;
+    /** Perceptual duration in, s (0.32). */
+    readonly duration?: number;
+    /** Bounce in (0.2); exits never bounce. */
+    readonly bounce?: number;
+    /** Perceptual duration out, s (0.2): exits run shorter than entrances. */
+    readonly exit?: number;
+    /** Called once it has gone (faded all the way out). */
+    onGone?(): void;
+    /** Each frame, with progress (0 → 1, may overshoot a little). */
+    onFrame?(p: number): void;
+}
+export interface Presence {
+    show(): void;
+    hide(): Promise<void>;
+    /** Jumps to shown (a hand-off between neighbours) or gone, with no motion. */
+    snap(to?: 0 | 1): void;
+    readonly shown: boolean;
+    /** Changes where it slides from (after a flip). */
+    from(dx: number, dy: number): void;
+    dispose(): void;
+}
+/** Brings `el` in and out on a spring: opacity, scale and blur from its transform-origin. */
+export declare function presence(el: HTMLElement, o?: PresenceOptions): Presence;
+export interface Dismissible {
+    readonly el: HTMLElement;
+    /** Pointer-downs inside these don't count as outside (the anchor, say). */
+    readonly inside?: () => readonly (Element | null | undefined)[];
+    /** Esc and outside clicks reach the layers under a modal one only through it. */
+    readonly modal?: boolean;
+    readonly outside?: boolean;
+    dismiss(reason: "escape" | "outside"): void;
+}
+export declare function pushLayer(doc: Document, layer: Dismissible): () => void;
+export declare const focusables: (root: HTMLElement) => HTMLElement[];
+/** Keeps Tab inside `root`; returns the remover. */
+export declare function trapFocus(root: HTMLElement): () => void;
+/** Where focus was, to return it there when the layer closes (if focus is still in the layer). */
+export declare function focusReturn(doc: Document, layer: HTMLElement): () => void;
+export type Anchor = HTMLElement | DOMRect | {
+    readonly x: number;
+    readonly y: number;
+};
+export declare const anchorBox: (a: Anchor) => {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+};
+export declare const viewBox: (doc: Document) => {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+};

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

@@ -0,0 +1,53 @@
+import { type TokenPreset } from "../core/theme.js";
+export type UiTheme = "dark" | "light" | "auto";
+/** What every piece takes to match the panels beside it. */
+export interface UiLook {
+    /** A token preset (`labPreset`): the same tokens a panel takes. */
+    readonly preset?: TokenPreset;
+    readonly theme?: UiTheme;
+}
+/** Adds the pieces' stylesheet once per document. */
+export declare function injectUiStyles(doc: Document): void;
+/** Styles, preset and theme for a piece's root. */
+export declare function applyLook(root: HTMLElement, look: UiLook): void;
+/**
+ * `--k-frame: flat` (a preset's, or a host's on any ancestor) marks the piece `data-frame`. Read
+ * again once the piece is in the page.
+ */
+export declare function syncFrame(root: HTMLElement): void;
+/** A look for `restyle`: what the pieces take, and a panel's density. */
+export interface RestyleLook extends UiLook {
+    readonly density?: "compact" | "default" | "comfortable";
+}
+/**
+ * Changes the look of what's already on screen: every knobs/ui piece and panel inside `target`
+ * (the whole document by default) takes `look`'s preset (none for knobs' own), theme and, for
+ * panels, density. Panels' tokens glide to the new values; splits and trees measure again. On a
+ * document, overlays opened afterwards take it too (`overlayLook`).
+ */
+export declare function restyle(target: Document | Element, look: RestyleLook): void;
+/** The look overlays take unless given their own (`overlayLook`, `restyle(document)`). */
+export declare const lookDefaults: {
+    current: UiLook;
+};
+export declare const reducedMotion: (win: Window | null) => boolean;
+/**
+ * Tells the page's GPU overlay that layout moved (a pane resizing, collapsing or sliding): it
+ * reads rects afresh on its next frame, so a panel inside a pane keeps up.
+ */
+export declare function notifyLayout(doc: Document): void;
+/** One rAF loop: `step(dt)` runs each frame while it returns true. */
+export declare function frameLoop(win: Window, step: (dt: number) => boolean): {
+    wake(): void;
+    readonly running: boolean;
+    stop(): void;
+};
+export declare const svg: (body: string, box?: number) => string;
+export declare const ICONS: {
+    caret: string;
+    chevronDown: string;
+    eye: string;
+    eyeOff: string;
+    lock: string;
+    unlock: string;
+};

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

@@ -0,0 +1,63 @@
+import type { UiLook } from "./look.js";
+import { type Anchor } from "./layer.js";
+import { type Placement } from "./overlay-model.js";
+export interface MenuItem {
+    readonly id?: string;
+    readonly label: string;
+    /** A glyph, or an `<svg>` string. */
+    readonly icon?: string;
+    /** A key combination shown as chips ("Mod+D", "Backspace"); display only, it binds nothing. */
+    readonly shortcut?: string;
+    /** Dim text at the end, before any shortcut. */
+    readonly hint?: string;
+    readonly disabled?: boolean;
+    /** A check mark (`menuitemcheckbox`), or with `radio` a dot (`menuitemradio`). */
+    readonly checked?: boolean;
+    readonly radio?: boolean;
+    /** Drawn in `--k-critical`, for what can't be taken back. */
+    readonly destructive?: boolean;
+    /** A submenu (or a function read when it opens). */
+    readonly items?: readonly MenuEntry[] | (() => readonly MenuEntry[]);
+    run?(): unknown;
+}
+/** An item, `"-"` for a separator, or `null` / `false` for nothing (a conditional item). */
+export type MenuEntry = MenuItem | "-" | null | false | undefined;
+export type MenuCloseReason = "select" | "escape" | "outside" | "close";
+export interface MenuOptions {
+    /** Where it opens beside its anchor (`bottom-start`; a point opens at its corner). */
+    readonly placement?: Placement;
+    /** Px between the anchor and the menu (4; 0 at a point). */
+    readonly offset?: number;
+    readonly label?: string;
+    readonly look?: UiLook;
+    /** The first item starts active (opened by a key rather than the pointer). */
+    readonly keyboard?: boolean;
+    onClose?(reason: MenuCloseReason): void;
+    /** Each item chosen, beside its own `run`. */
+    onSelect?(item: MenuItem): void;
+}
+export interface Menu {
+    readonly element: HTMLElement;
+    readonly open: boolean;
+    /** Closes it and any submenu (animated); resolves once they've gone. */
+    close(): Promise<void>;
+}
+/** A menu beside `anchor` (a button, a rect or a point). */
+export declare function menu(anchor: Anchor, items: readonly MenuEntry[], options?: MenuOptions): Menu;
+export interface ContextMenuOptions extends Omit<MenuOptions, "placement" | "offset" | "keyboard"> {
+}
+export interface ContextMenu {
+    /** Opens it at a point (or the focused element), as a right-click or the menu key would. */
+    open(at?: {
+        readonly x: number;
+        readonly y: number;
+    }): Menu | null;
+    readonly current: Menu | null;
+    dispose(): void;
+}
+/**
+ * A context menu for `target`: a right-click (or a two-finger click) opens it at the pointer, and
+ * the menu key or ⇧F10 at the focused element. `items` may be a function of the event, read each
+ * time (return `null` for no menu there, and the browser's own shows).
+ */
+export declare function contextMenu(target: HTMLElement, items: readonly MenuEntry[] | ((event: MouseEvent | KeyboardEvent | null) => readonly MenuEntry[] | null | undefined), options?: ContextMenuOptions): ContextMenu;

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

@@ -0,0 +1 @@
+export declare const overlayCss = "\n.knobs-layers{position:fixed;inset:0;z-index:2147480005;pointer-events:none}\n.knobs-layers>.knobs-layer,.knobs-ui.knobs-toast{position:fixed;left:0;top:0;box-sizing:border-box;pointer-events:auto;outline:none;\n  font:var(--ku-font-weight) var(--ku-font-size)/1.4 var(--ku-font);color:var(--ku-text);letter-spacing:normal;text-align:left;text-transform:none;\n  -webkit-font-smoothing:antialiased;will-change:transform,opacity,filter}\n/* The overlays' own elements stop a host's element rules; what you put in a popover is yours. */\n:where(.knobs-layers,.knobs-toast) :is(.knobs-kbd,.knobs-mitem,.knobs-menu-sep,.knobs-palette-input,.knobs-palette-label>mark,.knobs-confirm-title,.knobs-confirm-body,.knobs-confirm-btn,.knobs-toast-action){all:revert;box-sizing:border-box;font:inherit;color:inherit;letter-spacing:inherit;\n  background:transparent;border:0;margin:0;padding:0;outline:none;box-shadow:none}\n.knobs-layers .knobs-layer *{box-sizing:border-box}\n/* A floating surface: frosted, a hairline rim, a soft shadow. */\n.knobs-layers>:is(.knobs-popover-layer,.knobs-palette,.knobs-confirm,.knobs-menu-layer){background:color-mix(in srgb,var(--ku-bg) 88%,transparent);\n  -webkit-backdrop-filter:blur(28px) saturate(1.7);backdrop-filter:blur(28px) saturate(1.7);border-radius:var(--ku-panel-radius);\n  box-shadow:0 0 0 .5px var(--ku-line-hi),inset 0 1px 0 var(--ku-rim),0 12px 40px rgba(0,0,0,.36),0 2px 8px rgba(0,0,0,.18)}\n.knobs-layers>.knobs-popover-layer{min-width:120px;max-width:min(420px,calc(100vw - 16px));padding:6px}\n.knobs-popover-layer .knobs-popover-text{padding:4px 6px;color:var(--ku-label)}\n\n/* Menus: rows of the panel's control height, a soft wash on the active one (never an outline),\n   concentric corners inside the surface. */\n.knobs-layers>.knobs-menu-layer{display:flex;flex-direction:column;min-width:184px;max-width:min(340px,calc(100vw - 16px));max-height:calc(100vh - 16px);overflow:auto;padding:5px;\n  scrollbar-width:thin;overscroll-behavior:contain;user-select:none;-webkit-user-select:none}\n.knobs-menu-layer .knobs-mitem{position:relative;display:flex;align-items:center;gap:8px;flex:none;height:max(22px,calc(var(--ku-row) - 6px));padding:0 8px;\n  border-radius:max(0px,calc(var(--ku-panel-radius) - 5px));color:var(--ku-text);cursor:default;white-space:nowrap}\n.knobs-menu-layer .knobs-mitem[data-active],.knobs-menu-layer .knobs-mitem[data-open]{background:var(--ku-wash-hi)}\n.knobs-menu-layer .knobs-mitem[data-destructive]{color:var(--ku-critical)}\n.knobs-menu-layer .knobs-mitem[data-destructive][data-active]{background:color-mix(in srgb,var(--ku-critical) 16%,transparent)}\n.knobs-menu-layer .knobs-mitem[aria-disabled=\"true\"]{opacity:.38}\n.knobs-menu-layer .knobs-menu-lead{flex:none;display:flex;align-items:center;justify-content:center;width:14px;margin-left:-2px;color:var(--ku-label);font-size:calc(var(--ku-font-size) - 1px)}\n.knobs-menu-layer .knobs-mitem[data-destructive] .knobs-menu-lead,.knobs-menu-layer .knobs-mitem[aria-checked=\"true\"] .knobs-menu-lead{color:inherit}\n.knobs-menu-layer .knobs-menu-lead svg{width:13px;height:13px}\n.knobs-menu-layer .knobs-menu-label{flex:1;min-width:0;overflow:hidden;text-overflow:ellipsis}\n.knobs-menu-layer .knobs-menu-hint{flex:none;color:var(--ku-dim)}\n.knobs-menu-layer .knobs-menu-keys{display:inline-flex;gap:2px;flex:none;margin-left:12px}\n.knobs-menu-layer .knobs-mitem[data-active] .knobs-kbd{background:color-mix(in srgb,var(--ku-text) 14%,transparent);color:var(--ku-text)}\n.knobs-menu-layer .knobs-menu-caret{flex:none;display:flex;margin-left:8px;margin-right:-3px;color:var(--ku-dim)}\n.knobs-menu-layer .knobs-menu-caret svg{width:10px;height:10px}\n.knobs-menu-layer .knobs-menu-sep{flex:none;height:1px;margin:4px 8px;background:var(--ku-line)}\n\n.knobs-layers>.knobs-tooltip{display:inline-flex;align-items:center;gap:7px;max-width:300px;padding:4px 8px;pointer-events:none;white-space:nowrap;\n  font-size:calc(var(--ku-font-size) - .5px);background:var(--ku-bg);color:var(--ku-text);border-radius:min(var(--ku-radius),6px);\n  box-shadow:0 0 0 .5px var(--ku-line-hi),0 4px 14px rgba(0,0,0,.3)}\n.knobs-tooltip .knobs-tooltip-text{overflow:hidden;text-overflow:ellipsis}\n.knobs-layer :is(.knobs-tooltip-keys,.knobs-palette-keys){display:inline-flex;gap:2px;flex:none}\n.knobs-layer .knobs-tooltip-keys[hidden]{display:none}\n.knobs-layer .knobs-kbd{display:inline-flex;align-items:center;justify-content:center;min-width:17px;height:17px;padding:0 4px;\n  border-radius:min(var(--ku-radius),4px);background:var(--ku-surface-hi);color:var(--ku-label);font:500 calc(var(--ku-font-size) - 1.5px)/1 var(--ku-font)}\n\n.knobs-layers>.knobs-palette{left:50%;top:max(48px,15vh);translate:-50% 0;transform-origin:50% 0;display:flex;flex-direction:column;\n  width:min(580px,calc(100vw - 32px));max-height:min(460px,72vh);overflow:hidden}\n.knobs-palette .knobs-palette-field{display:flex;align-items:center;gap:10px;flex:none;height:46px;padding:0 16px;border-bottom:1px solid var(--ku-line);color:var(--ku-dim)}\n.knobs-palette .knobs-palette-field svg{width:15px;height:15px;flex:none}\n.knobs-palette .knobs-palette-input{flex:1;min-width:0;height:100%;font-size:calc(var(--ku-font-size) + 3px);color:var(--ku-text);caret-color:var(--ku-accent)}\n.knobs-palette .knobs-palette-input::placeholder{color:var(--ku-dim)}\n.knobs-palette .knobs-palette-list{position:relative;flex:1;min-height:0;overflow:auto;padding:6px;scrollbar-width:thin;overscroll-behavior:contain}\n.knobs-palette .knobs-palette-hl{position:absolute;left:6px;right:6px;top:0;border-radius:max(0px,calc(var(--ku-panel-radius) - 6px));background:var(--ku-wash-hi);opacity:0;pointer-events:none;\n  transition:transform var(--ku-ease-ms) var(--ku-ease),height var(--ku-ease-ms) var(--ku-ease),opacity .12s}\n.knobs-palette .knobs-palette-section{padding:10px 10px 4px;color:var(--ku-dim);font-size:calc(var(--ku-font-size) - 1px);font-weight:var(--ku-label-weight);user-select:none}\n.knobs-palette .knobs-palette-section:first-of-type{padding-top:4px}\n.knobs-palette .knobs-palette-item{position:relative;display:flex;align-items:center;gap:8px;height:max(32px,var(--ku-row));padding:0 10px;\n  color:var(--ku-label);cursor:default;user-select:none}\n.knobs-palette .knobs-palette-label{min-width:0;overflow:hidden;text-overflow:ellipsis;white-space:nowrap;color:var(--ku-text)}\n/* Searching, the label dims and its matched letters light up. */\n.knobs-palette[data-query] .knobs-palette-label{color:var(--ku-label)}\n.knobs-palette .knobs-palette-label mark{color:var(--ku-accent);font-weight:var(--ku-title-weight)}\n.knobs-palette[data-query] .knobs-palette-item[data-active] .knobs-palette-label{color:var(--ku-text)}\n.knobs-palette .knobs-palette-hint{flex:none;color:var(--ku-dim)}\n.knobs-palette .knobs-palette-fill{flex:1}\n.knobs-palette .knobs-palette-tag{flex:none;color:var(--ku-dim);font-size:calc(var(--ku-font-size) - 1px);white-space:nowrap}\n.knobs-palette .knobs-palette-item[aria-disabled=\"true\"]{opacity:.4}\n.knobs-palette .knobs-palette-empty{padding:18px 10px;color:var(--ku-dim);text-align:center}\n\n.knobs-layers>.knobs-scrim{inset:0;width:100%;height:100%;background:rgba(0,0,0,.3)}\n.knobs-layers>.knobs-confirm{left:50%;top:42%;translate:-50% -50%;width:min(340px,calc(100vw - 32px));padding:18px 18px 14px}\n.knobs-confirm .knobs-confirm-title{margin:0 0 6px;font-size:calc(var(--ku-font-size) + 1.5px);font-weight:var(--ku-title-weight);color:var(--ku-text);line-height:1.3}\n.knobs-confirm .knobs-confirm-body{margin:0;color:var(--ku-label);line-height:1.45}\n.knobs-confirm .knobs-confirm-buttons{display:flex;justify-content:flex-end;gap:8px;margin-top:18px}\n.knobs-confirm .knobs-confirm-btn{height:28px;padding:0 14px;border-radius:min(var(--ku-radius),7px);background:var(--ku-surface-hi);color:var(--ku-text);\n  font-weight:var(--ku-label-weight);cursor:pointer;transition:background .15s,filter .15s}\n.knobs-confirm .knobs-confirm-cancel:is(:hover,:focus-visible){background:color-mix(in srgb,var(--ku-text) 18%,transparent)}\n.knobs-confirm .knobs-confirm-ok{background:var(--ku-accent);color:var(--ku-bg)}\n.knobs-confirm .knobs-confirm-ok[data-destructive]{background:var(--ku-critical);color:#fff}\n.knobs-confirm .knobs-confirm-ok:is(:hover,:focus-visible){filter:brightness(1.14)}\n\n.knobs-ui.knobs-toast{left:50%;top:auto;bottom:24px;z-index:2147480005;translate:-50% 0;display:inline-flex;align-items:center;gap:10px;\n  max-width:min(480px,80vw);padding:8px 16px;background:var(--ku-bg);color:var(--ku-text);border-radius:calc(var(--ku-radius) * 999);\n  box-shadow:0 0 0 .5px var(--ku-line-hi),0 8px 28px rgba(0,0,0,.32)}\n.knobs-toast .knobs-toast-text{overflow-wrap:anywhere}\n.knobs-toast[data-tone=\"warn\"]::before,.knobs-toast[data-tone=\"error\"]::before{content:\"\";flex:none;width:7px;height:7px;border-radius:50%;background:var(--ku-warn)}\n.knobs-toast[data-tone=\"error\"]::before{background:var(--ku-critical)}\n.knobs-toast .knobs-toast-action{flex:none;color:var(--ku-accent);font-weight:var(--ku-title-weight);cursor:pointer}\n.knobs-toast .knobs-toast-action[hidden]{display:none}\n";

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

@@ -0,0 +1,87 @@
+export interface Box {
+    readonly x: number;
+    readonly y: number;
+    readonly w: number;
+    readonly h: number;
+}
+export type Side = "top" | "bottom" | "left" | "right";
+export type Placement = Side | `${Side}-start` | `${Side}-end`;
+export interface Placed {
+    readonly x: number;
+    readonly y: number;
+    /** The placement after flipping. */
+    readonly placement: Placement;
+    /** The anchor's nearest point, in the layer's own px: where it grows from. */
+    readonly origin: {
+        readonly x: number;
+        readonly y: number;
+    };
+}
+/**
+ * Places a `size` layer on `placement`'s side of `anchor`, `offset` px away: flipped to the
+ * other side when it doesn't fit and that side has more room, then shifted along the side to stay
+ * `margin` px inside `view`.
+ */
+export declare function place(o: {
+    anchor: Box;
+    size: {
+        readonly w: number;
+        readonly h: number;
+    };
+    view: Box;
+    placement?: Placement;
+    offset?: number;
+    margin?: number;
+}): Placed;
+export interface FuzzyMatch {
+    readonly score: number;
+    /** The matched characters' indices in the text, ascending. */
+    readonly indices: readonly number[];
+}
+/**
+ * Matches `query`'s characters in order anywhere in `text` (case-insensitive), or null. The best
+ * alignment wins: a match at the start, at word starts and in runs scores higher; gaps cost a
+ * little. Spaces in the query are ignored.
+ */
+export declare function fuzzy(query: string, text: string): FuzzyMatch | null;
+export interface Rankable {
+    readonly label: string;
+    readonly keywords?: readonly string[];
+    readonly section?: string;
+}
+export interface Ranked<T> {
+    readonly item: T;
+    readonly score: number;
+    /** Indices in the label (empty when only a keyword or the section matched). */
+    readonly indices: readonly number[];
+}
+/**
+ * Items matching `query`, best first; a label match beats a keyword's or the section's. Matches
+ * scattered thinly (letters strewn across words) are left out: a keyword or section must match
+ * at word starts or in runs, a label at least loosely.
+ */
+export declare function rank<T extends Rankable>(items: readonly T[], query: string): Ranked<T>[];
+/** `text` split into runs at `indices`: `[{ text, hit }]`, for highlighting. */
+export declare function marks(text: string, indices: readonly number[]): {
+    text: string;
+    hit: boolean;
+}[];
+/** The next item from `from` by `by` (±1) that `ok` accepts, wrapping; `from` -1 starts outside. */
+export declare function stepItem(count: number, from: number, by: 1 | -1, ok: (i: number) => boolean): number;
+/**
+ * Type-ahead over menu labels: the first item after `from` starting with `typed` (repeating one
+ * letter cycles through the items that start with it; more letters refine from where it is).
+ */
+export declare function matchItem(labels: readonly (string | null)[], from: number, typed: string): number;
+type Pt = {
+    readonly x: number;
+    readonly y: number;
+};
+/** Whether `p` is inside the triangle `a b c` (either winding). */
+export declare function inTriangle(p: Pt, a: Pt, b: Pt, c: Pt): boolean;
+/**
+ * The safe triangle of a submenu's hover intent: from where the pointer was to the submenu's
+ * near edge (a little past its corners). While the pointer travels inside it, the submenu stays.
+ */
+export declare function safeTriangle(from: Pt, sub: Box): [Pt, Pt, Pt];
+export {};

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

@@ -0,0 +1,38 @@
+import type { UiLook } from "./look.js";
+export interface Command {
+    /** Stable across sessions (recents remember it); the label by default. */
+    readonly id?: string;
+    readonly label: string;
+    /** The heading it sits under with no query, and its dimmed tag in results. */
+    readonly section?: string;
+    /** A shortcut shown as key chips (the palette doesn't bind it). */
+    readonly shortcut?: string;
+    /** Other words it answers to. */
+    readonly keywords?: readonly string[];
+    /** Text after the label, dimmed (a current value, say). */
+    readonly hint?: string;
+    readonly disabled?: boolean;
+    /** What it does; a string or a promise of one shows as a toast. */
+    run?(): unknown;
+}
+export interface CommandPaletteOptions {
+    /** The commands, or a function asked each time it opens. */
+    readonly commands: readonly Command[] | (() => readonly Command[]);
+    /** Called after a command runs (or instead, for commands with no `run`). */
+    onRun?(command: Command): void;
+    /** The key that toggles it, anywhere on the page (`"Mod+K"`); `false` for none. */
+    readonly hotkey?: string | false;
+    readonly placeholder?: string;
+    /** Recent commands are remembered under this key in localStorage; `false` remembers nothing. */
+    readonly recents?: string | false;
+    readonly look?: UiLook;
+    readonly doc?: Document;
+}
+export interface CommandPalette {
+    open(query?: string): void;
+    close(): void;
+    toggle(): void;
+    readonly isOpen: boolean;
+    dispose(): void;
+}
+export declare function commandPalette(options: CommandPaletteOptions): CommandPalette;

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

@@ -0,0 +1,35 @@
+import type { UiLook } from "./look.js";
+import { type Anchor } from "./layer.js";
+import { type Placement } from "./overlay-model.js";
+export interface PopoverOptions {
+    /** `bottom` by default; `top`, `left`, `right`, each with `-start` or `-end`. */
+    readonly placement?: Placement;
+    /** Px between the anchor and the layer (6). */
+    readonly offset?: number;
+    /** `dialog` by default; `menu`, `listbox`… for what the content is. */
+    readonly role?: string;
+    readonly label?: string;
+    /**
+     * Where focus goes when it opens: the first focusable element (`first`, the default), the
+     * layer itself (`layer`), or nowhere (`none`, focus stays where it was).
+     */
+    readonly focus?: "first" | "layer" | "none";
+    /** Tab stays inside (a modal popover). */
+    readonly trap?: boolean;
+    /** A click outside closes it (true). */
+    readonly closeOnOutside?: boolean;
+    readonly look?: UiLook;
+    /** Extra class names for the layer. */
+    readonly className?: string;
+    onClose?(reason: PopoverCloseReason): void;
+}
+export type PopoverCloseReason = "escape" | "outside" | "close";
+export interface Popover {
+    readonly element: HTMLElement;
+    /** Closes it (animated); resolves once it's gone. */
+    close(): Promise<void>;
+    /** Places it again (after its content or anchor moved). */
+    reposition(): void;
+    readonly open: boolean;
+}
+export declare function popover(anchor: Anchor, content: HTMLElement | string | ((close: () => void) => HTMLElement), options?: PopoverOptions): Popover;

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

@@ -0,0 +1,45 @@
+import { type CSSProperties, type ReactNode } from "react";
+import { type Bento as BentoHandle, type BentoOptions } from "./bento.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;

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";