@kitlangton/knobs 0.0.0-stage → 0.2.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/follow.d.ts

@@ -0,0 +1,17 @@
+/**
+ * A diff for each set of prop values, given the values the piece was made with: the props that
+ * differ from the last values seen (at first, those at creation).
+ */
+export declare function propChanges<P extends object>(initial: P, same?: (a: unknown, b: unknown) => boolean): (next: P) => Partial<P>;
+/** Whether a diff from `propChanges` has anything in it. */
+export declare const anyChanged: (changed: object) => boolean;
+/**
+ * A timeline's changed props as one `update()`: unset ones dropped, and so are values it already
+ * has (a `time` or `playing` it reported itself, markers it handed out).
+ */
+export declare function timelineChanges<C extends Record<string, unknown>>(now: {
+    readonly time: number;
+    readonly playing: boolean;
+    readonly markers: unknown;
+    readonly ranges: unknown;
+}, changed: C): Partial<C>;

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

@@ -0,0 +1,24 @@
+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 SplitFold, 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";
+export { activity, type Activity, type ActivityOptions, } from "./activity.js";
+export { diffActivity, flattenActivity, formatDuration, indexActivity, keepSelection as keepActivitySelection, navigateActivity, railSegments, showsSelection, stackRows, type ActivityEvent, type ActivityInput, type ActivityKey, type ActivityKind, type ActivityRow, type RailNode, } from "./activity-model.js";
+export { optionPicker, type OptionPicker, type OptionPickerOptions, type PickerOption, } from "./picker.js";
+export { claimsDigit, digitPick, keepPick, stepPick } from "./picker-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,62 @@
+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;
+export declare const tune: <T extends {
+    omega: number;
+    zeta: number;
+}>(s: T, m: {
+    readonly omega: number;
+    readonly zeta: number;
+}) => T;
+/** Whether `target` is an editable field or select that takes typed keys. */
+export declare const isTypingTarget: (t: EventTarget | 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/picker-css.d.ts

@@ -0,0 +1 @@
+export declare const pickerCss: string;

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

@@ -0,0 +1,53 @@
+/** The option a digit names: 1–9 pick the first nine, as they read; past the last, none. */
+export declare function digitPick(ids: readonly string[], key: string): string | undefined;
+/** ↑/↓ (and Home/End) from `current`, stopping at the ends. */
+export declare function stepPick(ids: readonly string[], current: string | null, key: "ArrowUp" | "ArrowDown" | "Home" | "End"): string | undefined;
+/**
+ * The selection after the options change: the option a host asked for before it was there
+ * (`wanted`) once it comes, else the selection while its option stays, else the first.
+ */
+export declare function keepPick(ids: readonly string[], selected: string | null, wanted?: string | null): string | null;
+/**
+ * A host's `select(id)`: picked now if its option is there; if not, remembered (`wanted`) for
+ * the `set()` that brings it, so the order a host's updates land in can't lose it. A later
+ * select replaces what was wanted.
+ */
+export declare function askPick(ids: readonly string[], id: string): {
+    pick: string | undefined;
+    wanted: string | null;
+};
+/** What's still wanted after the options change: nothing once its option has come. */
+export declare const stillWanted: (ids: readonly string[], wanted: string | null) => string | null;
+/** The number an option shows: its place, 1, 2, … 12 (only 1–9 are keys that pick). */
+export declare const pickDigit: (index: number) => string;
+/**
+ * Whether a key event goes to the picker's digits: a bare 1–9 that nothing focused claimed (a
+ * panel row picking its own options, a text field) and that isn't typed into a field.
+ */
+export declare function claimsDigit(event: {
+    readonly key: string;
+    readonly defaultPrevented: boolean;
+    readonly metaKey: boolean;
+    readonly ctrlKey: boolean;
+    readonly altKey: boolean;
+    readonly shiftKey: boolean;
+    readonly repeat: boolean;
+    readonly typing?: boolean;
+}, typing?: boolean): boolean;
+/**
+ * Where the card comes to rest on the option at `index`: below the options before it with their
+ * bodies shut (once a change settles only the selected option's is open), as tall as its head
+ * and its body. The card aims here from the start, rather than chasing the option's top while
+ * the last option's body closes above it. With the body not yet measured (a panel mounting for
+ * the first time) there's no target yet, and the card holds where it is.
+ */
+export declare function cardTarget(heads: readonly number[], index: number, body: number | undefined, gap?: number, top?: number): {
+    y: number;
+    h: number;
+} | null;
+/**
+ * A first-mounted body's height once it has settled: the same reading two frames running, or
+ * whatever it reads after `limit` frames (content that never settles doesn't hold the change
+ * up). Until then undefined: it's still laying out.
+ */
+export declare function settleHeight(previous: number | undefined, now: number, frames: number, limit?: number): number | undefined;

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

@@ -0,0 +1,67 @@
+import { type UiLook } from "./look.js";
+export interface PickerOption {
+    readonly id: string;
+    readonly label: string;
+    /** Marked "Suggested". */
+    readonly suggested?: boolean;
+    /**
+     * A picture of it (an image URL), small between the number and the name. It loads lazily and
+     * fades in once loaded; while loading, or if it fails, nothing is drawn.
+     */
+    readonly thumb?: string;
+}
+export interface OptionPickerOptions extends UiLook {
+    readonly options: readonly PickerOption[];
+    /** The option on show, its parameters open under it; the first unless set. */
+    readonly selected?: string | null;
+    /** The option decided on: it takes a check. */
+    readonly chosen?: string | null;
+    /** Keys, digits and clicks moved the selection (a host's `select()` doesn't call it). */
+    readonly onSelect?: (id: string, source: "key" | "digit" | "pointer") => void;
+    /** Enter on an option. */
+    readonly onChoose?: (id: string) => void;
+    /**
+     * Mounts an option's parameters into `element` the first time it opens (a knobs panel, say);
+     * return a cleanup for when the option goes or the picker is destroyed. It stays mounted
+     * while closed, so a panel keeps its state.
+     */
+    readonly body?: (option: PickerOption, element: HTMLElement) => (() => void) | void;
+    /**
+     * Where 1–9 pick from: `"focus"` (the default) while focus is in the picker, its panels
+     * included, `"page"` from anywhere, or `false`. A focused row that picks its own options with
+     * digits, and text fields, keep them.
+     */
+    readonly digits?: "focus" | "page" | false;
+    /** The accessible name. */
+    readonly label?: string;
+    /** The suggested mark's words ("Suggested"). */
+    readonly suggestedLabel?: string;
+}
+export interface OptionPicker {
+    readonly element: HTMLElement;
+    /**
+     * New options: the selection stays on its option while that's still there, or goes to one
+     * `select()` asked for before it was there.
+     */
+    set(options: readonly PickerOption[]): void;
+    /**
+     * Opens this option's parameters (closing the last one's). Doesn't call `onSelect`. An id that
+     * isn't there yet is remembered, and picked when `set()` brings it.
+     */
+    select(id: string): void;
+    readonly selected: string | null;
+    /** Marks the chosen option (`null` for none). */
+    choose(id: string | null): void;
+    readonly chosen: string | null;
+    /** Focuses the selected option. */
+    focus(): void;
+    destroy(): void;
+    dispose(): void;
+}
+/**
+ * A column of options (1–n), each with a name, a "Suggested" mark and a check on the chosen one.
+ * The selected option sits on a card that glides between options, and its parameters (what
+ * `body` mounts, a knobs panel's rows) open under it in place while the last option's close.
+ * ↑/↓, Home/End and 1–9 pick; Enter chooses; Tab goes into the parameters.
+ */
+export declare function optionPicker(container: HTMLElement, options: OptionPickerOptions): OptionPicker;

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;