@kitlangton/knobs 0.2.0 → 0.3.0

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

@@ -1,7 +1,7 @@
 import type { PanelCommand, PanelKeys } from "../core/store.js";
 /** How a panel reads keys that aren't commands (see `PanelKeys`): resolved once per panel. */
 export interface KeyPrefs {
-    /** j/k and h/l as aliases for the arrows. */
+    /** j/k as aliases for ↑/↓ (l is Lock, so ←/→ have no letters). */
     readonly vim: boolean;
     /** Digits, `.`, `-` and Enter on a slider open its inline number editor. */
     readonly edit: boolean;
@@ -14,7 +14,7 @@ export declare const DEFAULT_PREFS: KeyPrefs;
 export declare const setKeyPrefs: (root: Element, prefs: KeyPrefs) => WeakMap<Element, KeyPrefs>;
 /** The preferences of the panel `node` sits in. */
 export declare function keyPrefs(node: EventTarget | null): KeyPrefs;
-/** -1, 1 or 0 for ←/→ (and h/l unless the panel turned the letter aliases off). */
+/** -1, 1 or 0 for ←/→. */
 export declare function arrowOf(event: KeyboardEvent): -1 | 0 | 1;
 /** ⇧'s multiplier for this event (1 without ⇧). */
 export declare const bigOf: (event: KeyboardEvent) => number;

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

@@ -0,0 +1,20 @@
+import type { MorphFrame } from "./morph.js";
+export interface Presence {
+    readonly shown: boolean;
+    /** Shows or hides the panel; `animate: false` puts it there at once (a reload, a first paint). */
+    set(shown: boolean, animate: boolean): void;
+    /** The shape the GPU overlay draws while it shows or hides (see `MorphFrame`), else undefined. */
+    frame(now: number): MorphFrame | undefined;
+    dispose(): void;
+}
+/** What the panel looks like at `x` (0 hidden, 1 shown) on the way in or out. */
+export declare function presenceLook(x: number, inline: boolean, reduced: boolean): {
+    opacity: number;
+    blur: number;
+    scale: number;
+    fold: number;
+};
+export declare function createPresence(root: HTMLElement, options: {
+    readonly inline: boolean;
+    readonly wake: () => void;
+}): Presence;

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

@@ -7,6 +7,35 @@ export type CommandScope = "selection" | "row" | "group" | "all";
 export declare function commandScope(level: FocusLevel, selection?: boolean): CommandScope;
 /** How a command reads from where it would land: "Random this", "Reset group", "Random all". */
 export declare function scopeLabel(verb: string, scope: CommandScope): string;
+/** A level below the panel that the header's crumbs name: a card, a row, an open editor's part. */
+export type CrumbLevel = "card" | "row" | "editor";
+export interface Crumb {
+    readonly level: CrumbLevel;
+    readonly label: string;
+}
+/**
+ * Where keys go, as the header reads after the panel's title: `Shape › Cohesion`. A level that
+ * isn't focused (or has no name) is left out; the last crumb is the deepest, the one focused.
+ */
+export declare function crumbTrail(path: {
+    readonly card?: string;
+    readonly row?: string;
+    readonly editor?: string;
+}): Crumb[];
+/**
+ * Where Esc goes from the deepest crumb: the crumb before it, else the panel (`title`). Nothing
+ * at the panel itself (no crumbs), where Esc leaves.
+ */
+export declare function escTarget(trail: readonly Crumb[], title: string): string | undefined;
+/**
+ * How much of a trail fits `room` px: crumbs from `from` on show (the ones before it fold into
+ * one "…"), and the Esc hint shows only when it fits too. The deepest crumb always shows.
+ * `widths` are the crumbs' own; `sep` a separator's (with its gaps), `more` the "…"'s.
+ */
+export declare function fitCrumbs(widths: readonly number[], room: number, sep: number, more: number, hint?: number): {
+    from: number;
+    hint: boolean;
+};
 /**
  * The option a digit picks among `count` (0-based), or undefined when it names none: 1–9 pick
  * the first nine, as they read.

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

@@ -1,4 +1,5 @@
 import type { Knob as KnobField } from "../core/schema.js";
+import { type DetentKind } from "./feel.js";
 import { type Roll, Spring, VelocityTracker } from "./motion.js";
 export interface DigitPlace {
     ch: string;
@@ -39,6 +40,17 @@ export interface Slider {
     readonly notchRatio: number;
     /** Whether a drag is currently held on the default by the notch's magnet. */
     isMagnetized(): boolean;
+    /** The detent holding a drag right now, if any. */
+    heldDetent(): DetentKind | undefined;
+    /** Where the active preset's value sits [0..1], when it differs from the default. */
+    readonly baseRatio: number | undefined;
+    /** When the handle last caught a detent (see `settleScale`). */
+    readonly settledAt: number;
+    /**
+     * How many halvings the drag in hand moves at, for its ruler (0 at 1:1 or at rest, up to 3; each
+     * level halves the tenths again). Each level shows `rulerAlpha(depth, level)` of the way.
+     */
+    rulerDepth(): number;
     /** When the readout last popped (a click landing on a decile, or the default's magnet). */
     poppedAt: number;
     /** Formatted numeric string without unit (e.g. "0.45" or "98"). */
@@ -83,10 +95,15 @@ export declare function stepValue(field: {
 /**
  * A DialKit-style slider: the whole row is the track, the fill is a full-height block,
  * the handle is a hairline that only shows on hover, and the label + value sit on the
- * track itself. Dragging follows the pointer exactly (⌥ for 1/10 speed) and the default's notch
- * pulls it in from a few px away; a click snaps to the nearest step (or nearest 10% when there
- * are many steps) with a short spring-like ease. A sideways trackpad pan moves it like a drag.
+ * track itself. Dragging follows the pointer exactly, slower the further the pointer strays off
+ * the row (and ⌥ for 1/10 speed); detents at the default, the active preset's value and round
+ * values hold it for a few px, and past an end the row stretches like rubber. A click snaps
+ * to the nearest step (or nearest 10% when there are many steps) with a short spring-like ease.
+ * A sideways trackpad pan moves it like a drag.
  */
 export declare function createSlider(doc: Document, key: string, initialField: KnobField, set: (value: number, options?: {
     coalesce?: boolean;
-}) => void, onMotionWake?: () => void): Slider;
+}) => void, onMotionWake?: () => void, options?: {
+    /** The active preset's value for this key (what Reset goes back to first). */
+    readonly base?: () => number | undefined;
+}): Slider;

