@kitlangton/knobs 0.0.0-stage → 0.2.0

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

@@ -0,0 +1,83 @@
+/** The visible window: `start` seconds at the left edge, `span` seconds across. */
+export interface TimeView {
+    readonly start: number;
+    readonly span: number;
+}
+export type TimeUnits = "seconds" | "frames";
+export interface Tick {
+    readonly t: number;
+    readonly label: string;
+}
+export interface Ticks {
+    readonly major: readonly Tick[];
+    readonly minor: readonly number[];
+    /** Seconds between major ticks. */
+    readonly step: number;
+}
+/** A frame's time, rounded to the nearest frame. */
+export declare const toFrame: (t: number, fps: number) => number;
+export declare const frameTime: (t: number, fps: number) => number;
+/** "1.5s", "12s", "1:05", "1:02:05" for seconds; the frame number for frames. */
+export declare function timeLabel(t: number, units: TimeUnits, fps: number, step?: number): string;
+/**
+ * Ticks for a view `width` px wide: major ticks at least `minGap` px apart on a nice step (whole
+ * frames in frame units), labelled; minor ones between them, down to single frames once a frame
+ * is `frameGap` px wide.
+ */
+export declare function rulerTicks(view: TimeView, width: number, o: {
+    fps: number;
+    units?: TimeUnits;
+    minGap?: number;
+    frameGap?: number;
+}): Ticks;
+/** Clamps a view to `[0, duration]` with a little room (`pad` of the span) at either end. */
+export declare function clampView(view: TimeView, duration: number, o?: {
+    minSpan?: number;
+    pad?: number;
+}): TimeView;
+/** Zooms by `factor` (above 1 zooms in) keeping time `at` under the same point. */
+export declare function zoomView(view: TimeView, factor: number, at: number): TimeView;
+/** The view panned so `t` sits at least `margin` (of the span) inside it, or unchanged. */
+export declare function followView(view: TimeView, t: number, margin?: number): TimeView;
+/**
+ * The playhead's soft pull toward a marker while it's scrubbed: within `radius` px it follows the
+ * pointer by a curve that's flat at the marker (it sticks there) and meets the pointer at the
+ * edge, with no jump. Returns the time to show and the marker it rests on, if any.
+ */
+export declare function magnet(raw: number, stops: readonly number[], pxPerSec: number, radius?: number, stick?: number): {
+    t: number;
+    stop: number | null;
+};
+/**
+ * Where a scrub lands: on a marker it's resting on, else on the nearest frame (with `frames`),
+ * clamped to `[0, duration]`.
+ */
+export declare function scrubTime(raw: number, o: {
+    duration: number;
+    fps: number;
+    pxPerSec: number;
+    stops?: readonly number[];
+    frames?: boolean;
+    radius?: number;
+}): {
+    t: number;
+    shown: number;
+    stop: number | null;
+};
+/** The marker before (`-1`) or after (`1`) time `t`, by a frame's margin, or null. */
+export declare function adjacentMarker<M extends {
+    readonly time: number;
+}>(markers: readonly M[], t: number, dir: 1 | -1, fps: number): M | null;
+/** Advances playing time by `dt`, looping inside `loop` (or the whole) when asked. */
+export declare function advance(t: number, dt: number, o: {
+    duration: number;
+    loop?: {
+        start: number;
+        end: number;
+    } | null;
+    repeat?: boolean;
+}): {
+    t: number;
+    ended: boolean;
+    wrapped: boolean;
+};

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

