question-bank-framework 0.3.0 → 0.5.0

package/framework/components/question-response.tsx

@@ -0,0 +1,211 @@
+// Response widgets for the auto-graded non-choice kinds: numerical,
+// matching and dropdown. Framework-owned: eject with
+// `qb reveal framework/components/question-response.tsx`.
+
+import { Check, X } from 'lucide-react';
+import type { BaseQuestion, QuestionOption, QuizAnswer } from '../../core/types.ts';
+import { getPairingSlots, parseNumericAnswer, questionKind, toPairings } from '../../core/types.ts';
+import { MarkdownContent } from './markdown-content';
+import { Select, SelectContent, SelectItem, SelectTrigger, SelectValue } from './ui/select';
+import { cn } from '../lib/utils.ts';
+
+export const optionLetter = (index: number): string => String.fromCharCode(65 + index);
+
+/** Format the expected value of a numerical question, e.g. "71.667 (± 0.01) I/Os". */
+export function formatNumericAnswer(question: BaseQuestion): string {
+  const numeric = question.numeric;
+  if (!numeric) return '';
+  const tolerance = numeric.tolerance ? ` (± ${numeric.tolerance})` : '';
+  const unit = numeric.unit ? ` ${numeric.unit}` : '';
+  return `${numeric.value.toLocaleString('en-US', { maximumFractionDigits: 10 })}${tolerance}${unit}`;
+}
+
+export function NumericalResponse({
+  question,
+  answer,
+  checked,
+  correct,
+  onChange,
+}: {
+  question: BaseQuestion;
+  answer: QuizAnswer | undefined;
+  checked: boolean;
+  correct: boolean | null;
+  onChange: (value: string) => void;
+}) {
+  const text = typeof answer === 'string' ? answer : '';
+  const invalid = text.trim() !== '' && parseNumericAnswer(text) === null;
+  const inputId = `quiz-numeric-${question.id}`;
+  return (
+    <div className="mt-6">
+      <label htmlFor={inputId} className="text-sm font-semibold text-gray-900">
+        Your answer
+      </label>
+      <div className="mt-2 flex items-center gap-2">
+        <input
+          id={inputId}
+          type="text"
+          inputMode="decimal"
+          autoComplete="off"
+          value={text}
+          onChange={(event) => onChange(event.target.value)}
+          placeholder="Enter a number"
+          aria-invalid={invalid || (checked && correct === false) || undefined}
+          aria-describedby={invalid ? `${inputId}-hint` : undefined}
+          className={cn(
+            'h-10 w-48 rounded-lg border bg-white px-3 font-mono text-base tabular-nums text-gray-900 outline-none placeholder:font-sans placeholder:text-gray-400 focus-visible:ring-2 focus-visible:ring-gray-900/20',
+            checked && correct === true && 'border-green-600 bg-green-50',
+            checked && correct === false && 'border-red-600 bg-red-50',
+            !checked && 'border-gray-300',
+          )}
+        />
+        {question.numeric?.unit && <span className="text-sm text-gray-600">{question.numeric.unit}</span>}
+      </div>
+      {invalid && (
+        <p id={`${inputId}-hint`} className="mt-1.5 text-sm text-amber-800">
+          That doesn't look like a number — it will be marked incorrect.
+        </p>
+      )}
+    </div>
+  );
+}
+
+function OptionSelect({
+  id,
+  options,
+  value,
+  lettered,
+  onChange,
+  ariaLabel,
+  state,
+}: {
+  id: string;
+  options: readonly QuestionOption[];
+  value: string | undefined;
+  lettered: boolean;
+  onChange: (value: string) => void;
+  ariaLabel: string;
+  state: 'idle' | 'correct' | 'incorrect' | 'missing';
+}) {
+  return (
+    <Select value={value ?? ''} onValueChange={onChange}>
+      <SelectTrigger
+        id={id}
+        aria-label={ariaLabel}
+        className={cn(
+          'h-auto min-h-9 w-full min-w-48 whitespace-normal bg-white text-left sm:w-72',
+          state === 'correct' && 'border-green-600 bg-green-50',
+          (state === 'incorrect' || state === 'missing') && 'border-red-600 bg-red-50',
+        )}
+      >
+        <SelectValue placeholder="Choose…" />
+      </SelectTrigger>
+      <SelectContent position="popper" className="max-w-[min(36rem,calc(100vw-2rem))]">
+        {options.map((option, index) => (
+          <SelectItem key={option.id} value={option.id} className="whitespace-normal">
+            {lettered && <span className="font-semibold text-gray-500">{optionLetter(index)}.</span>}
+            <MarkdownContent inline content={option.text} />
+          </SelectItem>
+        ))}
+      </SelectContent>
+    </Select>
+  );
+}
+
+/** Matching rows or dropdown blanks: one select per slot, graded per slot once checked. */
+export function PairingResponse({
+  question,
+  answer,
+  checked,
+  onChange,
+}: {
+  question: BaseQuestion;
+  answer: QuizAnswer | undefined;
+  checked: boolean;
+  onChange: (value: Record<string, string>) => void;
+}) {
+  const kind = questionKind(question);
+  const matching = kind === 'matching';
+  const slots = getPairingSlots(question);
+  const pairings = toPairings(question, answer);
+  const answeredCount = Object.keys(pairings).length;
+
+  return (
+    <div className="mt-6">
+      <p id={`quiz-pairing-label-${question.id}`} className="text-sm font-semibold text-gray-900">
+        {matching ? 'Match each item to an option' : 'Fill in each blank'}
+        <span className="ml-2 font-normal text-gray-500">
+          {answeredCount}/{slots.length} answered
+        </span>
+      </p>
+
+      {matching && (
+        <div className="mt-3 rounded-lg border border-gray-200 bg-gray-50 p-3">
+          <p className="m-0 text-xs font-semibold uppercase tracking-wide text-gray-500">Options</p>
+          <ol className="m-0 mt-2 grid list-none gap-x-6 gap-y-1 p-0 sm:grid-cols-2">
+            {(question.options ?? []).map((option, index) => (
+              <li key={option.id} className="flex items-start gap-2 text-sm text-gray-800">
+                <span className="w-5 shrink-0 font-semibold text-gray-500">{optionLetter(index)}.</span>
+                <MarkdownContent inline content={option.text} className="min-w-0 flex-1" />
+              </li>
+            ))}
+          </ol>
+        </div>
+      )}
+
+      <ol aria-labelledby={`quiz-pairing-label-${question.id}`} className="m-0 mt-3 grid list-none gap-2 p-0">
+        {slots.map((slot, index) => {
+          const chosen = pairings[slot.id];
+          const isCorrect = chosen === slot.correctId;
+          const state = !checked ? 'idle' : chosen === undefined ? 'missing' : isCorrect ? 'correct' : 'incorrect';
+          const correctIndex = slot.options.findIndex((o) => o.id === slot.correctId);
+          const correctOption = slot.options[correctIndex];
+          const selectId = `quiz-slot-${question.id}-${slot.id}`;
+          const label = slot.label?.trim() ? slot.label : `Blank ${index + 1}`;
+          return (
+            <li
+              key={slot.id}
+              className={cn(
+                'flex flex-col gap-2 rounded-lg border p-3 sm:flex-row sm:items-center',
+                state === 'idle' && 'border-gray-200 bg-white',
+                state === 'correct' && 'border-green-300 bg-green-50/50',
+                (state === 'incorrect' || state === 'missing') && 'border-red-300 bg-red-50/50',
+              )}
+            >
+              <div className="flex min-w-0 flex-1 items-start gap-2">
+                <span className="mt-0.5 w-6 shrink-0 text-sm font-semibold tabular-nums text-gray-500">{index + 1}.</span>
+                <label htmlFor={selectId} className="min-w-0 flex-1 text-base leading-7 text-gray-900">
+                  <MarkdownContent inline content={label} />
+                </label>
+              </div>
+              <div className="flex shrink-0 flex-col gap-1 pl-8 sm:pl-0">
+                <div className="flex items-center gap-2">
+                  <OptionSelect
+                    id={selectId}
+                    options={slot.options}
+                    value={chosen}
+                    lettered={matching}
+                    ariaLabel={`Answer for ${matching ? 'item' : 'blank'} ${index + 1}`}
+                    state={state}
+                    onChange={(value) => onChange({ ...pairings, [slot.id]: value })}
+                  />
+                  {state === 'correct' && <Check aria-label="Correct" className="size-5 shrink-0 text-green-700" />}
+                  {(state === 'incorrect' || state === 'missing') && (
+                    <X aria-label={state === 'missing' ? 'Not answered' : 'Incorrect'} className="size-5 shrink-0 text-red-700" />
+                  )}
+                </div>
+                {(state === 'incorrect' || state === 'missing') && correctOption && (
+                  <p className="m-0 flex items-baseline gap-1 text-sm text-red-900">
+                    <span className="shrink-0">Correct:</span>
+                    {matching && <span className="font-semibold">{optionLetter(correctIndex)}.</span>}
+                    <MarkdownContent inline content={correctOption.text} />
+                  </p>
+                )}
+              </div>
+            </li>
+          );
+        })}
+      </ol>
+    </div>
+  );
+}

