@kitlangton/knobs 0.1.0 → 0.3.0

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

@@ -0,0 +1,122 @@
+/** The built-in kinds, each with its icon and tint. */
+export type ActivityKind = "you" | "agent" | "proposal" | "review" | "pr" | "build" | "blocked" | "shipped";
+export interface ActivityEvent {
+    /** Unique, and the same across `set()`: rows keep their identity and glide. */
+    readonly id: string;
+    /** A built-in kind (its icon and tint), or a name of your own with `icon` and `tint`. */
+    readonly kind?: ActivityKind | (string & {});
+    /** Who: "You", "Agent", "Ryan". */
+    readonly actor?: string;
+    /** One line; it fades at its end when cut off. A group without one says "3 updates". */
+    readonly title?: string;
+    /** Trailing, already formatted ("2m", "9:41"); it rolls when it changes. */
+    readonly time?: string;
+    /** A duration chip, "▶ 0:32": seconds, or text as it should read. */
+    readonly duration?: number | string;
+    /** Small thumbnails before the time (image URLs; four at most show). */
+    readonly thumbs?: readonly string[];
+    /** SVG markup, a glyph or a node in place of the kind's icon. */
+    readonly icon?: string | Node;
+    /** A CSS colour in place of the kind's tint. */
+    readonly tint?: string;
+    /** Makes a group that opens in place ("Agent · 3 updates"). One level deep. */
+    readonly children?: readonly ActivityEvent[];
+    /** The live or latest step: its node takes a ring. */
+    readonly current?: boolean;
+    /** Quieter: past steps, minor updates. */
+    readonly dimmed?: boolean;
+}
+export interface ActivityRow {
+    readonly id: string;
+    readonly event: ActivityEvent;
+    /** 0 for an event, 1 for one inside an open group. */
+    readonly depth: 0 | 1;
+    readonly parent: string | null;
+    /** Has children: it opens and closes. */
+    readonly group: boolean;
+    readonly expanded: boolean;
+}
+/** The rows on show: every event, and the children of open groups right after their group. */
+export declare function flattenActivity(events: readonly ActivityEvent[], expanded: ReadonlySet<string>): ActivityRow[];
+/** Every event by id, children included, with its group. */
+export declare function indexActivity(events: readonly ActivityEvent[]): Map<string, {
+    event: ActivityEvent;
+    parent: string | null;
+}>;
+export type ActivityKey = "ArrowUp" | "ArrowDown" | "ArrowLeft" | "ArrowRight" | "Home" | "End";
+export declare const isActivityKey: (key: string) => key is ActivityKey;
+/**
+ * What a key does from the selected row: ↑/↓ move (from nothing, to the first or the last),
+ * Home/End go to the ends, → opens a closed group and steps into an open one, ← closes an open
+ * group and steps out of a child to its group.
+ */
+export declare function navigateActivity(rows: readonly ActivityRow[], selected: string | null, key: ActivityKey): {
+    select?: string;
+    toggle?: {
+        id: string;
+        expanded: boolean;
+    };
+};
+/**
+ * Whether the rail takes a key it navigated: ↑/↓ and Home/End whenever there are rows (at an end
+ * they hold the selection), ← and → only when they open, close or step. A ← or → that does
+ * nothing is left to the page (a review stage stepping frames, say).
+ */
+export declare function takesActivityKey(key: ActivityKey, result: {
+    select?: string;
+    toggle?: unknown;
+}, rows: number): boolean;
+/**
+ * Where the selection goes when its row leaves the rows on show: to its group when that closed
+ * over it, else nowhere.
+ */
+export declare function keepSelection(rows: readonly ActivityRow[], selected: string | null, parentOf: (id: string) => string | null | undefined): string | null;
+/** What last moved the selection: keys show it as a tint, a pointer hides it. */
+export type ActivityInput = "key" | "pointer" | "blur" | "code";
+/**
+ * Whether the selection's tint shows: keys turn it on, a pointer turns it off (a click selects
+ * with no ring), losing focus turns it off unless the page's keys drive it, and a host's
+ * `select()` leaves it as it was.
+ */
+export declare function showsSelection(showing: boolean, input: ActivityInput, keys?: "focus" | "page"): boolean;
+/** Which ids came, went and stayed between two orders of rows. */
+export declare function diffActivity(before: readonly string[], after: readonly string[]): {
+    entered: string[];
+    left: string[];
+    kept: string[];
+};
+/** Rows stacked top to bottom from `top`: each one's y, and the bottom of the last. */
+export declare function stackRows(heights: readonly number[], top?: number, gap?: number): {
+    y: number[];
+    bottom: number;
+};
+export interface RailNode {
+    /** The node's centre. */
+    readonly y: number;
+    /** How far the line keeps clear of it on each side. */
+    readonly r: number;
+}
+/**
+ * The line through the nodes, as segments between neighbours that stop clear of each node, and
+ * only within `[from, to]` (the line's ends, which glide as rows come and go). One continuous
+ * thread at rest: nothing past the last node, nothing before the first.
+ */
+export declare function railSegments(nodes: readonly RailNode[], from: number, to: number): [number, number][];
+/**
+ * The scroll while a change takes the content from height `h0` to `h1` (now at `height`): it goes
+ * from `from` to where it has to end (no further down than the shorter content allows) in step
+ * with the height, and the space stays tall enough for it meanwhile. Closing a group at the
+ * scroll's end, the rows above glide down with the drawer instead of dropping in a frame.
+ */
+export declare function holdScroll(hold: {
+    readonly from: number;
+    readonly h0: number;
+    readonly h1: number;
+}, height: number, view: number): {
+    scroll: number;
+    space: number;
+};
+/** "0:32", "4:05", "1:02:03"; text passes through as it is. */
+export declare function formatDuration(duration: number | string): string;
+/** A group's title when it has none of its own: "1 update", "3 updates". */
+export declare function groupTitle(count: number): string;

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

