@panaversity/ksor 0.0.29 → 0.0.30

package/templates/scaffold/system/site/components/quiz.tsx

@@ -0,0 +1,321 @@
+"use client";
+
+import { Check, RotateCcw, X } from "lucide-react";
+import { useCallback, useEffect, useMemo, useState, type ReactElement } from "react";
+
+import { StudyAidHeader } from "@/components/study-aids";
+import { Button } from "@/components/ui/button";
+import { Card, CardContent } from "@/components/ui/card";
+import { Progress } from "@/components/ui/progress";
+import type { QuizEntry, QuizQuestion } from "@/lib/attachments";
+import { hasMoreRounds, roundOf } from "@/lib/quiz-round";
+
+/**
+ * Taking a quiz on the document you just read.
+ *
+ * The interaction model is the predecessor's and is the good part of it:
+ * answer, see IMMEDIATELY whether you were right, and read the explanation
+ * before moving on. Its own usage guide is explicit that this teaches through
+ * the mistake, which has more effect than a score revealed at the end — so the
+ * explanation is the point of the component and the score is a footnote.
+ *
+ * What is deliberately absent is everything the predecessor's `GatedQuiz`
+ * wrapper added: a sign-in gate, an XP modal, and a POST of the score to a
+ * progress API. The site is a static export with no backend, and decision 7
+ * fixes it as preview and review rather than an editor. A score here is the
+ * reader's, stays in their browser, and is sent nowhere.
+ */
+
+const STORAGE_VERSION = 1;
+
+interface Persisted {
+  readonly version: number;
+  /** questionHash -> the option index this reader chose. */
+  readonly answers: Record<string, number>;
+}
+
+function storageKey(quizPath: string): string {
+  return `ksor:quiz:${quizPath}`;
+}
+
+function readPersisted(quizPath: string): Record<string, number> {
+  try {
+    const raw = window.localStorage.getItem(storageKey(quizPath));
+    if (raw === null) return {};
+    const record = JSON.parse(raw) as Persisted;
+    // A version bump discards rather than migrates: the only thing lost is
+    // which options a reader clicked, and guessing at an old shape is how a
+    // reader ends up with someone else's answers against their questions.
+    if (record.version !== STORAGE_VERSION) return {};
+    return record.answers ?? {};
+  } catch {
+    // A private window, cleared site data, or storage disabled entirely. An
+    // unanswered quiz is a correct starting state, so this is not an error.
+    return {};
+  }
+}
+
+function writePersisted(quizPath: string, answers: Record<string, number>): void {
+  try {
+    window.localStorage.setItem(
+      storageKey(quizPath),
+      JSON.stringify({ version: STORAGE_VERSION, answers } satisfies Persisted),
+    );
+  } catch {
+    // Storage is a convenience here, never the record. Losing it costs the
+    // reader their place and nothing else.
+  }
+}
+
+/** The letter an author and a reader both use for an option index. */
+function letterOf(index: number): string {
+  return String.fromCharCode(65 + index);
+}
+
+export function Quiz({ quiz }: { quiz: QuizEntry }): ReactElement {
+  const size = quiz.questionsPerRound;
+  const banked = quiz.questions.length;
+  const canRedraw = hasMoreRounds(banked, size);
+
+  // Round zero is the authored order, chosen on the server AND the client so
+  // the first paint matches: `roundOf` returns the bank untouched when it fits
+  // in one round, and for a larger bank the shuffle happens only after mount
+  // (see the effect below). Sampling during render would differ between the
+  // server HTML and the first client render and would hydrate mismatched.
+  const [round, setRound] = useState<readonly QuizQuestion[]>(() =>
+    roundOf(quiz.questions, size, () => 0),
+  );
+  const [answers, setAnswers] = useState<Record<string, number>>({});
+  const [hydrated, setHydrated] = useState(false);
+  const [index, setIndex] = useState(0);
+  const [done, setDone] = useState(false);
+
+  useEffect(() => {
+    setAnswers(readPersisted(quiz.path));
+    if (canRedraw) setRound(roundOf(quiz.questions, size, Math.random));
+    setHydrated(true);
+  }, [quiz.path, quiz.questions, size, canRedraw]);
+
+  const current = round[index];
+  const chosen = current === undefined ? undefined : answers[current.hash];
+  const answered = chosen !== undefined;
+
+  const answeredCount = useMemo(
+    () => round.filter((q) => answers[q.hash] !== undefined).length,
+    [round, answers],
+  );
+  const correctCount = useMemo(
+    () => round.filter((q) => answers[q.hash] === q.answer).length,
+    [round, answers],
+  );
+
+  const choose = useCallback(
+    (option: number) => {
+      if (current === undefined || answers[current.hash] !== undefined) return;
+      const next = { ...answers, [current.hash]: option };
+      setAnswers(next);
+      writePersisted(quiz.path, next);
+    },
+    [answers, current, quiz.path],
+  );
+
+  const newRound = useCallback(() => {
+    setRound(roundOf(quiz.questions, size, Math.random));
+    setAnswers({});
+    writePersisted(quiz.path, {});
+    setIndex(0);
+    setDone(false);
+  }, [quiz.questions, size, quiz.path]);
+
+  const retry = useCallback(() => {
+    setAnswers({});
+    writePersisted(quiz.path, {});
+    setIndex(0);
+    setDone(false);
+  }, [quiz.path]);
+
+  if (current === undefined) return <></>;
+
+  if (done) {
+    return (
+      <section aria-label="Quiz results">
+        <StudyAidHeader title={quiz.title} description={quiz.description} />
+        <Card className="mx-auto max-w-2xl">
+          <CardContent className="flex flex-col items-center gap-6 py-12 text-center">
+            <p className="font-(family-name:--font-display) text-5xl font-semibold tabular-nums text-fd-foreground">
+              {correctCount}
+              <span className="text-fd-muted-foreground">/{round.length}</span>
+            </p>
+            <p className="max-w-sm text-sm text-fd-muted-foreground">
+              {/* No pass mark, deliberately: this checks understanding of a
+                  document, it does not certify anybody. */}
+              Answers are kept in this browser only.
+            </p>
+            <div className="flex flex-wrap justify-center gap-3">
+              <Button variant="outline" onClick={() => setIndex(0)}>
+                Review answers
+              </Button>
+              {canRedraw ? (
+                <Button onClick={newRound}>
+                  <RotateCcw aria-hidden className="size-4" />
+                  Another round
+                </Button>
+              ) : (
+                <Button onClick={retry}>
+                  <RotateCcw aria-hidden className="size-4" />
+                  Start again
+                </Button>
+              )}
+            </div>
+          </CardContent>
+        </Card>
+      </section>
+    );
+  }
+
+  return (
+    <section aria-label="Quiz">
+      <StudyAidHeader title={quiz.title} description={quiz.description} />
+
+      <div className="mx-auto max-w-2xl">
+        <div className="mb-4 flex items-baseline justify-between gap-4">
+          <p className="font-mono text-xs tracking-wide text-fd-muted-foreground uppercase">
+            Question {index + 1} / {round.length}
+            {canRedraw ? <span> · drawn from {banked}</span> : null}
+          </p>
+          <p className="font-mono text-xs tabular-nums text-fd-muted-foreground">
+            {answeredCount} answered
+          </p>
+        </div>
+        <Progress value={(answeredCount / round.length) * 100} className="mb-8 h-1" />
+
+        <Card>
+          <CardContent className="flex flex-col gap-6 py-8">
+            <h3 className="text-lg leading-snug font-medium text-balance text-fd-foreground">
+              {current.question}
+            </h3>
+
+            <ul className="flex flex-col gap-2">
+              {current.options.map((option, i) => {
+                const isAnswer = i === current.answer;
+                const isChoice = i === chosen;
+                // Three things have to be legible at once after a wrong
+                // answer, and they are three different facts: which option is
+                // RIGHT (green), which one is WRONG (red), and which one YOU
+                // picked (the accent ring). The accent alone cannot carry two
+                // of those, which is what it was doing — the correct option
+                // wore the same colour as a selection, so choosing wrongly
+                // looked like the page had answered for you.
+                //
+                // Colour is never the only channel: the check and cross icons
+                // and the verdict line below say the same thing in shape and
+                // in words.
+                //
+                // Plain CSS classes, not Tailwind arbitrary values: a
+                // `border-[color:var(--x)]` utility did not paint in a real
+                // build even with the rule in the stylesheet and the token
+                // resolving on the element. `app/global.css` is where this
+                // record's semantic colour already lives.
+                const tone = !answered
+                  ? "border-fd-border hover:border-fd-primary/60 hover:bg-fd-accent"
+                  : isAnswer
+                    ? "ksor-answer-correct"
+                    : isChoice
+                      ? "ksor-answer-wrong"
+                      : "border-fd-border opacity-60";
+                // Your own pick keeps the accent, whether it was right or
+                // wrong, so "what I chose" is never in doubt.
+                const mine = answered && isChoice ? " ksor-answer-mine" : "";
+                return (
+                  <li key={option}>
+                    <button
+                      type="button"
+                      disabled={answered}
+                      onClick={() => choose(i)}
+                      aria-pressed={isChoice}
+                      className={`flex w-full items-start gap-3 rounded-lg border px-4 py-3 text-left text-sm transition-colors motion-safe:duration-150 ${tone}${mine} ${answered ? "cursor-default" : "cursor-pointer"}`}
+                    >
+                      <span className="mt-px font-mono text-xs text-fd-muted-foreground">
+                        {letterOf(i)}
+                      </span>
+                      <span className="flex-1 text-fd-foreground">{option}</span>
+                      {answered && isAnswer ? (
+                        <Check
+                          aria-label="correct answer"
+                          className="ksor-answer-correct-text size-4 shrink-0"
+                        />
+                      ) : null}
+                      {answered && isChoice && !isAnswer ? (
+                        <X
+                          aria-label="your answer, which is wrong"
+                          className="ksor-answer-wrong-text size-4 shrink-0"
+                        />
+                      ) : null}
+                    </button>
+                  </li>
+                );
+              })}
+            </ul>
+
+            {answered ? (
+              <div
+                // Announced, because the whole value of the immediate-feedback
+                // model is this text, and a reader using a screen reader gets
+                // it only if the region says it changed.
+                role="status"
+                className="motion-safe:animate-in motion-safe:fade-in flex flex-col gap-3 border-t border-fd-border pt-5 text-sm"
+              >
+                <p className="font-mono text-xs tracking-wide uppercase">
+                  {chosen === current.answer ? (
+                    <span className="ksor-answer-correct-text">Correct</span>
+                  ) : (
+                    <span className="ksor-answer-wrong-text">
+                      Not quite — the answer is {letterOf(current.answer)}
+                    </span>
+                  )}
+                </p>
+                <p className="leading-relaxed text-fd-muted-foreground">{current.explanation}</p>
+                {current.source === undefined ? null : (
+                  // "In the document", never "Source": a citation in this
+                  // product carries a generation, and an attachment has no id
+                  // to pin — calling this a source would sell provenance that
+                  // is not here (spec §3).
+                  <p className="font-mono text-xs text-fd-muted-foreground">
+                    In the document: {current.source}
+                  </p>
+                )}
+              </div>
+            ) : null}
+          </CardContent>
+        </Card>
+
+        <div className="mt-6 flex items-center justify-between gap-4">
+          <Button
+            variant="ghost"
+            disabled={index === 0}
+            onClick={() => setIndex((i) => Math.max(0, i - 1))}
+          >
+            Back
+          </Button>
+          {index === round.length - 1 ? (
+            <Button disabled={!answered} onClick={() => setDone(true)}>
+              Finish
+            </Button>
+          ) : (
+            <Button disabled={!answered} onClick={() => setIndex((i) => i + 1)}>
+              Next
+            </Button>
+          )}
+        </div>
+
+        {/* Rendered only once the reader's own answers are in, so the server
+            HTML never claims a state this reader is not in. */}
+        {hydrated && answeredCount > 0 && !done ? (
+          <p className="mt-4 text-center font-mono text-xs text-fd-muted-foreground">
+            {correctCount} of {answeredCount} correct so far
+          </p>
+        ) : null}
+      </div>
+    </section>
+  );
+}

