@kitlangton/knobs 0.4.0-next.11 → 0.4.0-next.13

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

@@ -0,0 +1,116 @@
+/** The camera: a world point `p` is drawn at `p * scale + (x, y)` in the canvas's own px. */
+export interface CanvasView {
+    readonly x: number;
+    readonly y: number;
+    readonly scale: number;
+}
+export interface CanvasRect {
+    readonly x: number;
+    readonly y: number;
+    readonly w: number;
+    readonly h: number;
+}
+export interface CanvasPoint {
+    readonly x: number;
+    readonly y: number;
+}
+export declare const clamp: (v: number, lo: number, hi: number) => number;
+/**
+ * Tiles in rows, in order: each row takes tiles until the next would pass `width`, rows sit `gap`
+ * apart and tiles top-align in them. Rects land on whole px, so at 100% they're on the pixel grid.
+ */
+export declare function packRows(sizes: readonly {
+    readonly w: number;
+    readonly h: number;
+}[], opts: {
+    readonly gap: number;
+    readonly width: number;
+    readonly x?: number;
+    readonly y?: number;
+}): CanvasRect[];
+/**
+ * How wide rows run so the packed set comes out about `aspect` (width / height): a bisection
+ * between the widest tile and one long row, on how the packing actually comes out.
+ */
+export declare function rowWidth(sizes: readonly {
+    readonly w: number;
+    readonly h: number;
+}[], gap: number, aspect: number): number;
+/**
+ * Where every item goes: one with an `x` and `y` stays there; the rest pack in rows (`packRows`),
+ * under the placed ones if there are any.
+ */
+export declare function layoutCanvas(items: readonly {
+    readonly x?: number;
+    readonly y?: number;
+    readonly w: number;
+    readonly h: number;
+}[], opts: {
+    readonly gap: number;
+    readonly width?: number;
+    readonly aspect?: number;
+}): {
+    rects: CanvasRect[];
+    width: number;
+};
+/** The rect around `rects`, or null for none. */
+export declare function boundsOf(rects: readonly CanvasRect[]): CanvasRect | null;
+/** Screen (canvas px) to world, and back. */
+export declare const toWorld: (v: CanvasView, p: CanvasPoint) => CanvasPoint;
+export declare const toScreen: (v: CanvasView, p: CanvasPoint) => CanvasPoint;
+/** The view at `scale` (clamped to `min`…`max`), with the world point under `at` still under it. */
+export declare function zoomAround(v: CanvasView, scale: number, at: CanvasPoint, min?: number, max?: number): CanvasView;
+/**
+ * Two fingers moved: the world point under their old midpoint `from` lands under the new one
+ * `to`, with the zoom times `ratio` (zoom around `from`, then follow the midpoint).
+ */
+export declare function pinchView(v: CanvasView, from: CanvasPoint, to: CanvasPoint, ratio: number, min?: number, max?: number): CanvasView;
+/** The most one wheel event zooms (a mouse wheel's notch under ⌘ or ctrl). */
+export declare const WHEEL_ZOOM_MAX = 1.25;
+/**
+ * One ⌘/ctrl-wheel event's zoom factor, applied directly: a trackpad pinch (ctrl) at 1% per px,
+ * ⌘-scroll at .25%, and never more than `WHEEL_ZOOM_MAX` either way per event, so a mouse
+ * wheel's big notches step evenly without springing.
+ */
+export declare function wheelZoom(deltaY: number, pinch: boolean): number;
+/** The view that shows `r` whole and centred in a `w` × `h` canvas, `pad` px in from its edges. */
+export declare function fitView(r: CanvasRect, w: number, h: number, opts?: {
+    readonly pad?: number;
+    readonly min?: number;
+    readonly max?: number;
+}): CanvasView;
+/**
+ * A path between two views, `t` 0 → 1. It zooms around the one canvas point both views agree on,
+ * at an even rate in log scale, so every point on screen travels one straight line in one
+ * direction (no curve from springing x, y and scale apart). Views at the same scale pan straight.
+ */
+export declare function viewPath(from: CanvasView, to: CanvasView): (t: number) => CanvasView;
+/** The translate on the device-pixel grid, so a resting view draws crisp. */
+export declare const snapView: (v: CanvasView, dpr: number) => CanvasView;
+/**
+ * The background's dots: `step` world px apart, drawn `size` canvas px apart, and how strongly
+ * (0…1): they fade out as they crowd together zooming out and as they spread apart zooming in.
+ */
+export declare function dotGrid(scale: number, step?: number): {
+    size: number;
+    alpha: number;
+};
+/** What a key does to the view: 0 fits, 1 is 100%, = and - zoom in and out. */
+export type CanvasKey = "fit" | "actual" | "in" | "out";
+export declare function keyAction(e: {
+    readonly key: string;
+    readonly altKey?: boolean;
+}): CanvasKey | null;
+/** How far each zoom key steps. */
+export declare const KEY_ZOOM = 1.5;
+/**
+ * The hand's velocity at release (px/s) from recent samples `{ x, y, t (ms) }`: the travel over
+ * the last `window` ms. Zero if the hand had already stopped.
+ */
+export declare function releaseVelocity(samples: readonly {
+    readonly x: number;
+    readonly y: number;
+    readonly t: number;
+}[], now: number, window?: number): CanvasPoint;
+/** Momentum's time constant (s): the coast slows as iOS's scroll does (0.998 per ms). */
+export declare const COAST_TAU: number;

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

