question-bank-framework 0.2.0 → 0.4.0

package/framework/components/quiz-question-editor.tsx

@@ -0,0 +1,171 @@
+// Framework-owned: eject with `qb reveal framework/components/quiz-question-editor.tsx`.
+
+import { useEffect, useState } from 'react';
+import { ArrowDown, ArrowUp, GripVertical, Shuffle, Trash2 } from 'lucide-react';
+import { useBank } from '../../core/config.tsx';
+import type { QuizSession } from '../../core/types.ts';
+import { Button } from './ui/button';
+import { Sheet, SheetContent, SheetDescription, SheetFooter, SheetHeader, SheetTitle } from './ui/sheet';
+import { cn } from '../lib/utils.ts';
+
+const move = (ids: string[], from: number, to: number) => {
+  const next = [...ids];
+  const [item] = next.splice(from, 1);
+  if (item !== undefined) next.splice(to, 0, item);
+  return next;
+};
+
+export function QuizQuestionEditor({
+  quiz,
+  onOpenChange,
+  onSave,
+}: {
+  quiz: QuizSession | null;
+  onOpenChange: (open: boolean) => void;
+  onSave: (quiz: QuizSession, questionIds: string[]) => Promise<void>;
+}) {
+  const bank = useBank();
+  const [ids, setIds] = useState<string[]>([]);
+  const [dragIndex, setDragIndex] = useState<number | null>(null);
+  const [saving, setSaving] = useState(false);
+  const [saveError, setSaveError] = useState(false);
+
+  useEffect(() => {
+    if (!quiz) return;
+    setIds(quiz.questionIds);
+    setSaveError(false);
+  }, [quiz]);
+
+  const changed = quiz !== null && (ids.length !== quiz.questionIds.length || ids.some((id, index) => id !== quiz.questionIds[index]));
+
+  const shuffle = () => {
+    setIds((current) => {
+      if (current.length < 2) return current;
+      const next = [...current];
+      for (let i = next.length - 1; i > 0; i--) {
+        const j = Math.floor(Math.random() * (i + 1));
+        [next[i], next[j]] = [next[j] as string, next[i] as string];
+      }
+      return next;
+    });
+  };
+
+  const save = async () => {
+    if (!quiz) return;
+    setSaving(true);
+    setSaveError(false);
+    try {
+      await onSave(quiz, ids);
+      onOpenChange(false);
+    } catch {
+      setSaveError(true);
+    } finally {
+      setSaving(false);
+    }
+  };
+
+  return (
+    <Sheet open={quiz !== null} onOpenChange={onOpenChange}>
+      <SheetContent className="w-full gap-0 sm:max-w-md">
+        <SheetHeader className="border-b">
+          <SheetTitle>Edit questions</SheetTitle>
+          <SheetDescription>{quiz?.title}. Drag to reorder, or remove questions you no longer want.</SheetDescription>
+          <div className="mt-2 flex items-center justify-between gap-2">
+            <span className="text-sm text-muted-foreground">
+              {ids.length} {ids.length === 1 ? 'question' : 'questions'}
+            </span>
+            <Button
+              type="button"
+              variant="outline"
+              size="sm"
+              onClick={shuffle}
+              disabled={ids.length < 2}
+              aria-label="Shuffle question order"
+              title="Shuffle question order"
+            >
+              <Shuffle aria-hidden="true" />
+              Shuffle
+            </Button>
+          </div>
+        </SheetHeader>
+        <ol className="m-0 min-h-0 flex-1 list-none overflow-y-auto p-2">
+          {ids.map((id, index) => (
+            <li
+              key={id}
+              draggable
+              onDragStart={(event) => {
+                setDragIndex(index);
+                event.dataTransfer.effectAllowed = 'move';
+              }}
+              onDragOver={(event) => {
+                event.preventDefault();
+                if (dragIndex === null || dragIndex === index) return;
+                setIds((current) => move(current, dragIndex, index));
+                setDragIndex(index);
+              }}
+              onDragEnd={() => setDragIndex(null)}
+              className={cn(
+                'flex items-center gap-2 rounded-md border border-transparent px-2 py-2 hover:bg-muted',
+                dragIndex === index && 'border-gray-300 bg-muted opacity-60',
+              )}
+            >
+              <GripVertical aria-hidden="true" className="size-4 shrink-0 cursor-grab text-muted-foreground" />
+              <span className="w-6 shrink-0 text-right text-sm tabular-nums text-muted-foreground">{index + 1}</span>
+              <span className="min-w-0 flex-1 truncate text-sm">{bank.questionById.get(id)?.title ?? id}</span>
+              <Button
+                type="button"
+                variant="ghost"
+                size="icon-xs"
+                aria-label="Move up"
+                disabled={index === 0}
+                onClick={() => setIds((current) => move(current, index, index - 1))}
+              >
+                <ArrowUp aria-hidden="true" />
+              </Button>
+              <Button
+                type="button"
+                variant="ghost"
+                size="icon-xs"
+                aria-label="Move down"
+                disabled={index === ids.length - 1}
+                onClick={() => setIds((current) => move(current, index, index + 1))}
+              >
+                <ArrowDown aria-hidden="true" />
+              </Button>
+              <Button
+                type="button"
+                variant="ghost"
+                size="icon-xs"
+                aria-label="Remove question"
+                className="text-red-600 hover:bg-red-50 hover:text-red-700"
+                onClick={() => setIds((current) => current.filter((item) => item !== id))}
+              >
+                <Trash2 aria-hidden="true" />
+              </Button>
+            </li>
+          ))}
+          {ids.length === 0 && (
+            <li className="px-2 py-8 text-center text-sm text-muted-foreground">
+              No questions left. Delete the quiz instead if you no longer need it.
+            </li>
+          )}
+        </ol>
+        <SheetFooter className="border-t">
+          {saveError && (
+            <p role="alert" className="m-0 text-sm text-red-700">
+              Could not save changes. Please try again.
+            </p>
+          )}
+          <div className="flex justify-end gap-2">
+            <Button type="button" variant="ghost" onClick={() => onOpenChange(false)}>
+              Cancel
+            </Button>
+            <Button type="button" onClick={save} disabled={!changed || ids.length === 0 || saving}>
+              {saving ? 'Saving...' : 'Save'}
+            </Button>
+          </div>
+        </SheetFooter>
+      </SheetContent>
+    </Sheet>
+  );
+}

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.string()),
+    answers: v.record(v.string(), v.union(v.string(), v.array(v.string()))),
     currentQuestion: v.number(),
     completed: v.boolean(),
   },
