@kitlangton/knobs 0.1.0 → 0.2.0

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/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,60 @@ 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: 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.
+ */
+export declare function chevronFlip(f: number): 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,23 @@ 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) 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.
+     */
+    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.3 unless set. */
+    readonly duration?: number;
 }
 export interface SplitPane {
     readonly id: string;