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

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

@@ -0,0 +1,33 @@
+import { type HistoryData, type HistoryModel } from "./history-model.js";
+import { type UiLook } from "./look.js";
+export type { HistoryBand, HistoryData, HistoryEvent, HistoryEvidence, HistoryGroup, HistoryLane, HistoryProvenance, HistorySpan, HistoryState, HistoryTone, } from "./history-model.js";
+export interface HistoryOptions extends UiLook {
+    /** Lanes of spans and events (or the walkthrough's `groups` of events): plain JSON. */
+    readonly data: HistoryData;
+    /** The selected event or span's id. */
+    readonly selected?: string | null;
+    /** Clicks and keys moved the selection (a host's `select()` doesn't call it). */
+    readonly onSelect?: (id: string | null) => void;
+    /** Draws "Go to step" in the detail of anything with a `step`, and Enter on it. */
+    readonly onJump?: (step: string) => void;
+    /** Its accessible name. */
+    readonly label?: string;
+    /** Under this width (px) lane labels sit above their lanes instead of beside them (560). */
+    readonly narrow?: number;
+}
+export interface History {
+    readonly element: HTMLElement;
+    /** The data filled in: whole days, lanes, the axis and the order ←/→ walk. */
+    readonly model: HistoryModel;
+    readonly selected: string | null;
+    /** Selects an event or span (`null` clears); doesn't call `onSelect`. */
+    select(id: string | null): void;
+    set(data: HistoryData): void;
+    focus(): void;
+    dispose(): void;
+    /** The same as `dispose`. */
+    destroy(): void;
+}
+/** Adds the history's stylesheet once per document. */
+export declare function injectHistoryStyles(doc: Document): void;
+export declare function history(container: HTMLElement, options: HistoryOptions): History;

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,16 @@ 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;
 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,12 @@ 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 media after the first fold away under a quiet toggle with these words ("More clips"). */
+    readonly more?: string;
     /** A taste test: Kit picks one. */
     readonly options?: readonly WalkthroughOption[];
     /**
@@ -225,6 +237,11 @@ 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;
     readonly steps: readonly WalkthroughStep[];
@@ -241,6 +258,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 +270,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 {
@@ -266,6 +291,15 @@ 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;
     readonly sections: readonly WalkthroughSection[];
 }
 type CompareMedia = Extract<WalkthroughMedia, {
@@ -342,6 +376,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 +400,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,6 +413,8 @@ 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 steps: readonly WalkStep[];
@@ -391,6 +433,8 @@ 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;
@@ -470,6 +514,18 @@ 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;
+/** 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 +733,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

@@ -35,8 +35,16 @@ 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;
+    /** The contents and progress rail (on by default), beside the column on the right or left. */
+    readonly rail?: boolean | "right" | "left";
+    /** 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;
 }