@kitlangton/knobs 0.4.0-next.4 → 0.4.0-next.6

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

@@ -48,10 +48,15 @@ export interface TimelineOptions extends UiLook {
     /**
      * `"editor"` (the default): a ruler with labels over a lane of markers to add, drag and name,
      * zoomed and panned by the wheel. `"lane"`: one slim lane under a compare or a video, with ticks
-     * and no labels, markers as faint chapter ticks (the current one in text colour), nothing to
-     * edit, and the wheel left to the page.
+     * and no labels, markers as faint chapter ticks (the current one in text colour) and nothing to
+     * edit. A pinch, ⌘/ctrl-wheel or = and - zoom it around the pointer, a sideways scroll pans it,
+     * both following the hand 1:1; a double-click or 0 fits it again. An up-and-down wheel is left
+     * to the page. `"line"`: a player's progress, a single thin line under a video or a compare (no
+     * play button: the media and Space play), one segment per chapter with a small gap between,
+     * each filling as the time passes it, thicker under the pointer; click or drag anywhere on it
+     * to seek, 1:1, and the chapter and time under the pointer show over it. Zooms as a lane does.
      */
-    readonly variant?: "editor" | "lane";
+    readonly variant?: "editor" | "lane" | "line";
     readonly label?: string;
     /** The time moved: scrubbed, stepped, jumped, played (every frame) or set from code. */
     onSeek?(time: number, source: SeekSource): void;
@@ -117,3 +122,5 @@ export interface Timeline {
     dispose(): void;
 }
 export declare function timeline(container: HTMLElement, options: TimelineOptions): Timeline;
+export declare const PLAY = "<svg viewBox=\"0 0 16 16\" aria-hidden=\"true\"><path d=\"M5 3.6v8.8c0 .5.5.8.9.5l6.6-4.4c.4-.3.4-.8 0-1L5.9 3.1c-.4-.3-.9 0-.9.5Z\" fill=\"currentColor\"/></svg>";
+export declare const PAUSE = "<svg viewBox=\"0 0 16 16\" aria-hidden=\"true\"><rect x=\"4\" y=\"3.2\" width=\"2.8\" height=\"9.6\" rx=\"1\" fill=\"currentColor\"/><rect x=\"9.2\" y=\"3.2\" width=\"2.8\" height=\"9.6\" rx=\"1\" fill=\"currentColor\"/></svg>";

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

@@ -0,0 +1,42 @@
+import type { WalkthroughAnnotation } from "./walkthrough-model.js";
+export interface Rect {
+    readonly x: number;
+    readonly y: number;
+    readonly w: number;
+    readonly h: number;
+}
+/** The part of the picture in view, 0–1 (`{ u: 0, v: 0, w: 1, h: 1 }` is all of it). */
+export interface View {
+    readonly u: number;
+    readonly v: number;
+    readonly w: number;
+    readonly h: number;
+}
+/** Where the picture sits now: its rects in the layer (one, or a compare's two), view and time. */
+export interface Placement {
+    readonly rects: readonly Rect[];
+    readonly view?: View;
+    readonly time?: number;
+}
+export interface AnnotationLayer {
+    readonly element: HTMLElement;
+    /** Places the marks again: after a resize, a zoom, a seek, a mode change. */
+    update(): void;
+    dispose(): void;
+}
+/** Whether a mark shows at `time` (always without `at`, or without a time). */
+export declare const showsAt: (a: WalkthroughAnnotation, time: number | undefined) => boolean;
+/**
+ * A mark's box in the layer, in px, for a picture at `rect` showing `view` of itself; null when
+ * it's out of view.
+ */
+export declare function placeMark(a: WalkthroughAnnotation, rect: Rect, view?: View): Rect | null;
+/** Whether a page's annotations show. */
+export declare const annotationsOn: (scope: HTMLElement) => boolean;
+/** Shows or hides every annotation on a page (or a lone slot); its eye buttons follow. */
+export declare function setAnnotations(scope: HTMLElement, on: boolean): void;
+/**
+ * Draws `list` over `host` (positioned, the picture's box or a compare's stage), placing it with
+ * `place()`; the eye button goes in `corner` (the host by default).
+ */
+export declare function annotationLayer(host: HTMLElement, list: readonly WalkthroughAnnotation[], place: () => Placement, corner?: HTMLElement): AnnotationLayer;

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

@@ -1,7 +1,6 @@
 import { type ContextEvent, type WalkChapter, type WalkMedia } from "./walkthrough-model.js";
 /** The glyphs the blocks draw. */
 export declare const GLYPH: {
-    go: string;
     caret: string;
 };
 /** How media reach the page's steps: `step` on a history event, a stack item or a table cell. */
@@ -22,8 +21,12 @@ export interface Block {
         kind: string;
     };
 }
