question-bank-framework 0.6.0 → 0.7.1

package/framework/components/question-bank.tsx

@@ -13,6 +13,7 @@ import {
   useReactTable,
   type ColumnDef,
   type RowSelectionState,
+  type SortingFn,
   type SortingState,
 } from '@tanstack/react-table';
 import { Search } from 'lucide-react';
@@ -52,6 +53,11 @@ type DragSelection = {
   moved: boolean;
 };
 
+// Number-aware, case-insensitive text sort: "Q2" before "Q10".
+const naturalCollator = new Intl.Collator(undefined, { numeric: true, sensitivity: 'base' });
+const naturalSort: SortingFn<BaseQuestion> = (rowA, rowB, columnId) =>
+  naturalCollator.compare(String(rowA.getValue(columnId) ?? ''), String(rowB.getValue(columnId) ?? ''));
+
 const previewCloseDelay = 180;
 const previewOpenDelay = 400;
 const questionStatusStyles: Record<QuestionStatus, string> = {
@@ -279,13 +285,13 @@ export function QuestionBank() {
 
   useEffect(() => {
     let active = true;
-    getQuestionStatuses(bank.namespace).then((statuses) => {
+    getQuestionStatuses(bank).then((statuses) => {
       if (active) setQuestionStatusMap(statuses);
     });
     return () => {
       active = false;
     };
-  }, [bank.namespace]);
+  }, [bank]);
 
   const filteredQuestions = useMemo(
     () =>
@@ -327,6 +333,7 @@ export function QuestionBank() {
             return <span className="whitespace-normal break-words text-sm text-foreground">{formatCellValue(raw)}</span>;
           },
           enableSorting: sortable,
+          ...(def.type === 'number' ? {} : { sortingFn: naturalSort }),
           size: width,
         } satisfies ColumnDef<BaseQuestion>;
       });