@@ -0,0 +1,76 @@
+import { type UiLook } from "./look.js";
+import { type TimeUnits, type TimeView } from "./timeline-model.js";
+export interface TimelineMarker {
+    readonly id: string;
+    /** Seconds. */
+    readonly time: number;
+    readonly label?: string;
+    /** A colour of its own (CSS); the accent otherwise. */
+    readonly color?: string;
+}
+export interface TimelineRange {
+    readonly id: string;
+    readonly start: number;
+    readonly end: number;
+    readonly label?: string;
+    /** Playback loops inside it (`I` / `O` make the `"loop"` range, which loops). */
+    readonly loop?: boolean;
+}
+export type SeekSource = "scrub" | "key" | "marker" | "play" | "code";
+export interface TimelineOptions extends UiLook {
+    /** Seconds. */
+    readonly duration: number;
+    readonly time?: number;
+    readonly playing?: boolean;
+    /** Frames per second (30): frame steps, frame labels, and where scrubs land. */
+    readonly fps?: number;
+    /** What the ruler counts in (`"seconds"`). */
+    readonly units?: TimeUnits;
+    readonly markers?: readonly TimelineMarker[];
+    readonly ranges?: readonly TimelineRange[];
+    /** Scrubs land on frames and stick to markers (`true`); `{ frames, markers }` picks. */
+    readonly snap?: boolean | {
+        readonly frames?: boolean;
+        readonly markers?: boolean;
+    };
+    /** Playback speed (1). */
+    readonly speed?: number;
+    /** Playback starts over at the end when there's no loop range (`false`: it stops). */
+    readonly repeat?: boolean;
+    readonly label?: string;
+    /** The time moved: scrubbed, stepped, jumped, played (every frame) or set from code. */
+    onSeek?(time: number, source: SeekSource): void;
+    onPlay?(playing: boolean): void;
+    /** Markers were added, moved, renamed or removed (the whole list). */
+    onMarkers?(markers: readonly TimelineMarker[]): void;
+    /** Ranges were set, moved or cleared (the whole list). */
+    onRanges?(ranges: readonly TimelineRange[]): void;
+    /** Playback passed a marker. */
+    onCross?(marker: TimelineMarker): void;
+    /**
+     * Play, each marker and the playhead take codes in the page's hint mode (`s`), on by default:
+     * a marker's code jumps to it, the playhead's focuses the timeline.
+     */
+    readonly hints?: boolean;
+}
+export interface Timeline {
+    readonly element: HTMLElement;
+    readonly time: number;
+    readonly playing: boolean;
+    readonly markers: readonly TimelineMarker[];
+    readonly ranges: readonly TimelineRange[];
+    readonly view: TimeView;
+    seek(time: number): void;
+    play(): void;
+    pause(): void;
+    toggle(): void;
+    /** New duration, markers, ranges, fps, units or speed; the time and view stay. */
+    update(next: Partial<Omit<TimelineOptions, "onSeek" | "onPlay" | "onMarkers" | "onRanges" | "onCross">>): void;
+    /** Shows the whole duration (animated). */
+    fit(): void;
+    /** Zooms by `factor` (above 1 zooms in) around a time (the playhead's by default). */
+    zoom(factor: number, at?: number): void;
+    focus(): void;
+    dispose(): void;
+}
+export declare function timeline(container: HTMLElement, options: TimelineOptions): Timeline;

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

@@ -0,0 +1,19 @@
+import { type UiLook } from "./look.js";
+export interface ToastOptions {
+    /** Ms it stays (3200; errors 6000). */
+    readonly linger?: number;
+    readonly tone?: "info" | "warn" | "error";
+    /** A button in the pill (Undo, say). */
+    readonly action?: {
+        readonly label: string;
+        run(): void;
+    };
+    readonly look?: UiLook;
+    /** Where it lives, to take that element's tokens (a page); the overlay layer by default. */
+    readonly within?: HTMLElement;
+    readonly doc?: Document;
+}
+export interface Toast {
+    dismiss(): void;
+}
+export declare function toast(message: string, options?: ToastOptions): Toast;

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