package/dist/types/panel/tab-transition.d.ts

@@ -0,0 +1,15 @@
+/**
+ * A tab change, as one layout animation: what leaves fades out where it stood (lifted out of the
+ * flow, so it takes no room), what arrives fades in block by block with a small rise, what stays
+ * glides to its new place, and the surface (and any card whose rows change) springs to its new
+ * height. Every spring keeps its position and velocity when another tab is picked mid-flight.
+ *
+ * While the pointer stays on the panel the surface never shrinks: a panel anchored at its foot
+ * (or centred) would otherwise move its tabs out from under the pointer between two clicks. It
+ * settles to its size once the pointer leaves.
+ */
+export declare function tabTransition(body: HTMLElement, root: HTMLElement, wake: () => void): {
+    readonly running: boolean;
+    finish: () => void;
+    to(want: Map<HTMLElement, boolean>): void;
+};

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

@@ -28,4 +28,4 @@ export interface TabStrip {
     focus(options?: FocusOptions): void;
     dispose(): void;
 }
-export declare function createTabStrip(doc: Document, choose: (id: string) => void): TabStrip;
+export declare function createTabStrip(doc: Document, choose: (id: string, animate?: boolean) => void): TabStrip;

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

@@ -0,0 +1,27 @@
+import { type StoragePort } from "../core/storage.js";
+type KeyEventLike = Pick<KeyboardEvent, "key" | "code" | "ctrlKey" | "metaKey" | "altKey" | "shiftKey" | "repeat" | "isComposing" | "defaultPrevented" | "target">;
+/** Whether a keydown is `key` for the toggle: outside a text field, with no modifier held. */
+export declare function isToggleKey(event: KeyEventLike, key: string): boolean;
+/** A panel or chip that comes and goes with the toggle key. */
+export interface ToggleSurface {
+    /** Its store's id: what's remembered. */
+    readonly id: string;
+    readonly key: string;
+    readonly storage: () => StoragePort | null;
+    /** Where focus may be when it hides, to give back when it shows. */
+    readonly root: HTMLElement;
+    /** Shows or hides it; `animate: false` puts it there at once. */
+    show(shown: boolean, animate: boolean): void;
+}
+export interface ToggleLayer {
+    /** Joins the layer; `shown` is how it should start (what its store remembers). */
+    register(surface: ToggleSurface): {
+        readonly shown: boolean;
+        dispose(): void;
+    };
+    /** Shows or hides everything listening for `key`; false when nothing does. */
+    toggle(key: string): boolean;
+}
+/** The page's toggle layer, for `doc`. */
+export declare function toggleLayer(doc: Document): ToggleLayer;
+export {};

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