@@ -383,6 +390,7 @@ export function QuestionBank() {
         cell: ({ row }) => (
           <span className="whitespace-normal break-all font-mono text-sm text-muted-foreground">{row.original.id}</span>
         ),
+        sortingFn: naturalSort,
         size: idWidth,
       },
       {
@@ -393,6 +401,7 @@ export function QuestionBank() {
         accessorKey: 'title',
         header: 'Question',
         cell: ({ row }) => <QuestionPreviewPopover question={row.original} />,
+        sortingFn: naturalSort,
       },
       // Absorbent like title: no fixed size, takes up slack on wide screens.
       // minTableWidth (below) always reserves 200px for it, so it can
@@ -407,6 +416,7 @@ export function QuestionBank() {
               id: 'tags',
               accessorFn: (row) => row.tags.join(', '),
               header: 'Tags',
+              sortingFn: naturalSort,
               cell: ({ row }) => (
                 <div className="flex min-w-0 flex-wrap gap-1">
                   {row.original.tags.map((tag) => (
@@ -609,13 +619,23 @@ export function QuestionBank() {
 
   const selectedIds = Object.keys(rowSelection).filter((id) => rowSelection[id]);
 
+  // Selected questions in the table's current sort order; any selected rows
+  // hidden by the current filters follow in bank order.
+  const selectedInTableOrder = (exclude: ReadonlySet<string> = new Set()) => {
+    const visible = tableRows.map((row) => row.original);
+    const visibleIds = new Set(visible.map((question) => question.id));
+    return [...visible, ...bank.questions.filter((question) => !visibleIds.has(question.id))].filter(
+      (question) => rowSelection[question.id] && !exclude.has(question.id),
+    );
+  };
+
   const makeQuiz = async () => {
-    const chosenQuestions = bank.questions.filter((question) => rowSelection[question.id]);
+    const chosenQuestions = selectedInTableOrder();
     if (chosenQuestions.length === 0) return;
     setCreatingQuiz(true);
     const title = `${chosenQuestions.length}-question practice set`;
     try {
-      const quiz = await createQuiz(bank.namespace, title, chosenQuestions.map((question) => question.id));
+      const quiz = await createQuiz(bank, title, chosenQuestions.map((question) => question.id));
       await navigate({ to: '/quiz/$quizId', params: { quizId: quiz.id } });
     } finally {
       setCreatingQuiz(false);
@@ -627,17 +647,17 @@ export function QuestionBank() {
     if (!open) return;
     setExistingQuizzes(null);
     setAddToQuizError(false);
-    listQuizzes(bank.namespace).then(setExistingQuizzes, () => setExistingQuizzes([]));
+    listQuizzes(bank).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));
+    const additions = selectedInTableOrder(existing);
     setAddingToQuizId(quiz.id);
     setAddToQuizError(false);
     try {
       if (additions.length > 0) {
-        await setQuizQuestions(bank.namespace, quiz, [...quiz.questionIds, ...additions.map((question) => question.id)]);
+        await setQuizQuestions(bank, quiz, [...quiz.questionIds, ...additions.map((question) => question.id)]);
       }
       setAddToQuizOpen(false);
       await navigate({ to: '/quiz/$quizId', params: { quizId: quiz.id } });

package/framework/components/question-response.tsx

@@ -166,19 +166,21 @@ export function PairingResponse({
             <li
               key={slot.id}
               className={cn(
-                'flex flex-col gap-2 rounded-lg border p-3 sm:flex-row sm:items-center',
+                // Wraps instead of squeezing: short items sit beside their select, while
+                // wide items (long formulas) take the full row and the select drops below.
+                'flex flex-wrap items-center gap-x-4 gap-y-2 rounded-lg border p-3',
                 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">
+              <div className="flex min-w-0 max-w-full flex-[1_1_auto] 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 overflow-x-auto text-base leading-7 text-gray-900">
+                <label htmlFor={selectId} className="min-w-0 flex-1 overflow-x-auto overflow-y-hidden 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="ml-auto flex shrink-0 flex-col gap-1 pl-8 sm:pl-0">
                 <div className="flex items-center gap-2">
                   <OptionSelect
                     id={selectId}

package/framework/components/quiz-list.tsx

@@ -20,7 +20,7 @@ export function QuizList() {
 
   useEffect(() => {
     let active = true;
-    listQuizzes(bank.namespace).then((items) => {
+    listQuizzes(bank).then((items) => {
       if (active) setQuizzes(items);
     }).finally(() => {
       if (active) setLoading(false);
@@ -28,13 +28,13 @@ export function QuizList() {
     return () => {
       active = false;
     };
-  }, [bank.namespace]);
+  }, [bank]);
 
   const removeQuiz = async (quiz: QuizSession) => {
     setDeletingId(quiz.id);
     setDeleteError(false);
     try {
-      await deleteQuiz(bank.namespace, quiz.id);
+      await deleteQuiz(bank, quiz.id);
       setQuizzes((current) => current.filter((item) => item.id !== quiz.id));
     } catch {
       setDeleteError(true);
@@ -44,7 +44,7 @@ export function QuizList() {
   };
 
   const saveQuestions = async (quiz: QuizSession, questionIds: string[]) => {
-    const updated = await setQuizQuestions(bank.namespace, quiz, questionIds);
+    const updated = await setQuizQuestions(bank, quiz, questionIds);
     setQuizzes((current) => current.map((item) => (item.id === updated.id ? updated : item)));
   };
 

package/framework/components/quiz-page.tsx

@@ -26,7 +26,7 @@ import { MarkdownContent } from './markdown-content';
 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 { getQuiz, saveQuizLocally, syncQuiz } from '../lib/quiz-storage.ts';
 import { cn } from '../lib/utils.ts';
 
 const questionStatusStyles: Record<QuestionStatus, string> = {
@@ -68,39 +68,40 @@ export function QuizPage() {
   const activeIndex = Math.min(session?.currentQuestion ?? 0, Math.max(quizQuestions.length - 1, 0));
   const activeQuestion = quizQuestions[activeIndex];
 
+  // The session as loaded; not saved back, so merely opening a quiz never
+  // bumps its updatedAt.
+  const loadedSession = useRef<QuizSession | null>(null);
+
   useEffect(() => {
     let active = true;
     setShownAnswerId(null);
     setChecked({});
-    getQuiz(bank.namespace, quizId).then((quiz) => {
-      if (active) setSession(quiz);
+    getQuiz(bank, quizId).then((quiz) => {
+      if (!active) return;
+      loadedSession.current = quiz;
+      setSession(quiz);
     }).finally(() => {
       if (active) setLoading(false);
     });
-    getQuestionStatuses(bank.namespace).then((statuses) => {
+    getQuestionStatuses(bank).then((statuses) => {
       if (active) setStatusMap(statuses);
     });
     return () => {
       active = false;
     };
-  }, [quizId, bank.namespace]);
+  }, [quizId, bank]);
 
   useEffect(() => {
-    if (!session) return;
-    saveQuizLocally(bank.namespace, session);
-    if (session.id.startsWith('local_')) return;
+    if (!session || session === loadedSession.current) return;
+    // Local copy immediately; server push debounced.
+    const saved = saveQuizLocally(bank, session);
+    if (!bank.sync) return;
     setSaving(true);
     const timeout = window.setTimeout(() => {
-      saveQuizProgress(
-        bank.namespace,
-        session,
-        { title: session.title, answers: session.answers, currentQuestion: session.currentQuestion, completed: session.completed },
-      )
-        .then(() => setSaving(false))
-        .catch(() => setSaving(false));
+      void syncQuiz(bank, saved).finally(() => setSaving(false));
     }, 500);
     return () => window.clearTimeout(timeout);
-  }, [session, bank.namespace]);
+  }, [session, bank]);
 
   useEffect(() => {
     if (editingTitle) {
@@ -149,7 +150,7 @@ export function QuizPage() {
 
   const updateQuestionStatus = (status: QuestionStatus) => {
     if (!activeQuestion) return;
-    void setQuestionStatus(bank.namespace, activeQuestion.id, status);
+    void setQuestionStatus(bank, activeQuestion.id, status);
     setStatusMap((current) => ({ ...current, [activeQuestion.id]: status }));
     setShownAnswerId(null);
     setSession((current) =>

package/framework/index.ts

@@ -21,7 +21,16 @@ export {
 export type { FilterField, FilterMatch, FilterOperatorId, FilterRule } from './lib/question-filter.ts';
 
 export { createQuestionFilterStore, useQuestionFilterStore } from './lib/question-filter-store.ts';
-export { createQuiz, deleteQuiz, getQuiz, listQuizzes, saveQuizLocally, saveQuizProgress } from './lib/quiz-storage.ts';
+export {
+  createQuiz,
+  deleteQuiz,
+  getQuiz,
+  listQuizzes,
+  saveQuiz,
+  saveQuizLocally,
+  setQuizQuestions,
+  syncQuiz,
+} from './lib/quiz-storage.ts';
 export { getQuestionStatuses, setQuestionStatus } from './lib/question-status-storage.ts';
-export { convexApi } from './lib/convex-api.ts';
+export type { StorageTarget } from './lib/sync-client.ts';
 export { cn } from './lib/utils.ts';

package/framework/lib/question-status-storage.ts

@@ -1,117 +1,91 @@
-// Per-question status (unanswered/revisit/complete), Convex + localStorage.
+// Per-question status (unanswered/revisit/complete). localStorage is the
+// working copy; with `sync` set, changes are pushed to the server and merged
+// back (newest `updatedAt` wins).
 // Framework-owned: eject with `qb reveal framework/lib/question-status-storage.ts`.
 
-import { ConvexHttpClient } from 'convex/browser';
-import { convexApi } from './convex-api.ts';
 import { questionStatuses, type QuestionStatus, type QuestionStatusMap } from '../../core/types.ts';
-
-const convexUrl = import.meta.env?.VITE_CONVEX_URL || (import.meta.env?.CONVEX_URL as string | undefined);
-const convexClient = convexUrl ? new ConvexHttpClient(convexUrl) : null;
+import { readLocal, syncEnabled, syncRequest, writeLocal, type StorageTarget } from './sync-client.ts';
 
 type StoredQuestionStatus = {
   status: QuestionStatus;
   updatedAt: number;
+  /** Not yet confirmed by the server. */
   pending: boolean;
 };
 
-type QuestionStatusDocument = {
-  questionId: string;
-  status: QuestionStatus;
-  updatedAt: number;
-};
+type RemoteStatus = { status: QuestionStatus; updatedAt: number };
 
 const keyFor = (namespace: string) => `${namespace}-question-bank-statuses`;
 
 const isQuestionStatus = (value: unknown): value is QuestionStatus =>
   typeof value === 'string' && (questionStatuses as readonly string[]).includes(value);
 
+const isObject = (value: unknown): value is Record<string, unknown> =>
+  !!value && typeof value === 'object' && !Array.isArray(value);
+
 const readLocalStatuses = (namespace: string): Record<string, StoredQuestionStatus> => {
-  if (typeof window === 'undefined') return {};
-  try {
-    const value: unknown = JSON.parse(window.localStorage.getItem(keyFor(namespace)) ?? '{}');
-    if (!value || typeof value !== 'object' || Array.isArray(value)) return {};
-    return Object.fromEntries(
-      Object.entries(value).flatMap(([questionId, entry]) => {
-        if (!entry || typeof entry !== 'object' || Array.isArray(entry)) return [];
-        const stored = entry as Partial<StoredQuestionStatus>;
-        if (!isQuestionStatus(stored.status) || typeof stored.updatedAt !== 'number') return [];
-        return [
-          [
-            questionId,
-            { status: stored.status, updatedAt: stored.updatedAt, pending: stored.pending === true },
-          ],
-        ];
-      }),
-    );
-  } catch {
-    return {};
-  }
+  const value = readLocal(keyFor(namespace), {}, isObject);
+  return Object.fromEntries(
+    Object.entries(value).flatMap(([questionId, entry]) => {
+      if (!isObject(entry) || !isQuestionStatus(entry.status) || typeof entry.updatedAt !== 'number') return [];
+      return [[questionId, { status: entry.status, updatedAt: entry.updatedAt, pending: entry.pending === true }]];
+    }),
+  );
 };
 
-const writeLocalStatuses = (namespace: string, statuses: Record<string, StoredQuestionStatus>) => {
-  if (typeof window !== 'undefined') window.localStorage.setItem(keyFor(namespace), JSON.stringify(statuses));
-};
+const writeLocalStatuses = (namespace: string, statuses: Record<string, StoredQuestionStatus>) =>
+  writeLocal(keyFor(namespace), statuses);
 
 const toStatusMap = (statuses: Record<string, StoredQuestionStatus>): QuestionStatusMap =>
   Object.fromEntries(Object.entries(statuses).map(([questionId, entry]) => [questionId, entry.status]));
 
-async function syncPendingStatuses(namespace: string, statuses: Record<string, StoredQuestionStatus>) {
-  if (!convexClient) return statuses;
-  await Promise.all(
-    Object.entries(statuses).map(async ([questionId, entry]) => {
-      if (!entry.pending) return;
-      try {
-        const updatedAt = await convexClient.mutation(convexApi.questionStatuses.set, {
-          questionId,
-          status: entry.status,
-        });
-        const latest = readLocalStatuses(namespace);
-        if (latest[questionId]?.pending && latest[questionId]?.updatedAt === entry.updatedAt) {
-          latest[questionId] = { status: entry.status, updatedAt, pending: false };
-          writeLocalStatuses(namespace, latest);
-          statuses[questionId] = latest[questionId];
-        }
-      } catch {
-        // Keep the local status pending so it can be retried later.
-      }
-    }),
-  );
-  return statuses;
+/** Push one status; on success mark it confirmed unless it changed meanwhile. */
+async function pushStatus(target: StorageTarget, questionId: string, entry: StoredQuestionStatus): Promise<void> {
+  const { data } = await syncRequest<RemoteStatus>(target, `/statuses/${encodeURIComponent(questionId)}`, {
+    method: 'PUT',
+    body: { status: entry.status, updatedAt: entry.updatedAt },
+  });
+  const latest = readLocalStatuses(target.namespace);
+  const current = latest[questionId];
+  if (current && current.updatedAt === entry.updatedAt) {
+    latest[questionId] = { status: data.status, updatedAt: data.updatedAt, pending: false };
+    writeLocalStatuses(target.namespace, latest);
+  }
 }
 
-export async function getQuestionStatuses(namespace: string): Promise<QuestionStatusMap> {
-  const localStatuses = readLocalStatuses(namespace);
-  if (!convexClient) return toStatusMap(localStatuses);
-  await syncPendingStatuses(namespace, localStatuses);
+export async function getQuestionStatuses(target: StorageTarget): Promise<QuestionStatusMap> {
+  const local = readLocalStatuses(target.namespace);
+  if (!syncEnabled(target)) return toStatusMap(local);
   try {
-    const documents = (await convexClient.query(convexApi.questionStatuses.list, {})) as QuestionStatusDocument[];
+    await Promise.all(
+      Object.entries(local)
+        .filter(([, entry]) => entry.pending)
+        .map(([questionId, entry]) => pushStatus(target, questionId, entry)),
+    );
+    const { data } = await syncRequest<Record<string, RemoteStatus>>(target, '/statuses');
     const merged: Record<string, StoredQuestionStatus> = Object.fromEntries(
-      documents.map((document) => [document.questionId, { status: document.status, updatedAt: document.updatedAt, pending: false }]),
+      Object.entries(data).map(([questionId, entry]) => [questionId, { ...entry, pending: false }]),
     );
-    for (const [questionId, localStatus] of Object.entries(localStatuses)) {
-      if (localStatus.pending || !merged[questionId]) merged[questionId] = localStatus;
+    for (const [questionId, entry] of Object.entries(readLocalStatuses(target.namespace))) {
+      const server = merged[questionId];
+      if (!server || entry.updatedAt > server.updatedAt) merged[questionId] = { ...entry, pending: true };
     }
-    writeLocalStatuses(namespace, merged);
+    writeLocalStatuses(target.namespace, merged);
     return toStatusMap(merged);
   } catch {
-    return toStatusMap(localStatuses);
+    return toStatusMap(readLocalStatuses(target.namespace));
   }
 }
 
-export async function setQuestionStatus(namespace: string, questionId: string, status: QuestionStatus): Promise<void> {
-  const statuses = readLocalStatuses(namespace);
-  const localStatus: StoredQuestionStatus = { status, updatedAt: Date.now(), pending: true };
-  statuses[questionId] = localStatus;
-  writeLocalStatuses(namespace, statuses);
-  if (!convexClient) return;
+export async function setQuestionStatus(target: StorageTarget, questionId: string, status: QuestionStatus): Promise<void> {
+  const statuses = readLocalStatuses(target.namespace);
+  const entry: StoredQuestionStatus = { status, updatedAt: Date.now(), pending: true };
+  statuses[questionId] = entry;
+  writeLocalStatuses(target.namespace, statuses);
+  if (!syncEnabled(target)) return;
   try {
-    const updatedAt = await convexClient.mutation(convexApi.questionStatuses.set, { questionId, status });
-    const latest = readLocalStatuses(namespace);
-    if (latest[questionId]?.pending && latest[questionId]?.updatedAt === localStatus.updatedAt) {
-      latest[questionId] = { status, updatedAt, pending: false };
-      writeLocalStatuses(namespace, latest);
-    }
+    await pushStatus(target, questionId, entry);
   } catch {
-    // The local copy remains available and will be retried on the next status read.
+    // Stays pending; retried on the next getQuestionStatuses.
   }
 }