@brandon_m_behring/book-scaffold-astro 4.20.0 → 4.22.0

package/components/Flashcards.tsx

@@ -0,0 +1,247 @@
+/**
+ * Flashcards — Preact island for the spaced-recall deck (#116).
+ *
+ * Same controller-over-server-rendered-cards architecture as ExamRunner: card
+ * backs are MDX glossary definitions (not serializable into island props), so
+ * flashcards.astro renders every card statically and this island receives only
+ * the deck manifest (id + front). Start shuffles (the exam-engine Fisher–Yates)
+ * and shows ONE card at a time — others get the `hidden` attribute, the
+ * wrapper gains data-flashcards-mode="deck", and CSS keyed on that attribute
+ * hides the back of the unflipped current card. Know/still-learning buckets
+ * persist to localStorage (ToolFilter pattern) so the "review unknown only"
+ * pass survives reloads. No JS → the full front+back list stays readable.
+ *
+ * DOM contract with flashcards.astro:
+ *   [data-flashcards-root]          wrapper; gains data-flashcards-mode="deck"
+ *   [data-card-id="<id>"]           one card per term; `hidden` toggled;
+ *                                   gains/loses class "flashcard-flipped"
+ *
+ * Fail-loud (house invariant): a missing wrapper or deck/DOM drift throws a
+ * named error — never silently dead buttons or a silently short deck.
+ *
+ * Hydrated with `client:idle`. Colors via CSS tokens only.
+ */
+import { useEffect, useRef, useState } from 'preact/hooks';
+import { shuffle } from '../src/lib/exam-engine';
+import type { FlashcardRef } from '../src/lib/flashcards';
+
+const STORAGE_KEY = 'book:flashcards:known';
+
+interface Props {
+  /** Deck manifest (buildFlashcardDeck output) — card ids + fronts only. */
+  deck: FlashcardRef[];
+}
+
+type Phase = 'idle' | 'deck';
+
+function readKnown(): Set<string> {
+  try {
+    const raw = localStorage.getItem(STORAGE_KEY);
+    if (!raw) return new Set();
+    const parsed = JSON.parse(raw);
+    if (!Array.isArray(parsed)) return new Set();
+    return new Set(parsed.filter((s): s is string => typeof s === 'string'));
+  } catch {
+    return new Set();
+  }
+}
+
+function writeKnown(known: Set<string>): void {
+  try {
+    localStorage.setItem(STORAGE_KEY, JSON.stringify([...known]));
+  } catch {
+    /* localStorage unavailable — keep in-memory state only */
+  }
+}
+
+export default function Flashcards({ deck }: Props) {
+  const [phase, setPhase] = useState<Phase>('idle');
+  const [order, setOrder] = useState<string[]>([]);
+  const [pos, setPos] = useState(0);
+  const [flipped, setFlipped] = useState(false);
+  const [known, setKnown] = useState<Set<string>>(new Set());
+  const [unknownOnly, setUnknownOnly] = useState(false);
+  const ref = useRef<HTMLDivElement>(null);
+
+  useEffect(() => {
+    // Intersect the stored bucket with the CURRENT deck: a term deleted from
+    // the glossary would otherwise inflate "marked known" forever (even past
+    // deck.length) — evict stale ids on mount and persist the cleaned set.
+    const stored = readKnown();
+    const deckIds = new Set(deck.map((c) => c.id));
+    const cleaned = new Set([...stored].filter((id) => deckIds.has(id)));
+    if (cleaned.size !== stored.size) writeKnown(cleaned);
+    setKnown(cleaned);
+  }, []);
+
+  function requireRoot(): HTMLElement {
+    const r = ref.current?.closest<HTMLElement>('[data-flashcards-root]');
+    if (!r) {
+      throw new Error(
+        'Flashcards: no [data-flashcards-root] ancestor — mount the island inside ' +
+          'the wrapper that contains its cards (see the DOM contract in Flashcards.tsx).',
+      );
+    }
+    return r;
+  }
+  function cardEl(r: HTMLElement, id: string): HTMLElement {
+    const el = r.querySelector<HTMLElement>(`[data-card-id="${CSS.escape(id)}"]`);
+    if (!el) {
+      throw new Error(`Flashcards: deck/DOM drift — no rendered card for term "${id}".`);
+    }
+    return el;
+  }
+  function allCards(r: HTMLElement): HTMLElement[] {
+    return Array.from(r.querySelectorAll<HTMLElement>('[data-card-id]'));
+  }
+
+  function showOnly(r: HTMLElement, id: string): void {
+    for (const card of allCards(r)) {
+      card.hidden = card.dataset.cardId !== id;
+      card.classList.remove('flashcard-flipped');
+    }
+    setFlipped(false);
+  }
+
+  function start(): void {
+    const r = requireRoot();
+    const pool = unknownOnly ? deck.filter((c) => !known.has(c.id)) : deck;
+    if (pool.length === 0) return; // the idle UI disables Start in this state
+    const shuffled = shuffle(pool.map((c) => c.id));
+    // Fail loud on drift before hiding anything (ExamRunner precedent).
+    for (const id of shuffled) cardEl(r, id);
+    r.setAttribute('data-flashcards-mode', 'deck');
+    showOnly(r, shuffled[0]!);
+    setOrder(shuffled);
+    setPos(0);
+    setPhase('deck');
+  }
+
+  function goTo(next: number): void {
+    const r = requireRoot();
+    const clamped = Math.max(0, Math.min(next, order.length - 1));
+    showOnly(r, order[clamped]!);
+    setPos(clamped);
+  }
+
+  function flip(): void {
+    const r = requireRoot();
+    const card = cardEl(r, order[pos]!);
+    const next = !flipped;
+    card.classList.toggle('flashcard-flipped', next);
+    setFlipped(next);
+  }
+
+  function mark(knewIt: boolean): void {
+    const id = order[pos]!;
+    const next = new Set(known);
+    if (knewIt) next.add(id);
+    else next.delete(id);
+    setKnown(next);
+    writeKnown(next);
+    if (pos < order.length - 1) goTo(pos + 1);
+    else end();
+  }
+
+  function end(): void {
+    const r = requireRoot();
+    for (const card of allCards(r)) {
+      card.hidden = false;
+      card.classList.remove('flashcard-flipped');
+    }
+    r.removeAttribute('data-flashcards-mode');
+    setPhase('idle');
+    setOrder([]);
+    setPos(0);
+    setFlipped(false);
+  }
+
+  function resetKnown(): void {
+    const next = new Set<string>();
+    setKnown(next);
+    writeKnown(next);
+  }
+
+  if (deck.length === 0) {
+    return <p class="flashcards-empty">No glossary terms to study yet.</p>;
+  }
+
+  const unknownCount = deck.filter((c) => !known.has(c.id)).length;
+  const poolSize = unknownOnly ? unknownCount : deck.length;
+
+  return (
+    <div class="flashcards-runner" ref={ref}>
+      {phase === 'idle' && (
+        <div class="flashcards-controls">
+          <p class="flashcards-intro">
+            Study the glossary as flashcards: shuffled, one term at a time — recall the
+            definition, flip to check, and sort each card into "knew it" / "still learning".
+          </p>
+          <p class="flashcards-stats" role="status">
+            {deck.length} card{deck.length === 1 ? '' : 's'} · {known.size} marked known
+            {known.size > 0 && (
+              <>
+                {' '}
+                (<button type="button" class="flashcards-link" onClick={resetKnown}>reset</button>)
+              </>
+            )}
+          </p>
+          <label class="flashcards-filter-label">
+            <input
+              type="checkbox"
+              checked={unknownOnly}
+              onInput={(e) => setUnknownOnly((e.target as HTMLInputElement).checked)}
+            />{' '}
+            only cards I don't know yet ({unknownCount})
+          </label>
+          <button
+            type="button"
+            class="flashcards-button flashcards-start"
+            onClick={start}
+            disabled={poolSize === 0}
+          >
+            {poolSize === 0 ? 'All cards marked known — reset to review' : `Start deck (${poolSize})`}
+          </button>
+        </div>
+      )}
+
+      {phase === 'deck' && (
+        <div class="flashcards-controls">
+          <p class="flashcards-progress" role="status">
+            Card {pos + 1} of {order.length} · {known.size} known
+          </p>
+          <div class="flashcards-buttons">
+            <button type="button" class="flashcards-button flashcards-flip" onClick={flip}>
+              {flipped ? 'Hide definition' : 'Flip'}
+            </button>
+            <button type="button" class="flashcards-button flashcards-knew" onClick={() => mark(true)}>
+              Knew it
+            </button>
+            <button type="button" class="flashcards-button flashcards-learning" onClick={() => mark(false)}>
+              Still learning
+            </button>
+            <button
+              type="button"
+              class="flashcards-button flashcards-prev"
+              onClick={() => goTo(pos - 1)}
+              disabled={pos === 0}
+            >
+              ← Prev
+            </button>
+            <button
+              type="button"
+              class="flashcards-button flashcards-next"
+              onClick={() => goTo(pos + 1)}
+              disabled={pos === order.length - 1}
+            >
+              Next →
+            </button>
+            <button type="button" class="flashcards-button flashcards-end" onClick={end}>
+              End — show all
+            </button>
+          </div>
+        </div>
+      )}
+    </div>
+  );
+}

