@kitlangton/knobs 0.4.0-next.8 → 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. */
@@ -410,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;
@@ -426,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[];
@@ -442,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;
@@ -520,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.

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;