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

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

@@ -1,4 +1,9 @@
 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. */
 export interface StepLinks {
     /** The step a ref names (its key, id or number), or null when there's none. */
@@ -17,6 +22,8 @@ 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;
 export declare function mountHistory(host: HTMLElement, m: Extract<WalkMedia, {
     kind: "history";
 }>, steps: StepLinks | undefined): Block;
@@ -27,7 +34,7 @@ export declare function mountTable(host: HTMLElement, m: Extract<WalkMedia, {
     kind: "table";
 }>, steps: StepLinks | undefined): Block;
 export interface ChapterPills {
-    /** The chapter the time is in (call as it plays or seeks): the highlight springs to it. */
+    /** The chapter the time is in (call as it plays or seeks): the pill slides to it. */
     sync(): void;
     /** The chapter playing, or null. */
     readonly current: WalkChapter | null;
@@ -40,4 +47,34 @@ export declare function chapterPills(host: HTMLElement, chapters: readonly WalkC
     seek(time: number): void;
     onEvent: OnEvent;
 }): ChapterPills;
+export interface Disclosure {
+    readonly element: HTMLElement;
+    readonly open: boolean;
+    toggle(open?: boolean): void;
+    dispose(): void;
+}
+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

@@ -144,6 +144,14 @@ export type WalkthroughMedia = string | {
     readonly columns: readonly WalkthroughTableColumn[];
     readonly rows: readonly WalkthroughTableRow[];
     readonly caption?: string;
+    /**
+     * Where the step is too narrow for its columns, each row becomes a block: its primary cell
+     * as a title over the rest as term and value (`"auto"`, the default); always; or never
+     * (the table scrolls sideways instead).
+     */
+    readonly stack?: "auto" | "always" | "never";
+    /** The column that titles a stacked row (its key); the first by default. */
+    readonly primary?: string;
 } | {
     readonly kind: "image";
     readonly src: string;
@@ -205,8 +213,15 @@ export interface WalkthroughStep {
     readonly title: string;
     /** A line or two: what it shows and how it was made. `code`, **bold** and [links](…) work. */
     readonly caption?: string;
-    /** One slot; two or more sit side by side, stacking where it's narrow. */
+    /** One slot, or several one under another (`columns` sets them side by side). */
     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 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[];
     /**
@@ -225,8 +240,15 @@ export interface WalkthroughSection {
         readonly href: string;
         readonly label?: string;
     };
+    /**
+     * The words that lead its meta line, in text colour: its count by default (`"PR 2 of 5"` where
+     * `link` is a pull request, or the doc's `kickers` noun), your own words, or `false` for none.
+     */
+    readonly kicker?: string | false;
     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 {
@@ -241,6 +263,10 @@ export interface WalkthroughUpdate {
     readonly text: string;
     /** The step it's about: its key, id or number ("1.2"). */
     readonly step?: string;
+    /** Its state in a word or two (`"shipped"`, `"changes"`), last on its meta line. */
+    readonly status?: string;
+    /** Context, folded away under the item: one line each, `"0:04 · Played the compare"`. */
+    readonly trail?: readonly string[];
 }
 /** A question Kit asked and the agent's answer. */
 export interface WalkthroughQA {
@@ -249,6 +275,10 @@ export interface WalkthroughQA {
     readonly q: string;
     readonly a: string;
     readonly step?: string;
+    /** `"shipped"` or `"changes"` (shown as "Changes queued"), or your own words. */
+    readonly status?: string;
+    /** What Kit did before asking, folded away under the answer: `"0:04 · Played the compare"`. */
+    readonly trail?: readonly string[];
 }
 /** The document an agent writes: plain data, JSON but for `mount` media. */
 export interface WalkthroughDoc {
@@ -256,6 +286,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. */
@@ -266,8 +298,31 @@ export interface WalkthroughDoc {
     readonly updates?: readonly WalkthroughUpdate[];
     /** Kit's questions and the agent's answers. */
     readonly qa?: readonly WalkthroughQA[];
+    /**
+     * How sections are counted on their meta line: `"pr"` (the default) gives "PR i of N" to the
+     * sections that link a pull request, `{ noun: "Part" }` "Part i of N" to every section, and
+     * `false` none. A section's own `kicker` wins over its count, and `false` hides it, without
+     * renumbering the rest.
+     */
+    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";
 }>;
@@ -342,6 +397,9 @@ export type WalkMedia = Exclude<WalkthroughMedia, string | {
     readonly columns: readonly WalkTableColumn[];
     readonly rows: readonly Readonly<Record<string, WalkTableCell>>[];
     readonly caption?: string;
+    readonly stack: "auto" | "always" | "never";
+    /** The key of the column that titles a stacked row. */
+    readonly primary: string;
 };
 export interface WalkOption {
     readonly id: string;
@@ -363,6 +421,9 @@ export interface WalkStep {
     readonly caption?: string;
     readonly question?: string;
     readonly media: readonly WalkMedia[];
+    /** Media to a row: 1 (one under another) unless the step asked for more. */
+    readonly columns: number;
+    readonly more?: string;
     readonly options: readonly WalkOption[];
     readonly ask: "note" | "pick" | "none";
 }
@@ -373,8 +434,11 @@ export interface WalkSection {
         readonly href: string;
         readonly label: string;
     };
+    /** What leads its meta line ("PR 2 of 5"), when anything does. */
+    readonly kicker?: string;
     readonly status?: WalkthroughStatus;
     readonly summary?: string;
+    readonly more?: string;
     readonly steps: readonly WalkStep[];
 }
 export interface WalkVerdict {
@@ -391,11 +455,14 @@ export interface FeedItem {
     readonly q?: string;
     /** The step's key, when it names one that's there. */
     readonly step: string | null;
+    readonly status?: string;
+    readonly trail: readonly string[];
 }
 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[];
@@ -403,6 +470,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". */
@@ -470,6 +541,22 @@ 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;
+/**
+ * Whether a table stacks its rows into blocks: always, never, or (auto) when the room it has is
+ * less than its columns' natural width.
+ */
+export declare function tableStacks(stack: "auto" | "always" | "never", room: number, natural: number): boolean;
+/**
+ * The page's bottom reserve for the docked note bar: its height, the gap it floats above the
+ * page's edge, and a gap above it, so the last step and a step gone to never sit under it.
+ */
+export declare function noteBarReserve(bar: number, inset: number, gap: number): number;
 /** An ISO time as epoch ms; null when it isn't one. */
 export declare function parseAt(at: string | undefined): number | null;
 /** Newest first; items without a time after those with one, later-written first. */
@@ -677,5 +764,7 @@ export declare function feedbackMarkdown(fb: WalkthroughFeedback, verdicts?: rea
  * Inline Markdown as safe HTML: `code`, **bold**, *italic* and [links](https://…), the rest
  * escaped. Links take http(s), relative and # URLs only; blank lines make paragraphs' breaks.
  */
+/** Inline Markdown as plain words, for a contents row, a label or a title attribute. */
+export declare function plainMarkdown(text: string): string;
 export declare function inlineMarkdown(text: string): string;
 export {};

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,26 @@ 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). */
-    readonly rail?: boolean;
+    /**
+     * 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;
+    /**
+     * The note bar: a small launcher in the column's corner that opens into the bar on a click, n,
+     * a recording or ink, and folds back when it's empty (`"collapsed"`, the default); the bar
+     * always there (`"docked"`); or none (`"hidden"`; `send()` still works).
+     */
+    readonly noteBar?: "collapsed" | "docked" | "hidden";
     /** Sending a note moves on to the next step (on by default). */
     readonly advance?: boolean;
 }