question-bank-framework 0.4.0 → 0.5.0

package/README.md

@@ -99,6 +99,33 @@ defineBank({
 });
 ```
 
+## Question kinds
+
+Every question has `id/title/prompt/tags`; `kind` (default `written`) picks the
+response UI and grading. All kinds except `written` are auto-graded in quizzes
+(Check answer → per-question feedback, the bank's answer shown as the explanation).
+
+| kind | extra fields | answer UI |
+|---|---|---|
+| `written` | — | free-text box; "Show answer" reveals `answers[id]` |
+| `single` | `options`, `correctIds` (exactly one) | radio list |
+| `multiple` | `options`, `correctIds` (≥ 1, exact-set match) | checkbox list |
+| `numerical` | `numeric: { value, tolerance?, unit? }` | number input; correct within ±`tolerance` (default exact). Accepts `1,756`, `1.2e3`. |
+| `matching` | shared `options`, `items: [{ id, text, correctId }]` | one dropdown per item, options lettered A, B, … |
+| `dropdown` | `blanks: [{ id, label?, options, correctId }]` | one dropdown per blank, each with its own options |
+
+```json
+{ "id": "q7", "kind": "matching", "title": "…", "prompt": "Match each join to its cost.", "tags": [],
+  "options": [{ "id": "a", "text": "Hash join" }, { "id": "b", "text": "Sort-merge join" }],
+  "items": [{ "id": "1", "text": "`3(M + N)`", "correctId": "a" }] }
+```
+
+Matching and dropdown questions earn partial credit per item/blank in the
+review (`gradeAnswer`), but only count as correct in the quiz score when every
+item is right. `defineBank` validates each question's fields against its kind
+and throws on mismatches (e.g. a `correctId` that isn't one of the options).
+Don't repeat the option list or answer table in `prompt`; the UI renders them.
+
 ## Dev
 
 ```sh

package/core/config.tsx

