question-bank-framework 0.1.1 → 0.3.0

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,7 +231,9 @@ function resolveFieldValue(
     if (ruleField === 'title') return question.title;
     if (ruleField === 'id') return question.id;
     if (ruleField === 'tags') return question.tags;
-    return (question[ruleField] as string | number | null | readonly string[]) ?? null;
+    // 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);
 }
@@ -321,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);
@@ -344,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,
@@ -352,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.1.1",
+  "version": "0.3.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/bank.config.ts

@@ -3,26 +3,20 @@
 // config-defined — the framework never hardcodes subject fields.
 
 import { defineBank } from 'question-bank-framework';
+import type { BaseQuestion } from 'question-bank-framework';
 import questionsJson from './content/questions.json' with { type: 'json' };
 import { answers } from './content/answers.ts';
-import type { BaseQuestion } from 'question-bank-framework';
-
-const questions = questionsJson as BaseQuestion[];
 
-const str = (q: BaseQuestion, key: string): string => {
-  const v = q[key];
-  return typeof v === 'string' || typeof v === 'number' ? String(v) : '';
-};
+/** Subject question shape. Declare every field your accessors touch. */
+export interface Comp20008Question extends BaseQuestion {
+  year: number;
+  semester: string;
+  number: number;
+  marks: number | null;
+  source: string;
+}
 
-const num = (q: BaseQuestion, key: string): number | null => {
-  const v = q[key];
-  if (typeof v === 'number' && Number.isFinite(v)) return v;
-  if (typeof v === 'string' && v.trim() !== '') {
-    const n = Number(v);
-    return Number.isFinite(n) ? n : null;
-  }
-  return null;
-};
+const questions = questionsJson as Comp20008Question[];
 
 export const bank = defineBank({
   site: {
@@ -36,14 +30,14 @@ export const bank = defineBank({
       id: 'year',
       label: 'Year',
       type: 'select',
-      getValue: (q) => (typeof q['year'] === 'number' ? String(q['year']) : ''),
+      getValue: (q) => String(q.year),
       searchable: true,
     },
     {
       id: 'semester',
       label: 'Semester',
       type: 'select',
-      getValue: (q) => str(q, 'semester'),
+      getValue: (q) => q.semester,
       options: [
         { value: 'S1', label: 'Semester 1' },
         { value: 'S2', label: 'Semester 2' },
@@ -53,7 +47,7 @@ export const bank = defineBank({
       id: 'exam',
       label: 'Exam',
       type: 'text',
-      getValue: (q) => `${str(q, 'year')} ${str(q, 'semester')}`.trim(),
+      getValue: (q) => `${q.year} ${q.semester}`,
       searchable: true,
       column: { header: 'Exam', width: 108, sortable: false },
     },
@@ -61,7 +55,7 @@ export const bank = defineBank({
       id: 'marks',
       label: 'Marks',
       type: 'number',
-      getValue: (q) => num(q, 'marks'),
+      getValue: (q) => q.marks,
       placeholder: 'Value',
       column: { header: 'Marks', width: 78 },
     },

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';