-/** A small arrow that goes to the step a ref names; null when it names none. */
-export declare function stepButton(doc: Document, ref: string | undefined, steps: StepLinks | undefined): HTMLButtonElement | null;
+/**
+ * Makes a whole row go to the step a ref names (a click away from its links, Enter or Space when
+ * it has focus); nothing trails it, so rows with and without a step line up.
+ */
+export declare function rowLink(row: HTMLElement, ref: string | undefined, steps: StepLinks | undefined): void;
+/** A history through `history()`: lanes of spans over a date axis, or the older groups of events. */
 export declare function mountHistory(host: HTMLElement, m: Extract<WalkMedia, {
     kind: "history";
 }>, steps: StepLinks | undefined): Block;
@@ -55,8 +58,25 @@ export interface Disclosure {
 }
 export declare function disclosure(host: HTMLElement, options: {
     label: string;
-    count?: number;
     open?: boolean;
     content: HTMLElement;
 }): Disclosure;
+declare const PR_STATE: {
+    readonly merged: "Merged";
+    readonly open: "Open";
+    readonly draft: "Draft";
+    readonly closed: "Closed";
+};
+export interface PRInfo {
+    readonly state?: keyof typeof PR_STATE;
+    readonly title?: string;
+    readonly href?: string;
+}
+/** A pull request as a small chip: its state's icon and number, the title and state on hover. */
+export declare function prChip(doc: Document, n: string, pr: PRInfo): HTMLElement;
+/**
+ * Turns the pull requests in some rendered prose into chips: links to one whose words are its
+ * number or URL, and bare `#57148`s the page can resolve. Code, buttons and media stay as they are.
+ */
+export declare function linkPRs(root: HTMLElement, find: (n: string) => PRInfo | null): void;
 export {};

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

@@ -1,5 +1,6 @@
 import type { CompareMode } from "./compare-model.js";
 import type { DiffSource } from "./diff-model.js";
+import type { HistoryData, HistoryEvent } from "./history-model.js";
 /** Where a PR or topic stands, as the agent sees it: a chip beside its title. */
 export type WalkthroughStatus = "ready" | "needs-taste" | "draft" | "blocked" | "merged" | (string & {});
 /** A picture or video, by URL. */