@@ -31,6 +31,10 @@ export type {
   BankSiteConfig,
   BaseQuestion,
   DefineBankInput,
+  DropdownBlank,
+  MatchingItem,
+  NumericAnswer,
+  PairingSlot,
   QuestionKind,
   QuestionOption,
   QuestionStatus,
@@ -40,13 +44,19 @@ export type {
 } from './types.ts';
 export {
   getCorrectIds,
+  getPairingSlots,
+  gradeAnswer,
   isAnswerCorrect,
   isAnswerProvided,
   isChoiceQuestion,
+  isGradeableQuestion,
+  isPairingQuestion,
+  parseNumericAnswer,
   questionKind,
   questionKindLabels,
   questionKinds,
   scoreAnswers,
+  toPairings,
   toSelectedIds,
 } from './types.ts';
 export { questionStatuses } from './types.ts';

package/core/index.ts

@@ -7,14 +7,20 @@ export {
   useBank,
   defineBank,
   getCorrectIds,
+  getPairingSlots,
+  gradeAnswer,
   isAnswerCorrect,
   isAnswerProvided,
   isChoiceQuestion,
+  isGradeableQuestion,
+  isPairingQuestion,
+  parseNumericAnswer,
   questionKind,
   questionKindLabels,
   questionKinds,
   questionStatuses,
   scoreAnswers,
+  toPairings,
   toSelectedIds,
 } from './config.tsx';
 export type {
@@ -26,6 +32,10 @@ export type {
   BankSiteConfig,
   BaseQuestion,
   DefineBankInput,
+  DropdownBlank,
+  MatchingItem,
+  NumericAnswer,
+  PairingSlot,
   QuestionKind,
   QuestionOption,
   QuestionStatus,

package/core/types.ts

@@ -9,17 +9,25 @@ export type QuestionStatus = (typeof questionStatuses)[number];
 export type QuestionStatusMap = Record<string, QuestionStatus>;
 
 // ---------------------------------------------------------------------------
-// Question kinds: written (free response) vs choice (auto-gradeable).
+// Question kinds. `written` is free response; every other kind is
+// auto-gradeable:
+//   single / multiple — pick option(s) from `options`
+//   numerical         — type a number, checked against `numeric`
+//   matching          — pair each of `items` with one of the shared `options`
+//   dropdown          — fill each of `blanks` from its own option list
 // ---------------------------------------------------------------------------
 
-export type QuestionKind = 'written' | 'single' | 'multiple';
+export type QuestionKind = 'written' | 'single' | 'multiple' | 'numerical' | 'matching' | 'dropdown';
 
-export const questionKinds: readonly QuestionKind[] = ['written', 'single', 'multiple'];
+export const questionKinds: readonly QuestionKind[] = ['written', 'single', 'multiple', 'numerical', 'matching', 'dropdown'];
 
 export const questionKindLabels: Record<QuestionKind, string> = {
   written: 'Written',
   single: 'Single choice',
   multiple: 'Multiple choice',
+  numerical: 'Numerical',
+  matching: 'Matching',
+  dropdown: 'Dropdowns',
 };
 
 export interface QuestionOption {
@@ -29,20 +37,61 @@ export interface QuestionOption {
   text: string;
 }
 
-/** Written answers are free text; choice answers are selected option ids. */
-export type QuizAnswer = string | string[];
+/** A left-hand row of a matching question, answered from the question's shared `options`. */
+export interface MatchingItem {
+  /** Stable within the question, e.g. "1", "2". */
+  id: string;
+  /** Row text. Markdown supported. */
+  text: string;
+  /** Id of the correct option in the question's `options`. */
+  correctId: string;
+}
+
+/** One blank of a dropdown question, with its own option list. */
+export interface DropdownBlank {
+  /** Stable within the question, e.g. "1", "key". */
+  id: string;
+  /** Text shown before the dropdown, e.g. "A possible candidate key is:". Markdown supported. */
+  label?: string;
+  options: QuestionOption[];
+  /** Id of the correct option in this blank's `options`. */
+  correctId: string;
+}
+
+/** Expected answer of a numerical question. */
+export interface NumericAnswer {
+  value: number;
+  /** Absolute tolerance: answers within ±tolerance of value are correct. Defaults to 0 (exact). */
+  tolerance?: number;
+  /** Unit shown next to the input, e.g. "I/Os" or "bytes". */
+  unit?: string;
+}
+
+/**
+ * Stored quiz answer:
+ *   written / numerical — the typed text
+ *   single / multiple   — selected option ids
+ *   matching / dropdown — item/blank id → chosen option id
+ */
+export type QuizAnswer = string | string[] | Record<string, string>;
 
 export interface BaseQuestion {
   id: string;
   title: string;
   prompt: string;
   tags: string[];
-  /** Defaults to 'written' when omitted. Choice kinds require options + correctIds. */
+  /** Defaults to 'written' when omitted. Each other kind requires its own answer fields (see below). */
   kind?: QuestionKind;
-  /** Choice options. Required for single/multiple, forbidden for written. */
+  /** Choice options (single/multiple), or the shared option list of a matching question. */
   options?: QuestionOption[];
-  /** Correct option ids. Single choice requires exactly one. */
+  /** Correct option ids (single/multiple). Single choice requires exactly one. */
   correctIds?: string[];
+  /** Rows to match (matching). */
+  items?: MatchingItem[];
+  /** Blanks to fill (dropdown). */
+  blanks?: DropdownBlank[];
+  /** Expected number (numerical). */
+  numeric?: NumericAnswer;
   // Subjects extend this interface with their own fields; see template/bank.config.ts.
 }
 
@@ -161,48 +210,110 @@ export function defineBank<Q extends BaseQuestion>(input: DefineBankInput<Q>): B
   };
 }
 
-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.`);
+type KindField = 'options' | 'correctIds' | 'items' | 'blanks' | 'numeric';
+
+const kindFields: Record<QuestionKind, readonly KindField[]> = {
+  written: [],
+  single: ['options', 'correctIds'],
+  multiple: ['options', 'correctIds'],
+  numerical: ['numeric'],
+  matching: ['options', 'items'],
+  dropdown: ['blanks'],
+};
+
+function validateOptionList(questionId: string, where: string, options: readonly QuestionOption[] | undefined): Set<string> {
+  const list = options ?? [];
+  if (list.length < 2) {
+    throw new Error(`Question "${questionId}" ${where} needs at least 2 options.`);
   }
   const seen = new Set<string>();
-  for (const option of options) {
+  for (const option of list) {
     if (!option.id || seen.has(option.id)) {
-      throw new Error(`Question "${question.id}" has a duplicate or empty option id "${option.id}".`);
+      throw new Error(`Question "${questionId}" ${where} 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.`);
+  return seen;
+}
+
+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 === 'multiple' && correctIds.length < 1) {
-    throw new Error(`Question "${question.id}" (multiple) needs at least one correctId.`);
+  const allowed = kindFields[kind];
+  for (const field of ['options', 'correctIds', 'items', 'blanks', 'numeric'] as const) {
+    if (question[field] !== undefined && !allowed.includes(field)) {
+      throw new Error(`Question "${question.id}" is ${kind} and must not define ${field}.`);
+    }
   }
-  for (const id of correctIds) {
-    if (!seen.has(id)) {
-      throw new Error(`Question "${question.id}" has unknown correctId "${id}".`);
+
+  switch (kind) {
+    case 'written':
+      return;
+    case 'single':
+    case 'multiple': {
+      const seen = validateOptionList(question.id, `(${kind})`, question.options);
+      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}".`);
+      }
+      return;
+    }
+    case 'numerical': {
+      const numeric = question.numeric;
+      if (!numeric || typeof numeric.value !== 'number' || !Number.isFinite(numeric.value)) {
+        throw new Error(`Question "${question.id}" (numerical) needs numeric.value as a finite number.`);
+      }
+      if (numeric.tolerance !== undefined && !(Number.isFinite(numeric.tolerance) && numeric.tolerance >= 0)) {
+        throw new Error(`Question "${question.id}" (numerical) has an invalid tolerance.`);
+      }
+      return;
+    }
+    case 'matching': {
+      const seen = validateOptionList(question.id, '(matching)', question.options);
+      const items = question.items ?? [];
+      if (items.length < 1) throw new Error(`Question "${question.id}" (matching) needs at least 1 item.`);
+      const itemIds = new Set<string>();
+      for (const item of items) {
+        if (!item.id || itemIds.has(item.id)) {
+          throw new Error(`Question "${question.id}" has a duplicate or empty item id "${item.id}".`);
+        }
+        itemIds.add(item.id);
+        if (!seen.has(item.correctId)) {
+          throw new Error(`Question "${question.id}" item "${item.id}" has unknown correctId "${item.correctId}".`);
+        }
+      }
+      return;
+    }
+    case 'dropdown': {
+      const blanks = question.blanks ?? [];
+      if (blanks.length < 1) throw new Error(`Question "${question.id}" (dropdown) needs at least 1 blank.`);
+      const blankIds = new Set<string>();
+      for (const blank of blanks) {
+        if (!blank.id || blankIds.has(blank.id)) {
+          throw new Error(`Question "${question.id}" has a duplicate or empty blank id "${blank.id}".`);
+        }
+        blankIds.add(blank.id);
+        const seen = validateOptionList(question.id, `blank "${blank.id}"`, blank.options);
+        if (!seen.has(blank.correctId)) {
+          throw new Error(`Question "${question.id}" blank "${blank.id}" has unknown correctId "${blank.correctId}".`);
+        }
+      }
+      return;
     }
   }
 }
 
 // ---------------------------------------------------------------------------