@@ -48,3 +48,15 @@ export const saveProgress = mutation({
     await ctx.db.patch(quizId, { title, answers, currentQuestion, completed })
   },
 })
+
+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()))),
+    currentQuestion: v.number(),
+  },
+  handler: async (ctx, { quizId, questionIds, answers, currentQuestion }) => {
+    await ctx.db.patch(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.string()),
+    answers: v.record(v.string(), v.union(v.string(), v.array(v.string()))),
     currentQuestion: v.number(),
     completed: v.boolean(),
     createdAt: v.number(),

package/framework/lib/convex-api.ts

@@ -2,16 +2,22 @@
 // Framework-owned: eject with `qb reveal framework/lib/convex-api.ts`.
 
 import { makeFunctionReference } from 'convex/server';
-import type { QuestionStatus, QuizSession } from '../../core/types.ts';
+import type { QuestionStatus, QuizAnswer, QuizSession } from '../../core/types.ts';
 
 type CreateQuizArgs = { title: string; questionIds: string[] };
 type ProgressArgs = {
   quizId: string;
   title: string;
-  answers: Record<string, string>;
+  answers: Record<string, QuizAnswer>;
   currentQuestion: number;
   completed: boolean;
 };
+type SetQuestionsArgs = {
+  quizId: string;
+  questionIds: string[];
+  answers: Record<string, QuizAnswer>;
+  currentQuestion: number;
+};
 type QuizDocument = QuizSession & { _id: string; _creationTime: number };
 type QuestionStatusDocument = {
   _id: string;
@@ -28,6 +34,7 @@ export const convexApi = {
     list: makeFunctionReference<'query', Record<string, never>, QuizDocument[]>('quizzes:list'),
     remove: makeFunctionReference<'mutation', { quizId: string }, null>('quizzes:remove'),
     saveProgress: makeFunctionReference<'mutation', ProgressArgs, null>('quizzes:saveProgress'),
+    setQuestions: makeFunctionReference<'mutation', SetQuestionsArgs, null>('quizzes:setQuestions'),
   },
   questionStatuses: {
     list: makeFunctionReference<'query', Record<string, never>, QuestionStatusDocument[]>('questionStatuses:list'),

package/framework/lib/question-filter.ts

@@ -3,7 +3,7 @@
 // by config-defined `BankFieldDef[]` plus the three built-ins.
 // Framework-owned: eject with `qb reveal framework/lib/question-filter.ts`.
 
-import { questionStatuses, type BankFieldDef, type BankFilterOperatorId, type BaseQuestion, type QuestionStatus } from '../../core/types.ts';
+import { questionKind, questionKindLabels, questionKinds, questionStatuses, type BankFieldDef, type BankFilterOperatorId, type BaseQuestion, type QuestionStatus } from '../../core/types.ts';
 
 export type FilterMatch = 'and' | 'or';
 
@@ -101,6 +101,13 @@ function builtinFields(): FilterField[] {
     { id: 'title', label: 'Question', type: 'text', operators: textOperators, placeholder: 'Type a value…' },
     { id: 'id', label: 'ID', type: 'text', operators: textOperators, placeholder: 'Type a value…' },
     { id: 'tags', label: 'Tags', type: 'multiselect', operators: multiSelectOperators },
+    {
+      id: 'kind',
+      label: 'Type',
+      type: 'select',
+      operators: selectOperators,
+      options: questionKinds.map((kind) => ({ value: kind, label: questionKindLabels[kind] })),
+    },
     {
       id: 'status',
       label: 'Status',
@@ -128,7 +135,11 @@ function distinctStrings(values: Array<string | number | null | readonly string[
  * Build filter fields from bank config. Select/multiselect options default to
  * the distinct values across questions unless the field declares `options`.
  */
-export function createFilterFields(questions: readonly BaseQuestion[], fieldDefs: readonly BankFieldDef[]): FilterField[] {
+export function createFilterFields(
+  questions: readonly BaseQuestion[],
+  fieldDefs: readonly BankFieldDef[],
+  hideTagsColumn = false,
+): FilterField[] {
   const customs: FilterField[] = fieldDefs.map((def) => {
     let options: readonly FilterOption[] | undefined;
     if (def.options) {
@@ -156,7 +167,7 @@ export function createFilterFields(questions: readonly BaseQuestion[], fieldDefs
     };
   });
 
-  const builtins = builtinFields();
+  const builtins = builtinFields().filter((field) => !(hideTagsColumn && field.id === 'tags'));
   // Attach tag options derived from the bank (like the original).
   const tags = [...new Set(questions.flatMap((q) => q.tags))].sort((a, b) => a.localeCompare(b));
   const withTags = builtins.map((field) =>
@@ -220,8 +231,8 @@ function resolveFieldValue(
     if (ruleField === 'title') return question.title;
     if (ruleField === 'id') return question.id;
     if (ruleField === 'tags') return question.tags;
-    // status is handled by matchesRule before reaching here. Any other id
-    // is stale (no def, not a built-in) — match nothing.
+    // status/kind are handled by matchesRule before reaching here. Any other
+    // id is stale (no def, not a built-in) — match nothing.
     return null;
   }
   return def.getValue(question);
@@ -323,6 +334,7 @@ export function matchesRule(
 ): boolean {
   const type = filterFieldType(fields, rule.field);
   if (rule.field === 'status') return matchSelect(status, rule);
+  if (rule.field === 'kind') return matchSelect(questionKind(question), rule);
   const def = fieldDefs.find((d) => d.id === rule.field);
   const raw = resolveFieldValue(def, rule.field, question);
   if (type === 'text') return matchText(toText(raw), rule);
@@ -346,7 +358,7 @@ export function matchesFilters(
     : active.some((rule) => matchesRule(rule, fields, fieldDefs, question, status));
 }
 
-/** Free-text search across id/title/prompt/tags plus `searchable` custom fields. */
+/** Free-text search across id/title/prompt/tags/options plus `searchable` custom fields. */
 export function matchesSearch(
   question: BaseQuestion,
   query: string,
@@ -354,7 +366,13 @@ export function matchesSearch(
 ): boolean {
   const q = query.trim().toLowerCase();
   if (!q) return true;
-  const parts = [question.id, question.title, question.prompt, question.tags.join(' ')];
+  const parts = [
+    question.id,
+    question.title,
+    question.prompt,
+    question.tags.join(' '),
+    (question.options ?? []).map((o) => o.text).join(' '),
+  ];
   for (const def of fieldDefs) {
     if (!def.searchable) continue;
     const raw = def.getValue(question);

package/framework/lib/quiz-storage.ts

@@ -104,6 +104,28 @@ export async function saveQuizProgress(
   });
 }
 
+// Replaces a quiz's question list (reorder / remove / append). Answers for
+// removed questions are dropped and the current position is kept on the same
+// question where possible.
+export async function setQuizQuestions(namespace: string, session: QuizSession, questionIds: string[]): Promise<QuizSession> {
+  const kept = new Set(questionIds);
+  const answers = Object.fromEntries(Object.entries(session.answers).filter(([id]) => kept.has(id)));
+  const currentId = session.questionIds[session.currentQuestion];
+  const currentIndex = currentId === undefined ? -1 : questionIds.indexOf(currentId);
+  const currentQuestion = currentIndex >= 0 ? currentIndex : Math.min(session.currentQuestion, Math.max(questionIds.length - 1, 0));
+  const updated: QuizSession = { ...session, questionIds, answers, currentQuestion };
+  if (convexClient && !updated.id.startsWith('local_')) {
+    await convexClient.mutation(convexApi.quizzes.setQuestions, {
+      quizId: updated.id,
+      questionIds,
+      answers,
+      currentQuestion,
+    });
+  }
+  saveQuizLocally(namespace, updated);
+  return updated;
+}
+
 export async function listQuizzes(namespace: string): Promise<QuizSession[]> {
   const localQuizzes = readLocalQuizzes(namespace);
   if (!convexClient) return localQuizzes;

package/framework/styles/theme.css

@@ -0,0 +1,58 @@
+/* shadcn-style theme tokens consumed by question-bank-framework UI components.
+ * Import this from your app stylesheet (after tailwindcss) instead of
+ * copy-pasting the tokens, so every bank inherits upstream token changes:
+ *
+ *   @import 'tailwindcss';
+ *   @source '../node_modules/question-bank-framework';
+ *   @import 'question-bank-framework/framework/styles/theme.css';
+ */
+
+@theme inline {
+  --font-sans: 'DM Sans', ui-sans-serif, system-ui, sans-serif;
+  --font-display: 'Fraunces', Georgia, serif;
+  --font-mono: 'DM Mono', ui-monospace, monospace;
+  --radius-sm: calc(var(--radius) - 4px);
+  --radius-md: calc(var(--radius) - 2px);
+  --radius-lg: var(--radius);
+  --radius-xl: calc(var(--radius) + 4px);
+  --color-background: var(--background);
+  --color-foreground: var(--foreground);
+  --color-card: var(--card);
+  --color-card-foreground: var(--card-foreground);
+  --color-popover: var(--popover);
+  --color-popover-foreground: var(--popover-foreground);
+  --color-primary: var(--primary);
+  --color-primary-foreground: var(--primary-foreground);
+  --color-secondary: var(--secondary);
+  --color-secondary-foreground: var(--secondary-foreground);
+  --color-muted: var(--muted);
+  --color-muted-foreground: var(--muted-foreground);
+  --color-accent: var(--accent);
+  --color-accent-foreground: var(--accent-foreground);
+  --color-destructive: var(--destructive);
+  --color-border: var(--border);
+  --color-input: var(--input);
+  --color-ring: var(--ring);
+}
+
+:root {
+  --radius: 0.625rem;
+  --background: #ffffff;
+  --foreground: #111827;
+  --card: #ffffff;
+  --card-foreground: #111827;
+  --popover: #ffffff;
+  --popover-foreground: #111827;
+  --primary: #25564c;
+  --primary-foreground: #ffffff;
+  --secondary: #f1f5f2;
+  --secondary-foreground: #263a2f;
+  --muted: #f3f4f6;
+  --muted-foreground: #6b7280;
+  --accent: #eef3ef;
+  --accent-foreground: #263a2f;
+  --destructive: #b91c1c;
+  --border: #d1d5db;
+  --input: #d1d5db;
+  --ring: #78a589;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "question-bank-framework",
-  "version": "0.2.0",
+  "version": "0.4.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",
@@ -62,7 +62,6 @@
     "version-packages": "changeset version",
     "release": "pnpm build:bin && changeset publish",
     "reveal": "node ./bin/qb.js reveal",
-    "template:check": "node ./bin/qb.js check-template",
     "build:bin": "tsc bin/qb.ts --ignoreConfig --outDir bin --target es2022 --module nodenext --moduleResolution nodenext --strict --skipLibCheck --types node && chmod +x bin/qb.js"
   }
 }

package/template/content/answers.ts

@@ -3,4 +3,6 @@
 
 export const answers: Record<string, string> = {
   '2019-s1-q01': String.raw`**(a)** Not well-formed: several sibling top-level elements, so no single root.`,
+  '2019-s1-mc01': String.raw`Only **B** has a single root element with matching open and close tags. A never closes, C closes in the wrong order, and D is not an element at all.`,
+  '2019-s1-mc02': String.raw`Remove or correct physically impossible values (**A**), always investigate before discarding (**C**), and document any imputation (**D**). Deleting everything above the mean (**B**) discards roughly half of legitimate data.`,
 };

package/template/content/questions.json

@@ -1,6 +1,7 @@
 [
   {
     "id": "2019-s1-q01",
+    "kind": "written",
     "year": 2019,
     "semester": "S1",
     "number": 1,
@@ -12,6 +13,7 @@
   },
   {
     "id": "2019-s1-q02",
+    "kind": "written",
     "year": 2019,
     "semester": "S1",
     "number": 2,
@@ -23,6 +25,7 @@
   },
   {
     "id": "ioa-001",
+    "kind": "written",
     "year": 2026,
     "semester": "S2",
     "number": 1,
@@ -31,5 +34,43 @@
     "prompt": "What is your research question, and what result would count as evidence?",
     "source": "assignment-ioa",
     "tags": ["Assignment questions", "Justification"]
+  },
+  {
+    "id": "2019-s1-mc01",
+    "kind": "single",
+    "year": 2019,
+    "semester": "S1",
+    "number": 3,
+    "marks": 1,
+    "title": "Well-formed XML",
+    "prompt": "Which of the following XML documents is well-formed?",
+    "options": [
+      { "id": "a", "text": "`<subject>COMP20008<subject>`" },
+      { "id": "b", "text": "`<subject>COMP20008</subject>`" },
+      { "id": "c", "text": "`<subject><topic>COMP20008</subject></topic>`" },
+      { "id": "d", "text": "`COMP20008`" }
+    ],
+    "correctIds": ["b"],
+    "source": "2019-s1.md",
+    "tags": ["Data fundamentals", "Data, formats & databases"]
+  },
+  {
+    "id": "2019-s1-mc02",
+    "kind": "multiple",
+    "year": 2019,
+    "semester": "S1",
+    "number": 4,
+    "marks": 2,
+    "title": "Outlier handling",
+    "prompt": "A temperature sensor reports occasional extreme spikes. Which of the following are reasonable outlier-handling steps? **Select all that apply.**",
+    "options": [
+      { "id": "a", "text": "Remove spikes that are physically impossible for the sensor" },
+      { "id": "b", "text": "Delete every reading above the mean" },
+      { "id": "c", "text": "Flag spikes and investigate whether they coincide with known events" },
+      { "id": "d", "text": "Replace spikes with interpolated values and document the change" }
+    ],
+    "correctIds": ["a", "c", "d"],
+    "source": "2019-s1.md",
+    "tags": ["Data preparation", "Data quality & preparation"]
   }
 ]

package/template/src/routes/styles.css

@@ -0,0 +1,7 @@
+@import url('https://fonts.googleapis.com/css2?family=DM+Mono:wght@400;500&family=DM+Sans:wght@400;500;600;700;800&family=Fraunces:opsz,wght@9..144,600;9..144,700&display=swap');
+@import 'katex/dist/katex.min.css';
+@import 'tailwindcss';
+@import 'tw-animate-css';
+@import 'question-bank-framework/framework/styles/theme.css';
+
+@source '../../node_modules/question-bank-framework';