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

package/dist/themes.js

@@ -447,6 +447,22 @@ var TOKENS = [
     source: css("var(--k-warn)"),
     doc: "Modified lines."
   },
+  {
+    name: "before",
+    tier: "semantic",
+    type: "color",
+    group: "Data",
+    source: css("var(--k-fg-3)"),
+    doc: "Before in a comparison, and only Before: its label and side of the seam. Neutral unless a theme gives it a colour."
+  },
+  {
+    name: "after",
+    tier: "semantic",
+    type: "color",
+    group: "Data",
+    source: css("var(--k-fg)"),
+    doc: "After in a comparison, and only After."
+  },
   {
     name: "series-1",
     tier: "semantic",
@@ -537,6 +553,150 @@ var TOKENS = [
     source: value("288px"),
     doc: "Panel width."
   },
+  {
+    name: "space-inside",
+    tier: "semantic",
+    type: "length",
+    group: "Space",
+    source: css("var(--k-unit)"),
+    doc: "Parts of one thing: an icon and its label, a meta line and its title."
+  },
+  {
+    name: "space-sibling",
+    tier: "semantic",
+    type: "length",
+    group: "Space",
+    source: css("calc(var(--k-unit) * 2)"),
+    doc: "Siblings in a group: buttons in a row, a list item's lines."
+  },
+  {
+    name: "space-title",
+    tier: "semantic",
+    type: "length",
+    group: "Space",
+    source: css("calc(var(--k-unit) * 3)"),
+    doc: "A heading and what it heads."
+  },
+  {
+    name: "space-group",
+    tier: "semantic",
+    type: "length",
+    group: "Space",
+    source: css("calc(var(--k-unit) * 12)"),
+    doc: "Groups inside a section (prose, video, diff), stacked media, feed items (a hairline in the middle)."
+  },
+  {
+    name: "space-section",
+    tier: "semantic",
+    type: "length",
+    group: "Space",
+    source: css("calc(var(--k-unit) * 24)"),
+    doc: "Sections of a page (the intro, the updates, each PR), a hairline in the middle."
+  },
+  {
+    name: "space-column",
+    tier: "semantic",
+    type: "length",
+    group: "Space",
+    source: css("calc(var(--k-unit) * 6)"),
+    doc: "Columns: a contents rail and the page, media side by side."
+  },
+  {
+    name: "pad-page",
+    tier: "semantic",
+    type: "length",
+    group: "Space",
+    source: css("calc(var(--k-unit) * 6)"),
+    doc: "A page's edge; 16px under 640px wide."
+  },
+  {
+    name: "pad-card",
+    tier: "semantic",
+    type: "length",
+    group: "Space",
+    source: css("calc(var(--k-unit) * 3)"),
+    doc: "Inside a card or popover."
+  },
+  {
+    name: "type-heading",
+    tier: "semantic",
+    type: "length",
+    group: "Type",
+    source: value("20px"),
+    doc: "A page's title, weight 500."
+  },
+  {
+    name: "leading-heading",
+    tier: "semantic",
+    type: "length",
+    group: "Type",
+    source: value("28px"),
+    doc: "Line height for type-heading."
+  },
+  {
+    name: "type-title",
+    tier: "semantic",
+    type: "length",
+    group: "Type",
+    source: value("16px"),
+    doc: "Section titles (under their kicker), weight 500."
+  },
+  {
+    name: "leading-title",
+    tier: "semantic",
+    type: "length",
+    group: "Type",
+    source: value("24px"),
+    doc: "Line height for type-title."
+  },
+  {
+    name: "type-body",
+    tier: "semantic",
+    type: "length",
+    group: "Type",
+    source: value("13px"),
+    doc: "Prose, questions, list rows, step titles; 400, or 500 for emphasis."
+  },
+  {
+    name: "leading-body",
+    tier: "semantic",
+    type: "length",
+    group: "Type",
+    source: value("20px"),
+    doc: "Line height for type-body."
+  },
+  {
+    name: "type-label",
+    tier: "semantic",
+    type: "length",
+    group: "Type",
+    source: value("12px"),
+    doc: "Mono inside body text: code and paths."
+  },
+  {
+    name: "leading-label",
+    tier: "semantic",
+    type: "length",
+    group: "Type",
+    source: value("16px"),
+    doc: "Line height for type-label."
+  },
+  {
+    name: "type-small",
+    tier: "semantic",
+    type: "length",
+    group: "Type",
+    source: value("11px"),
+    doc: "Meta, controls, keys, timestamps; mono inside labels."
+  },
+  {
+    name: "leading-small",
+    tier: "semantic",
+    type: "length",
+    group: "Type",
+    source: value("16px"),
+    doc: "Line height for type-small."
+  },
   {
     name: "font-size",
     tier: "semantic",
@@ -1443,28 +1603,6 @@ var knobs = defineTheme({
   material: "glass"
 });
 
-// src/themes/void.ts
-var voidTheme = defineTheme({
-  name: "void",
-  extends: knobs,
-  gray: { hue: 0, chroma: 0 },
-  accent: { dark: "#ffffff", light: "#1c1c1c" },
-  material: "flat",
-  tokens: {
-    dark: {
-      "bg-page": "#000000",
-      "bg-inset": "#0a0a0a",
-      bg: "#000000",
-      "bg-raised": "#1c1c1e",
-      "bg-overlay": "#2c2c2e",
-      fg: "#ededed",
-      "fg-2": "#cecece",
-      "fg-3": "#989898",
-      "fg-4": "#7a7a7a",
-      "compare-stage": "#000000"
-    }
-  }
-});
 // src/core/spring.ts
 class Spring {
   x;
@@ -1547,6 +1685,125 @@ function springCss(value) {
   return { easing, duration: ms };
 }
 
+// src/core/motion.ts
+var SPRINGS = {
+  instant: { duration: 0.1, bounce: 0 },
+  snappy: { duration: 0.25, bounce: 0 },
+  default: { duration: 0.3, bounce: 0 },
+  calm: { duration: 0.4, bounce: 0 },
+  smooth: { duration: 0.45, bounce: 0 }
+};
+var FADE = { duration: 0.16, bounce: 0 };
+var CLOSE = { duration: 0.18, bounce: 0 };
+var MOTION = Object.fromEntries(Object.entries(SPRINGS).map(([name, spring]) => [name, springMotion(spring)]));
+var springLinear = (spring) => {
+  const { omega, zeta } = springMotion(spring);
+  return springEasing(omega, zeta);
+};
+var names = Object.keys(SPRINGS);
+var linear = Object.fromEntries(names.map((n) => [n, springLinear(SPRINGS[n])]));
+var SPRING_TOKEN = `${SPRINGS.default.duration} ${SPRINGS.default.bounce}`;
+var DEFAULT_LINEAR = linear.default;
+var motionCss = `:where(:root,:host){${names.map((n) => `--_k-motion-${n}:${linear[n].easing};--_k-motion-${n}-ms:${linear[n].ms}`).join(";")}}
+@media(prefers-reduced-motion:reduce){:where(:root,:host){${names.map((n) => `--_k-motion-${n}-ms:0`).join(";")}}}`;
+
+// src/review/foundations.ts
+var TRACKING = 0.03;
+var MEASURE = "66ch";
+var FONT = {
+  sans: 'system-ui,-apple-system,BlinkMacSystemFont,"Segoe UI Variable Text","Segoe UI",Roboto,"Helvetica Neue",Arial,sans-serif',
+  mono: 'ui-monospace,"SF Mono",SFMono-Regular,"Cascadia Mono","JetBrains Mono",Menlo,Consolas,monospace'
+};
+var FEATURES = {
+  figures: "tabular-nums",
+  data: '"tnum" 1,"ss01" 1',
+  code: "none"
+};
+var MOTION2 = [
+  {
+    name: "hover",
+    spring: null,
+    ms: "0 in, 120 out",
+    use: "A hover's fill: on at once, off softly"
+  },
+  {
+    name: "quick",
+    spring: FADE,
+    use: "Replacing a whole thing in place: fade, scale .98, blur 3 px"
+  },
+  { name: "close", spring: CLOSE, use: "A popover closing" },
+  { name: "snappy", spring: SPRINGS.snappy, use: "Controls: a toggle, a pick, a chapter row" },
+  { name: "state", spring: SPRINGS.default, use: "The selection pill, a disclosure opening" },
+  {
+    name: "calm",
+    spring: SPRINGS.calm,
+    use: "Layout: a compare's height, the page scrolling to a step"
+  },
+  { name: "smooth", spring: SPRINGS.smooth, use: "A step opening to the full window" }
+];
+var foundationCss = `
+:where(.knobs-walkthrough,.knobs-wt-slot,.knobs-review){
+  --_kr-track:calc((var(--_k-type-body) - 1em) * ${TRACKING});
+  --_kr-measure:var(--k-walkthrough-measure,${MEASURE});
+  --_kr-block:calc(var(--_k-space-title) * 2);
+  --_kr-data:${FEATURES.data};
+  letter-spacing:var(--_kr-track);font-variant-numeric:${FEATURES.figures};font-optical-sizing:auto;font-kerning:normal}
+:where(.knobs-walkthrough,.knobs-wt-slot,.knobs-review) :where(*){letter-spacing:var(--_kr-track)}
+:where(.knobs-walkthrough,.knobs-wt-slot,.knobs-review) :where(code,pre,kbd,samp,.knobs-wt-mono){letter-spacing:0;font-variant-ligatures:${FEATURES.code}}
+`;
+
+// src/themes/void.ts
+var voidTheme = defineTheme({
+  name: "void",
+  extends: knobs,
+  gray: { hue: 0, chroma: 0 },
+  accent: { dark: "#ffffff", light: "#1c1c1c" },
+  material: "flat",
+  tokens: {
+    dark: {
+      "bg-page": "#000000",
+      "bg-inset": "#0a0a0a",
+      bg: "#000000",
+      "bg-raised": "#1c1c1e",
+      "bg-overlay": "#2c2c2e",
+      fg: "#ededed",
+      "fg-2": "#cecece",
+      "fg-3": "#989898",
+      "fg-4": "#7a7a7a",
+      "compare-stage": "#000000"
+    }
+  }
+});
+
+// src/themes/review.ts
+var reviewTheme = defineTheme({
+  name: "review",
+  extends: voidTheme,
+  font: FONT,
+  tokens: {
+    dark: {
+      fill: "#ededed0f",
+      "fill-hover": "#ededed1a",
+      "fill-selected": "#ededed24",
+      "border-subtle": "#ededed47",
+      border: "#ededed4f",
+      "border-strong": "#585858"
+    },
+    light: {
+      "bg-page": "#ffffff",
+      "bg-inset": "#f7f7f7",
+      bg: "#ffffff",
+      "bg-raised": "#ffffff",
+      "bg-overlay": "#ffffff",
+      fill: "#1919190a",
+      "fill-hover": "#19191912",
+      "fill-selected": "#1919191c",
+      "border-subtle": "#19191917",
+      border: "#1919191d",
+      "border-strong": "#dcdcdc"
+    }
+  }
+});
 // src/core/theme.ts
 var property = (k) => k.startsWith("--") ? k : `--k-${k}`;
 function presetCss(preset) {
@@ -1724,7 +1981,7 @@ var problemsPreset = {
   }
 };
 // src/themes/index.ts
-var themes = { knobs, void: voidTheme };
+var themes = { knobs, void: voidTheme, review: reviewTheme };
 export {
   APCA_BUDGET,
   defineTheme,
@@ -1732,6 +1989,7 @@ export {
   labPreset,
   presetCss,
   problemsPreset,
+  reviewTheme,
   themes,
   voidTheme
 };

package/dist/types/review/font.d.ts

@@ -0,0 +1,13 @@
+import { type Theme } from "../themes/define.js";
+export interface ReviewFontOptions {
+    /** A stylesheet that declares the face (Google Fonts, rsms.me/inter, your own). */
+    readonly href?: string;
+    /** The family, first in the stack: `"Inter"`, `"Geist"`. The platform's face follows it. */
+    readonly sans?: string;
+    readonly mono?: string;
+}
+/**
+ * The review look in a webfont: loads `href` once per document and returns the review theme with
+ * `sans` (and `mono`) first in its stacks. Pass it as `theme`.
+ */
+export declare function reviewFont(doc: Document, options: ReviewFontOptions): Theme;

package/dist/types/review/foundations.d.ts

@@ -0,0 +1,175 @@
+/** The five sizes. Two weights: 400, and 500 for titles and emphasis. */
+export declare const TYPE: readonly [{
+    readonly role: "heading";
+    readonly size: 20;
+    readonly leading: 28;
+    readonly weight: 500;
+    readonly use: "A page's title";
+}, {
+    readonly role: "title";
+    readonly size: 16;
+    readonly leading: 24;
+    readonly weight: 500;
+    readonly use: "A section's title, under its kicker";
+}, {
+    readonly role: "body";
+    readonly size: 13;
+    readonly leading: 20;
+    readonly weight: 400;
+    readonly use: "Prose, step and option titles (500), rows, values";
+}, {
+    readonly role: "label";
+    readonly size: 12;
+    readonly leading: 16;
+    readonly weight: 400;
+    readonly use: "Mono inside body text: code, paths, evidence chips";
+}, {
+    readonly role: "small";
+    readonly size: 11;
+    readonly leading: 16;
+    readonly weight: 400;
+    readonly use: "Meta, terms, kickers, controls, keys, times";
+}];
+export type TypeRole = (typeof TYPE)[number]["role"];
+/**
+ * Tracking follows size, one rule for every element: (body − size) × 0.03, so 20 px closes up by
+ * 0.21 px, 16 px by 0.09, 13 px sits at 0 and 11 px opens by 0.06. Mono never tracks.
+ */
+export declare const TRACKING = 0.03;
+export declare const trackingAt: (size: number, body?: number) => number;
+/** Prose stops here: 45–75 characters, centred on 66. */
+export declare const MEASURE = "66ch";
+/**
+ * The type stack: the platform's own UI face (SF Pro with its optical sizes on Apple, Segoe UI
+ * Variable on Windows), so nothing downloads, nothing swaps in, and the pages read like the native
+ * apps beside them. A webfont goes in through `reviewFont`.
+ */
+export declare const FONT: {
+    readonly sans: "system-ui,-apple-system,BlinkMacSystemFont,\"Segoe UI Variable Text\",\"Segoe UI\",Roboto,\"Helvetica Neue\",Arial,sans-serif";
+    readonly mono: "ui-monospace,\"SF Mono\",SFMono-Regular,\"Cascadia Mono\",\"JetBrains Mono\",Menlo,Consolas,monospace";
+};
+/**
+ * OpenType: tabular figures everywhere (times and counts never jitter); in data, `ss01` too
+ * (straight-sided 6 and 9 in SF, open digits in Inter: figures that can't be misread); code with
+ * no ligatures (`=>` stays two characters).
+ */
+export declare const FEATURES: {
+    readonly figures: "tabular-nums";
+    readonly data: "\"tnum\" 1,\"ss01\" 1";
+    readonly code: "none";
+};
+/** The space roles (px, on the 4 px unit); each from `title` up at least doubles the one below. */
+export declare const SPACE: readonly [{
+    readonly role: "inside";
+    readonly px: 4;
+    readonly use: "Parts of one thing: an icon and its label, a term and its value";
+}, {
+    readonly role: "sibling";
+    readonly px: 8;
+    readonly use: "Siblings in a group: rows, buttons, a list's lines";
+}, {
+    readonly role: "title";
+    readonly px: 12;
+    readonly use: "A heading and what it heads";
+}, {
+    readonly role: "block";
+    readonly px: 24;
+    readonly use: "Blocks inside one piece: fact groups, columns, media and its caption";
+}, {
+    readonly role: "group";
+    readonly px: 48;
+    readonly use: "Steps and options, a hairline in the middle";
+}, {
+    readonly role: "section";
+    readonly px: 96;
+    readonly use: "Sections of a page, a hairline in the middle";
+}];
+/** Hairlines and fills: alpha of the text colour, held to an APCA target on the page. */
+export declare const HAIRLINES: readonly [{
+    readonly token: "border-subtle";
+    readonly lc: 9;
+    readonly use: "Dividers between rows, steps and sections";
+}, {
+    readonly token: "border";
+    readonly lc: 12;
+    readonly use: "Rings round frames and wells";
+}, {
+    readonly token: "border-strong";
+    readonly lc: 17;
+    readonly use: "Interactive edges, a focus that isn't the accent";
+}];
+export declare const FILLS: readonly [{
+    readonly token: "fill";
+    readonly use: "A well at rest: code, a chip, a frame loading";
+}, {
+    readonly token: "fill-hover";
+    readonly use: "Under the pointer, at once";
+}, {
+    readonly token: "fill-selected";
+    readonly use: "The selection pill, a pressed toggle";
+}];
+/** Radii, concentric: what sits inside a frame takes the frame's radius less the gap between. */
+export declare const RADII: readonly [{
+    readonly token: "radius";
+    readonly px: 8;
+    readonly use: "Controls and rows 28–32 px high";
+}, {
+    readonly token: "radius-panel";
+    readonly px: 12;
+    readonly use: "Frames, wells, cards";
+}, {
+    readonly token: "radius / 2";
+    readonly px: 4;
+    readonly use: "Inline code, chips, rows 20 px high";
+}];
+/**
+ * The motion set. Springs are a duration and no bounce; nothing moves on load; hovers land at once
+ * and ease out; a whole thing replaced in place fades with a 3 px blur.
+ */
+export declare const MOTION: readonly [{
+    readonly name: "hover";
+    readonly spring: null;
+    readonly ms: "0 in, 120 out";
+    readonly use: "A hover's fill: on at once, off softly";
+}, {
+    readonly name: "quick";
+    readonly spring: import("../index.js").SpringValue;
+    readonly use: "Replacing a whole thing in place: fade, scale .98, blur 3 px";
+}, {
+    readonly name: "close";
+    readonly spring: import("../index.js").SpringValue;
+    readonly use: "A popover closing";
+}, {
+    readonly name: "snappy";
+    readonly spring: {
+        readonly duration: 0.25;
+        readonly bounce: 0;
+    };
+    readonly use: "Controls: a toggle, a pick, a chapter row";
+}, {
+    readonly name: "state";
+    readonly spring: {
+        readonly duration: 0.3;
+        readonly bounce: 0;
+    };
+    readonly use: "The selection pill, a disclosure opening";
+}, {
+    readonly name: "calm";
+    readonly spring: {
+        readonly duration: 0.4;
+        readonly bounce: 0;
+    };
+    readonly use: "Layout: a compare's height, the page scrolling to a step";
+}, {
+    readonly name: "smooth";
+    readonly spring: {
+        readonly duration: 0.45;
+        readonly bounce: 0;
+    };
+    readonly use: "A step opening to the full window";
+}];
+/**
+ * The foundations as private tokens on every review root; the review stylesheet reads them.
+ * Tracking is a calc in em, so it resolves on each element at its own size.
+ */
+export declare const foundationCss: string;

package/dist/types/review/index.d.ts

@@ -0,0 +1,13 @@
+export { FEATURES, FILLS, FONT, HAIRLINES, MEASURE, MOTION, RADII, SPACE, TRACKING, TYPE, trackingAt, type TypeRole, } from "./foundations.js";
+export { reviewFont, type ReviewFontOptions } from "./font.js";
+export { reviewTheme } from "../themes/review.js";
+export { injectUiStyles, restyle, type RestyleLook, type UiLook } from "../ui/look.js";
+export { tasteTest, walkthrough, type TasteTest, type TasteTestOptions, type Walkthrough, type WalkthroughOptions, } from "../ui/walkthrough.js";
+export { decision, facts, mediaSlot, type DecisionOptions, type FactsOptions, type MediaSlot, type MediaSlotOptions, type StepLinks, } from "../ui/walkthrough-media.js";
+export { compare, type Compare, type CompareLoop, type CompareMode, type CompareOptions, type CompareSource, type CompareView, type ZoomRegion, } from "../ui/compare.js";
+export { compareStrip, type CompareStrip, type CompareStripOptions } from "../ui/compare-strip.js";
+export { player, type Player, type PlayerChapter, type PlayerOptions } from "../ui/player.js";
+export { codeDiff, diffReview, type CodeDiff, type CodeDiffOptions, type CodeDiffUpdate, type DiffLayout, type DiffReview, type DiffReviewOptions, } from "../ui/diff.js";
+export type { DiffSource } from "../ui/diff-model.js";
+export { history, type History, type HistoryBand, type HistoryData, type HistoryEvent, type HistoryEvidence, type HistoryGroup, type HistoryLane, type HistoryOptions, type HistoryProvenance, type HistorySpan, type HistoryState, type HistoryTone, } from "../ui/history.js";
+export { collectFeedback, feedbackMarkdown, inlineMarkdown, normalizeWalkthrough, plainMarkdown, readState as readWalkthroughState, walkthroughProgress, type FeedbackItem, type FeedbackNote, type WalkPage, type WalkStep, type WalkthroughAnnotation, type WalkthroughChapter, type WalkthroughDecisionOption, type WalkthroughFact, type WalkthroughFactGroup, type WalkthroughFacts, type WalkthroughDoc, type WalkthroughEvidence, type WalkthroughFeedback, type WalkthroughHistoryEvent, type WalkthroughHistoryGroup, type WalkthroughMedia, type WalkthroughMeta, type WalkthroughOption, type WalkthroughPR, type WalkthroughQA, type WalkthroughSection, type WalkthroughSource, type WalkthroughStackItem, type WalkthroughState, type WalkthroughStatus, type WalkthroughStep, type WalkthroughTableCell, type WalkthroughTableColumn, type WalkthroughTableRow, type WalkthroughTone, type WalkthroughUpdate, } from "../ui/walkthrough-model.js";

package/dist/types/review/react.d.ts

@@ -0,0 +1 @@
+export { CodeDiff, Compare, CompareStrip, DiffReview, MediaSlot, TasteTest, Walkthrough, type CodeDiffProps, type CompareProps, type CompareStripProps, type DiffReviewProps, type MediaSlotProps, type TasteTestProps, type WalkthroughDoc, type WalkthroughFeedback, type WalkthroughProps, } from "../ui/react.js";

package/dist/types/review/solid.d.ts

@@ -0,0 +1 @@
+export { CodeDiff, Compare, CompareStrip, DiffReview, MediaSlot, TasteTest, Walkthrough, type CodeDiffProps, type CompareProps, type CompareStripProps, type DiffReviewProps, type MediaSlotProps, type TasteTestProps, type WalkthroughDoc, type WalkthroughFeedback, type WalkthroughProps, } from "../ui/solid.js";

package/dist/types/themes/index.d.ts

@@ -1,12 +1,17 @@
 import { knobs } from "./knobs.js";
+import { reviewTheme } from "./review.js";
 import { voidTheme } from "./void.js";
 export { APCA_BUDGET, type Appearance as ThemeAppearance, type Density, defineTheme, type GpuColors, type Material, type ResolvedTokens, type Theme, type ThemeInputs, type ThemeSpec, type TokenOverrides, } from "./define.js";
-export { knobs, voidTheme };
+export { knobs, reviewTheme, voidTheme };
 export type { Appearance } from "../core/appearance.js";
 export type { PublicTokenName, TokenName, TokenProperty } from "../tokens/schema.js";
-/** The shipped themes: Knobs (the default) and Void (true black, flat, for OLED and video). */
+/**
+ * The shipped themes: Knobs (the default), Void (true black, flat, for OLED and video) and Review
+ * (the review pieces' own default: Void with hairlines you can see).
+ */
 export declare const themes: {
     readonly knobs: import("./define.js").Theme;
     readonly void: import("./define.js").Theme;
+    readonly review: import("./define.js").Theme;
 };
 export { labPreset, presetCss, problemsPreset, type TokenPreset } from "../core/theme.js";

package/dist/types/themes/review.d.ts

@@ -0,0 +1,8 @@
+/**
+ * The review pieces' own look (walkthrough, compare, player, diff, facts, decision): Void's true
+ * black, flat and neutral, with hairlines you can see. Borders are alpha of the text colour, set
+ * by APCA on the page: subtle ≈ Lc 9, default ≈ Lc 12, strong ≈ Lc 17, in both appearances
+ * (Void's composited 6% and 10% read Lc 0 on black). Fills step 6 / 10 / 14% so a hover's
+ * background is plain to see. Light is white, page and surface alike. The platform's own face.
+ */
+export declare const reviewTheme: import("./define.js").Theme;