@kitlangton/knobs 0.4.0-next.5 → 0.4.0-next.7

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,14 +21,18 @@ 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;
 export declare function mountStack(host: HTMLElement, m: Extract<WalkMedia, {
     kind: "stack";
-}>, steps: StepLinks | undefined): Block;
+}>, steps: StepLinks | undefined, findPR?: (n: string) => PRInfo | null): Block;
 export declare function mountTable(host: HTMLElement, m: Extract<WalkMedia, {
     kind: "table";
 }>, steps: StepLinks | undefined): Block;
@@ -55,7 +58,6 @@ export interface Disclosure {
 }
 export declare function disclosure(host: HTMLElement, options: {
     label: string;
-    count?: number;
     open?: boolean;
     content: HTMLElement;
 }): Disclosure;
@@ -65,8 +67,20 @@ declare const PR_STATE: {
     readonly draft: "Draft";
     readonly closed: "Closed";
 };
+export type PRState = keyof typeof PR_STATE;
+/**
+ * A stack row's pull-request state from its `status` words: the first word when it's merged,
+ * draft, open or closed (any case), and whether they say its checks pass ("green", "passing",
+ * "CI"). The state comes from the words, never the tone.
+ */
+export declare function prStatus(status: string | undefined): {
+    state: PRState | null;
+    checks: boolean;
+};
+/** A pull request's state as GitHub shows it: its glyph and word, quietly tinted; a check after. */
+export declare function prStateLabel(doc: Document, state: PRState, checks: boolean, title?: string): HTMLSpanElement;
 export interface PRInfo {
-    readonly state?: keyof typeof PR_STATE;
+    readonly state?: PRState;
     readonly title?: string;
     readonly href?: string;
 }

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

@@ -1,5 +1,5 @@
 import { type UiLook } from "./look.js";
-import { type StepLinks } from "./walkthrough-blocks.js";
+import { type PRInfo, type StepLinks } from "./walkthrough-blocks.js";
 import { type ContextEvent, type MediaContext, type WalkthroughMedia } from "./walkthrough-model.js";
 export interface MediaSlotOptions extends UiLook {
     readonly media: WalkthroughMedia;
@@ -9,6 +9,8 @@ export interface MediaSlotOptions extends UiLook {
     readonly onEvent?: (event: Omit<ContextEvent, "at" | "step">) => void;
     /** The page's steps, for `step` on a history event, a stack item or a table cell. */
     readonly steps?: StepLinks;
+    /** What the page knows of a pull request by its number (a stack row's state and link). */
+    readonly findPR?: (n: string) => PRInfo | null;
 }
 export type { StepLinks };
 export interface MediaSlot {

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. */
@@ -245,6 +277,7 @@ 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). */
@@ -336,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;
@@ -387,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;
@@ -486,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;