-// Choice helpers. All UI + scoring goes through these so option storage
-// (ids) stays decoupled from presentation (letters, markdown).
+// Answer helpers. All UI + scoring goes through these so answer storage
+// (ids, raw text) stays decoupled from presentation (letters, markdown).
 // ---------------------------------------------------------------------------
 
 /** Effective kind: questions without `kind` are written. */
@@ -210,19 +321,60 @@ export function questionKind(question: BaseQuestion): QuestionKind {
   return question.kind ?? 'written';
 }
 
+/** Single or multiple choice (pick from `options`). */
 export function isChoiceQuestion(question: BaseQuestion): boolean {
   const kind = questionKind(question);
   return kind === 'single' || kind === 'multiple';
 }
 
-/** Correct option ids. Empty for written questions. */
+/** Matching or dropdown (each row/blank maps to one option id). */
+export function isPairingQuestion(question: BaseQuestion): boolean {
+  const kind = questionKind(question);
+  return kind === 'matching' || kind === 'dropdown';
+}
+
+/** Every kind except written can be auto-graded. */
+export function isGradeableQuestion(question: BaseQuestion): boolean {
+  return questionKind(question) !== 'written';
+}
+
+/** Correct option ids. Empty unless single/multiple. */
 export function getCorrectIds(question: BaseQuestion): string[] {
   return isChoiceQuestion(question) ? [...(question.correctIds ?? [])] : [];
 }
 
