@brandon_m_behring/book-scaffold-astro 4.27.0 → 4.28.0

package/dist/demo.mjs

@@ -0,0 +1,353 @@
+// components/demo/DemoFrame.tsx
+import { useId } from "preact/hooks";
+import { jsx, jsxs } from "preact/jsx-runtime";
+var DEMO_HEADING_LEVELS = [2, 3, 4, 5, 6];
+function assertNonEmpty(value, prop) {
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new Error(`DemoFrame: ${prop} must be a non-empty string.`);
+  }
+}
+function generatedBaseId(id, generated) {
+  if (id !== void 0) {
+    assertNonEmpty(id, "id");
+    if (/\s/.test(id)) {
+      throw new Error("DemoFrame: id must not contain whitespace.");
+    }
+    return id;
+  }
+  return `demo-${generated.replace(/[^a-zA-Z0-9_-]/g, "")}`;
+}
+function DemoFrame({
+  title,
+  description,
+  caption,
+  children,
+  id,
+  className,
+  busy = false,
+  headingLevel = 3
+}) {
+  assertNonEmpty(title, "title");
+  if (description !== void 0) assertNonEmpty(description, "description");
+  if (typeof caption === "string") assertNonEmpty(caption, "caption");
+  if (!DEMO_HEADING_LEVELS.includes(headingLevel)) {
+    throw new Error("DemoFrame: headingLevel must be one of 2 | 3 | 4 | 5 | 6.");
+  }
+  const baseId = generatedBaseId(id, useId());
+  const titleId = `${baseId}-title`;
+  const descriptionId = description ? `${baseId}-description` : null;
+  const captionId = caption != null ? `${baseId}-caption` : null;
+  const describedBy = [descriptionId, captionId].filter(Boolean).join(" ") || void 0;
+  const classes = ["demo-frame", className].filter(Boolean).join(" ");
+  const Heading = `h${headingLevel}`;
+  return /* @__PURE__ */ jsxs(
+    "figure",
+    {
+      id,
+      class: classes,
+      "aria-labelledby": titleId,
+      "aria-describedby": describedBy,
+      "aria-busy": busy || void 0,
+      children: [
+        /* @__PURE__ */ jsxs("header", { class: "demo-frame__header", children: [
+          /* @__PURE__ */ jsx(Heading, { id: titleId, class: "demo-frame__title", children: title }),
+          description && /* @__PURE__ */ jsx("p", { id: descriptionId, class: "demo-frame__description", children: description })
+        ] }),
+        /* @__PURE__ */ jsx("div", { class: "demo-frame__body", children }),
+        caption != null && /* @__PURE__ */ jsx("figcaption", { id: captionId, class: "demo-frame__caption", children: caption })
+      ]
+    }
+  );
+}
+
+// components/demo/Slider.tsx
+import { useId as useId2 } from "preact/hooks";
+import { jsx as jsx2, jsxs as jsxs2 } from "preact/jsx-runtime";
+function assertFinite(value, prop) {
+  if (!Number.isFinite(value)) {
+    throw new Error(`Slider: ${prop} must be a finite number.`);
+  }
+}
+function isStepAligned(value, min, step) {
+  const steps = (value - min) / step;
+  const nearest = Math.round(steps);
+  const tolerance = Number.EPSILON * Math.max(1, Math.abs(steps)) * 16;
+  return Math.abs(steps - nearest) <= tolerance;
+}
+function assertSliderProps({
+  label,
+  value,
+  min,
+  max,
+  step = 1,
+  id,
+  description,
+  onValueChange,
+  formatValue,
+  getValueText
+}) {
+  if (typeof label !== "string" || label.trim() === "") {
+    throw new Error("Slider: label must be a non-empty string.");
+  }
+  assertFinite(value, "value");
+  assertFinite(min, "min");
+  assertFinite(max, "max");
+  assertFinite(step, "step");
+  if (max <= min) throw new Error("Slider: max must be greater than min.");
+  if (step <= 0) throw new Error("Slider: step must be greater than 0.");
+  if (value < min || value > max) {
+    throw new Error(`Slider: value ${value} must be within [${min}, ${max}].`);
+  }
+  if (!isStepAligned(value, min, step)) {
+    throw new Error("Slider: value must align with min + (n \xD7 step).");
+  }
+  if (id !== void 0 && (typeof id !== "string" || id.trim() === "" || /\s/.test(id))) {
+    throw new Error("Slider: id must be a non-empty string without whitespace.");
+  }
+  if (description !== void 0 && (typeof description !== "string" || description.trim() === "")) {
+    throw new Error("Slider: description must be a non-empty string.");
+  }
+  if (typeof onValueChange !== "function") {
+    throw new Error("Slider: onValueChange must be a function.");
+  }
+  if (formatValue !== void 0 && typeof formatValue !== "function") {
+    throw new Error("Slider: formatValue must be a function.");
+  }
+  if (getValueText !== void 0 && typeof getValueText !== "function") {
+    throw new Error("Slider: getValueText must be a function.");
+  }
+}
+function Slider(props) {
+  assertSliderProps(props);
+  const {
+    label,
+    value,
+    min,
+    max,
+    step = 1,
+    onValueChange,
+    id,
+    name,
+    description,
+    disabled = false,
+    className,
+    formatValue = String,
+    getValueText = formatValue
+  } = props;
+  const generated = useId2().replace(/[^a-zA-Z0-9_-]/g, "");
+  const inputId = id ?? `demo-slider-${generated}`;
+  const descriptionId = description ? `${inputId}-description` : void 0;
+  const displayValue = formatValue(value);
+  if (typeof displayValue !== "string" || displayValue.trim() === "") {
+    throw new Error("Slider: formatValue must return a non-empty string.");
+  }
+  const valueText = getValueText(value);
+  if (typeof valueText !== "string" || valueText.trim() === "") {
+    throw new Error("Slider: getValueText must return a non-empty string.");
+  }
+  const classes = ["demo-slider", className].filter(Boolean).join(" ");
+  return /* @__PURE__ */ jsxs2("div", { class: classes, "data-disabled": disabled || void 0, children: [
+    /* @__PURE__ */ jsxs2("div", { class: "demo-slider__head", children: [
+      /* @__PURE__ */ jsx2("label", { class: "demo-slider__label", for: inputId, children: label }),
+      /* @__PURE__ */ jsx2("output", { class: "demo-slider__value", for: inputId, children: displayValue })
+    ] }),
+    description && /* @__PURE__ */ jsx2("p", { id: descriptionId, class: "demo-slider__description", children: description }),
+    /* @__PURE__ */ jsx2(
+      "input",
+      {
+        id: inputId,
+        class: "demo-slider__input",
+        type: "range",
+        name,
+        min,
+        max,
+        step,
+        value,
+        disabled,
+        "aria-describedby": descriptionId,
+        "aria-valuetext": valueText,
+        onInput: (event) => {
+          const next = Number.parseFloat(event.currentTarget.value);
+          if (!Number.isFinite(next)) {
+            throw new Error("Slider: native input produced a non-finite value.");
+          }
+          onValueChange(next);
+        }
+      }
+    )
+  ] });
+}
+
+// components/demo/StatCards.tsx
+import { Fragment, jsx as jsx3, jsxs as jsxs3 } from "preact/jsx-runtime";
+var STAT_CARD_TONES = ["neutral", "accent", "positive", "warning"];
+function assertText(value, path) {
+  if (typeof value !== "string" || value.trim() === "") {
+    throw new Error(`StatCards: ${path} must be a non-empty string.`);
+  }
+}
+function assertItems(items) {
+  if (!Array.isArray(items) || items.length === 0) {
+    throw new Error("StatCards: items must contain at least one statistic.");
+  }
+  const keys = /* @__PURE__ */ new Set();
+  for (const [index, item] of items.entries()) {
+    if (item === null || typeof item !== "object") {
+      throw new Error(`StatCards: items[${index}] must be a statistic object.`);
+    }
+    assertText(item.label, `items[${index}].label`);
+    if (typeof item.value !== "string" && typeof item.value !== "number") {
+      throw new Error(`StatCards: items[${index}].value must be a string or number.`);
+    }
+    if (typeof item.value === "number" && !Number.isFinite(item.value)) {
+      throw new Error(`StatCards: items[${index}].value must be finite.`);
+    }
+    if (typeof item.value === "string") assertText(item.value, `items[${index}].value`);
+    if (item.unit !== void 0) assertText(item.unit, `items[${index}].unit`);
+    if (item.detail !== void 0) assertText(item.detail, `items[${index}].detail`);
+    const tone = item.tone ?? "neutral";
+    if (!STAT_CARD_TONES.includes(tone)) {
+      throw new Error(
+        `StatCards: items[${index}].tone must be one of ${STAT_CARD_TONES.join(" | ")}.`
+      );
+    }
+    const key = item.id ?? item.label;
+    assertText(key, `items[${index}].id`);
+    if (keys.has(key)) throw new Error(`StatCards: duplicate item key "${key}".`);
+    keys.add(key);
+  }
+}
+function StatCards({
+  items,
+  label = "Key statistics",
+  live = "off",
+  className
+}) {
+  assertItems(items);
+  assertText(label, "label");
+  if (live !== "off" && live !== "polite") {
+    throw new Error("StatCards: live must be off | polite.");
+  }
+  const classes = ["demo-stat-cards", className].filter(Boolean).join(" ");
+  return /* @__PURE__ */ jsx3(
+    "dl",
+    {
+      class: classes,
+      "aria-label": label,
+      "aria-live": live,
+      "aria-atomic": live === "polite" || void 0,
+      children: items.map((item) => {
+        const tone = item.tone ?? "neutral";
+        return /* @__PURE__ */ jsxs3("div", { class: "demo-stat-card", "data-tone": tone, children: [
+          /* @__PURE__ */ jsx3("dt", { class: "demo-stat-card__label", children: item.label }),
+          /* @__PURE__ */ jsxs3("dd", { class: "demo-stat-card__value", children: [
+            item.value,
+            item.unit && /* @__PURE__ */ jsxs3(Fragment, { children: [
+              " ",
+              /* @__PURE__ */ jsx3("span", { class: "demo-stat-card__unit", children: item.unit })
+            ] })
+          ] }),
+          item.detail && /* @__PURE__ */ jsx3("dd", { class: "demo-stat-card__detail", children: item.detail })
+        ] }, item.id ?? item.label);
+      })
+    }
+  );
+}
+
+// components/demo/useThemeColors.ts
+import { useEffect, useState } from "preact/hooks";
+function fallbackColors(specs) {
+  return Object.fromEntries(
+    Object.entries(specs).map(([key, [, fallback]]) => [key, fallback])
+  );
+}
+function unresolvedSnapshot(specs) {
+  return {
+    theme: null,
+    colors: fallbackColors(specs),
+    reducedMotion: null
+  };
+}
+function assertSpecs(specs) {
+  if (specs === null || typeof specs !== "object" || Array.isArray(specs)) {
+    throw new Error("useThemeColors: specs must be a token-map object.");
+  }
+  const entries = Object.entries(specs);
+  if (entries.length === 0) {
+    throw new Error("useThemeColors: provide at least one CSS token mapping.");
+  }
+  for (const [key, spec] of entries) {
+    if (key.trim() === "") {
+      throw new Error("useThemeColors: color keys must be non-empty strings.");
+    }
+    if (!Array.isArray(spec) || spec.length !== 2) {
+      throw new Error(`useThemeColors: "${key}" must be a [token, fallback] pair.`);
+    }
+    const [token, fallback] = spec;
+    if (typeof token !== "string" || !/^--\S+$/.test(token)) {
+      throw new Error(`useThemeColors: "${key}" token must start with -- and contain no whitespace.`);
+    }
+    if (typeof fallback !== "string" || fallback.trim() === "") {
+      throw new Error(`useThemeColors: "${key}" fallback must be a non-empty string.`);
+    }
+  }
+}
+function effectiveTheme() {
+  const explicit = document.documentElement.getAttribute("data-theme");
+  if (explicit === "light" || explicit === "dark") return explicit;
+  return window.matchMedia("(prefers-color-scheme: dark)").matches ? "dark" : "light";
+}
+function snapshot(specs, themeHint) {
+  const computed = getComputedStyle(document.documentElement);
+  const colors = Object.fromEntries(
+    Object.entries(specs).map(([key, [token, fallback]]) => {
+      const resolved = computed.getPropertyValue(token).trim();
+      return [key, resolved || fallback];
+    })
+  );
+  return {
+    theme: themeHint ?? effectiveTheme(),
+    colors,
+    reducedMotion: window.matchMedia("(prefers-reduced-motion: reduce)").matches
+  };
+}
+function useThemeColors(specs) {
+  assertSpecs(specs);
+  const signature = JSON.stringify(specs);
+  const [current, setCurrent] = useState(() => ({
+    signature,
+    value: unresolvedSnapshot(specs)
+  }));
+  useEffect(() => {
+    const refresh = (themeHint) => setCurrent({
+      signature,
+      value: snapshot(specs, themeHint)
+    });
+    const onThemeChange = (event) => {
+      const detail = event.detail;
+      const theme = detail?.theme === "light" || detail?.theme === "dark" ? detail.theme : void 0;
+      refresh(theme);
+    };
+    const onMediaChange = () => refresh();
+    const colorScheme = window.matchMedia("(prefers-color-scheme: dark)");
+    const reducedMotion = window.matchMedia("(prefers-reduced-motion: reduce)");
+    refresh();
+    window.addEventListener("book:theme:change", onThemeChange);
+    colorScheme.addEventListener("change", onMediaChange);
+    reducedMotion.addEventListener("change", onMediaChange);
+    return () => {
+      window.removeEventListener("book:theme:change", onThemeChange);
+      colorScheme.removeEventListener("change", onMediaChange);
+      reducedMotion.removeEventListener("change", onMediaChange);
+    };
+  }, [signature]);
+  return current.signature === signature ? current.value : unresolvedSnapshot(specs);
+}
+export {
+  DEMO_HEADING_LEVELS,
+  DemoFrame,
+  STAT_CARD_TONES,
+  Slider,
+  StatCards,
+  useThemeColors
+};

