@kitlangton/knobs 0.4.0-next.1 → 0.4.0-next.11

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

@@ -0,0 +1,87 @@
+import { type ContextEvent, type WalkChapter, type WalkMedia, prStatus, type PRState } from "./walkthrough-model.js";
+/** The glyphs the blocks draw. */
+export declare const GLYPH: {
+    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. */
+    find(ref: string): {
+        readonly key: string;
+        readonly number: string;
+        readonly title: string;
+    } | null;
+    /** Goes to the step, as j / k do. */
+    go(key: string): void;
+}
+type OnEvent = ((event: Omit<ContextEvent, "at" | "step">) => void) | undefined;
+export interface Block {
+    dispose(): void;
+    context?(): {
+        kind: string;
+    };
+}
+/**
+ * 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, findPR?: (n: string) => PRInfo | null): Block;
+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 pill slides to it. */
+    sync(): void;
+    /** The chapter playing, or null. */
+    readonly current: WalkChapter | null;
+    dispose(): void;
+}
+export declare function chapterPills(host: HTMLElement, chapters: readonly WalkChapter[], io: {
+    /** Seconds. */
+    now(): number;
+    /** Seeks and plays. */
+    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;
+    open?: boolean;
+    content: HTMLElement;
+}): Disclosure;
+export { prStatus, type PRState };
+/** 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?: PRState;
+    readonly kind?: "pr" | "issue";
+    readonly checks?: boolean;
+    readonly title?: string;
+    readonly href?: string;
+}
+/**
+ * A pull request (or an issue) as a capsule: its state's glyph and number, tinted quietly by state
+ * (neutral where none is known), a faint check where its checks pass, title and state on hover.
+ */
+export declare function prChip(doc: Document, n: string, pr: PRInfo): HTMLElement;
+/** What the page knows of a pull request or issue by number (null when nothing). */
+export type FindPR = (n: string, kind: "pr" | "issue") => PRInfo | null;
+/**
+ * Turns every pull request and issue ref in some rendered prose into a capsule: links to one
+ * whose words are its number or URL, inline code that's just a ref, and bare `#57148`s
+ * (`issue:#123` for an issue). One the page knows nothing of is a neutral chip, linked only where
+ * the page has a repo.
+ */
+export declare function linkPRs(root: HTMLElement, find: FindPR): void;

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

@@ -1,4 +1,5 @@
 import { type UiLook } from "./look.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;
@@ -6,7 +7,12 @@ export interface MediaSlotOptions extends UiLook {
     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;
+    /** 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 {
     readonly element: HTMLElement;
     /** Whether its content is mounted (heavy kinds wait until they're near the view). */
@@ -25,5 +31,28 @@ export interface MediaSlot {
 }
 /** 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 function mediaSlot(container: HTMLElement, given: MediaSlotOptions): MediaSlot;
 export declare const CHECK: string;
+type FactsMedia = Extract<WalkthroughMedia, {
+    kind: "facts";
+}>;
+type DecisionMedia = Extract<WalkthroughMedia, {
+    kind: "decision";
+}>;
+export interface FactsOptions extends UiLook, Omit<FactsMedia, "kind"> {
+}
+export interface DecisionOptions extends UiLook, Omit<DecisionMedia, "kind">, Pick<MediaSlotOptions, "lazy" | "steps" | "onEvent"> {
+}
+/**
+ * Term → value pairs in an aligned grid: terms small and faint in a fixed gutter, values beside
+ * them, code and evidence as small mono chips; groups under a heading, hairlines between. Each
+ * term sits over its value where it's narrow. Also a walkthrough's `{ kind: "facts" }`.
+ */
+export declare function facts(container: HTMLElement, options: FactsOptions): MediaSlot;
+/**
+ * N ways to go, one recommended: each a title, a sentence, optional media and what changes as
+ * facts, side by side where there's room (whole rows only), hairlines between, the recommended one
+ * marked by a quiet word. Also a walkthrough's `{ kind: "decision" }`; a step's `options` (Kit
+ * picks) look the same.
+ */
+export declare function decision(container: HTMLElement, options: DecisionOptions): MediaSlot;