@@ -89,6 +90,22 @@ export interface WalkthroughTableColumn {
 export type WalkthroughTableRow = Readonly<Record<string, WalkthroughTableCell>> | {
     readonly cells: Readonly<Record<string, WalkthroughTableCell>>;
 };
+/**
+ * A mark on a picture drawing the eye to what matters: a ring round a box, a dot or an arrow at a
+ * point, with a small label. In 0–1 of the picture (`x`, `y` the box's top-left or the point).
+ */
+export interface WalkthroughAnnotation {
+    readonly x: number;
+    readonly y: number;
+    /** A box's size; left out, it's a point. */
+    readonly w?: number;
+    readonly h?: number;
+    readonly label?: string;
+    /** Seconds it shows between, on a video or compare; always, left out. */
+    readonly at?: readonly [number, number];
+    /** `"box"` where it has a size, else `"dot"`. */
+    readonly shape?: "box" | "dot" | "arrow";
+}
 /** A stretch of a video: a pill under it, and a marker on its timeline. */
 export interface WalkthroughChapter {
     readonly id?: string;
@@ -115,6 +132,8 @@ export type WalkthroughMedia = string | {
     readonly strip?: boolean;
     /** Pills under it that seek, and markers on its timeline. */
     readonly chapters?: readonly WalkthroughChapter[];
+    /** Marks on the pictures, on both sides (and under a zoom). */
+    readonly annotations?: readonly WalkthroughAnnotation[];
 } | {
     readonly kind: "video";
     readonly src: string;
@@ -127,12 +146,23 @@ export type WalkthroughMedia = string | {
     readonly captions?: string;
     /** Another name for `captions`. */
     readonly captionsSrc?: string;
+    /** Marks on the picture. */
+    readonly annotations?: readonly WalkthroughAnnotation[];
 } | {
     readonly kind: "history";
-    /** Dated events under quiet headings… */
+    /** Lanes of dated spans over one axis (`history()`'s shape)… */
+    readonly lanes?: HistoryData["lanes"];
+    readonly bands?: HistoryData["bands"];
+    readonly states?: HistoryData["states"];
+    readonly axis?: HistoryData["axis"];
+    /** …dated events (on the lanes, or one run of them in the older shape)… */
+    readonly events?: readonly (WalkthroughHistoryEvent | HistoryEvent)[];
+    /** …or the older groups of events under quiet headings. */
     readonly groups?: readonly WalkthroughHistoryGroup[];
-    /** …or one run of them. */
-    readonly events?: readonly WalkthroughHistoryEvent[];
+    /** Its accessible name. */
+    readonly label?: string;
+    /** The event types marked from the start (releases and deletions), or `"all"`. */
+    readonly marks?: readonly string[] | "all";
 } | {
     readonly kind: "stack";
     /** The branch the stack lands on ("dev"); else the one most items merge into. */
@@ -157,6 +187,8 @@ export type WalkthroughMedia = string | {
     readonly src: string;
     readonly label?: string;
     readonly alt?: string;
+    /** Marks on the picture. */
+    readonly annotations?: readonly WalkthroughAnnotation[];
 } | {
     readonly kind: "diff";
     /** `git diff` / `git show` output. */
@@ -217,7 +249,10 @@ export interface WalkthroughStep {
     readonly media?: WalkthroughMedia | readonly WalkthroughMedia[];
     /** Media side by side, this many to a row where there's room; one under another by default. */
     readonly columns?: 1 | 2 | 3;
-    /** The media after the first fold away under a quiet toggle with these words ("More clips"). */
+    /**
+     * The rest, folded away under the caption behind "More" (Markdown; blank lines start new
+     * paragraphs). Keep the title the claim and the caption one sentence; everything else goes here.
+     */
     readonly more?: string;
     /** A taste test: Kit picks one. */
     readonly options?: readonly WalkthroughOption[];
@@ -242,8 +277,11 @@ export interface WalkthroughSection {
      * `link` is a pull request, or the doc's `kickers` noun), your own words, or `false` for none.
      */
     readonly kicker?: string | false;
+    /** A chip on its meta line ("needs-taste" → Needs taste), with `review: true` only. */
     readonly status?: WalkthroughStatus;
     readonly summary?: string;
+    /** The rest, folded away under the summary behind "More" (Markdown). */
+    readonly more?: string;
     readonly steps: readonly WalkthroughStep[];
 }
 export interface WalkthroughMeta {
@@ -281,6 +319,8 @@ export interface WalkthroughDoc {
     readonly id: string;
     readonly title: string;
     readonly summary?: string;
+    /** The rest, folded away under the summary behind "More" (Markdown). */
+    readonly more?: string;
     /** Facts beside the title: branch, commit, date… */
     readonly meta?: Readonly<Record<string, string>> | readonly WalkthroughMeta[];
     /** Relative media URLs resolve against this. */
@@ -300,8 +340,22 @@ export interface WalkthroughDoc {
     readonly kickers?: "pr" | {
         readonly noun: string;
     } | false;
+    /**
+     * The pull requests the page mentions, by number: their state and title. A `#57148` in a title,
+     * caption or summary, a link to a pull request, and a section's PR `link` read as a small chip
+     * (its state's icon and number; the title on hover).
+     */
+    readonly prs?: Readonly<Record<string, WalkthroughPR>>;
+    /** `owner/name` on GitHub, so a bare `#57148` links to its pull request. */
+    readonly repo?: string;
     readonly sections: readonly WalkthroughSection[];
 }
+export interface WalkthroughPR {
+    readonly state?: "merged" | "open" | "draft" | "closed";
+    readonly title?: string;
+    /** Its URL, when neither `repo` nor a link on the page gives it. */
+    readonly href?: string;
+}
 type CompareMedia = Extract<WalkthroughMedia, {
     kind: "compare";
 }>;
@@ -315,11 +369,6 @@ export interface WalkChapter {
     readonly start: number;
     readonly end?: number;
 }
-export interface WalkHistoryGroup {
-    readonly heading?: string;
-    readonly summary?: string;
-    readonly events: readonly WalkthroughHistoryEvent[];
-}
 /** A stack's item filled in: its PR as `#123`, its branch split, `step` for `stepId`. */
 export interface WalkStackItem {
     readonly pr: string;
@@ -366,7 +415,9 @@ export type WalkMedia = Exclude<WalkthroughMedia, string | {
     readonly chapters?: readonly WalkChapter[];
 }) | {
     readonly kind: "history";
-    readonly groups: readonly WalkHistoryGroup[];
+    readonly data: HistoryData;
+    readonly label?: string;
+    readonly marks?: readonly string[] | "all";
 } | {
     readonly kind: "stack";
     readonly base?: string;
@@ -417,6 +468,7 @@ export interface WalkSection {
     readonly kicker?: string;
     readonly status?: WalkthroughStatus;
     readonly summary?: string;
+    readonly more?: string;
     readonly steps: readonly WalkStep[];
 }
 export interface WalkVerdict {
@@ -440,6 +492,7 @@ export interface WalkPage {
     readonly id: string;
     readonly title: string;
     readonly summary?: string;
+    readonly more?: string;
     readonly meta: readonly WalkthroughMeta[];
     readonly verdicts: readonly WalkVerdict[];
     readonly sections: readonly WalkSection[];
@@ -447,6 +500,10 @@ export interface WalkPage {
     readonly steps: readonly WalkStep[];
     /** Updates and answers, newest first. */
     readonly feed: readonly FeedItem[];
+    /** The pull requests the page knows, by number, each with its URL when one is known. */
+    readonly prs: Readonly<Record<string, WalkthroughPR>>;
+    /** `owner/name`, when the doc gave one. */
+    readonly repo?: string;
 }
 export declare const DEFAULT_VERDICTS: readonly ["ship", "change", "unsure"];
 /** A URL-safe id from a title: "Retired model (HTTP 410)" → "retired-model-http-410". */
@@ -459,6 +516,13 @@ export declare const mediaOf: (src: string) => WalkMedia;
 export declare function parseAspect(aspect: number | string | undefined): number | undefined;
 /** Media filled in: a bare URL as a video or image, sources resolved against `base`. */
 export declare function fillMedia(m: WalkthroughMedia, base?: string): WalkMedia;
+/**
+ * What `history()` draws: the lanes shape as written, or the older groups (`rows` read as
+ * `events`, bare `events` as one group first) for it to lay on the code lane.
+ */
+export declare function historyData(m: Extract<WalkthroughMedia, {
+    kind: "history";
+}>): HistoryData;
 /** `"head → base"` (or `->`, `=>`, `⇒`) as its two branches; one name is the head alone. */
 export declare function parseBranch(branch: string | undefined): {
     head?: string;
@@ -514,6 +578,10 @@ export declare function linkLabel(href: string): string;
  * ask, options lettered, media URLs resolved against `base`, and the verdicts labelled.
  */
 export declare function normalizeWalkthrough(doc: WalkthroughDoc): WalkPage;
+/** The number in a pull request's URL (`…/pull/57148`), or null. */
+export declare const prNumber: (href: string) => string | null;
+/** A pull request by number: what the page knows, or (with a repo) its URL. */
+export declare function findPR(prs: Readonly<Record<string, WalkthroughPR>>, n: string, repo?: string): WalkthroughPR | null;
 /** Whether a link is a pull (or merge) request: GitHub's `/pull/123`, GitLab's merge requests. */
 export declare const isPullRequest: (href: string) => boolean;
 /**

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

@@ -11,6 +11,8 @@ export interface TasteTestOptions extends UiLook {
     readonly lazy?: boolean;
     /** The page's steps, for media that name one. */
     readonly steps?: StepLinks;
+    /** Options can be picked (on by default); off, they sit side by side under their labels. */
+    readonly pickable?: boolean;
 }
 export interface TasteTest {
     readonly element: HTMLElement;
@@ -35,8 +37,18 @@ export interface WalkthroughOptions extends UiLook {
     readonly onFeedback?: (feedback: WalkthroughFeedback) => void;
     /** The page's keys (on by default). */
     readonly keys?: boolean;
-    /** The contents and progress rail (on by default), beside the column on the right or left. */
-    readonly rail?: boolean | "right" | "left";
+    /**
+     * Kit's review tools (off by default): progress, notes (typed, voice, ink) and their bar,
+     * Copy feedback, the key hints, and picking between options. Off, the page only shows: options
+     * sit side by side, and j / k, f and the arrows still work.
+     */
+    readonly review?: boolean;
+    /**
+     * The contents and progress rail (on by default): sticky at the page's left edge, the column
+     * centred in the room beside it; `"right"` mirrors it. Under 960 px it hides (with review
+     * on, a bar on top keeps the progress and the export).
+     */
+    readonly rail?: boolean | "left" | "right";
     /** Each step on a card of its own (off by default: steps sit on the page, hairlines between). */
     readonly cards?: boolean;
     /**