@kitlangton/knobs 0.0.0-stage → 0.1.0

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