package/components/QuestionCard.astro

@@ -0,0 +1,166 @@
+---
+/**
+ * QuestionCard — one server-rendered question card (v4.21.0, #112-UI/#113).
+ *
+ * The shared partial between /practice-exam and <AssessmentTest>: renders the
+ * MDX stem (passed as a rendered Content component — stems can't cross into
+ * island props), MCQ options as radio inputs the ExamRunner island reads on
+ * submit, and the answer behind the static <details> reveal (the no-JS
+ * fallback — radios still work as a manual self-check without the island).
+ *
+ * DOM contract with ExamRunner.tsx (see its module doc): data-question-id /
+ * data-exam-scoreable on the article; input[name="exam-<id>"] per option;
+ * details.question-reveal. The exam-phase CSS lives here (with :global() for
+ * the [data-exam-phase] ancestor the island sets on the wrapper section):
+ * answers hide during an active exam, cards get a result border on review.
+ */
+import type { Question } from '../src/schemas.js';
+
+interface Props {
+  /** The question's frontmatter (CollectionEntry data). */
+  data: Question;
+  /** The rendered MDX stem, or null for reserved (cloze) questions. */
+  Content: any | null;
+  /** True for cloze — schema-accepted, render-deferred. */
+  reserved: boolean;
+}
+const { data, Content, reserved } = Astro.props;
+
+const scoreable = data.type === 'mcq' && (data.options?.length ?? 0) > 0;
+const correct = data.type === 'mcq' && data.options
+  ? data.options.find((o) => o.correct)
+  : undefined;
+
+/** Filled/hollow diamonds for a 1–4 difficulty, mirroring Practice.astro. */
+function difficultyMarks(d: string | undefined): string {
+  if (!d) return '';
+  const n = Number.parseInt(d, 10);
+  return '◆'.repeat(n) + '◇'.repeat(4 - n);
+}
+---
+<article
+  class="question"
+  id={`question-${data.id}`}
+  data-question-id={data.id}
+  data-question-domain={data.domain}
+  data-exam-scoreable={scoreable ? 'true' : 'false'}
+>
+  <header class="question-header">
+    <span class="question-meta-id">{data.id}</span>
+    <span class="question-meta-type">{data.type}</span>
+    {data.bloom_level && <span class="question-meta-bloom">{data.bloom_level}</span>}
+    {data.difficulty && (
+      <span class="question-meta-difficulty" aria-label={`Difficulty ${data.difficulty} of 4`}>
+        {difficultyMarks(data.difficulty)}
+      </span>
+    )}
+  </header>
+
+  {reserved ? (
+    <p class="question-reserved">
+      Cloze question — interactive rendering deferred to a later release.
+    </p>
+  ) : (
+    Content && (
+      <div class="question-stem"><Content /></div>
+    )
+  )}
+
+  {data.type === 'mcq' && data.options && (
+    <fieldset class="question-options">
+      <legend class="question-options-legend">Options</legend>
+      {data.options.map((o) => (
+        <label class="question-option">
+          <input type="radio" name={`exam-${data.id}`} value={o.id} />
+          <span class="question-option-key">{o.id}.</span>
+          <span class="question-option-text">{o.text ?? o.id}</span>
+        </label>
+      ))}
+    </fieldset>
+  )}
+
+  {!reserved && (
+    <details class="question-reveal">
+      <summary>Show answer</summary>
+      {data.type === 'mcq' && correct && (
+        <p class="question-answer-line">
+          Correct: <strong>{correct.text ?? correct.id}</strong>
+        </p>
+      )}
+      {data.type === 'free' && data.answer && (
+        <p class="question-answer-line">{data.answer}</p>
+      )}
+    </details>
+  )}
+</article>
+
+<style>
+  .question {
+    margin-block: 1.25rem;
+    padding: 1rem 1.1rem;
+    border: 1px solid var(--color-border, #e5e7eb);
+    border-radius: 0.5rem;
+    background: var(--color-surface, transparent);
+  }
+  .question-header {
+    display: flex;
+    flex-wrap: wrap;
+    gap: 0.5rem;
+    align-items: center;
+    font-size: 0.78rem;
+    color: var(--color-text-muted, #6b7280);
+    margin-block-end: 0.5rem;
+  }
+  .question-meta-id { font-family: var(--font-mono, ui-monospace, monospace); }
+  .question-meta-type,
+  .question-meta-bloom {
+    text-transform: uppercase;
+    letter-spacing: 0.04em;
+    padding: 0.05rem 0.4rem;
+    border-radius: 0.25rem;
+    background: var(--color-code-bg, rgba(127, 127, 127, 0.12));
+  }
+  .question-meta-difficulty { margin-inline-start: auto; letter-spacing: 0.1em; }
+  .question-options {
+    margin-block: 0.6rem;
+    border: none;
+    padding: 0;
+  }
+  .question-options-legend {
+    position: absolute;
+    width: 1px;
+    height: 1px;
+    overflow: hidden;
+    clip-path: inset(50%);
+  }
+  .question-option {
+    display: flex;
+    gap: 0.5rem;
+    align-items: baseline;
+    margin-block: 0.25rem;
+    cursor: pointer;
+  }
+  .question-option-key { color: var(--color-text-muted, #6b7280); }
+  .question-reveal { margin-block-start: 0.6rem; }
+  .question-reveal > summary {
+    cursor: pointer;
+    font-weight: 600;
+    color: var(--color-accent, #4f46e5);
+  }
+  .question-answer-line { margin-block: 0.5rem 0.25rem; }
+  .question-reserved { color: var(--color-text-muted, #6b7280); font-style: italic; }
+
+  /* Exam phases (ExamRunner island sets data-exam-phase on the wrapper
+     section): no peeking at answers during an active exam; result borders +
+     re-opened reveals on review. :global() crosses the wrapper's scope — the
+     element side stays scoped to this card. */
+  :global([data-exam-phase='active']) .question-reveal { display: none; }
+  .question[data-exam-result='correct'] {
+    border-color: var(--color-success, #15803d);
+    box-shadow: inset 3px 0 0 var(--color-success, #15803d);
+  }
+  .question[data-exam-result='incorrect'] {
+    border-color: var(--color-danger, #b91c1c);
+    box-shadow: inset 3px 0 0 var(--color-danger, #b91c1c);
+  }
+</style>

package/components/Rationale.astro

@@ -1,28 +1,71 @@
 ---
 /**
  * <Rationale> — collapsible answer/explanation for a study-guide question
- * (v4.17.0, Tier 3). Renders its slot inside a <details> so the answer stays
- * hidden until the reader chooses to reveal it (Bjork desirable-difficulties:
- * delayed feedback aids retention). Authored in a question's MDX body; the
- * answer-rationale back-appendix (#114) will later hoist these into an appendix
- * using this same marker — so a rich, cited rationale has a stable home now.
+ * (v4.17.0, Tier 3; appendix mode v4.21.0, #114). Renders its slot inside a
+ * <details> so the answer stays hidden until the reader chooses to reveal it
+ * (Bjork desirable-difficulties: delayed feedback aids retention).
+ *
+ * Appendix mode (#114): `<Rationale appendix for="<question-id>">` keeps the
+ * chapter/bank body clean Sybex-style — everywhere EXCEPT the /answers route
+ * it renders a link to /answers#answer-<id> instead of the details; on
+ * /answers itself (where the full question body is re-rendered) it renders the
+ * details as normal so the appendix carries the content. Fail-loud, both
+ * misuse modes throw at build: `appendix` without `for=` (no anchor target),
+ * and `appendix` with the answers route disabled (the link would 404).
  *
  * Any profile. Register it in src/mdx-components.ts (defineMdxComponents) to use
  * inside src/content/questions/**.mdx. Slot freely: prose, math, <Cite>, code.
  */
+import bookConfig from 'virtual:book-scaffold/book-config';
+
 interface Props {
   /** Summary label for the reveal. Defaults to "Answer & rationale". */
   title?: string;
+  /** Render as a link into the /answers appendix instead of inline details
+   *  (except on /answers itself). Requires `for` + routes.answers enabled. */
+  appendix?: boolean;
+  /** The question's frontmatter `id` — the /answers#answer-<id> anchor target.
+   *  Required with `appendix`. */
+  for?: string;
+}
+const { title = 'Answer & rationale', appendix = false, for: forId } = Astro.props;
+
+if (appendix && !forId) {
+  throw new Error(
+    `<Rationale appendix> requires for="<question-id>" — it is the ` +
+      `/answers#answer-<id> anchor target.`,
+  );
+}
+if (appendix && !(bookConfig.enabledRoutes ?? []).includes('answers')) {
+  throw new Error(
+    `<Rationale appendix for="${forId}"> — the answers route is not enabled, so ` +
+      `the appendix link would 404. Set routes: { answers: true } in ` +
+      `defineBookConfig (or drop the appendix prop for an inline reveal).`,
+  );
 }
-const { title = 'Answer & rationale' } = Astro.props;
+
+// Exact match against the configured base — on the appendix route itself the
+// full rationale must render (the appendix re-renders question bodies via
+// render()). BASE_URL-prefixed + trailing-slash tolerant; an endsWith()
+// heuristic would also fire on e.g. a chapter whose slug is "answers".
+const basePath = (import.meta.env.BASE_URL ?? '/').replace(/\/+$/, '');
+const onAnswersRoute = Astro.url.pathname.replace(/\/+$/, '') === `${basePath}/answers`;
+const asLink = appendix && !onAnswersRoute;
 ---
-<details class="question-rationale">
-  <summary>{title}</summary>
-  <div class="question-rationale-body"><slot /></div>
-</details>
+{asLink ? (
+  <p class="question-rationale-ref">
+    <a href={`/answers#answer-${forId}`}>{title} →</a>
+  </p>
+) : (
+  <details class="question-rationale">
+    <summary>{title}</summary>
+    <div class="question-rationale-body"><slot /></div>
+  </details>
+)}
 
 <style>
-  .question-rationale {
+  .question-rationale,
+  .question-rationale-ref {
     margin-block: 0.75rem;
     border-inline-start: 3px solid var(--color-accent, #4f46e5);
     padding-inline-start: 0.75rem;
@@ -32,6 +75,10 @@ const { title = 'Answer & rationale' } = Astro.props;
     font-weight: 600;
     color: var(--color-accent, #4f46e5);
   }
+  .question-rationale-ref > a {
+    font-weight: 600;
+    color: var(--color-accent, #4f46e5);
+  }
   .question-rationale-body {
     margin-block-start: 0.5rem;
   }

package/dist/components/ExamRunner.d.ts

@@ -0,0 +1,24 @@
+import * as preact from 'preact';
+import { a as ExamQuestion, R as RoutingChapter } from '../exam-manifest-DbTHo90M.js';
+import '../schemas-DDWDRUxs.js';
+import 'astro/zod';
+
+interface Props {
+    /** Scoreable MCQ pool (buildExamManifest output) — ids/domains/options only. */
+    manifest: ExamQuestion[];
+    /** practice: domain-agnostic sampling, weak domains anchor to #domain-<d> on
+     *  the same page. assessment: cross-domain spread blueprint, weak domains
+     *  route to chapters via `domainRouting`. */
+    mode: 'practice' | 'assessment';
+    /** Default form size (clamped to the pool; reader can adjust before start). */
+    count?: number;
+    /** Weak-domain threshold passed to scoreExam (default 0.7). */
+    passMark?: number;
+    /** Assessment mode: domain → chapters carrying its questions (deriveDomainRouting). */
+    domainRouting?: Record<string, RoutingChapter[]>;
+    /** Assessment mode: href of the practice bank when that route is enabled, else null. */
+    practiceExamHref?: string | null;
+}
+declare function ExamRunner({ manifest, mode, count, passMark, domainRouting, practiceExamHref, }: Props): preact.JSX.Element;
+
+export { ExamRunner as default };