+export interface PairingSlot {
+  id: string;
+  /** Row text (matching) or blank label (dropdown). */
+  label: string | undefined;
+  options: readonly QuestionOption[];
+  correctId: string;
+}
+
+/** Rows of a matching question or blanks of a dropdown question, uniformly. Empty otherwise. */
+export function getPairingSlots(question: BaseQuestion): PairingSlot[] {
+  const kind = questionKind(question);
+  if (kind === 'matching') {
+    const options = question.options ?? [];
+    return (question.items ?? []).map((item) => ({ id: item.id, label: item.text, options, correctId: item.correctId }));
+  }
+  if (kind === 'dropdown') {
+    return (question.blanks ?? []).map((blank) => ({
+      id: blank.id,
+      label: blank.label,
+      options: blank.options,
+      correctId: blank.correctId,
+    }));
+  }
+  return [];
+}
+
+const isRecordAnswer = (answer: QuizAnswer | undefined): answer is Record<string, string> =>
+  typeof answer === 'object' && answer !== null && !Array.isArray(answer);
+
 /** Normalize a stored answer to selected option ids — tolerates legacy strings. */
 export function toSelectedIds(question: BaseQuestion, answer: QuizAnswer | undefined): string[] {
-  if (answer === undefined) return [];
+  if (answer === undefined || isRecordAnswer(answer)) return [];
   const ids =
     typeof answer === 'string' ? (answer === '' ? [] : [answer]) : answer.filter((id) => typeof id === 'string');
   if (!isChoiceQuestion(question)) return ids;
@@ -230,9 +382,34 @@ export function toSelectedIds(question: BaseQuestion, answer: QuizAnswer | undef
   return ids.filter((id) => valid.has(id));
 }
 
-/** Whether the user has provided an answer (non-blank text, or ≥1 selection). */
+/** Normalize a stored answer to slot id → option id, dropping unknown slots/options. */
+export function toPairings(question: BaseQuestion, answer: QuizAnswer | undefined): Record<string, string> {
+  if (!isRecordAnswer(answer)) return {};
+  const out: Record<string, string> = {};
+  for (const slot of getPairingSlots(question)) {
+    const chosen = answer[slot.id];
+    if (typeof chosen === 'string' && slot.options.some((o) => o.id === chosen)) out[slot.id] = chosen;
+  }
+  return out;
+}
+
+/**
+ * Parse a typed number. Accepts thousands separators ("1,756"), spaces,
+ * a leading "+", scientific notation and a trailing "%" (kept as the
+ * literal number). Returns null when the text is not a number.
+ */
+export function parseNumericAnswer(text: string): number | null {
+  const cleaned = text.trim().replace(/[\s,_]/g, '').replace(/%$/, '').replace(/^\+/, '');
+  if (cleaned === '' || !/^-?(\d+\.?\d*|\.\d+)(e[-+]?\d+)?$/i.test(cleaned)) return null;
+  const value = Number(cleaned);
+  return Number.isFinite(value) ? value : null;
+}
+
+/** Whether the user has provided an answer (non-blank text, ≥1 selection, or ≥1 pairing). */
 export function isAnswerProvided(question: BaseQuestion, answer: QuizAnswer | undefined): boolean {
   if (answer === undefined) return false;
+  if (isPairingQuestion(question)) return Object.keys(toPairings(question, answer)).length > 0;
+  if (isRecordAnswer(answer)) 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));
@@ -240,20 +417,45 @@ export function isAnswerProvided(question: BaseQuestion, answer: QuizAnswer | un
 }
 
 /**
- * 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).
+ * Per-part credit for an answer: { earned, possible }. null for written
+ * questions or when unanswered. Matching/dropdown earn one part per correct
+ * row/blank; every other gradeable kind is a single all-or-nothing part.
  */