@@ -0,0 +1,66 @@
+import { type CanvasPoint, type CanvasRect, type CanvasView } from "./canvas-model.js";
+import { type UiLook } from "./look.js";
+export interface CanvasItem {
+    readonly id: string;
+    /** Where it sits on the canvas (world px). Without both, it packs into the grid. */
+    readonly x?: number;
+    readonly y?: number;
+    /** The card's size (px). Without them, the card takes its content's size. */
+    readonly w?: number;
+    readonly h?: number;
+    /** Shown above the card. */
+    readonly title?: string;
+    /** Draws the item into its card; return a cleanup for when it goes. */
+    readonly render: (el: HTMLElement) => void | (() => void);
+}
+export interface CanvasOptions extends UiLook {
+    readonly items: readonly CanvasItem[];
+    /** Between packed items, world px (48). */
+    readonly gap?: number;
+    /** Around what `fit` and `focus` show, px on screen (48). */
+    readonly padding?: number;
+    /** How wide packed rows run, world px (as wide as makes the set about the canvas's shape). */
+    readonly width?: number;
+    /** The zoom's range (.05 … 8). */
+    readonly minZoom?: number;
+    readonly maxZoom?: number;
+    /** The zoom readout, with fit and 100% (true). */
+    readonly readout?: boolean;
+    /** The view moved: a gesture, a key, a fit or a focus. */
+    readonly onView?: (view: CanvasView) => void;
+    /** The canvas's accessible name. */
+    readonly label?: string;
+}
+export interface Canvas {
+    readonly element: HTMLElement;
+    readonly view: CanvasView;
+    /** Each item's place (world px, its title included). */
+    readonly rects: ReadonlyMap<string, CanvasRect>;
+    /** Shows every item. */
+    fit(): void;
+    /** Brings an item to the middle and zooms to fit it (at most 200%). */
+    focus(id: string): void;
+    /** Zooms to `scale` around a point on the canvas (its middle by default). */
+    zoomTo(scale: number, at?: CanvasPoint): void;
+    /** New items: those that stay keep their content and glide to new places; new ones fade in, gone ones out. */
+    update(items: readonly CanvasItem[]): void;
+    /** Whether anything is moving (the frame loop runs only then). */
+    readonly moving: boolean;
+    /** Frames stepped, and the script time each took (ms), for perf checks. */
+    stats(): {
+        frames: number;
+        p50: number;
+        p95: number;
+        max: number;
+    };
+    dispose(): void;
+}
+/**
+ * An infinite canvas: items as cards on a dotted page that pans and zooms freely. Drag the page
+ * (or hold Space, or the middle button, and drag anywhere) or scroll with two fingers to pan;
+ * pinch or ⌘/ctrl-scroll to zoom around the pointer. Both follow the hand 1:1 and coast on
+ * release. 0 fits everything, 1 is 100%, = and - zoom, and a double-click focuses an item (again,
+ * or on the page, fits). Items stay live: clicks and keys reach them. Items without a place pack
+ * into rows sized to their content. Nothing moves on load: the first fit is instant.
+ */
+export declare function canvas(container: HTMLElement, options: CanvasOptions): Canvas;

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