@@ -39,7 +39,7 @@ export declare const tune: <T extends {
     readonly zeta: number;
 }) => T;
 /** Whether `target` is an editable field or select that takes typed keys. */
-export declare const isTypingTarget: (t: EventTarget | null) => boolean;
+export { isTypingTarget } from "../core/keys.js";
 /**
  * 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.

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

@@ -0,0 +1,12 @@
+/**
+ * A thin scrollbar drawn over a scroller's content, in place of the native one beside it. A native
+ * scrollbar that's always shown (as a system may be set) takes its width from the rows the moment
+ * the content overflows, so every row jumps sideways, and gives it back when it stops; this one
+ * takes no room. It shows while the content scrolls and while the pointer is over the scroller,
+ * and drags. `content` is the element whose height makes the scroll: it's watched for changes.
+ * The scroller hides its own (`scrollbar-width: none`) and is positioned.
+ */
+export declare function overlayScrollbar(scroller: HTMLElement, content: Element): {
+    update: () => void;
+    dispose(): void;
+};

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

@@ -97,10 +97,11 @@ export declare function foldFaces(prev: FoldFaces, p: number): FoldFaces;
  */
 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.
+ * The fold's chevron, flipping over: its turn about its vertical axis (degrees, drawn with depth)
+ * against the rail's chevron at flip progress `f` (0 open, 1 folded). Edge-on halfway, it comes
+ * round mirrored, rolling the way the pane's edge travels.
  */
-export declare function chevronFlip(f: number): number;
+export declare function chevronFlip(f: number, edge: "start" | "end"): number;
 /** How a pane folds: see `SplitOptions.fold`. */
 export interface FoldStyle {
     readonly chevron: "flip" | "turn";

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

@@ -45,8 +45,9 @@ export interface SplitOptions extends UiLook {
 /** 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.
+     * The collapse chevron: `"flip"` (default) turns it over about its vertical axis, with depth,
+     * mirrored as it travels, on its own snappy spring; `"turn"` spins it half a turn flat, with
+     * the fold.
      */
     readonly chevron?: "flip" | "turn";
     /**
@@ -54,7 +55,7 @@ export interface SplitFold {
      * 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. */
+    /** The fold's spring, in seconds (no bounce): 0.25 unless set. */
     readonly duration?: number;
 }
 export interface SplitPane {
@@ -85,8 +86,9 @@ export interface Split {
 /**
  * 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.
+ * the arrow keys (⇧ for bigger steps) and Enter to collapse; in a row, double-click a pane's header
+ * to collapse it too. 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;