@@ -0,0 +1,67 @@
+import { type ActivityEvent } from "./activity-model.js";
+import { type UiLook } from "./look.js";
+export interface ActivityOptions extends UiLook {
+    readonly events: readonly ActivityEvent[];
+    /** The selected event's id. */
+    readonly selected?: string | null;
+    /** Groups open from the start. */
+    readonly expanded?: Iterable<string>;
+    /** Keys and clicks moved the selection (a host's `select()` doesn't call it). */
+    readonly onSelect?: (id: string, event: ActivityEvent, source: "key" | "pointer") => void;
+    /** Enter on the selected row (on a group with no `onActivate`, Enter opens or closes it). */
+    readonly onActivate?: (id: string, event: ActivityEvent) => void;
+    readonly onToggle?: (id: string, expanded: boolean) => void;
+    /** Makes the duration chip a button. */
+    readonly onPlay?: (id: string, event: ActivityEvent) => void;
+    /**
+     * Where the newest events are: `"bottom"` (the default; oldest first) or `"top"`. `add()` puts
+     * an event there, and new events slide in from that side.
+     */
+    readonly newest?: "top" | "bottom";
+    /** Stay pinned to the newest end when it was in view as events arrive (default true). */
+    readonly follow?: boolean;
+    /**
+     * Where the keys come from: `"focus"` (the default) while the rail has focus, or `"page"` from
+     * anywhere a focused field or widget doesn't take them.
+     */
+    readonly keys?: "focus" | "page";
+    /** Icons (SVG markup or a glyph) for your own kinds, or in place of built-in ones. */
+    readonly icons?: Readonly<Record<string, string>>;
+    /** Tints (CSS colours) for your own kinds, or in place of built-in ones. */
+    readonly tints?: Readonly<Record<string, string>>;
+    /** The rail's accessible name. */
+    readonly label?: string;
+    /** Shown with no events. */
+    readonly empty?: string;
+}
+export interface Activity {
+    readonly element: HTMLElement;
+    /** New events: those that stay glide to their places, new ones bloom in, gone ones soften out. */
+    set(events: readonly ActivityEvent[]): void;
+    /** One more event at the newest end. */
+    add(event: ActivityEvent): void;
+    /**
+     * New events and where the newest are, in one change: rows glide to their new places, as with
+     * `set` (flipping `newest` with the events reversed reverses the rail in place).
+     */
+    update(next: {
+        events?: readonly ActivityEvent[];
+        newest?: "top" | "bottom";
+    }): void;
+    /** Selects (opening its group); `null` clears. Doesn't call `onSelect`. */
+    select(id: string | null): void;
+    readonly selected: string | null;
+    expand(id: string, expanded?: boolean): void;
+    isExpanded(id: string): boolean;
+    focus(): void;
+    destroy(): void;
+    /** The same as `destroy`, as the other pieces name it. */
+    dispose(): void;
+}
+/**
+ * A vertical rail of events: who did what, one line each, with a kind's icon on one continuous
+ * line. Groups open in place with their children on the same line. ↑/↓, Home/End move the
+ * selection (a tint that shows only once keys move it), ←/→ close and open groups, Enter
+ * activates. New events bloom in while the rest glide; every move is an interruptible spring.
+ */
+export declare function activity(container: HTMLElement, options: ActivityOptions): Activity;

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

