question-bank-framework 0.2.0 → 0.3.0

package/README.md

@@ -24,6 +24,20 @@ Your app owns:
 - `content/questions.json`, `content/answers.ts`, `content/figures/`
 - Thin TanStack Start routes in `src/routes/` (see `template/src/routes/`)
   wrapping `<BankProvider bank={bank}>` + `<AppShell brand>` + framework pages.
+- `src/routes/styles.css` (scaffolded by `qb init`, imported as `?url` from
+  `__root.tsx`). It must list the framework as a Tailwind source — v4 ignores
+  `node_modules` by default, so without this none of the grid/badge/filter
+  utilities are generated and the app renders unstyled:
+
+```css
+@import 'tailwindcss';
+@import 'question-bank-framework/framework/styles/theme.css';
+@source '../node_modules/question-bank-framework'; /* relative to this file */
+```
+
+Pass `hideTagsColumn: true` to `defineBank` when tags merely duplicate
+dedicated fields (every tag equals a topic/type value already in its own
+column). Tags still feed free-text search.
 
 ## Reveal (eject) files
 

package/core/config.tsx

@@ -31,8 +31,22 @@ export type {
   BankSiteConfig,
   BaseQuestion,
   DefineBankInput,
+  QuestionKind,
+  QuestionOption,
   QuestionStatus,
   QuestionStatusMap,
+  QuizAnswer,
   QuizSession,
 } from './types.ts';
+export {
+  getCorrectIds,
+  isAnswerCorrect,
+  isAnswerProvided,
+  isChoiceQuestion,
+  questionKind,
+  questionKindLabels,
+  questionKinds,
+  scoreAnswers,
+  toSelectedIds,
+} from './types.ts';
 export { questionStatuses } from './types.ts';

package/core/index.ts

@@ -1,7 +1,22 @@
 // Re-export the stable core: types + BankContext/useBank/defineBank.
 // Framework code (ejectable) lives under framework/.
 
