@brandon_m_behring/book-scaffold-astro 4.0.0 → 4.1.0

package/CLAUDE.md

@@ -66,7 +66,9 @@ Two callout families coexist. Authors import what they need.
 
 **Academic family** (`src/components/callouts/`, 10 components): `NoteBox`, `ExampleBox`, `DynConnect`, `InsightBox`, `WarnBox`, `CounterBox`, `TipBox`, `OpenQuestion`, `PaperBox`, `ResultBox`. Plus `Theorem` (unified for theorem/proposition/lemma/corollary/definition/example/exercise/remark/proof).
 
-**Utility components** (`src/components/`, any profile): `Cite`, `XRef`, `Figure`, `MarginNote`, `Sidenote`, `WeekRef`, `CodeRef`, `CodeBlock`, `Tag`, `StatusBadge`.
+**Pedagogy family** (v4.1.0+, any profile, 3 components): `Pitfall` (rose; "common mistake" — distinct from `WarnBox`'s preemptive warning), `WorkedExample` (plum; collapsible `<details>` block with `#worked-example-{id}` anchor for deep links), `YouWillLearn` (gold; chapter-opener with optional `prerequisites` prop). Slot bullets/code freely; render at any preset.
+
+**Utility components** (`src/components/`, any profile): `Cite`, `XRef`, `Figure`, `MarginNote`, `Sidenote`, `WeekRef`, `CodeRef`, `CodeBlock`, `Tag`, `StatusBadge`, `PocLayout` (v4.1.0+; wraps slot in a per-`kind` layout shell — 5 closed-union kinds; see `recipes/15-defining-styles.md`).
 
 Full reference in `recipes/04-component-library.md`.
 

package/components/Pitfall.astro

@@ -0,0 +1,17 @@
+---
+/**
+ * Pitfall — distinct from generic <WarnBox>.
+ * Retrospective "this often goes wrong" callout (vs WarnBox's preemptive
+ * "this could go wrong"). React.dev "Pitfall" vocabulary. Closes #58.
+ *
+ * Family: crimson (--callout-pitfall, deeper than warn-rose).
+ */
+interface Props {
+  title?: string;
+}
+const { title = 'Common mistake' } = Astro.props;
+---
+<aside class="callout callout-pitfall" role="note">
+  <strong class="callout-title">{title}</strong>
+  <div class="callout-body"><slot /></div>
+</aside>

package/components/PocLayout.astro

@@ -0,0 +1,28 @@
+---
+/**
+ * PocLayout — per-PoC-kind layout selector (closes #56).
+ *
+ * Wraps slotted content in a <div> that swaps 3 CSS variables per kind
+ * (line-length, vertical rhythm, heading emphasis). 5 closed-union kinds.
+ *
+ * CSS variable surface defined in package/styles/poc-layouts.css. Authors
+ * can override per-kind in their own stylesheets via `:where(.poc-layout-X)`.
+ *
+ * Closed `kind` union: discriminated literal type. To add a 6th kind in
+ * a future release, expand the union + add a CSS block in poc-layouts.css.
+ */
+export type PocLayoutKind =
+  | 'tutorial'
+  | 'how-to'
+  | 'tldr'
+  | 'part-summary'
+  | 'cheat-sheet';
+
+interface Props {
+  kind: PocLayoutKind;
+}
+const { kind } = Astro.props;
+---
+<div class={`poc-layout poc-layout-${kind}`}>
+  <slot />
+</div>

package/components/WorkedExample.astro

@@ -0,0 +1,29 @@
+---
+/**
+ * WorkedExample — collapsible demonstration block (closes #57).
+ *
+ * Pedagogical worked-example-effect treatment (Sweller/Cooper). Uses
+ * native <details>; collapsed by default unless `expanded` prop set.
+ * The outer aside carries `id="worked-example-{id}"` for deep links
+ * from TL;DRs or cheat-sheets. Prefix avoids collision with author
+ * heading anchors.
+ *
+ * Family: plum (--callout-worked, reuses --callout-official authority hue).
+ */
+interface Props {
+  id: string;
+  title: string;
+  expanded?: boolean;
+}
+const { id, title, expanded = false } = Astro.props;
+const anchorId = `worked-example-${id}`;
+---
+<aside class="callout callout-worked" id={anchorId} role="note">
+  <details open={expanded}>
+    <summary>
+      <strong class="callout-title">{title}</strong>
+      <span class="callout-chip">Worked example</span>
+    </summary>
+    <div class="callout-body"><slot /></div>
+  </details>
+</aside>

package/components/YouWillLearn.astro

@@ -0,0 +1,24 @@
+---
+/**
+ * YouWillLearn — chapter-opener "what this chapter delivers" callout
+ * (closes #59). React.dev pedagogy vocabulary; Bloom's-taxonomy framing.
+ *
+ * Slotted body — author writes markdown bullets directly.
+ * Optional `prerequisites` prop renders a small "Before you start" sub-block.
+ *
+ * Family: gold (--callout-learn, reuses --callout-insight to signal importance).
+ */
+interface Props {
+  prerequisites?: string;
+}
+const { prerequisites } = Astro.props;
+---
+<aside class="callout callout-learn" role="note">
+  {prerequisites && (
+    <div class="callout-prereq">
+      <strong class="callout-prereq-label">Before you start:</strong> {prerequisites}
+    </div>
+  )}
+  <strong class="callout-title">You will learn</strong>
+  <div class="callout-body"><slot /></div>
+</aside>

package/dist/schemas.mjs

@@ -1,5 +1,5 @@
 // src/schemas-entry.ts
-import { existsSync as existsSync2 } from "fs";
+import { existsSync as existsSync2, readFileSync as readFileSync2 } from "fs";
 import { defineCollection } from "astro:content";
 import { glob, file } from "astro/loaders";
 
@@ -565,6 +565,15 @@ function resolvePreset(explicitPreset, explicitProfile) {
 }
 
 // src/schemas-entry.ts
+function isYamlEmpty(path) {
+  try {
+    const raw = readFileSync2(path, "utf8");
+    const stripped = raw.split(/\r?\n/).map((line) => line.replace(/#.*$/, "").trim()).filter((line) => line.length > 0).join("");
+    return stripped === "" || stripped === "[]";
+  } catch {
+    return false;
+  }
+}
 function frontmatterCollection(schema, base = "./src/content/frontmatter") {
   return defineCollection({
     loader: glob({
@@ -589,7 +598,7 @@ function defineBookSchemas(opts = {}) {
   const collections = {
     chapters
   };
-  if (existsSync2("./sources/manifest.yaml")) {
+  if (existsSync2("./sources/manifest.yaml") && !isYamlEmpty("./sources/manifest.yaml")) {
     collections.sources = defineCollection({
       loader: file("sources/manifest.yaml"),
       schema: sourcesSchema

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@brandon_m_behring/book-scaffold-astro",
   "description": "Astro 6 + MDX toolkit for long-form technical books. Profile-aware (academic / tools / minimal); ships Tufte typography, KaTeX, BibTeX citations, Pagefind, Cloudflare Workers deploy. See PACKAGE_DESIGN.md for the API contract.",
-  "version": "4.0.0",
+  "version": "4.1.0",
   "type": "module",
   "license": "MIT",
   "author": "Brandon Behring",
@@ -65,6 +65,8 @@
     "./components/OpenQuestion.astro": "./components/OpenQuestion.astro",
     "./components/PaperBox.astro": "./components/PaperBox.astro",
     "./components/PatternTimeline.astro": "./components/PatternTimeline.astro",
+    "./components/Pitfall.astro": "./components/Pitfall.astro",
+    "./components/PocLayout.astro": "./components/PocLayout.astro",
     "./components/PolicyRef.astro": "./components/PolicyRef.astro",
     "./components/PreReleaseBanner.astro": "./components/PreReleaseBanner.astro",
     "./components/Recovery.astro": "./components/Recovery.astro",
@@ -88,7 +90,9 @@
     },
     "./components/WarnBox.astro": "./components/WarnBox.astro",
     "./components/WeekRef.astro": "./components/WeekRef.astro",
+    "./components/WorkedExample.astro": "./components/WorkedExample.astro",
     "./components/XRef.astro": "./components/XRef.astro",
+    "./components/YouWillLearn.astro": "./components/YouWillLearn.astro",
     "./styles/tokens.css": "./styles/tokens.css",
     "./styles/layout.css": "./styles/layout.css",
     "./styles/callouts.css": "./styles/callouts.css",
@@ -96,6 +100,7 @@
     "./styles/typography.css": "./styles/typography.css",
     "./styles/print.css": "./styles/print.css",
     "./styles/convergence.css": "./styles/convergence.css",
+    "./styles/poc-layouts.css": "./styles/poc-layouts.css",
     "./styles/tool-filter.css": "./styles/tool-filter.css",
     "./layouts/Base.astro": "./layouts/Base.astro",
     "./layouts/Chapter.astro": "./layouts/Chapter.astro",

package/styles/callouts.css

@@ -162,6 +162,54 @@
   background: var(--color-bg-subtle);
 }
 
+/* Crimson — Pitfall (v4.1.0, #58). Distinct from warn-rose: deeper, more
+ * saturated. Used for "common mistake" / retrospective error patterns. */
+.callout-pitfall {
+  border-left-color: var(--callout-pitfall);
+  background: var(--warm-crimson-tint);
+}
+
+/* Plum-dashed — WorkedExample (v4.1.0, #57). Reuses callout-official
+ * (plum) bar; <details>/<summary> chrome is plain — no extra structure. */
+.callout-worked {
+  border-left-color: var(--callout-worked);
+  background: var(--warm-plum-tint);
+}
+.callout-worked summary {
+  cursor: pointer;
+  list-style: none;
+  display: flex;
+  align-items: baseline;
+  gap: var(--space-3);
+}
+.callout-worked summary::-webkit-details-marker {
+  display: none;
+}
+.callout-worked .callout-chip {
+  font-size: var(--text-xs);
+  text-transform: uppercase;
+  letter-spacing: 0.05em;
+  padding: 0 var(--space-2);
+  border: 1px solid var(--callout-worked);
+  border-radius: var(--radius-sm);
+  color: var(--callout-worked);
+}
+
+/* Gold — YouWillLearn (v4.1.0, #59). Reuses callout-insight (gold) hue;
+ * "Before you start" prereq sub-block sits above the title in muted style. */
+.callout-learn {
+  border-left-color: var(--callout-learn);
+  background: var(--warm-gold-tint);
+}
+.callout-learn .callout-prereq {
+  font-size: var(--text-sm);
+  color: var(--color-text-muted);
+  margin-bottom: var(--space-2);
+}
+.callout-learn .callout-prereq-label {
+  color: var(--color-text);
+}
+
 /* ===== Theorem family (Theorem.astro) =====
  * Plain (theorem/proposition/lemma/corollary): italic body
  * Definition family (definition/example/exercise/remark/proof): upright body

package/styles/poc-layouts.css

@@ -0,0 +1,57 @@
+/* poc-layouts.css — per-PoC-kind layout variables (v4.1.0, closes #56).
+ *
+ * Each kind swaps 3 CSS variables that downstream stylesheets (chapter.css,
+ * layout.css) can read. Consumers can override per-kind in their own
+ * stylesheets via `:where(.poc-layout-X) { --bs-content-line-length: ... }`.
+ *
+ * Variable surface (intentionally narrow):
+ *   --bs-content-line-length       — main column max line length (ch)
+ *   --bs-content-vertical-rhythm   — body line-height multiplier
+ *   --bs-heading-emphasis          — heading font-weight (400-900)
+ */
+
+:where(.poc-layout-tutorial) {
+  --bs-content-line-length: 70ch;
+  --bs-content-vertical-rhythm: 1.6;
+  --bs-heading-emphasis: 600;
+}
+
+:where(.poc-layout-how-to) {
+  --bs-content-line-length: 68ch;
+  --bs-content-vertical-rhythm: 1.5;
+  --bs-heading-emphasis: 700;
+}
+
+:where(.poc-layout-tldr) {
+  --bs-content-line-length: 65ch;
+  --bs-content-vertical-rhythm: 1.4;
+  --bs-heading-emphasis: 500;
+}
+
+:where(.poc-layout-part-summary) {
+  --bs-content-line-length: 90ch;
+  --bs-content-vertical-rhythm: 1.5;
+  --bs-heading-emphasis: 600;
+}
+
+:where(.poc-layout-cheat-sheet) {
+  --bs-content-line-length: 55ch;
+  --bs-content-vertical-rhythm: 1.3;
+  --bs-heading-emphasis: 600;
+}
+
+/* All kinds: apply the variables to the wrapper itself.
+ * Authors can read these vars from descendants for tighter control. */
+.poc-layout {
+  max-width: var(--bs-content-line-length, 70ch);
+  line-height: var(--bs-content-vertical-rhythm, 1.6);
+}
+
+.poc-layout :is(h1, h2, h3, h4, h5, h6) {
+  font-weight: var(--bs-heading-emphasis, 600);
+}
+
+/* Cheat-sheet: tables should fill the available width since the column is narrower. */
+.poc-layout-cheat-sheet table {
+  width: 100%;
+}

package/styles/tokens.css

@@ -14,6 +14,7 @@
   --warm-green:  #4A7E3F;  /* positive: tips, practitioner */
   --warm-plum:   #8A4E82;  /* authority: official, exercises */
   --warm-gold:   #C09840;  /* insight: convergence, reasoning */
+  --warm-crimson:#A03838;  /* pitfall: deeper red distinct from warm-rose */
 
   /* Warm neutrals (Anthropic-derived) */
   --paper:       #FDFCF9;  /* page background — slightly off-white */
@@ -27,6 +28,7 @@
   --warm-green-tint: color-mix(in srgb, var(--warm-green) 6%, var(--paper));
   --warm-plum-tint:  color-mix(in srgb, var(--warm-plum)  6%, var(--paper));
   --warm-gold-tint:  color-mix(in srgb, var(--warm-gold)  6%, var(--paper));
+  --warm-crimson-tint:color-mix(in srgb, var(--warm-crimson) 6%, var(--paper));
 
   /* ===== Layer 2: Semantic roles (light mode) ===== */
   --color-bg:         var(--paper);
@@ -45,6 +47,9 @@
   --callout-tip:      var(--warm-green);
   --callout-official: var(--warm-plum);
   --callout-insight:  var(--warm-gold);
+  --callout-pitfall:  var(--warm-crimson);
+  --callout-worked:   var(--warm-plum);
+  --callout-learn:    var(--warm-gold);
 
   /* ===== Typography scale ===== */
   --font-body: 'Roboto Variable', -apple-system, BlinkMacSystemFont, 'Segoe UI', sans-serif;