@@ -0,0 +1,19 @@
+import type { UiLook } from "./look.js";
+import { type Placement } from "./overlay-model.js";
+export interface TooltipOptions {
+    /** A key or combination (`"Mod+K"`, `"Space"`): shown as chips after the text. */
+    readonly shortcut?: string;
+    /** `top` by default. */
+    readonly placement?: Placement;
+    /** Ms over the target before it shows (500); a hand-off shows at once. */
+    readonly delay?: number;
+    readonly look?: UiLook;
+}
+/** Text, a function read each time it shows, or text with options. */
+export type TooltipContent = string | (() => string) | ({
+    readonly text: string | (() => string);
+} & TooltipOptions);
+/** Shows `content` over `el` after a pause (or on keyboard focus). Returns the remover. */
+export declare function tooltip(el: HTMLElement, content: TooltipContent, options?: TooltipOptions): () => void;
+/** Turns on `data-tip` (and `data-tip-shortcut`, `data-tip-placement`) tooltips in a document. */
+export declare function tooltips(doc?: Document): void;

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

@@ -0,0 +1,125 @@
+/** How a tree reads your items. */
+export interface TreeAccess<T> {
+    id(item: T): string;
+    /** Children, or nothing for a leaf. An empty array is a parent with none (it takes drops). */
+    children(item: T): readonly T[] | null | undefined;
+    label(item: T): string;
+}
+export interface FlatRow<T> {
+    readonly id: string;
+    readonly item: T;
+    readonly depth: number;
+    readonly parent: string | null;
+    /** Position among its parent's children (all of them, filtered or not). */
+    readonly index: number;
+    readonly hasChildren: boolean;
+    /** Takes children (a drop "into" it). */
+    readonly container: boolean;
+    readonly expanded: boolean;
+    /** Where the filter matched its label, if it did. */
+    readonly match?: readonly [number, number];
+    /** Shown only because something under it matched. */
+    readonly ancestor?: boolean;
+}
+export type TreeFilter<T> = string | ((item: T) => boolean) | null | undefined;
+/** Where the filter matches a label: a case-insensitive substring. */
+export declare function matchLabel(label: string, query: string): readonly [number, number] | undefined;
+/**
+ * The rows on show, top to bottom: expanded parents' children follow them. With a filter, rows
+ * that match show with every ancestor (opened while it runs, marked `ancestor` when they don't
+ * match themselves).
+ */
+export declare function flatten<T>(roots: readonly T[], access: TreeAccess<T>, expanded: ReadonlySet<string>, filter?: TreeFilter<T>): FlatRow<T>[];
+/** Every item by id, with its parent and position. */
+export declare function indexTree<T>(roots: readonly T[], access: TreeAccess<T>): Map<string, {
+    item: T;
+    parent: string | null;
+    index: number;
+    depth: number;
+}>;
+/** The ids of an item's ancestors, nearest first. */
+export declare function ancestors(index: ReadonlyMap<string, {
+    parent: string | null;
+}>, id: string): string[];
+export type NavKey = "ArrowUp" | "ArrowDown" | "ArrowLeft" | "ArrowRight" | "Home" | "End";
+export interface NavResult {
+    readonly active: string | null;
+    /** Open or close a parent instead of moving. */
+    readonly toggle?: {
+        readonly id: string;
+        readonly expanded: boolean;
+    };
+}
+/** Roving focus: ↑↓ move, ← closes or goes to the parent, → opens or goes to the first child. */
+export declare function navigate<T>(rows: readonly FlatRow<T>[], active: string | null, key: NavKey | "PageUp" | "PageDown", page?: number): NavResult;
+/**
+ * Type-ahead: the next row whose label starts with what's been typed, after the active one (or
+ * from it, once the word is longer than a letter, so typing on refines in place).
+ */
+export declare function typeahead<T>(rows: readonly FlatRow<T>[], active: string | null, typed: string, label: (item: T) => string): string | null;
+export interface Selection {
+    readonly ids: readonly string[];
+    readonly anchor: string | null;
+}
+/**
+ * A click or keyboard selection: plain picks one, ⌘/Ctrl adds or removes, ⇧ takes the range from
+ * the anchor in the order shown (⇧⌘ adds it to what's there).
+ */
+export declare function select<T>(rows: readonly FlatRow<T>[], current: Selection, id: string, mods?: {
+    readonly shift?: boolean;
+    readonly toggle?: boolean;
+}): Selection;
+/** The topmost of `ids`: none whose ancestor is also among them, in tree order. */
+export declare function topmost<T>(roots: readonly T[], access: TreeAccess<T>, ids: Iterable<string>): string[];
+/**
+ * A move: take `ids` out (with their subtrees), then insert them in order at `index` among
+ * `parent`'s remaining children (`null` is the top level).
+ */
+export interface TreeMove {
+    readonly ids: readonly string[];
+    readonly parent: string | null;
+    readonly index: number;
+}
+/** Whether a move keeps the tree a tree: nothing goes inside itself. */
+export declare function validMove<T>(roots: readonly T[], access: TreeAccess<T>, move: TreeMove): boolean;
+/** The tree's defaults: `item.id`, `item.children`, and `item.label` or the id. */
+export declare const plainAccess: TreeAccess<{
+    readonly id: string;
+    readonly label?: string;
+    readonly children?: readonly unknown[] | null;
+}>;
+/**
+ * Applies a move to plain `{ id, children }` items (or any, through `access`), returning new
+ * arrays along the changed paths (items themselves are copied only where their children change).
+ * `make(item, children)` builds a parent with new children; the default spreads the item.
+ */
+export declare function applyMove<T extends {
+    readonly id: string;
+}>(roots: readonly T[], move: TreeMove): T[];
+export declare function applyMove<T>(roots: readonly T[], access: TreeAccess<T>, move: TreeMove, make?: (item: T, children: T[]) => T): T[];
+/**
+ * ⌥↑/⌥↓: the selected rows step past their neighbour among their siblings. Rows under different
+ * parents move with the first one's parent; at an end they stay.
+ */
+export declare function stepMove<T>(roots: readonly T[], access: TreeAccess<T>, ids: readonly string[], dir: -1 | 1): TreeMove | undefined;
+export type DropZone = "before" | "after" | "into";
+export interface DropTarget {
+    readonly move: TreeMove;
+    /** Draw a line after row `line` (−1: above the first row) at `depth`… */
+    readonly line?: {
+        readonly after: number;
+        readonly depth: number;
+    };
+    /** …or wash the row a drop goes into. */
+    readonly into?: string;
+}
+/** Which zone of a row the pointer is over (0–1 down the row): parents take a middle band. */
+export declare function zoneAt(fraction: number, container: boolean): DropZone;
+/**
+ * Where a drop lands. Over the top of a row it goes before it; over the middle of a parent, into
+ * it (at the end); over the bottom, after it, or first inside it when it's open. Below the last
+ * row of a branch, `depth` (from the pointer's x) picks how far out it goes.
+ */
+export declare function dropTarget<T>(rows: readonly FlatRow<T>[], access: TreeAccess<T>, over: number, zone: DropZone, ids: readonly string[], depth?: number): DropTarget | undefined;
+/** The rows a scroller of `height` at `scrollTop` shows, with `overscan` either side. */
+export declare function virtualWindow(scrollTop: number, height: number, rowHeight: number, count: number, overscan?: number): readonly [number, number];

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

