@kitlangton/knobs 0.3.0 → 0.4.0-next.0

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

@@ -12,13 +12,21 @@ 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 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 { timeline, type SeekSource, type Timeline, type TimelineMarker, type TimelineListener, 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";
+export { compare, COMPARE_FFMPEG, type Compare, type CompareLoop, type CompareMode, type CompareOptions, type CompareSource, type CompareView, type MediaKind, type ZoomRegion, } from "./compare.js";
+export { compareStrip, type CompareStrip, type CompareStripOptions } from "./compare-strip.js";
+export { compareLayout, frameMidpoint, frameOf, letterbox, mediaKind, meanAbsDiff, requestSeek, seeked, seekTime, stripColumns, stripPeaks, syncAction, wipeAt, wipeGrab, wipeKey, wipeX, zoomAbout, type CompareLayout, type SeekState, type StripColumn, type SyncAction, } from "./compare-model.js";
 export { tree, type Tree, type TreeOptions, type TreeRowContext, type TreeToggle } from "./tree.js";
 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 { codeDiff, diffCounts, diffReview, diffStatus, type CodeDiff, type CodeDiffOptions, type CodeDiffUpdate, type DiffLayout, type DiffLines, type DiffReview, type DiffReviewOptions, } from "./diff.js";
+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 { 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";
+export { tasteTest, walkthrough, type TasteTest, type TasteTestOptions, type Walkthrough, type WalkthroughOptions, } from "./walkthrough.js";
+export { mediaSlot, type MediaSlot, type MediaSlotOptions } from "./walkthrough-media.js";
+export { collectFeedback, feedbackMarkdown, inlineMarkdown, normalizeWalkthrough, readState as readWalkthroughState, walkthroughProgress, type ContextEvent, type FeedbackItem, type FeedbackNote, type FeedItem, type MediaContext, type NoteContext, type WalkInk, type WalkNote, type WalkVoice, type WalkthroughQA, type WalkthroughUpdate, type WalkPage, type WalkStep, type WalkthroughDoc, type WalkthroughFeedback, type WalkthroughMedia, type WalkthroughMeta, type WalkthroughOption, type WalkthroughSection, type WalkthroughSource, type WalkthroughState, type WalkthroughStatus, type WalkthroughStep, } from "./walkthrough-model.js";

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

@@ -1,10 +1,15 @@
 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 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";
 import { type Timeline as TimelineHandle, type TimelineOptions } from "./timeline.js";
+import { type Compare as CompareHandle, type CompareOptions } from "./compare.js";
+import { type CompareStrip as CompareStripHandle, type CompareStripOptions } from "./compare-strip.js";
 import { type Tree as TreeHandle, type TreeOptions } from "./tree.js";
+import { type TasteTest as TasteTestHandle, type TasteTestOptions, type Walkthrough as WalkthroughHandle, type WalkthroughOptions } from "./walkthrough.js";
+import { type MediaSlot as MediaSlotHandle, type MediaSlotOptions } from "./walkthrough-media.js";
 export type SplitProps = SplitOptions & {
     /** One child per pane, in the panes' order; each renders into its pane's body. */
     children?: ReactNode;
@@ -24,6 +29,24 @@ export type TreeProps<T> = TreeOptions<T> & {
  * `filter` follow their props; callbacks always call the latest props.
  */
 export declare function Tree<T>(props: TreeProps<T>): import("react").JSX.Element;
+export type CodeDiffProps = CodeDiffOptions & {
+    className?: string;
+    style?: CSSProperties;
+    onReady?: (diff: CodeDiffHandle) => void;
+};
+/**
+ * `codeDiff()` as a component. `patch`, `files`, `file`, `layout`, `wrap`, `viewed`, `height` and
+ * `maxHeight` follow their
+ * props; callbacks always call the latest props.
+ */
+export declare function CodeDiff(props: CodeDiffProps): import("react").JSX.Element;
+export type DiffReviewProps = DiffReviewOptions & {
+    className?: string;
+    style?: CSSProperties;
+    onReady?: (review: DiffReviewHandle) => void;
+};
+/** `diffReview()` as a component: the file tree beside the diff; follows as `CodeDiff` does. */
+export declare function DiffReview(props: DiffReviewProps): import("react").JSX.Element;
 export type TimelineProps = TimelineOptions & {
     className?: string;
     style?: CSSProperties;
@@ -35,6 +58,24 @@ export type TimelineProps = TimelineOptions & {
  * always call the latest props.
  */
 export declare function Timeline(props: TimelineProps): import("react").JSX.Element;
+export type CompareProps = CompareOptions & {
+    className?: string;
+    style?: CSSProperties;
+    onReady?: (compare: CompareHandle) => void;
+};
+/**
+ * `compare()` as a component. `before`, `after` (by `src`), `mode`, `wipe`, `loupe`, `threshold`
+ * and `fps` follow their props; a new `timeline` handle, `strip` or `renderer` makes it afresh;
+ * callbacks always call the latest props.
+ */
+export declare function Compare(props: CompareProps): import("react").JSX.Element;
+export type CompareStripProps = CompareStripOptions & {
+    className?: string;
+    style?: CSSProperties;
+    onReady?: (strip: CompareStripHandle) => void;
+};
+/** `compareStrip()` as a component, on a timeline handle; new sources (by `src`) follow. */
+export declare function CompareStrip(props: CompareStripProps): import("react").JSX.Element;
 export type BentoProps = BentoOptions & {
     className?: string;
     style?: CSSProperties;
@@ -70,3 +111,28 @@ export type OptionPickerProps = Omit<OptionPickerOptions, "body"> & {
 export declare function OptionPicker(props: OptionPickerProps): import("react").JSX.Element;
 export type { ActivityEvent } from "./activity-model.js";
 export type { PickerOption } from "./picker.js";
+export type WalkthroughProps = WalkthroughOptions & {
+    className?: string;
+    style?: CSSProperties;
+    onReady?: (walkthrough: WalkthroughHandle) => void;
+};
+/**
+ * `walkthrough()` as a component: a new `doc` is a new draft (answers carry over by step key);
+ * `onFeedback` always calls the latest prop.
+ */
+export declare function Walkthrough(props: WalkthroughProps): import("react").JSX.Element;
+export type TasteTestProps = TasteTestOptions & {
+    className?: string;
+    style?: CSSProperties;
+    onReady?: (test: TasteTestHandle) => void;
+};
+/** `tasteTest()` as a component: `picked` follows its prop; new `options` make it afresh. */
+export declare function TasteTest(props: TasteTestProps): import("react").JSX.Element;
+export type MediaSlotProps = MediaSlotOptions & {
+    className?: string;
+    style?: CSSProperties;
+    onReady?: (slot: MediaSlotHandle) => void;
+};
+/** `mediaSlot()` as a component: one walkthrough media slot; new `media` mounts afresh. */
+export declare function MediaSlot(props: MediaSlotProps): import("react").JSX.Element;
+export type { WalkthroughDoc, WalkthroughFeedback } from "./walkthrough-model.js";

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

@@ -2,8 +2,8 @@
  * 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.
+ * takes no room. It shows while the pointer is over the scroller, while you scroll it and while
+ * you drag it; a scroll from code (a reveal, a restored position) doesn't flash it. `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): {

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

@@ -1,10 +1,15 @@
 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 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";
 import { type Timeline as TimelineHandle, type TimelineOptions } from "./timeline.js";
+import { type Compare as CompareHandle, type CompareOptions } from "./compare.js";
+import { type CompareStrip as CompareStripHandle, type CompareStripOptions } from "./compare-strip.js";
 import { type Tree as TreeHandle, type TreeOptions } from "./tree.js";
+import { type TasteTest as TasteTestHandle, type TasteTestOptions, type Walkthrough as WalkthroughHandle, type WalkthroughOptions } from "./walkthrough.js";
+import { type MediaSlot as MediaSlotHandle, type MediaSlotOptions } from "./walkthrough-media.js";
 export type SplitProps = SplitOptions & {
     /** One element per pane, in the panes' order; each goes into its pane's body. */
     children?: JSX.Element;
@@ -23,6 +28,20 @@ export type TreeProps<T> = TreeOptions<T> & {
  * `filter` follow their props; callbacks always call the latest props.
  */
 export declare function Tree<T>(props: TreeProps<T>): JSX.Element;
+export type CodeDiffProps = CodeDiffOptions & {
+    onReady?: (diff: CodeDiffHandle) => void;
+};
+/**
+ * `codeDiff()` as a component. `patch`, `files`, `file`, `layout`, `wrap`, `viewed`, `height` and
+ * `maxHeight` follow their
+ * props; callbacks always call the latest props.
+ */
+export declare function CodeDiff(props: CodeDiffProps): JSX.Element;
+export type DiffReviewProps = DiffReviewOptions & {
+    onReady?: (review: DiffReviewHandle) => void;
+};
+/** `diffReview()` as a component: the file tree beside the diff; follows as `CodeDiff` does. */
+export declare function DiffReview(props: DiffReviewProps): JSX.Element;
 export type TimelineProps = TimelineOptions & {
     onReady?: (timeline: TimelineHandle) => void;
 };
@@ -32,6 +51,20 @@ export type TimelineProps = TimelineOptions & {
  * always call the latest props.
  */
 export declare function Timeline(props: TimelineProps): JSX.Element;
+export type CompareProps = CompareOptions & {
+    onReady?: (compare: CompareHandle) => void;
+};
+/**
+ * `compare()` as a component, made once (with the `timeline`, `strip` and `renderer` it starts
+ * with). `before`, `after` (by `src`), `mode`, `wipe`, `loupe`, `threshold` and `fps` follow
+ * their props; callbacks always call the latest props.
+ */
+export declare function Compare(props: CompareProps): JSX.Element;
+export type CompareStripProps = CompareStripOptions & {
+    onReady?: (strip: CompareStripHandle) => void;
+};
+/** `compareStrip()` as a component, on a timeline handle; new sources (by `src`) follow. */
+export declare function CompareStrip(props: CompareStripProps): JSX.Element;
 export type BentoProps = BentoOptions & {
     onReady?: (bento: BentoHandle) => void;
 };
@@ -61,3 +94,22 @@ export type OptionPickerProps = Omit<OptionPickerOptions, "body"> & {
 export declare function OptionPicker(props: OptionPickerProps): JSX.Element;
 export type { ActivityEvent } from "./activity-model.js";
 export type { PickerOption } from "./picker.js";
+export type WalkthroughProps = WalkthroughOptions & {
+    onReady?: (walkthrough: WalkthroughHandle) => void;
+};
+/**
+ * `walkthrough()` as a component: a new `doc` is a new draft (answers carry over by step key);
+ * `onFeedback` always calls the latest prop.
+ */
+export declare function Walkthrough(props: WalkthroughProps): JSX.Element;
+export type TasteTestProps = TasteTestOptions & {
+    onReady?: (test: TasteTestHandle) => void;
+};
+/** `tasteTest()` as a component: `picked` follows its prop. */
+export declare function TasteTest(props: TasteTestProps): JSX.Element;
+export type MediaSlotProps = MediaSlotOptions & {
+    onReady?: (slot: MediaSlotHandle) => void;
+};
+/** `mediaSlot()` as a component: one walkthrough media slot. */
+export declare function MediaSlot(props: MediaSlotProps): JSX.Element;
+export type { WalkthroughDoc, WalkthroughFeedback } from "./walkthrough-model.js";

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

@@ -37,6 +37,14 @@ export interface TimelineOptions extends UiLook {
     readonly speed?: number;
     /** Playback starts over at the end when there's no loop range (`false`: it stops). */
     readonly repeat?: boolean;
+    /**
+     * What ←/→ move: frames (one, ten with ⇧) by default, or seconds (`{ step: 0.5, shift: 2 }`),
+     * the playhead gliding there; `,` and `.` step a frame either way.
+     */
+    readonly arrows?: "frames" | {
+        readonly step: number;
+        readonly shift: number;
+    };
     readonly label?: string;
     /** The time moved: scrubbed, stepped, jumped, played (every frame) or set from code. */
     onSeek?(time: number, source: SeekSource): void;
@@ -47,29 +55,54 @@ export interface TimelineOptions extends UiLook {
     onRanges?(ranges: readonly TimelineRange[]): void;
     /** Playback passed a marker. */
     onCross?(marker: TimelineMarker): void;
+    /** The visible window moved: a zoom, a pan, a fit or a follow. */
+    onView?(view: TimeView): 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;
 }
+/** What `listen` reports: the same as the options' callbacks, for pieces bound to a timeline. */
+export interface TimelineListener {
+    onSeek?(time: number, source: SeekSource): void;
+    onPlay?(playing: boolean): void;
+    onView?(view: TimeView): void;
+    /** A scrub of the playhead started (`true`) or let go (`false`). */
+    onScrub?(active: boolean): void;
+    /** Ranges were set, moved or cleared (the whole list). */
+    onRanges?(ranges: readonly TimelineRange[]): void;
+}
 export interface Timeline {
     readonly element: HTMLElement;
     readonly time: number;
     readonly playing: boolean;
+    readonly duration: number;
+    readonly fps: number;
     readonly markers: readonly TimelineMarker[];
     readonly ranges: readonly TimelineRange[];
     readonly view: TimeView;
-    seek(time: number): void;
+    /** `glide`: the playhead springs there (the time, and what it drives, land at once). */
+    seek(time: number, options?: {
+        readonly glide?: boolean;
+    }): 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;
+    update(next: Partial<Omit<TimelineOptions, "onSeek" | "onPlay" | "onMarkers" | "onRanges" | "onCross" | "onView">>): 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;
+    /** Hears seeks, play and pause, and view moves alongside the options' callbacks; returns a stop. */
+    listen(listener: TimelineListener): () => void;
+    /**
+     * While playing, time follows `clock` (seconds, `Infinity` once it has run out: a video's
+     * `currentTime`, say) instead of the timeline's own frame clock, so the two never drift; loops
+     * and the end still apply. `null` hands time back.
+     */
+    drive(clock: (() => number) | null): void;
     focus(): void;
     dispose(): void;
 }

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

@@ -29,8 +29,8 @@ export interface TreeOptions<T> extends UiLook {
     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;
+    /** Dimmed text (or a node of your own) after the label: a count, a kind. */
+    readonly detail?: (item: T) => string | Node | undefined;
     /** Your own content in place of the label. */
     readonly render?: (item: T, row: TreeRowContext) => Node | string | undefined | void;
     readonly selection?: Iterable<string>;
@@ -63,6 +63,11 @@ export interface TreeOptions<T> extends UiLook {
      * row as a click does. While the page has hint mode, `s` goes to it rather than type-ahead.
      */
     readonly hints?: boolean;
+    /**
+     * The selected row (one) shows as one highlight that glides to the next row selected, on the
+     * rows' own spring, instead of each row lighting in place. Several selected rows light in place.
+     */
+    readonly glide?: boolean;
 }
 export interface Tree<T> {
     readonly element: HTMLElement;

package/dist/types/ui/walkthrough-css.d.ts

@@ -0,0 +1 @@
+export declare const walkthroughCss: string;

package/dist/types/ui/walkthrough-media.d.ts

@@ -0,0 +1,29 @@
+import { type UiLook } from "./look.js";
+import { type ContextEvent, type MediaContext, type WalkthroughMedia } from "./walkthrough-model.js";
+export interface MediaSlotOptions extends UiLook {
+    readonly media: WalkthroughMedia;
+    /** Mount heavy kinds near the view and let them go far from it (on by default). */
+    readonly lazy?: boolean;
+    /** Kit played, paused or sought a video, or showed another diff file (for a note's log). */
+    readonly onEvent?: (event: Omit<ContextEvent, "at" | "step">) => void;
+}
+export interface MediaSlot {
+    readonly element: HTMLElement;
+    /** Whether its content is mounted (heavy kinds wait until they're near the view). */
+    readonly mounted: boolean;
+    /** Pauses any video in it. */
+    pause(): void;
+    /** Moves its video (or compare) by `seconds`; false when there's none mounted. */
+    seekBy(seconds: number): boolean;
+    /** What it's showing now: a video's time, a compare's loop, zoom and mode, a diff's file. */
+    context(): MediaContext | null;
+    /** A zoomed compare back to the whole picture; false when nothing was zoomed. */
+    unzoom(): boolean;
+    /** Fills the slot's height (its step full window) or goes back: a diff switches its height. */
+    fill(on: boolean): void;
+    dispose(): void;
+}
+/** Adds the walkthrough's stylesheet once per document. */
+export declare function injectWalkthroughStyles(doc: Document): void;
+export declare function mediaSlot(container: HTMLElement, options: MediaSlotOptions): MediaSlot;
+export declare const CHECK: string;