package/framework/components/quiz-list.tsx

@@ -49,7 +49,7 @@ export function QuizList() {
   };
 
   return (
-    <div className="grid gap-8">
+    <div className="grid grid-cols-[minmax(0,1fr)] gap-8">
       <div className="flex flex-wrap items-end justify-between gap-4">
         <div>
           <h1 className="m-0 text-3xl font-bold tracking-tight text-gray-900">My quizzes</h1>
@@ -69,7 +69,7 @@ export function QuizList() {
               Could not delete that quiz. Please try again.
             </p>
           )}
-          <div className="grid grid-cols-1 gap-4 sm:grid-cols-2">
+          <div className="grid grid-cols-[minmax(0,1fr)] gap-4 sm:grid-cols-[repeat(2,minmax(0,1fr))]">
             {quizzes.map((quiz) => {
               const questions = quiz.questionIds
                 .map((id) => bank.questionById.get(id))
@@ -85,7 +85,7 @@ export function QuizList() {
                     params={{ quizId: quiz.id }}
                     className="block rounded-xl border border-gray-200 bg-white p-5 transition-colors hover:border-gray-400 focus-visible:outline-2 focus-visible:outline-offset-2 focus-visible:outline-gray-500"
                   >
-                    <h2 className="m-0 pr-16 text-lg font-semibold text-gray-900">{quiz.title}</h2>
+                    <h2 className="m-0 break-words pr-16 text-lg font-semibold text-gray-900">{quiz.title}</h2>
                     <p className="mt-2 text-sm text-gray-700">
                       {quiz.questionIds.length} {quiz.questionIds.length === 1 ? 'question' : 'questions'}
                     </p>

package/framework/components/quiz-page.tsx

@@ -4,12 +4,15 @@ import { useEffect, useMemo, useRef, useState } from 'react';
 import { Link, useParams } from '@tanstack/react-router';
 import { Check, Pencil, X } from 'lucide-react';
 import { useBank } from '../../core/config.tsx';
-import type { QuestionStatus, QuizAnswer, QuizSession } from '../../core/types.ts';
+import type { QuestionStatus, QuestionStatusMap, QuizAnswer, QuizSession } from '../../core/types.ts';
 import {
   getCorrectIds,
+  gradeAnswer,
   isAnswerCorrect,
   isAnswerProvided,
   isChoiceQuestion,
+  isGradeableQuestion,
+  isPairingQuestion,
   questionKind,
   questionKindLabels,
   scoreAnswers,
@@ -19,11 +22,23 @@ import { Badge } from './ui/badge';
 import { Button } from './ui/button';
 import { Input } from './ui/input';
 import { MarkdownContent } from './markdown-content';
-import { setQuestionStatus } from '../lib/question-status-storage.ts';
+import { formatNumericAnswer, NumericalResponse, optionLetter, PairingResponse } from './question-response';
+import { setQuestionStatus, getQuestionStatuses } from '../lib/question-status-storage.ts';
+import { questionStatusLabels } from '../lib/question-filter.ts';
 import { getQuiz, saveQuizLocally, saveQuizProgress } from '../lib/quiz-storage.ts';
 import { cn } from '../lib/utils.ts';
 
-const optionLetter = (index: number): string => String.fromCharCode(65 + index);
+const questionStatusStyles: Record<QuestionStatus, string> = {
+  unanswered: 'border-gray-300 bg-gray-50 text-gray-700',
+  revisit: 'border-amber-300 bg-amber-50 text-amber-900',
+  complete: 'border-green-300 bg-green-50 text-green-800',
+};
+
+const questionStatusDotStyles: Record<QuestionStatus, string> = {
+  unanswered: 'border-gray-300 bg-white text-gray-600 hover:border-gray-500',
+  revisit: 'border-amber-400 bg-amber-100 text-amber-900 hover:border-amber-600',
+  complete: 'border-green-500 bg-green-100 text-green-900 hover:border-green-700',
+};
 
 export function QuizPage() {
   const bank = useBank();
@@ -35,6 +50,7 @@ export function QuizPage() {
   const [checked, setChecked] = useState<Record<string, boolean>>({});
   const [editingTitle, setEditingTitle] = useState(false);
   const [titleDraft, setTitleDraft] = useState('');
+  const [statusMap, setStatusMap] = useState<QuestionStatusMap>({});
   const titleInputRef = useRef<HTMLInputElement>(null);
   const quizQuestions = useMemo(
     () =>
@@ -53,6 +69,9 @@ export function QuizPage() {
     }).finally(() => {
       if (active) setLoading(false);
     });
+    getQuestionStatuses(bank.namespace).then((statuses) => {
+      if (active) setStatusMap(statuses);
+    });
     return () => {
       active = false;
     };
@@ -94,7 +113,7 @@ export function QuizPage() {
     );
   };
 
-  const setChoiceAnswer = (questionId: string, value: string[]) => {
+  const setGradedAnswer = (questionId: string, value: QuizAnswer) => {
     setChecked((current) => (current[questionId] ? { ...current, [questionId]: false } : current));
     setSession((current) =>
       current ? { ...current, completed: false, answers: { ...current.answers, [questionId]: value } } : current,
@@ -105,9 +124,9 @@ export function QuizPage() {
     if (!activeQuestion) return;
     const current = toSelectedIds(activeQuestion, session?.answers[questionId]);
     if (single) {
-      setChoiceAnswer(questionId, current[0] === optionId ? [] : [optionId]);
+      setGradedAnswer(questionId, current[0] === optionId ? [] : [optionId]);
     } else {
-      setChoiceAnswer(
+      setGradedAnswer(
         questionId,
         current.includes(optionId) ? current.filter((id) => id !== optionId) : [...current, optionId],
       );
@@ -123,6 +142,7 @@ export function QuizPage() {
   const updateQuestionStatus = (status: QuestionStatus) => {
     if (!activeQuestion) return;
     void setQuestionStatus(bank.namespace, activeQuestion.id, status);
+    setStatusMap((current) => ({ ...current, [activeQuestion.id]: status }));
     setShownAnswerId(null);
     setSession((current) =>
       current
@@ -166,16 +186,19 @@ export function QuizPage() {
   const suggestedAnswer = bank.answers[activeQuestion.id];
   const isSuggestedAnswerShown = shownAnswerId === activeQuestion.id;
   const choice = isChoiceQuestion(activeQuestion);
+  const gradeable = isGradeableQuestion(activeQuestion);
   const kind = questionKind(activeQuestion);
   const selectedIds = toSelectedIds(activeQuestion, answer);
   const hasSelection = isAnswerProvided(activeQuestion, answer);
   const isChecked = checked[activeQuestion.id] === true;
   const correctness = isChecked ? isAnswerCorrect(activeQuestion, answer) : null;
+  const grade = isChecked ? gradeAnswer(activeQuestion, answer) : null;
   const correctIds = getCorrectIds(activeQuestion);
+  const activeStatus: QuestionStatus = statusMap[activeQuestion.id] ?? 'unanswered';
   const score = scoreAnswers(quizQuestions, session.answers);
 
   return (
-    <div className="mx-auto grid max-w-3xl gap-6">
+    <div className="mx-auto grid w-full max-w-3xl grid-cols-[minmax(0,1fr)] gap-6">
       <Link to="/quizzes" className="text-sm font-semibold text-gray-600 hover:text-gray-900">
         Back to My quizzes
       </Link>
@@ -208,7 +231,7 @@ export function QuizPage() {
           </form>
         ) : (
           <div className="flex min-w-0 items-center gap-2">
-            <h1 className="m-0 text-3xl font-bold tracking-tight text-gray-900">{session.title}</h1>
+            <h1 className="m-0 min-w-0 break-words text-3xl font-bold tracking-tight text-gray-900">{session.title}</h1>
             <Button type="button" variant="ghost" size="icon-xs" aria-label="Edit quiz title" title="Edit quiz title" onClick={startEditingTitle}>
               <Pencil aria-hidden="true" />
             </Button>
@@ -233,6 +256,35 @@ export function QuizPage() {
         )}
       </div>
 
+      {quizQuestions.length > 1 && (
+        <nav aria-label="Questions in this quiz">
+          <ol className="m-0 flex list-none flex-wrap gap-1.5 p-0">
+            {quizQuestions.map((question, index) => {
+              const status = statusMap[question.id] ?? 'unanswered';
+              const isActive = index === activeIndex;
+              return (
+                <li key={question.id}>
+                  <button
+                    type="button"
+                    onClick={() => goToQuestion(index)}
+                    aria-label={`Go to question ${index + 1}: ${question.title} — ${questionStatusLabels[status]}${isActive ? ' (current question)' : ''}`}
+                    aria-current={isActive ? 'true' : undefined}
+                    title={`${question.title} — ${questionStatusLabels[status]}`}
+                    className={cn(
+                      'flex size-8 items-center justify-center rounded-md border text-xs font-semibold tabular-nums transition-colors',
+                      questionStatusDotStyles[status],
+                      isActive && 'ring-2 ring-gray-900 ring-offset-2',
+                    )}
+                  >
+                    {index + 1}
+                  </button>
+                </li>
+              );
+            })}
+          </ol>
+        </nav>
+      )}
+
       {session.completed && score.gradeable > 0 && (
         <section aria-label="Quiz results" className="rounded-xl border border-gray-200 bg-gray-50 p-5">
           <h2 className="m-0 text-lg font-semibold text-gray-900">
@@ -241,13 +293,24 @@ export function QuizPage() {
           <ol className="mt-3 grid gap-1.5">
             {quizQuestions.map((question, index) => {
               const result = isAnswerCorrect(question, session.answers[question.id]);
+              const parts = isPairingQuestion(question) ? gradeAnswer(question, session.answers[question.id]) : null;
+              const resultLabel =
+                result === null
+                  ? isGradeableQuestion(question)
+                    ? 'Unanswered'
+                    : 'Written'
+                  : result
+                    ? 'Correct'
+                    : parts
+                      ? `Incorrect · ${parts.earned}/${parts.possible}`
+                      : 'Incorrect';
               return (
                 <li key={question.id}>
                   <button
                     type="button"
                     onClick={() => goToQuestion(index)}
                     className="flex w-full items-center gap-2 rounded-lg px-2 py-1.5 text-left text-sm hover:bg-gray-100"
-                    aria-label={`Review question ${index + 1}: ${question.title} — ${result === null ? 'written' : result ? 'correct' : 'incorrect'}`}
+                    aria-label={`Review question ${index + 1}: ${question.title} — ${resultLabel.toLowerCase()}`}
                   >
                     <span
                       aria-hidden="true"
@@ -261,9 +324,7 @@ export function QuizPage() {
                       {result === true ? <Check className="size-3" /> : result === false ? <X className="size-3" /> : index + 1}
                     </span>
                     <span className="min-w-0 flex-1 truncate text-gray-900">{question.title}</span>
-                    <span className="shrink-0 text-xs text-gray-500">
-                      {result === null ? 'Written' : result ? 'Correct' : 'Incorrect'}
-                    </span>
+                    <span className="shrink-0 text-xs text-gray-500">{resultLabel}</span>
                   </button>
                 </li>
               );
@@ -272,16 +333,19 @@ export function QuizPage() {
         </section>
       )}
 
-      <section className="rounded-xl border border-gray-200 bg-white p-5">
+      <section className="min-w-0 rounded-xl border border-gray-200 bg-white p-5">
         <div className="flex flex-wrap items-center gap-2">
-          <h2 className="m-0 flex-1 text-xl font-semibold text-gray-900">{activeQuestion.title}</h2>
+          <h2 className="m-0 min-w-0 flex-1 break-words text-xl font-semibold text-gray-900">{activeQuestion.title}</h2>
           <Badge variant="outline">{questionKindLabels[kind]}</Badge>
+          <Badge variant="outline" className={questionStatusStyles[activeStatus]}>
+            {questionStatusLabels[activeStatus]}
+          </Badge>
         </div>
-        <p className="mt-1 font-mono text-xs text-gray-500">{activeQuestion.id}</p>
+        <p className="mt-1 break-all font-mono text-xs text-gray-500">{activeQuestion.id}</p>
         {activeQuestion.tags.length > 0 && (
           <div className="mt-2 flex flex-wrap gap-1">
             {activeQuestion.tags.map((tag) => (
-              <Badge key={tag} variant="secondary">
+              <Badge key={tag} variant="secondary" className="max-w-full shrink whitespace-normal break-words">
                 {tag}
               </Badge>
             ))}
@@ -350,6 +414,39 @@ export function QuizPage() {
               })}
             </div>
 
+          </div>
+        ) : kind === 'numerical' ? (
+          <NumericalResponse
+            question={activeQuestion}
+            answer={answer}
+            checked={isChecked}
+            correct={correctness}
+            onChange={(value) => setGradedAnswer(activeQuestion.id, value)}
+          />
+        ) : isPairingQuestion(activeQuestion) ? (
+          <PairingResponse
+            question={activeQuestion}
+            answer={answer}
+            checked={isChecked}
+            onChange={(value) => setGradedAnswer(activeQuestion.id, value)}
+          />
+        ) : (
+          <div className="mt-6">
+            <label htmlFor="quiz-answer" className="text-sm font-semibold text-gray-900">
+              Your answer
+            </label>
+            <textarea
+              id="quiz-answer"
+              value={typeof answer === 'string' ? answer : ''}
+              onChange={(event) => updateWrittenAnswer(event.target.value)}
+              placeholder="Write your working or notes here..."
+              className="mt-2 block min-h-40 w-full resize-y rounded-lg border border-gray-300 bg-white p-3 text-base leading-relaxed text-gray-900 outline-none placeholder:text-gray-400"
+            />
+          </div>
+        )}
+
+        {gradeable && (
+          <div>
             {isChecked && correctness !== null && (
               <div
                 role="status"
@@ -360,12 +457,16 @@ export function QuizPage() {
               >
                 {correctness
                   ? 'Correct — nice work.'
-                  : `Not quite. Correct answer${correctIds.length > 1 ? 's' : ''}: ${correctIds
-                      .map((id) => {
-                        const index = (activeQuestion.options ?? []).findIndex((o) => o.id === id);
-                        return index >= 0 ? optionLetter(index) : id;
-                      })
-                      .join(', ')}`}
+                  : kind === 'numerical'
+                    ? `Not quite. Expected ${formatNumericAnswer(activeQuestion)}.`
+                    : isPairingQuestion(activeQuestion) && grade
+                      ? `Not quite — ${grade.earned} of ${grade.possible} correct. Corrections are shown on each ${kind === 'matching' ? 'item' : 'blank'}.`
+                      : `Not quite. Correct answer${correctIds.length > 1 ? 's' : ''}: ${correctIds
+                          .map((id) => {
+                            const index = (activeQuestion.options ?? []).findIndex((o) => o.id === id);
+                            return index >= 0 ? optionLetter(index) : id;
+                          })
+                          .join(', ')}`}
               </div>
             )}
 
@@ -385,24 +486,11 @@ export function QuizPage() {
               )}
             </div>
           </div>
-        ) : (
-          <div className="mt-6">
-            <label htmlFor="quiz-answer" className="text-sm font-semibold text-gray-900">
-              Your answer
-            </label>
-            <textarea
-              id="quiz-answer"
-              value={typeof answer === 'string' ? answer : ''}
-              onChange={(event) => updateWrittenAnswer(event.target.value)}
-              placeholder="Write your working or notes here..."
-              className="mt-2 block min-h-40 w-full resize-y rounded-lg border border-gray-300 bg-white p-3 text-base leading-relaxed text-gray-900 outline-none placeholder:text-gray-400"
-            />
-          </div>
         )}
 
-        {suggestedAnswer && (choice ? isSuggestedAnswerShown : true) && (
+        {suggestedAnswer && (gradeable ? isSuggestedAnswerShown : true) && (
           <div className="mt-5">
-            {!choice && (
+            {!gradeable && (
               <Button
                 variant="outline"
                 aria-expanded={isSuggestedAnswerShown}
@@ -415,7 +503,7 @@ export function QuizPage() {
             {isSuggestedAnswerShown && (
               <section id="suggested-answer" className="mt-4 rounded-lg border border-gray-200 bg-gray-50 p-4">
                 <h3 className="m-0 text-base font-semibold text-gray-900">
-                  {choice ? 'Explanation' : 'Suggested answer'}
+                  {gradeable ? 'Explanation' : 'Suggested answer'}
                 </h3>
                 <MarkdownContent content={suggestedAnswer} className="mt-3 text-sm leading-relaxed text-gray-800" />
               </section>

package/framework/convex/quizzes.ts

@@ -40,7 +40,7 @@ export const saveProgress = mutation({
   args: {
     quizId: v.id('quizzes'),
     title: v.string(),
-    answers: v.record(v.string(), v.union(v.string(), v.array(v.string()))),
+    answers: v.record(v.string(), v.union(v.string(), v.array(v.string()), v.record(v.string(), v.string()))),
     currentQuestion: v.number(),
     completed: v.boolean(),
   },
@@ -53,7 +53,7 @@ export const setQuestions = mutation({
   args: {
     quizId: v.id('quizzes'),
     questionIds: v.array(v.string()),
-    answers: v.record(v.string(), v.union(v.string(), v.array(v.string()))),
+    answers: v.record(v.string(), v.union(v.string(), v.array(v.string()), v.record(v.string(), v.string()))),
     currentQuestion: v.number(),
   },
   handler: async (ctx, { quizId, questionIds, answers, currentQuestion }) => {

package/framework/convex/schema.ts

@@ -5,7 +5,7 @@ export default defineSchema({
   quizzes: defineTable({
     title: v.string(),
     questionIds: v.array(v.string()),
-    answers: v.record(v.string(), v.union(v.string(), v.array(v.string()))),
+    answers: v.record(v.string(), v.union(v.string(), v.array(v.string()), v.record(v.string(), v.string()))),
     currentQuestion: v.number(),
     completed: v.boolean(),
     createdAt: v.number(),

package/framework/index.ts

@@ -7,6 +7,7 @@ export { QuizList } from './components/quiz-list.tsx';
 export { AppShell } from './components/app-shell.tsx';
 export { FilterBuilder } from './components/filter-builder.tsx';
 export { MarkdownContent } from './components/markdown-content.tsx';
+export { NumericalResponse, PairingResponse, formatNumericAnswer } from './components/question-response.tsx';
 
 export {
   createFilterFields,

package/framework/lib/question-filter.ts

@@ -358,7 +358,7 @@ export function matchesFilters(
     : active.some((rule) => matchesRule(rule, fields, fieldDefs, question, status));
 }
 
-/** Free-text search across id/title/prompt/tags/options plus `searchable` custom fields. */
+/** Free-text search across id/title/prompt/tags/options/items/blanks plus `searchable` custom fields. */
 export function matchesSearch(
   question: BaseQuestion,
   query: string,
@@ -372,6 +372,8 @@ export function matchesSearch(
     question.prompt,
     question.tags.join(' '),
     (question.options ?? []).map((o) => o.text).join(' '),
+    (question.items ?? []).map((item) => item.text).join(' '),
+    (question.blanks ?? []).map((blank) => [blank.label ?? '', ...blank.options.map((o) => o.text)].join(' ')).join(' '),
   ];
   for (const def of fieldDefs) {
     if (!def.searchable) continue;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "question-bank-framework",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Framework-style question bank: TanStack Start + TanStack Table grid, quizzes, and filter DSL. Bring your own bank.config.ts + content/. Eject any framework/ file with `qb reveal` (Vike-style).",
   "type": "module",
   "license": "MIT",