package/templates/scaffold/system/site/components/study-aids.tsx

@@ -4,7 +4,7 @@ import type { ReactElement, ReactNode } from "react";
  * The end-of-document region: what a reader DOES with a document once they
  * have read it.
  *
- * The deck lives here, and the quiz will sit beside it. Deliberately not a tab:
+ * The deck and the quiz live here, in that order. Deliberately not a tab:
  * a study aid is used AFTER the document, and a tab would hide the document
  * while you used it. Deliberately one region rather than each aid finding its
  * own spot on the page, so a second aid is a child here and not a new layout

package/templates/scaffold/system/site/lib/attachment-rule.ts

@@ -21,6 +21,7 @@ export const ATTACHMENT_SUFFIXES = [
   { suffix: ".summary.md", kind: "summary" },
   { suffix: ".summary.mdx", kind: "summary" },
   { suffix: ".flashcards.yaml", kind: "deck" },
+  { suffix: ".quiz.yaml", kind: "quiz" },
 ] as const;
 
 export type AttachmentKind = (typeof ATTACHMENT_SUFFIXES)[number]["kind"];
@@ -37,6 +38,8 @@ export const ATTACHMENT_NEAR_MISSES = [
   { suffix: ".flashcards.yml", want: ".flashcards.yaml" },
   { suffix: ".flashcards.json", want: ".flashcards.yaml" },
   { suffix: ".summary.markdown", want: ".summary.md" },
+  { suffix: ".quiz.yml", want: ".quiz.yaml" },
+  { suffix: ".quiz.json", want: ".quiz.yaml" },
 ] as const;
 
 /**
@@ -102,6 +105,7 @@ export function nearMissOf(
 export const ATTACHMENT_CASES = [
   { name: "returns.summary.md", kind: "summary", parent: "returns.md" },
   { name: "returns.flashcards.yaml", kind: "deck", parent: "returns.md" },
+  { name: "returns.quiz.yaml", kind: "quiz", parent: "returns.md" },
   { name: "index.summary.md", kind: "summary", parent: "index.md" },
   // A stem containing dots keeps every one of them: the parent is the same
   // name with the attachment suffix removed, never "up to the first dot".
@@ -110,15 +114,18 @@ export const ATTACHMENT_CASES = [
   { name: "returns.md", kind: null, parent: null },
   { name: "summary.md", kind: null, parent: null },
   { name: "flashcards.yaml", kind: null, parent: null },
+  { name: "quiz.yaml", kind: null, parent: null },
   { name: "my-summary.md", kind: null, parent: null },
   // A dotfile with no stem attaches to nothing — refused as an attachment so
   // it is refused as an unexpected file instead, which is the honest error.
   { name: ".summary.md", kind: null, parent: null },
   { name: ".flashcards.yaml", kind: null, parent: null },
+  { name: ".quiz.yaml", kind: null, parent: null },
   // Case matters: the record already refuses two names differing only in case,
   // so an uppercase suffix is a different file, not the same rule.
   { name: "returns.SUMMARY.md", kind: null, parent: null },
   // Not attachments — near misses, which get their own refusal.
   { name: "returns.flashcards.yml", kind: null, parent: null },
   { name: "returns.flashcards.json", kind: null, parent: null },
+  { name: "returns.quiz.yml", kind: null, parent: null },
 ] as const;

package/templates/scaffold/system/site/lib/attachments.ts

@@ -1,8 +1,11 @@
-import { decks, summaries } from "collections/server";
+import { decks, quizzes, summaries } from "collections/server";
 
 import { ATTACHMENT_SUFFIXES } from "./attachment-rule";
 import { cardHash, type Card, type Deck } from "./deck";
 import { newCard, type CardSchedule } from "./srs";
+import { type Question, type Quiz } from "./quiz";
+import { DEFAULT_QUESTIONS_PER_ROUND } from "./quiz-round";
+import { questionHash } from "./identity";
 
 /**
  * Finding a document's study attachments.
@@ -83,9 +86,44 @@ export function deckFor(documentPath: string): DeckEntry | null {
   };
 }
 
-/** True when a document has either attachment — the presence gate for the UI. */
+/** One question as the quiz UI consumes it: authored text plus its identity. */
+export interface QuizQuestion extends Question {
+  /** Identity: a hash of the question's own text, so an edit resets only this one. */
+  readonly hash: string;
+}
+
+export interface QuizEntry {
+  readonly title: string;
+  readonly description?: string;
+  readonly questionsPerRound: number;
+  readonly questions: readonly QuizQuestion[];
+  /** The record-relative path — the quiz's identity, used to key saved answers. */
+  readonly path: string;
+}
+
+/** The quiz for a document, or null when it has none. */
+export function quizFor(documentPath: string): QuizEntry | null {
+  const wanted = attachmentPath(documentPath, ".quiz.yaml");
+  const hit = quizzes.find((entry) => entry.info.path === wanted);
+  if (hit === undefined) return null;
+
+  const parsed = hit as unknown as Quiz & { readonly info: { readonly path: string } };
+  return {
+    title: parsed.quiz.title,
+    description: parsed.quiz.description,
+    questionsPerRound: parsed.quiz.questionsPerRound ?? DEFAULT_QUESTIONS_PER_ROUND,
+    path: parsed.info.path,
+    questions: parsed.questions.map((q) => ({ ...q, hash: questionHash(q) })),
+  };
+}
+
+/** True when a document has ANY attachment — the presence gate for the UI. */
 export function hasAttachments(documentPath: string): boolean {
-  return summaryFor(documentPath) !== null || deckFor(documentPath) !== null;
+  return (
+    summaryFor(documentPath) !== null ||
+    deckFor(documentPath) !== null ||
+    quizFor(documentPath) !== null
+  );
 }
 
 /**

package/templates/scaffold/system/site/lib/deck.ts

@@ -1,5 +1,7 @@
 import { z } from "zod";
 
+import { textHash } from "./identity";
+
 /**
  * The shape of a `<doc>.flashcards.yaml` deck.
  *
@@ -44,16 +46,5 @@ export type Card = z.infer<typeof CardSchema>;
  * and rewording it should not throw away a learner's history with the card.
  */
 export function cardHash(card: Card): string {
-  // NUL as the separator, written as an escape rather than embedded: a raw
-  // NUL in the source makes git treat this file as binary. It has to be a
-  // separator of some kind — without one, front "ab"/back "c" hashes the same
-  // as front "a"/back "bc" — and NUL is the one character authored card text
-  // cannot contain.
-  const text = `${card.front}\u0000${card.back}`;
-  let hash = 0x811c9dc5;
-  for (let i = 0; i < text.length; i += 1) {
-    hash ^= text.charCodeAt(i);
-    hash = Math.imul(hash, 0x01000193) >>> 0;
-  }
-  return hash.toString(16).padStart(8, "0");
+  return textHash([card.front, card.back]);
 }

