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

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

@@ -222,6 +222,20 @@ export type WalkthroughMedia = string | {
 } | {
     readonly kind: "text";
     readonly text: string;
+} | {
+    readonly kind: "facts";
+    /** A small faint label over it. */
+    readonly title?: string;
+    /** One run of term → value pairs… */
+    readonly facts?: WalkthroughFacts;
+    /** …or several, each under a heading, hairlines between. */
+    readonly groups?: readonly WalkthroughFactGroup[];
+} | {
+    readonly kind: "decision";
+    /** Side by side where there's room, one under another where there isn't. */
+    readonly options: readonly WalkthroughDecisionOption[];
+    /** The word before each option's number: "Option" by default. */
+    readonly noun?: string;
 } | {
     readonly kind: "mount";
     readonly mount: (element: HTMLElement) => (() => void) | void;
@@ -229,6 +243,35 @@ export type WalkthroughMedia = string | {
     readonly height?: number;
 };
 export type CalloutTone = "info" | "good" | "warn" | "bad";
+/** A term and its value. */
+export interface WalkthroughFact {
+    readonly term: string;
+    /** Markdown, where `code` reads as a small mono chip; several values sit one under another. */
+    readonly value: string | readonly string[];
+    /** Each value is code or evidence (a string splits at commas): small mono chips. */
+    readonly code?: boolean;
+}
+/** Facts as a list, or as `{ term: value }`. */
+export type WalkthroughFacts = readonly WalkthroughFact[] | Readonly<Record<string, string | readonly string[]>>;
+export interface WalkthroughFactGroup {
+    readonly title?: string;
+    readonly facts: WalkthroughFacts;
+}
+/** One way to go in a decision. */
+export interface WalkthroughDecisionOption {
+    readonly id?: string;
+    readonly title: string;
+    /** A sentence: what it does. Markdown. */
+    readonly summary?: string;
+    /** What it looks like: a picture, a compare, code. */
+    readonly media?: WalkthroughMedia;
+    /** What changes, as facts ("What the user sees", "Size"). */
+    readonly facts?: WalkthroughFacts;
+    readonly pros?: readonly string[];
+    readonly cons?: readonly string[];
+    /** The one to take: a quiet "Recommended" beside its number. */
+    readonly recommended?: boolean;
+}
 /** One option in a taste test. */
 export interface WalkthroughOption {
     /** "a", "b"… by position when left out. */
@@ -236,8 +279,12 @@ export interface WalkthroughOption {
     readonly label: string;
     readonly caption?: string;
     readonly media?: WalkthroughMedia;
-    /** The agent's own pick, marked "Suggested". */
+    /** What changes, as facts, under its caption. */
+    readonly facts?: WalkthroughFacts;
+    /** The agent's own pick, marked "Recommended". */
     readonly suggested?: boolean;
+    /** Another name for `suggested`. */
+    readonly recommended?: boolean;
 }
 export interface WalkthroughStep {
     /** From the title when left out. */
@@ -352,6 +399,10 @@ export interface WalkthroughDoc {
 }
 export interface WalkthroughPR {
     readonly state?: "merged" | "open" | "draft" | "closed";
+    /** An issue rather than a pull request (`issue:` refs and `/issues/` links are). */
+    readonly kind?: "pr" | "issue";
+    /** Its checks pass (a stack item's status saying green, passing or CI). */
+    readonly checks?: boolean;
     readonly title?: string;
     /** Its URL, when neither `repo` nor a link on the page gives it. */
     readonly href?: string;
@@ -406,7 +457,7 @@ export interface WalkTableColumn {
  * nothing.
  */
 export type WalkMedia = Exclude<WalkthroughMedia, string | {
-    readonly kind: "compare" | "video" | "history" | "stack" | "table";
+    readonly kind: "compare" | "video" | "history" | "stack" | "table" | "facts" | "decision";
 }> | (Omit<CompareMedia, "before" | "after" | "chapters"> & {
     readonly before: WalkthroughSource;
     readonly after: WalkthroughSource;
@@ -422,6 +473,13 @@ export type WalkMedia = Exclude<WalkthroughMedia, string | {
     readonly kind: "stack";
     readonly base?: string;
     readonly items: readonly WalkStackItem[];
+} | {
+    readonly kind: "facts";
+    readonly title?: string;
+    readonly groups: readonly WalkFactGroup[];
+} | {
+    readonly kind: "decision";
+    readonly options: readonly WalkDecisionOption[];
 } | {
     readonly kind: "table";
     readonly columns: readonly WalkTableColumn[];
@@ -438,8 +496,30 @@ export interface WalkOption {
     readonly letter: string;
     readonly caption?: string;
     readonly media?: WalkMedia;
+    readonly facts?: readonly WalkFact[];
     readonly suggested: boolean;
 }
+/** A fact filled in: its values as a list. */
+export interface WalkFact {
+    readonly term: string;
+    readonly value: readonly string[];
+    readonly code: boolean;
+}
+export interface WalkFactGroup {
+    readonly title?: string;
+    readonly facts: readonly WalkFact[];
+}
+/** A decision's option filled in: its id, its number's words, pros and cons as facts. */
+export interface WalkDecisionOption {
+    readonly id: string;
+    /** "Option 1". */
+    readonly number: string;
+    readonly title: string;
+    readonly summary?: string;
+    readonly media?: WalkMedia;
+    readonly facts: readonly WalkFact[];
+    readonly recommended: boolean;
+}
 export interface WalkStep {
     /** `section/step`: where its feedback is kept. */
     readonly key: string;
@@ -516,6 +596,15 @@ 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;
+/** Facts as a list of terms and their values (a code value split at its commas). */
+export declare function fillFacts(facts: WalkthroughFacts | readonly WalkFact[]): readonly WalkFact[];
+/**
+ * How many options sit side by side: as many as fit at `min` px each with `gap` between, up to 4,
+ * and always a count that fills whole rows (4 → 4, 2 or 1; 3 → 3 or 1; 5 → 1), so no row is short.
+ */
+export declare function optionColumns(count: number, width: number, min?: number, gap?: number): number;
+/** A decision's options filled in: ids, "Option 1"…, pros and cons as the last facts. */
+export declare function fillDecision(options: readonly (WalkthroughDecisionOption | WalkDecisionOption)[], noun?: string, base?: string): readonly WalkDecisionOption[];
 /**
  * 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.
@@ -580,8 +669,23 @@ export declare function linkLabel(href: string): string;
 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;
+export type PRState = NonNullable<WalkthroughPR["state"]>;
+/**
+ * A pull request's state from some status words: the first word when it's merged, draft, open or
+ * closed (any case; shipped and done read as merged), and whether they say its checks pass
+ * ("green", "passing", "CI"). The state comes from the words, never a tone.
+ */
+export declare function prStatus(status: string | undefined): {
+    state: PRState | null;
+    checks: boolean;
+};
+/**
+ * A pull request (or an issue) by number: what the page knows, or (with a repo) its URL; null
+ * when it knows nothing. An issue takes only what `prs` says of it as an issue.
+ */
+export declare function findPR(prs: Readonly<Record<string, WalkthroughPR>>, n: string, repo?: string, kind?: "pr" | "issue"): WalkthroughPR | null;
+/** The number in an issue's URL (`…/issues/123`), or null. */
+export declare const issueNumber: (href: string) => string | 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

@@ -28,7 +28,7 @@ export interface TasteTest {
  * A vs B (or more): each option's letter, label and media side by side (stacking where it's
  * narrow). The picked one takes a check and a wash; the others step back.
  */
-export declare function tasteTest(container: HTMLElement, options: TasteTestOptions): TasteTest;
+export declare function tasteTest(container: HTMLElement, given: TasteTestOptions): TasteTest;
 export interface WalkthroughOptions extends UiLook {
     readonly doc: WalkthroughDoc;
     /** Where Kit's answers are kept (localStorage by default; `null` keeps none). */
@@ -82,4 +82,4 @@ export interface Walkthrough {
     reset(): void;
     dispose(): void;
 }
-export declare function walkthrough(container: HTMLElement, options: WalkthroughOptions): Walkthrough;
+export declare function walkthrough(container: HTMLElement, given: WalkthroughOptions): Walkthrough;