-export function isAnswerCorrect(question: BaseQuestion, answer: QuizAnswer | undefined): boolean | null {
-  if (!isChoiceQuestion(question)) return null;
-  if (!isAnswerProvided(question, answer)) return null;
+export function gradeAnswer(
+  question: BaseQuestion,
+  answer: QuizAnswer | undefined,
+): { earned: number; possible: number } | null {
+  if (!isGradeableQuestion(question) || !isAnswerProvided(question, answer)) return null;
+  const kind = questionKind(question);
+  if (kind === 'numerical') {
+    const value = typeof answer === 'string' ? parseNumericAnswer(answer) : null;
+    const expected = question.numeric;
+    if (value === null || !expected) return { earned: 0, possible: 1 };
+    const tolerance = expected.tolerance ?? 0;
+    // Small relative epsilon so 0.1 + 0.2 style float noise never fails an exact answer.
+    const epsilon = Math.max(Math.abs(expected.value), 1) * 1e-9;
+    return { earned: Math.abs(value - expected.value) <= tolerance + epsilon ? 1 : 0, possible: 1 };
+  }
+  if (kind === 'matching' || kind === 'dropdown') {
+    const pairings = toPairings(question, answer);
+    const slots = getPairingSlots(question);
+    const earned = slots.filter((slot) => pairings[slot.id] === slot.correctId).length;
+    return { earned, possible: slots.length };
+  }
   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;
+  const exact = selected.size === correct.size && [...selected].every((id) => correct.has(id));
+  return { earned: exact ? 1 : 0, possible: 1 };
+}
+
+/**
+ * Grade an answer. Returns null for written questions or when unanswered.
+ * Single: exactly the correct id. Multiple: exact set match. Numerical:
+ * within tolerance. Matching/dropdown: every row/blank correct.
+ */
+export function isAnswerCorrect(question: BaseQuestion, answer: QuizAnswer | undefined): boolean | null {
+  const grade = gradeAnswer(question, answer);
+  return grade === null ? null : grade.earned === grade.possible;
 }
 
 /** Score a set of questions against answers: { correct, gradeable, answered }. */
@@ -266,7 +468,7 @@ export function scoreAnswers(
   let answered = 0;
   for (const question of questions) {
     if (isAnswerProvided(question, answers[question.id])) answered += 1;
-    if (!isChoiceQuestion(question)) continue;
+    if (!isGradeableQuestion(question)) continue;
     gradeable += 1;
     if (isAnswerCorrect(question, answers[question.id]) === true) correct += 1;
   }

package/framework/components/markdown-content.tsx

@@ -9,7 +9,7 @@ const components: Components = {
   blockquote: ({ ...props }) => <blockquote className="my-4 border-l-2 border-gray-300 pl-4 text-gray-700" {...props} />,
   code: ({ className, children, ...props }) => {
     const isBlock = className?.startsWith('language-') ?? false
-    return <code className={cn(isBlock ? 'font-mono text-sm' : 'rounded bg-gray-100 px-1 py-0.5 font-mono text-[0.9em] text-gray-900', className)} {...props}>{children}</code>
+    return <code className={cn(isBlock ? 'font-mono text-sm' : 'rounded bg-gray-100 px-1 py-0.5 font-mono text-[0.9em] text-gray-900 break-words', className)} {...props}>{children}</code>
   },
   h1: ({ ...props }) => <h1 className="mb-3 mt-6 text-2xl font-bold tracking-tight text-gray-950 first:mt-0" {...props} />,
   h2: ({ ...props }) => <h2 className="mb-3 mt-6 text-xl font-bold tracking-tight text-gray-950 first:mt-0" {...props} />,
@@ -98,12 +98,23 @@ const normalizeGfmTables = (content: string) => {
   }).join('')
 }
 
-export function MarkdownContent({ content, className }: { content: string; className?: string }) {
-  return (
-    <div className={cn('min-w-0 text-base leading-7 text-gray-800', className)}>
-      <ReactMarkdown remarkPlugins={[remarkGfm, remarkMath]} rehypePlugins={[rehypeKatex]} components={components}>
-        {normalizeGfmTables(normalizeMathDelimiters(content))}
-      </ReactMarkdown>
-    </div>
+// Inline mode: paragraphs render as spans so short markdown (option text,
+// blank labels) can sit inside buttons, select triggers and flex rows.
+const inlineComponents: Components = {
+  ...components,
+  p: ({ ...props }) => <span className="whitespace-pre-wrap" {...props} />,
+}
+
+// min-w-0 + break-words keep long tokens inside the column; display math
+// and wide tables/code scroll horizontally instead of widening the page.
+const blockClassName = 'min-w-0 max-w-full break-words [&_.katex-display]:overflow-x-auto [&_.katex-display]:overflow-y-hidden [&_.katex-display]:py-1'
+
+export function MarkdownContent({ content, className, inline = false }: { content: string; className?: string; inline?: boolean }) {
+  const markdown = (
+    <ReactMarkdown remarkPlugins={[remarkGfm, remarkMath]} rehypePlugins={[rehypeKatex]} components={inline ? inlineComponents : components}>
+      {normalizeGfmTables(normalizeMathDelimiters(content))}
+    </ReactMarkdown>
   )
+  if (inline) return <span className={cn('min-w-0', className)}>{markdown}</span>
+  return <div className={cn(blockClassName, 'text-base leading-7 text-gray-800', className)}>{markdown}</div>
 }

package/framework/components/question-bank.tsx

@@ -18,7 +18,7 @@ import {
 import { Search } from 'lucide-react';
 import { useBank } from '../../core/config.tsx';
 import type { BaseQuestion, QuestionKind, QuestionStatus, QuestionStatusMap, QuizSession } from '../../core/types.ts';
-import { isChoiceQuestion, questionKind, questionKindLabels } from '../../core/types.ts';
+import { getPairingSlots, isChoiceQuestion, questionKind, questionKindLabels } from '../../core/types.ts';
 import { Badge } from './ui/badge';
 import { Button } from './ui/button';
 import { Checkbox } from './ui/checkbox';
@@ -64,10 +64,30 @@ 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',
+  numerical: 'border-emerald-300 bg-emerald-50 text-emerald-900',
+  matching: 'border-orange-300 bg-orange-50 text-orange-900',
+  dropdown: 'border-rose-300 bg-rose-50 text-rose-900',
 };
 
 const optionLetter = (index: number): string => String.fromCharCode(65 + index);
 
+/** Short structural summary for the Type badge tooltip, e.g. "5 items · 11 options". */
+function kindDetail(question: BaseQuestion): string | undefined {
+  switch (questionKind(question)) {
+    case 'single':
+    case 'multiple':
+      return `${question.options?.length ?? 0} options`;
+    case 'matching':
+      return `${question.items?.length ?? 0} items · ${question.options?.length ?? 0} options`;
+    case 'dropdown':
+      return `${question.blanks?.length ?? 0} blanks`;
+    case 'numerical':
+      return question.numeric?.unit ? `Numeric answer (${question.numeric.unit})` : 'Numeric answer';
+    default:
+      return undefined;
+  }
+}
+
 function QuestionPreviewPopover({ question }: { question: BaseQuestion }) {
   const [open, setOpen] = useState(false);
   const openTimeout = useRef<number | null>(null);
@@ -184,6 +204,16 @@ function QuestionPreviewPopover({ question }: { question: BaseQuestion }) {
               ))}
             </ol>
           )}
+          {getPairingSlots(question).length > 0 && (
+            <ol className="mt-3 list-decimal space-y-1 pl-6 text-sm text-gray-800">
+              {getPairingSlots(question).map((slot, index) => (
+                <li key={slot.id}>
+                  <MarkdownContent inline content={slot.label?.trim() ? slot.label : `Blank ${index + 1}`} />
+                  <span className="text-gray-500"> → ___</span>
+                </li>
+              ))}
+            </ol>
+          )}
         </div>
       </PopoverContent>
     </Popover>
@@ -394,9 +424,8 @@ export function QuestionBank() {
         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}>
+            <Badge variant="outline" className={questionKindStyles[kind]} title={kindDetail(row.original)}>
               {questionKindLabels[kind]}
             </Badge>
           );