@@ -27,6 +27,8 @@ export { codeDiff, diffCounts, diffReview, diffStatus, type CodeDiff, type CodeD
 export { compareText, comparePaths, countChanges, diffBar, diffFiles, diffFolders, diffStats, diffTree, fileKey, filesUnder, keepFile, matchPath, parsePatch, splitPath, stepFile, type DiffChange, type DiffFile, type DiffInput, type DiffRows, type DiffSource, type DiffTreeItem, } from "./diff-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 { canvas, type Canvas, type CanvasItem, type CanvasOptions } from "./canvas.js";
+export { boundsOf as canvasBounds, dotGrid, fitView, layoutCanvas, packRows, viewPath, zoomAround, type CanvasPoint, type CanvasRect, type CanvasView, } from "./canvas-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";

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

@@ -1,6 +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 Canvas as CanvasHandle, type CanvasOptions } from "./canvas.js";
 import { type CodeDiff as CodeDiffHandle, type CodeDiffOptions, type DiffReview as DiffReviewHandle, type DiffReviewOptions } from "./diff.js";
 import { type OptionPicker as OptionPickerHandle, type OptionPickerOptions, type PickerOption } from "./picker.js";
 import { type Split as SplitHandle, type SplitOptions } from "./split.js";
@@ -86,6 +87,17 @@ export type BentoProps = BentoOptions & {
  * prop; callbacks always call the latest props.
  */
 export declare function Bento(props: BentoProps): import("react").JSX.Element;
+export type CanvasProps = CanvasOptions & {
+    className?: string;
+    style?: CSSProperties;
+    onReady?: (canvas: CanvasHandle) => void;
+};
+/**
+ * `canvas()` as a component. New `items` update it in place (items that stay keep their content
+ * and glide); `onView` always calls the latest prop. Keep `items` (and their `render`s) stable
+ * across renders, or each render redraws the cards.
+ */
+export declare function Canvas(props: CanvasProps): import("react").JSX.Element;
 export type ActivityProps = ActivityOptions & {
     className?: string;
     style?: CSSProperties;

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

@@ -1,6 +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 Canvas as CanvasHandle, type CanvasOptions } from "./canvas.js";
 import { type CodeDiff as CodeDiffHandle, type CodeDiffOptions, type DiffReview as DiffReviewHandle, type DiffReviewOptions } from "./diff.js";
 import { type OptionPicker as OptionPickerHandle, type OptionPickerOptions, type PickerOption } from "./picker.js";
 import { type Split as SplitHandle, type SplitOptions } from "./split.js";
@@ -73,6 +74,14 @@ export type BentoProps = BentoOptions & {
  * prop; callbacks always call the latest props.
  */
 export declare function Bento(props: BentoProps): JSX.Element;
+export type CanvasProps = CanvasOptions & {
+    onReady?: (canvas: CanvasHandle) => void;
+};
+/**
+ * `canvas()` as a component. New `items` update it in place (items that stay keep their content
+ * and glide); `onView` always calls the latest prop.
+ */
+export declare function Canvas(props: CanvasProps): JSX.Element;
 export type ActivityProps = ActivityOptions & {
     onReady?: (activity: ActivityHandle) => void;
 };