package/templates/scaffold/system/site/lib/identity.ts

@@ -0,0 +1,55 @@
+/**
+ * Identity for authored text: the hash, and what a question hashes.
+ *
+ * FNV-1a, 32-bit, hand-rolled — the site has no crypto import at build time and
+ * this has to produce the same value in the browser, where the saved progress
+ * it keys actually lives. A collision costs one card's or one question's saved
+ * state, never correctness, so 32 bits is the right size of hammer.
+ *
+ * Extracted so the deck and the quiz share ONE implementation. Two hand-rolled
+ * copies of a hash is the kind of duplication that stays identical right up
+ * until someone fixes a separator in one of them.
+ *
+ * A LEAF, and it has to stay one. This repo can only unit-test a scaffold
+ * module with no relative imports: `tsc` under node16 resolution demands a
+ * `.js` specifier, and Next's bundler in the scaffold cannot resolve that back
+ * to a `.ts` file — so a scaffold module that imports a sibling either fails
+ * the typecheck or fails the site build. `questionHash` therefore lives here
+ * beside the hash it calls rather than in a file of its own.
+ */
+
+/**
+ * The separator between parts, written as an escape rather than embedded: a raw
+ * NUL in the source makes git treat the file as binary.
+ *
+ * A separator is load-bearing. Without one, `["ab", "c"]` and `["a", "bc"]`
+ * hash identically, and NUL is the one character authored text cannot contain.
+ */
+const SEPARATOR = "\u0000";
+
+/** Hash these parts as one identity. */
+export function textHash(parts: readonly string[]): string {
+  const text = parts.join(SEPARATOR);
+  let hash = 0x811c9dc5;
+  for (let i = 0; i < text.length; i += 1) {
+    hash ^= text.charCodeAt(i);
+    hash = Math.imul(hash, 0x01000193) >>> 0;
+  }
+  return hash.toString(16).padStart(8, "0");
+}
+
+/**
+ * A question's identity: a hash of the text the reader actually sees.
+ *
+ * The stem AND the options, deliberately including their ORDER — reordering
+ * changes which index is correct, so a saved answer would otherwise be
+ * re-scored against a different question and silently become right or wrong.
+ * `explanation` and `source` are excluded: they teach ABOUT the question
+ * rather than being it, so improving an explanation costs the reader nothing.
+ */
+export function questionHash(question: {
+  readonly question: string;
+  readonly options: readonly string[];
+}): string {
+  return textHash([question.question, ...question.options]);
+}