package/dist/index.mjs

@@ -1130,6 +1130,21 @@ function defineMdxComponents(components) {
 // src/integration.ts
 var BOOK_CONFIG_VIRTUAL_ID = "virtual:book-scaffold/book-config";
 var BOOK_CONFIG_RESOLVED_ID = "\0" + BOOK_CONFIG_VIRTUAL_ID;
+function makeRobotoFontDisplayVitePlugin() {
+  return {
+    name: "book-scaffold:roboto-font-display",
+    enforce: "pre",
+    transform(code, id) {
+      const [path = id] = id.split("?");
+      const normalizedPath = path.replaceAll("\\", "/");
+      if (!normalizedPath.endsWith("/@fontsource-variable/roboto/index.css")) {
+        return null;
+      }
+      const transformed = code.replace(/font-display:\s*swap/g, "font-display: optional");
+      return transformed === code ? null : { code: transformed, map: null };
+    }
+  };
+}
 function makeBookConfigVitePlugin(config) {
   const serialized = `export default ${JSON.stringify(config)};`;
   return {
@@ -1302,6 +1317,7 @@ function bookScaffoldIntegration(opts) {
         updateConfig({
           vite: {
             plugins: [
+              makeRobotoFontDisplayVitePlugin(),
               makeMdxComponentsVitePlugin(resolvedMdxPath),
               makeBookConfigVitePlugin({
                 title: title ?? null,

package/layouts/Base.astro

@@ -39,6 +39,7 @@
  * — or the page ends up with duplicate `<main>` landmarks (a11y, #91).
  */
 import '@fontsource-variable/roboto';
+import robotoLatinUrl from '@fontsource-variable/roboto/files/roboto-latin-wght-normal.woff2?url';
 import '@fontsource-variable/source-code-pro';
 // KaTeX CSS is injected by bookScaffoldIntegration for academic profile
 // only (since v3.0 alpha.8) — tools/minimal profiles don't install katex
@@ -128,6 +129,15 @@ const baseUrl = normalizeBase(import.meta.env.BASE_URL);
   <head>
     <meta charset="utf-8" />
     <link rel="icon" type="image/svg+xml" href={`${baseUrl}favicon.svg`} />
+    {/* #187: start the common Latin body face early. Its Fontsource rules use
+        font-display: optional, so a slow response never swaps after paint. */}
+    <link
+      rel="preload"
+      href={robotoLatinUrl}
+      as="font"
+      type="font/woff2"
+      crossorigin="anonymous"
+    />
     <meta name="viewport" content="width=device-width, initial-scale=1" />
     <meta name="color-scheme" content="light dark" />
     <meta name="generator" content={Astro.generator} />
@@ -244,8 +254,7 @@ const baseUrl = normalizeBase(import.meta.env.BASE_URL);
       CSS recolors via the `data-theme` attribute alone; canvas/JS islands can't,
       so they subscribe to this event (and read the attribute / matchMedia on
       mount for the initial value) to redraw. Contract documented in the package
-      CLAUDE.md. Event-only by design — a `useThemeColors` helper graduates later
-      with the demo kit.
+      CLAUDE.md; the opt-in demo entry now wraps it with `useThemeColors` (#143).
     */}
     <script is:inline>
       (function () {

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@brandon_m_behring/book-scaffold-astro",
   "description": "Astro 6 + MDX toolkit for long-form technical books with five typed presets, Tufte typography, citations, search, PDF, and Cloudflare deployment.",
-  "version": "4.27.0",
+  "version": "4.28.0",
   "type": "module",
   "license": "MIT",
   "author": "Brandon Behring",
@@ -40,6 +40,10 @@
       "types": "./dist/schemas.d.ts",
       "import": "./dist/schemas.mjs"
     },
+    "./demo": {
+      "types": "./dist/demo.d.ts",
+      "import": "./dist/demo.mjs"
+    },
     "./package.json": "./package.json",
     "./components/AICollaborationDisclosure.astro": "./components/AICollaborationDisclosure.astro",
     "./components/AssessmentTest.astro": "./components/AssessmentTest.astro",
@@ -138,6 +142,7 @@
     "./styles/exam-runner.css": "./styles/exam-runner.css",
     "./styles/flashcards.css": "./styles/flashcards.css",
     "./styles/section-map.css": "./styles/section-map.css",
+    "./styles/demo.css": "./styles/demo.css",
     "./layouts/Base.astro": "./layouts/Base.astro",
     "./layouts/Chapter.astro": "./layouts/Chapter.astro",
     "./lib": {

package/recipes/23-interactive-demo-substrate.md

@@ -0,0 +1,103 @@
+# Recipe 23 — Interactive demo substrate
+
+**Profile:** any
+
+## TL;DR
+
+Build the domain logic in your book, then compose the package's opt-in Preact
+primitives for the repeated shell and accessibility plumbing. Import the
+stylesheet explicitly and hydrate your own island; the scaffold never mounts a
+demo, chooses data, or ships statistical/visualization kernels for you.
+
+```astro
+---
+import SamplingDemo from '../components/SamplingDemo.tsx';
+import '@brandon_m_behring/book-scaffold-astro/styles/demo.css';
+---
+
+<SamplingDemo client:visible />
+```
+
+Inside the island:
+
+```tsx
+import { useState } from 'preact/hooks';
+import { DemoFrame, Slider, StatCards } from '@brandon_m_behring/book-scaffold-astro/demo';
+
+export default function SamplingDemo() {
+  const [size, setSize] = useState(20);
+
+  return (
+    <DemoFrame id="sampling-demo" title="Sampling distribution"
+      headingLevel={2}
+      description="Adjust sample size and compare uncertainty."
+      caption="Simulation and chart logic remain in this book.">
+      <Slider
+        label="Sample size"
+        value={size} min={10} max={100} step={10}
+        onValueChange={setSize}
+        formatValue={(value) => `n = ${value}`}
+        getValueText={(value) => `${value} observations`}
+      />
+      <StatCards items={[
+        { label: 'Sample size', value: size, tone: 'accent' },
+        { label: 'Standard error', value: (1 / Math.sqrt(size)).toFixed(3) },
+      ]} />
+    </DemoFrame>
+  );
+}
+```
+
+## Theme-aware visuals
+
+Inline SVG should normally stay in CSS. Give the SVG an accessible name and
+use the stylesheet's semantic attributes; they recolor without JavaScript:
+
+```tsx
+<div class="demo-frame__visual">
+  <svg data-demo-visual role="img" aria-labelledby="plot-title plot-desc" viewBox="0 0 320 120">
+    <title id="plot-title">Estimate by sample size</title>
+    <desc id="plot-desc">The estimate approaches the reference line.</desc>
+    <path data-demo-stroke="accent" fill="none" d="M0 90 L320 30" />
+    <circle data-demo-fill="warning" cx="80" cy="70" r="5" />
+  </svg>
+</div>
+```
+
+Canvas and JS-computed drawing attributes need concrete colors. Resolve an
+explicit token map with `useThemeColors`; it is SSR-safe, refreshes after
+`book:theme:change` and system color-scheme changes, and reports reduced motion:
+
+```tsx
+import { useThemeColors } from '@brandon_m_behring/book-scaffold-astro/demo';
+
+const TOKENS = { ink: ['--color-text', '#1a1a19'], accent: ['--color-link', '#3b6fa0'] } as const;
+
+const { colors, theme, reducedMotion } = useThemeColors(TOKENS);
+// Repaint from colors. Theme/motion are null during SSR; animate only when
+// reducedMotion === false.
+```
+
+## Contracts and gotchas
+
+- `DemoFrame` owns `<figure>`, heading, description, caption, and generated ID relationships. Set `headingLevel` to match the surrounding outline (h2-h6; default h3). Give the visualization itself `role="img"` and a useful `<title>`/`<desc>` or `aria-label`; the frame cannot describe chart content.
+- `Slider` is controlled. Update its `value` in `onValueChange`. Its label and
+  current value are always visible; use `getValueText` when visible shorthand
+  would be unclear when spoken. The value must align with `min + (n * step)`;
+  this prevents the browser from silently displaying a different range value.
+- `StatCards` renders a semantic definition list. It is not live by default so
+  dragging a slider does not create announcement spam. Use `live="polite"`
+  only for changes that occur independently of the user's control.
+- `demo.css` scopes its reduced-motion guard to `.demo-frame`; the hook exposes the same preference for canvas or requestAnimationFrame logic. Its value is `null` until the client preference resolves, so start animation only when it is explicitly `false`.
+- Props fail loudly for empty labels, invalid numeric ranges, non-finite values,
+  invalid tones, duplicate metric keys, and malformed token maps.
+
+Not included: OLS/residualization/sampling kernels, chart primitives, data loaders,
+tabs, predict/reveal policy, or domain logic. Keep those consumer-owned.
+
+## Canonical files
+
+- `components/demo/` — component and hook source
+- `styles/demo.css` — explicitly imported styling and SVG token helpers
+- `tests/demo-substrate.test.mjs` — semantics and fail-loud contracts
+- `gallery/src/pages/demo-substrate.astro` — interaction/theme fixture

package/recipes/README.md

@@ -27,6 +27,8 @@ Terse pointers into canonical code for the most common book-authoring workflows.
 | 19 | [Prevalidate hook](19-prevalidate-hook.md) | any | Wire `prevalidate` to run `build:bib` + `build:labels` before `validate` |
 | 20 | [Anki deck export (consumer-side)](20-anki-export.md) | any (esp. course-notes, research-portfolio) | Roll-your-own `<AnkiCard>` + extractor; scaffold deliberately doesn't ship this |
 | 21 | [Multiple guides in one app](21-multi-guide-single-app.md) | any | `generateId` namespacing over one collection; flat-slug footgun; interim until multibook (#80) |
+| 22 | [Responsive navigation and multi-book routing](22-responsive-nav-and-multibook-routing.md) | any | Mobile/desktop nav, base-aware route ownership, and the interim multi-book routing contract |
+| 23 | [Interactive demo substrate](23-interactive-demo-substrate.md) | any | Opt-in Preact shell, slider, stat cards, theme colors, a11y, and reduced motion |
 
 ## How to read recipes