@@ -0,0 +1,95 @@
+import { type UiLook } from "./look.js";
+import { type TreeFilter, type TreeMove } from "./tree-model.js";
+/** A row accessory that flips a flag: visibility, a lock, or one of your own. */
+export interface TreeToggle<T> {
+    /** `"visible"` and `"locked"` bring their own icons. */
+    readonly id: string;
+    readonly label: string;
+    /** Whether the item is in its usual state (visible, unlocked): only the other one shows at rest. */
+    get(item: T): boolean;
+    /** Flip it for these ids (the selection, when the row is in it). */
+    set(ids: readonly string[], value: boolean): void;
+    /** SVG markup for each state. */
+    icon?(on: boolean): string;
+}
+export interface TreeRowContext {
+    readonly id: string;
+    readonly depth: number;
+    readonly expanded: boolean;
+    readonly selected: boolean;
+    readonly element: HTMLElement;
+}
+export interface TreeOptions<T> extends UiLook {
+    readonly items: readonly T[];
+    /** Item → id (unique); `item.id` unless set. */
+    readonly getId?: (item: T) => string;
+    /** Item → children (`item.children` unless set); an array, even empty, takes drops. */
+    readonly getChildren?: (item: T) => readonly T[] | null | undefined;
+    /** Item → label (`item.label`, else its id). */
+    readonly getLabel?: (item: T) => string;
+    /** A glyph, SVG markup or node before the label. */
+    readonly icon?: (item: T) => string | Node | undefined;
+    /** Dimmed text after the label (a count, a kind). */
+    readonly detail?: (item: T) => string | undefined;
+    /** Your own content in place of the label. */
+    readonly render?: (item: T, row: TreeRowContext) => Node | string | undefined | void;
+    readonly selection?: Iterable<string>;
+    readonly onSelect?: (ids: readonly string[], primary: string | null) => void;
+    readonly expanded?: Iterable<string>;
+    readonly onToggle?: (id: string, expanded: boolean) => void;
+    /** Drag and ⌥↑↓ report moves; apply them (`applyMove` does for plain items) and `update`. */
+    readonly onMove?: (move: TreeMove) => void;
+    readonly canDrop?: (move: TreeMove) => boolean;
+    /** F2 or Enter renames in place. */
+    readonly onRename?: (id: string, label: string) => void;
+    /** A double-click (and Enter, without `onRename`). */
+    readonly onActivate?: (id: string) => void;
+    readonly toggles?: readonly TreeToggle<T>[];
+    readonly filter?: TreeFilter<T>;
+    /** Pixels; `--k-row` unless set. */
+    readonly rowHeight?: number;
+    /** The tree's accessible name. */
+    readonly label?: string;
+    /** Shown with no rows. */
+    readonly empty?: string;
+    /**
+     * Letters jump to a matching label (on by default). `false` leaves every letter to the page (a
+     * host's single-key shortcuts), and a function decides by key which ones start a jump; once one
+     * has, the letters typed right after it carry on the run.
+     */
+    readonly typeahead?: boolean | ((key: string) => boolean);
+    /**
+     * Its rows on screen take codes in the page's hint mode (`s`), on by default; a code selects its
+     * row as a click does. While the page has hint mode, `s` goes to it rather than type-ahead.
+     */
+    readonly hints?: boolean;
+}
+export interface Tree<T> {
+    readonly element: HTMLElement;
+    /** New items: rows that stay glide to their new places, others fold in and out. */
+    update(items: readonly T[]): void;
+    select(ids: Iterable<string>, primary?: string | null): void;
+    readonly selection: readonly string[];
+    readonly active: string | null;
+    expand(id: string, expanded?: boolean): void;
+    isExpanded(id: string): boolean;
+    /** A query (label substring) or a test; matching rows show with their ancestors. */
+    filter(filter: TreeFilter<T>): void;
+    /** The ids on show, top to bottom. */
+    rows(): readonly string[];
+    focus(id?: string): void;
+    /** Opens its ancestors and scrolls it into view. */
+    reveal(id: string): void;
+    rename(id: string): void;
+    /** Draws rows again from their items (after you change them in place). */
+    refresh(): void;
+    dispose(): void;
+}
+/**
+ * An outliner: virtualised rows (thousands scroll at full speed), springing open and shut with
+ * the children cascading out from under their parent. Roving focus (↑↓, ← to close or go up, → to
+ * open or go down, Home/End, type-ahead, Space), ⇧/⌘ multi-selection, drag to reorder and
+ * reparent (⌥↑↓ by keys), inline rename, visibility and lock toggles, and a filter that keeps
+ * matching rows' ancestors.
+ */
+export declare function tree<T>(container: HTMLElement, options: TreeOptions<T>): Tree<T>;