@@ -10,7 +10,7 @@ export { popover, type Popover, type PopoverCloseReason, type PopoverOptions } f
 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 { 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";
@@ -18,3 +18,7 @@ export { tree, type Tree, type TreeOptions, type TreeRowContext, type TreeToggle
 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/look.d.ts

@@ -31,6 +31,15 @@ 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 { 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/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/react.d.ts

@@ -1,5 +1,7 @@
 import { type CSSProperties, type ReactNode } from "react";
+import { type Activity as ActivityHandle, type ActivityOptions } from "./activity.js";
 import { type Bento as BentoHandle, type BentoOptions } from "./bento.js";
+import { type OptionPicker as OptionPickerHandle, type OptionPickerOptions, type PickerOption } from "./picker.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";
@@ -43,3 +45,28 @@ export type BentoProps = BentoOptions & {
  * prop; callbacks always call the latest props.
  */
 export declare function Bento(props: BentoProps): import("react").JSX.Element;
+export type ActivityProps = ActivityOptions & {
+    className?: string;
+    style?: CSSProperties;
+    onReady?: (activity: ActivityHandle) => void;
+};
+/**
+ * `activity()` as a component. New `events` update it in place (rows keep their identity and
+ * glide); `selected` follows its prop; callbacks always call the latest props.
+ */
+export declare function Activity(props: ActivityProps): import("react").JSX.Element;
+export type OptionPickerProps = Omit<OptionPickerOptions, "body"> & {
+    /** An option's parameters, portalled under it the first time it opens (a `<Knobs>` panel, say). */
+    children?: (option: PickerOption) => ReactNode;
+    className?: string;
+    style?: CSSProperties;
+    onReady?: (picker: OptionPickerHandle) => void;
+};
+/**
+ * `optionPicker()` as a component: `children` renders each opened option's parameters into its
+ * place through a portal, so context and state carry through. `options`, `selected` and
+ * `chosen` follow their props; callbacks always call the latest props.
+ */
+export declare function OptionPicker(props: OptionPickerProps): import("react").JSX.Element;
+export type { ActivityEvent } from "./activity-model.js";
+export type { PickerOption } from "./picker.js";

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/solid.d.ts

@@ -1,5 +1,7 @@
 import { type JSX } from "solid-js";
+import { type Activity as ActivityHandle, type ActivityOptions } from "./activity.js";
 import { type Bento as BentoHandle, type BentoOptions } from "./bento.js";
+import { type OptionPicker as OptionPickerHandle, type OptionPickerOptions, type PickerOption } from "./picker.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";
@@ -38,3 +40,24 @@ export type BentoProps = BentoOptions & {
  * prop; callbacks always call the latest props.
  */
 export declare function Bento(props: BentoProps): JSX.Element;
+export type ActivityProps = ActivityOptions & {
+    onReady?: (activity: ActivityHandle) => void;
+};
+/**
+ * `activity()` as a component. New `events` update it in place (rows keep their identity and
+ * glide); `selected` follows its prop; callbacks always call the latest props.
+ */
+export declare function Activity(props: ActivityProps): JSX.Element;
+export type OptionPickerProps = Omit<OptionPickerOptions, "body"> & {
+    /** An option's parameters, rendered once, the first time it opens (a `KnobsPanel`, say). */
+    children?: (option: PickerOption) => JSX.Element;
+    onReady?: (picker: OptionPickerHandle) => void;
+};
+/**
+ * `optionPicker()` as a component: `children` renders an option's parameters under it, in this
+ * component's context. `options`, `selected` and `chosen` follow their props; callbacks always
+ * call the latest props.
+ */
+export declare function OptionPicker(props: OptionPickerProps): JSX.Element;
+export type { ActivityEvent } from "./activity-model.js";
+export type { PickerOption } from "./picker.js";

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

@@ -75,6 +75,61 @@ export declare function collapsibleSide(panes: readonly PaneSpec[], index: numbe
  * the rest to the end.
  */
 export declare function edgeOf(panes: readonly PaneSpec[], id: string): "start" | "end";
+/** How far a folding pane is from its open size (0) to its rail (1), by the size it shows. */
+export declare function foldProgress(size: number, open: number, rail: number): number;
+/** How much of each face a folding pane shows (0…1): its content, open, and its rail, folded. */
+export interface FoldFaces {
+    readonly content: number;
+    readonly rail: number;
+}
+/** A face that's leaving is gone by this far along the fold. */
+export declare const FACE_OUT = 0.4;
+/** A face that's arriving shows only over this last part of the fold. */
+export declare const FACE_IN = 0.3;
+/**
+ * The faces at fold progress `p`, from the last frame's. The content and the rail never show
+ * together: the content is gone before 40% and the rail starts past 70% (folding or opening).
+ */
+export declare function foldFaces(prev: FoldFaces, p: number): FoldFaces;
+/**
+ * The fold's chevron turn (degrees) at progress `p`: half a turn from the open pane's chevron to
+ * the rail's, rolling the way the pane's edge travels.
+ */
+export declare function chevronTurn(p: number, edge: "start" | "end"): number;
+/**
+ * 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, edge: "start" | "end"): number;
+/** How a pane folds: see `SplitOptions.fold`. */
+export interface FoldStyle {
+    readonly chevron: "flip" | "turn";
+    readonly title: "travel" | "fade";
+    /** Seconds, on a spring with no bounce. */
+    readonly duration: number;
+}
+export declare const FOLD_STYLE: FoldStyle;
+export declare function foldStyle(options?: Partial<FoldStyle>): FoldStyle;
+/**
+ * Where a header's title and the rail's label sit, each from its own box's start edge and the
+ * pane's top (`dy` is the title's height less the label's), as measured with the pane open.
+ */
+export interface TitlePlaces {
+    readonly title: number;
+    readonly label: number;
+    readonly dy: number;
+}
+/**
+ * The rail's label travelling as the header's title, at fold progress `p`: the offset that puts it
+ * on the title (the rail holds on to the pane's moving edge, the header to the inner content that
+ * keeps its open size), and its turn from upright (-90°) to the rail's vertical (0°).
+ */
+export declare function titleTravel(at: TitlePlaces, open: number, rail: number, edge: "start" | "end", p: number): {
+    x: number;
+    y: number;
+    turn: number;
+};
 /** A saved layout, kept only where it names known panes with sane values. */
 export declare function parseLayout(raw: unknown, panes: readonly PaneSpec[]): SplitLayout | undefined;
 /** A layout as saved: sizes rounded to a tenth of a pixel. */

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

@@ -39,6 +39,24 @@ export interface SplitOptions extends UiLook {
      * hint mode (`s`), on by default; a code presses its button.
      */
     readonly hints?: boolean;
+    /** How collapsible panes fold to their rails and open again. */
+    readonly fold?: SplitFold;
+}
+/** How a pane folds (each part has a default). */
+export interface SplitFold {
+    /**
+     * 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";
+    /**
+     * The header's title: `"travel"` (default) turns it and slides it into the rail's label, one
+     * 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.25 unless set. */
+    readonly duration?: number;
 }
 export interface SplitPane {
     readonly id: string;
@@ -68,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;