-export { BankContext, BankProvider, useBank, defineBank, questionStatuses } from './config.tsx';
+export {
+  BankContext,
+  BankProvider,
+  useBank,
+  defineBank,
+  getCorrectIds,
+  isAnswerCorrect,
+  isAnswerProvided,
+  isChoiceQuestion,
+  questionKind,
+  questionKindLabels,
+  questionKinds,
+  questionStatuses,
+  scoreAnswers,
+  toSelectedIds,
+} from './config.tsx';
 export type {
   Bank,
   BankFieldDef,
@@ -11,7 +26,10 @@ export type {
   BankSiteConfig,
   BaseQuestion,
   DefineBankInput,
+  QuestionKind,
+  QuestionOption,
   QuestionStatus,
   QuestionStatusMap,
+  QuizAnswer,
   QuizSession,
 } from './config.tsx';

package/core/types.ts

@@ -8,11 +8,41 @@ export const questionStatuses = ['unanswered', 'revisit', 'complete'] as const;
 export type QuestionStatus = (typeof questionStatuses)[number];
 export type QuestionStatusMap = Record<string, QuestionStatus>;
 
+// ---------------------------------------------------------------------------
+// Question kinds: written (free response) vs choice (auto-gradeable).
+// ---------------------------------------------------------------------------
+
+export type QuestionKind = 'written' | 'single' | 'multiple';
+
+export const questionKinds: readonly QuestionKind[] = ['written', 'single', 'multiple'];
+
+export const questionKindLabels: Record<QuestionKind, string> = {
+  written: 'Written',
+  single: 'Single choice',
+  multiple: 'Multiple choice',
+};
+
+export interface QuestionOption {
+  /** Stable within the question, e.g. "a", "b", "c". */
+  id: string;
+  /** Option body. Markdown supported. */
+  text: string;
+}
+
+/** Written answers are free text; choice answers are selected option ids. */
+export type QuizAnswer = string | string[];
+
 export interface BaseQuestion {
   id: string;
   title: string;
   prompt: string;
   tags: string[];
+  /** Defaults to 'written' when omitted. Choice kinds require options + correctIds. */
+  kind?: QuestionKind;
+  /** Choice options. Required for single/multiple, forbidden for written. */
+  options?: QuestionOption[];
+  /** Correct option ids. Single choice requires exactly one. */
+  correctIds?: string[];
   // Subjects extend this interface with their own fields; see template/bank.config.ts.
 }
 
@@ -20,7 +50,7 @@ export interface QuizSession {
   id: string;
   title: string;
   questionIds: string[];
-  answers: Record<string, string>;
+  answers: Record<string, QuizAnswer>;
   currentQuestion: number;
   completed: boolean;
   createdAt: number;
@@ -99,6 +129,13 @@ export interface DefineBankInput<Q extends BaseQuestion = BaseQuestion> {
   answers?: Record<string, string>;
   /** Default sort for the grid, e.g. [{ id: "exam", desc: true }]. */
   defaultSorting?: Array<{ id: string; desc?: boolean }>;
+  /**
+   * Hide the built-in Tags column (and the Tags filter option). Useful when
+   * tags merely duplicate dedicated fields — e.g. every tag equals a
+   * topic/type value already shown in its own column. Tags still feed
+   * free-text search. Defaults to false.
+   */
+  hideTagsColumn?: boolean;
   /** Extra per-question figures, resolved by prompt `![](/figures/…)` etc. */
   publicPath?: string;
 }
@@ -114,9 +151,124 @@ export interface Bank extends DefineBankInput<BaseQuestion> {
  * access, no casts or coercion helpers.
  */
 export function defineBank<Q extends BaseQuestion>(input: DefineBankInput<Q>): Bank {
+  for (const question of input.questions) {
+    validateQuestion(question);
+  }
   return {
     ...input,
     answers: input.answers ?? {},
     questionById: new Map(input.questions.map((q) => [q.id, q])),
   };
 }
+
+function validateQuestion(question: BaseQuestion): void {
+  const kind: QuestionKind = question.kind ?? 'written';
+  if (!questionKinds.includes(kind)) {
+    throw new Error(`Question "${question.id}" has unknown kind "${question.kind}".`);
+  }
+  if (kind === 'written') {
+    if (question.options !== undefined) {
+      throw new Error(`Question "${question.id}" is written and must not define options.`);
+    }
+    if (question.correctIds !== undefined) {
+      throw new Error(`Question "${question.id}" is written and must not define correctIds.`);
+    }
+    return;
+  }
+  const options = question.options ?? [];
+  if (options.length < 2) {
+    throw new Error(`Question "${question.id}" (${kind}) needs at least 2 options.`);
+  }
+  const seen = new Set<string>();
+  for (const option of options) {
+    if (!option.id || seen.has(option.id)) {
+      throw new Error(`Question "${question.id}" has a duplicate or empty option id "${option.id}".`);
+    }
+    seen.add(option.id);
+  }
+  const correctIds = question.correctIds ?? [];
+  if (kind === 'single' && correctIds.length !== 1) {
+    throw new Error(`Question "${question.id}" (single) needs exactly one correctId.`);
+  }
+  if (kind === 'multiple' && correctIds.length < 1) {
+    throw new Error(`Question "${question.id}" (multiple) needs at least one correctId.`);
+  }
+  for (const id of correctIds) {
+    if (!seen.has(id)) {
+      throw new Error(`Question "${question.id}" has unknown correctId "${id}".`);
+    }
+  }
+}
+
+// ---------------------------------------------------------------------------
+// Choice helpers. All UI + scoring goes through these so option storage
+// (ids) stays decoupled from presentation (letters, markdown).
+// ---------------------------------------------------------------------------
+
+/** Effective kind: questions without `kind` are written. */
+export function questionKind(question: BaseQuestion): QuestionKind {
+  return question.kind ?? 'written';
+}
+
+export function isChoiceQuestion(question: BaseQuestion): boolean {
+  const kind = questionKind(question);
+  return kind === 'single' || kind === 'multiple';
+}
+
+/** Correct option ids. Empty for written questions. */
+export function getCorrectIds(question: BaseQuestion): string[] {
+  return isChoiceQuestion(question) ? [...(question.correctIds ?? [])] : [];
+}
+
+/** Normalize a stored answer to selected option ids — tolerates legacy strings. */
+export function toSelectedIds(question: BaseQuestion, answer: QuizAnswer | undefined): string[] {
+  if (answer === undefined) return [];
+  const ids =
+    typeof answer === 'string' ? (answer === '' ? [] : [answer]) : answer.filter((id) => typeof id === 'string');
+  if (!isChoiceQuestion(question)) return ids;
+  const valid = new Set((question.options ?? []).map((o) => o.id));
+  return ids.filter((id) => valid.has(id));
+}
+
+/** Whether the user has provided an answer (non-blank text, or ≥1 selection). */
+export function isAnswerProvided(question: BaseQuestion, answer: QuizAnswer | undefined): boolean {
+  if (answer === undefined) return false;
+  if (typeof answer === 'string') return answer.trim().length > 0;
+  if (!isChoiceQuestion(question)) return answer.some((id) => id.trim().length > 0);
+  const valid = new Set((question.options ?? []).map((o) => o.id));
+  return answer.some((id) => valid.has(id));
+}
+
+/**
+ * Grade a choice answer. Returns null for written questions or when
+ * unanswered. Single: exactly the correct id. Multiple: exact set match
+ * (order-insensitive, no extras, no omissions).
+ */
+export function isAnswerCorrect(question: BaseQuestion, answer: QuizAnswer | undefined): boolean | null {
+  if (!isChoiceQuestion(question)) return null;
+  if (!isAnswerProvided(question, answer)) return null;
+  const selected = new Set(toSelectedIds(question, answer));
+  const correct = new Set(getCorrectIds(question));
+  if (selected.size !== correct.size) return false;
+  for (const id of selected) {
+    if (!correct.has(id)) return false;
+  }
+  return true;
+}
+
+/** Score a set of questions against answers: { correct, gradeable, answered }. */
+export function scoreAnswers(
+  questions: readonly BaseQuestion[],
+  answers: Record<string, QuizAnswer>,
+): { correct: number; gradeable: number; answered: number } {
+  let correct = 0;
+  let gradeable = 0;
+  let answered = 0;
+  for (const question of questions) {
+    if (isAnswerProvided(question, answers[question.id])) answered += 1;
+    if (!isChoiceQuestion(question)) continue;
+    gradeable += 1;
+    if (isAnswerCorrect(question, answers[question.id]) === true) correct += 1;
+  }
+  return { correct, gradeable, answered };
+}

package/framework/components/question-bank.tsx

@@ -17,14 +17,15 @@ import {
 } from '@tanstack/react-table';
 import { Search } from 'lucide-react';
 import { useBank } from '../../core/config.tsx';
-import type { BaseQuestion, QuestionStatus, QuestionStatusMap } from '../../core/types.ts';
+import type { BaseQuestion, QuestionKind, QuestionStatus, QuestionStatusMap, QuizSession } from '../../core/types.ts';
+import { isChoiceQuestion, questionKind, questionKindLabels } from '../../core/types.ts';
 import { Badge } from './ui/badge';
 import { Button } from './ui/button';
 import { Checkbox } from './ui/checkbox';
 import { Input } from './ui/input';
 import { FilterBuilder } from './filter-builder';
 import { MarkdownContent } from './markdown-content';
-import { Popover, PopoverAnchor, PopoverContent } from './ui/popover';
+import { Popover, PopoverAnchor, PopoverContent, PopoverTrigger } from './ui/popover';
 import { Table, TableBody, TableCell, TableHead, TableHeader, TableRow } from './ui/table';
 import {
   createFilterFields,
@@ -36,7 +37,7 @@ import {
 import { useQuestionFilterStore } from '../lib/question-filter-store.ts';
 import { cn } from '../lib/utils.ts';
 import { getQuestionStatuses } from '../lib/question-status-storage.ts';
-import { createQuiz } from '../lib/quiz-storage.ts';
+import { createQuiz, listQuizzes, setQuizQuestions } from '../lib/quiz-storage.ts';
 
 type DragSelection = {
   value: boolean;
@@ -59,6 +60,14 @@ const questionStatusStyles: Record<QuestionStatus, string> = {
   complete: 'border-green-300 bg-green-50 text-green-800',
 };
 
+const questionKindStyles: Record<QuestionKind, string> = {
+  written: 'border-gray-300 bg-gray-50 text-gray-700',
+  single: 'border-sky-300 bg-sky-50 text-sky-900',
+  multiple: 'border-violet-300 bg-violet-50 text-violet-900',
+};
+
+const optionLetter = (index: number): string => String.fromCharCode(65 + index);
+
 function QuestionPreviewPopover({ question }: { question: BaseQuestion }) {
   const [open, setOpen] = useState(false);
   const openTimeout = useRef<number | null>(null);
@@ -163,6 +172,18 @@ function QuestionPreviewPopover({ question }: { question: BaseQuestion }) {
       >
         <div className="px-4 py-3">
           <MarkdownContent content={question.prompt} />
+          {isChoiceQuestion(question) && (
+            <ol className="mt-3 space-y-1.5">
+              {(question.options ?? []).map((option, index) => (
+                <li key={option.id} className="flex items-start gap-2 text-sm text-gray-800">
+                  <span className="mt-0.5 flex size-5 shrink-0 items-center justify-center rounded-full border border-gray-300 bg-gray-50 text-[11px] font-bold text-gray-600">
+                    {optionLetter(index)}
+                  </span>
+                  <MarkdownContent content={option.text} className="min-w-0 flex-1 text-sm leading-6" />
+                </li>
+              ))}
+            </ol>
+          )}
         </div>
       </PopoverContent>
     </Popover>
@@ -193,6 +214,10 @@ export function QuestionBank() {
     (bank.defaultSorting ?? [{ id: 'id' }]).map((s) => ({ id: s.id, desc: s.desc ?? false })),
   );
   const [creatingQuiz, setCreatingQuiz] = useState(false);
+  const [addToQuizOpen, setAddToQuizOpen] = useState(false);
+  const [existingQuizzes, setExistingQuizzes] = useState<QuizSession[] | null>(null);
+  const [addingToQuizId, setAddingToQuizId] = useState<string | null>(null);
+  const [addToQuizError, setAddToQuizError] = useState(false);
   const tableContainerRef = useRef<HTMLDivElement>(null);
   const rowSelectionRef = useRef(rowSelection);
   rowSelectionRef.current = rowSelection;
@@ -200,7 +225,18 @@ export function QuestionBank() {
   const pendingCheckboxChange = useRef<{ rowId: string; value: boolean } | null>(null);
   const suppressRowClick = useRef<string | null>(null);
 
-  const filterFields = useMemo(() => createFilterFields(bank.questions, bank.fields), [bank]);
+  const filterFields = useMemo(
+    () => createFilterFields(bank.questions, bank.fields, bank.hideTagsColumn ?? false),
+    [bank],
+  );
+
+  // Size the ID column to the data: fits typical ids on one line, caps
+  // monsters (they wrap via break-all). Mono averages ~8.4px/char at
+  // text-sm, plus px-4 padding. e.g. econ ≈168, info hits the 320 cap.
+  const idWidth = useMemo(() => {
+    const longest = bank.questions.reduce((n, q) => Math.max(n, q.id.length), 0);
+    return Math.min(320, Math.max(120, Math.ceil(longest * 8.4 + 32)));
+  }, [bank.questions]);
 
   const handleAddFilter = (field: string) => {
     const type = filterFields.find((f) => f.id === field)?.type ?? 'text';
@@ -258,7 +294,7 @@ export function QuestionBank() {
                 </div>
               );
             }
-            return <span className="text-sm text-foreground">{formatCellValue(raw)}</span>;
+            return <span className="whitespace-normal break-words text-sm text-foreground">{formatCellValue(raw)}</span>;
           },
           enableSorting: sortable,
           size: width,
@@ -314,28 +350,58 @@ export function QuestionBank() {
       {
         accessorKey: 'id',
         header: 'ID',
-        cell: ({ row }) => <span className="font-mono text-sm text-muted-foreground">{row.original.id}</span>,
-        size: 104,
+        cell: ({ row }) => (
+          <span className="whitespace-normal break-all font-mono text-sm text-muted-foreground">{row.original.id}</span>
+        ),
+        size: idWidth,
       },
       {
+        // Sole absorbent column: no fixed size, so it takes up slack on wide
+        // screens instead of leaving dead space. Table min-width (below)
+        // always reserves 300px for it, so it can never collapse — and text
+        // wraps, so it can never paint over neighbours either.
         accessorKey: 'title',
         header: 'Question',
         cell: ({ row }) => <QuestionPreviewPopover question={row.original} />,
-        size: 340,
       },
+      // Absorbent like title: no fixed size, takes up slack on wide screens.
+      // minTableWidth (below) always reserves 200px for it, so it can
+      // never collapse to zero the way it did when the fixed columns
+      // already summed past the old 1200px floor.
+      // Hidden entirely when the bank sets hideTagsColumn (tags that merely
+      // duplicate dedicated fields).
+      ...(bank.hideTagsColumn
+        ? []
+        : [
+            {
+              id: 'tags',
+              accessorFn: (row) => row.tags.join(', '),
+              header: 'Tags',
+              cell: ({ row }) => (
+                <div className="flex min-w-0 flex-wrap gap-1">
+                  {row.original.tags.map((tag) => (
+                    <Badge key={tag} variant="secondary" className="min-w-0 whitespace-normal break-words">
+                      {tag}
+                    </Badge>
+                  ))}
+                </div>
+              ),
+            } satisfies ColumnDef<BaseQuestion>,
+          ]),
       {
-        id: 'tags',
-        accessorFn: (row) => row.tags.join(', '),
-        header: 'Tags',
-        cell: ({ row }) => (
-          <div className="flex flex-wrap gap-1">
-            {row.original.tags.map((tag) => (
-              <Badge key={tag} variant="secondary">
-                {tag}
-              </Badge>
-            ))}
-          </div>
-        ),
+        id: 'kind',
+        accessorFn: (row) => questionKind(row),
+        header: 'Type',
+        cell: ({ row }) => {
+          const kind = questionKind(row.original);
+          const count = row.original.options?.length ?? 0;
+          return (
+            <Badge variant="outline" className={questionKindStyles[kind]} title={count > 0 ? `${count} options` : undefined}>
+              {questionKindLabels[kind]}
+            </Badge>
+          );
+        },
+        size: 132,
       },
       ...customs,
       {
@@ -353,7 +419,22 @@ export function QuestionBank() {
         size: 108,
       },
     ];
-  }, [bank.fields, questionStatusMap]);
+  }, [bank.fields, bank.hideTagsColumn, idWidth, questionStatusMap]);
+
+  // Floor the table width at the sum of fixed columns plus 300px for the
+  // absorbent title and 200px for the absorbent tags, so neither can ever
+  // collapse to zero (which squeezed content over neighbouring columns).
+  const minTableWidth = useMemo(() => {
+    let total = 0;
+    for (const column of columns) {
+      // ColumnDef inputs use accessorKey instead of id for the id/title columns.
+      const key = column.id ?? (column as { accessorKey?: string }).accessorKey;
+      if (key === 'title') total += 300;
+      else if (key === 'tags') total += 200;
+      else total += column.size ?? 150;
+    }
+    return Math.max(1200, total);
+  }, [columns]);
 
   const table = useReactTable({
     data: filteredQuestions,
@@ -512,6 +593,32 @@ export function QuestionBank() {
     }
   };
 
+  const openAddToQuiz = (open: boolean) => {
+    setAddToQuizOpen(open);
+    if (!open) return;
+    setExistingQuizzes(null);
+    setAddToQuizError(false);
+    listQuizzes(bank.namespace).then(setExistingQuizzes, () => setExistingQuizzes([]));
+  };
+
+  const addToQuiz = async (quiz: QuizSession) => {
+    const existing = new Set(quiz.questionIds);
+    const additions = bank.questions.filter((question) => rowSelection[question.id] && !existing.has(question.id));
+    setAddingToQuizId(quiz.id);
+    setAddToQuizError(false);
+    try {
+      if (additions.length > 0) {
+        await setQuizQuestions(bank.namespace, quiz, [...quiz.questionIds, ...additions.map((question) => question.id)]);
+      }
+      setAddToQuizOpen(false);
+      await navigate({ to: '/quiz/$quizId', params: { quizId: quiz.id } });
+    } catch {
+      setAddToQuizError(true);
+    } finally {
+      setAddingToQuizId(null);
+    }
+  };
+
   return (
     <div className="flex min-h-0 flex-1 flex-col">
       <div className="border-b bg-background px-4 py-3">
@@ -544,14 +651,16 @@ export function QuestionBank() {
         </div>
       </div>
 
-      <Table containerRef={tableContainerRef} containerClassName="min-h-0 flex-1 overflow-auto" className="min-w-[1200px] table-fixed">
+      <Table containerRef={tableContainerRef} containerClassName="min-h-0 flex-1 overflow-auto" className="table-fixed" style={{ minWidth: minTableWidth }}>
         <TableHeader>
           {table.getHeaderGroups().map((headerGroup) => (
             <TableRow key={headerGroup.id}>
               {headerGroup.headers.map((header) => (
                 <TableHead
                   key={header.id}
-                  style={header.column.id === 'tags' ? undefined : { width: header.getSize() }}
+                  // Title and tags are the absorbent columns (no width → take up
+                  // slack on wide screens). minTableWidth below floors them.
+                  style={header.column.id === 'tags' || header.column.id === 'title' ? undefined : { width: header.getSize() }}
                   className="sticky top-0 z-10 h-12 border-b bg-muted px-4 text-sm font-semibold text-foreground"
                 >
                   {header.isPlaceholder ? null : header.column.getCanSort() ? (
@@ -598,7 +707,10 @@ export function QuestionBank() {
                     {row.getVisibleCells().map((cell) => (
                       <TableCell
                         key={cell.id}
-                        className={cn('border-b px-4 py-2 align-middle', cell.column.id === 'title' && 'whitespace-normal')}
+                        className={cn(
+                          'border-b px-4 py-2 align-middle',
+                          cell.column.id === 'title' && 'whitespace-normal break-words',
+                        )}
                         onClick={cell.column.id === 'select' ? (event) => event.stopPropagation() : undefined}
                       >
                         {flexRender(cell.column.columnDef.cell, cell.getContext())}
@@ -642,7 +754,51 @@ export function QuestionBank() {
           <Button variant="ghost" className="text-base" onClick={() => setRowSelection({})}>
             Clear
           </Button>
-          <div className="ml-auto">
+          <div className="ml-auto flex gap-2">
+            <Popover open={addToQuizOpen} onOpenChange={openAddToQuiz}>
+              <PopoverTrigger asChild>
+                <Button variant="outline" className="text-base">
+                  Add to quiz
+                </Button>
+              </PopoverTrigger>
+              <PopoverContent side="top" align="end" className="w-80 p-1">
+                {existingQuizzes === null ? (
+                  <p className="m-0 px-3 py-4 text-center text-sm text-muted-foreground">Loading quizzes...</p>
+                ) : existingQuizzes.length === 0 ? (
+                  <p className="m-0 px-3 py-4 text-center text-sm text-muted-foreground">No quizzes yet. Use "Make quiz" instead.</p>
+                ) : (
+                  <ul className="m-0 max-h-72 list-none overflow-y-auto p-0">
+                    {existingQuizzes.map((quiz) => {
+                      const newCount = selectedIds.filter((id) => !quiz.questionIds.includes(id)).length;
+                      return (
+                        <li key={quiz.id}>
+                          <button
+                            type="button"
+                            disabled={addingToQuizId !== null}
+                            onClick={() => addToQuiz(quiz)}
+                            className="flex w-full flex-col items-start rounded-sm px-3 py-2 text-left hover:bg-muted focus-visible:bg-muted focus-visible:outline-none disabled:opacity-50"
+                          >
+                            <span className="text-sm font-medium">{quiz.title}</span>
+                            <span className="text-xs text-muted-foreground">
+                              {addingToQuizId === quiz.id
+                                ? 'Adding...'
+                                : `${quiz.questionIds.length} ${quiz.questionIds.length === 1 ? 'question' : 'questions'} • ${
+                                    newCount === 0 ? 'all selected already included' : `+${newCount} new`
+                                  }`}
+                            </span>
+                          </button>
+                        </li>
+                      );
+                    })}
+                  </ul>
+                )}
+                {addToQuizError && (
+                  <p role="alert" className="m-0 px-3 py-2 text-sm text-red-700">
+                    Could not add to that quiz. Please try again.
+                  </p>
+                )}
+              </PopoverContent>
+            </Popover>
             <Button className="text-base" onClick={makeQuiz} disabled={creatingQuiz}>
               {creatingQuiz ? 'Making quiz...' : 'Make quiz'}
             </Button>