question-bank-framework 0.9.0 → 0.10.0

package/README.md

@@ -60,7 +60,9 @@ time (e.g. 08:30) and reading/writing minutes, then press Start: the top right
 of the header shows the mock exam time, starting at 08:30, with a book icon
 during reading time and a pen during writing time. It updates once a minute.
 Toasts announce reading time over, 30 and 10 minutes remaining, and exam over;
-the clock disappears once the exam is over. The timer lives in localStorage,
+the clock disappears once the exam is over. Pause freezes the clock (the
+header shows a pause icon) and Resume carries on from the same mock time, so
+breaks don't eat into the exam. The timer lives in localStorage,
 so it survives reloads and shows in every open tab.
 
 ## Sync (Cloudflare Durable Objects)

package/framework/components/exam-timer.tsx

@@ -1,16 +1,27 @@
 // Mock-exam clock: <ExamTimerBadge> shows the mock time in the header while an
-// exam is running; <ExamTimerPage> (the /timer route) is the only place to start it.
+// exam is running; <ExamTimerPage> (the /timer route) is the only place to start,
+// pause, resume or stop it.
 // Framework-owned: eject with `qb reveal framework/components/exam-timer.tsx`.
 
 import { useEffect, useRef, useState, type FormEvent } from 'react';
-import { BookOpen, PenLine } from 'lucide-react';
+import { BookOpen, Pause, PenLine } from 'lucide-react';
 import { useBank } from '../../core/config.tsx';
 import { Button } from './ui/button';
 import { Card, CardContent, CardFooter } from './ui/card';
 import { Field, FieldGroup, FieldLabel } from './ui/field';
 import { Input } from './ui/input';
 import { toast } from './ui/toast';
-import { examState, formatClock, MINUTE, setExamTimer, useExamNow, useExamTimer, type ExamTimer } from '../lib/exam-timer.ts';
+import {
+  examState,
+  formatClock,
+  MINUTE,
+  pauseExamTimer,
+  resumeExamTimer,
+  setExamTimer,
+  useExamNow,
+  useExamTimer,
+  type ExamTimer,
+} from '../lib/exam-timer.ts';
 
 /** Moments to announce, in minutes after Start. */
 const milestones = ({ readingMinutes: reading, writingMinutes: writing }: ExamTimer) => {
@@ -43,14 +54,15 @@ export function ExamTimerBadge() {
   }, [timer?.startedAt, state?.elapsed]);
 
   if (!state || state.phase === 'over') return null;
-  const Icon = state.phase === 'reading' ? BookOpen : PenLine;
+  const Icon = state.paused ? Pause : state.phase === 'reading' ? BookOpen : PenLine;
+  const label = `${state.phase === 'reading' ? 'Reading time' : 'Writing time'}${state.paused ? ' (paused)' : ''}`;
   return (
     <span
-      className="flex items-center gap-1.5 text-sm font-medium tabular-nums text-foreground"
-      title={state.phase === 'reading' ? 'Reading time' : 'Writing time'}
+      className={`flex items-center gap-1.5 text-sm font-medium tabular-nums ${state.paused ? 'text-muted-foreground' : 'text-foreground'}`}
+      title={label}
     >
       <Icon aria-hidden="true" className="size-4 text-muted-foreground" />
-      <span className="sr-only">{state.phase === 'reading' ? 'Reading time' : 'Writing time'}, mock exam time </span>
+      <span className="sr-only">{label}, mock exam time </span>
       {state.clock}
     </span>
   );
@@ -74,6 +86,7 @@ export function ExamTimerPage({
   const timer = useExamTimer(namespace);
   const now = useExamNow(timer);
   const running = timer !== null && examState(timer, now).phase !== 'over';
+  const paused = running && timer.pausedAt !== undefined;
   const [start, setStart] = useState(defaultStart);
   const [reading, setReading] = useState(String(defaultReadingMinutes));
   const [writing, setWriting] = useState(String(defaultWritingMinutes));
@@ -121,6 +134,15 @@ export function ExamTimerPage({
           </CardContent>
           <CardFooter className="gap-2">
             <Button type="submit">{running ? 'Restart' : 'Start'}</Button>
+            {running && (
+              <Button
+                type="button"
+                variant="outline"
+                onClick={() => (paused ? resumeExamTimer(namespace, timer) : pauseExamTimer(namespace, timer))}
+              >
+                {paused ? 'Resume' : 'Pause'}
+              </Button>
+            )}
             {running && (
               <Button type="button" variant="ghost" onClick={() => setExamTimer(namespace, null)}>
                 Stop

package/framework/index.ts

@@ -33,7 +33,7 @@ export {
   syncQuiz,
 } from './lib/quiz-storage.ts';
 export { getQuestionStatuses, setQuestionStatus } from './lib/question-status-storage.ts';
-export { examState, setExamTimer, useExamTimer } from './lib/exam-timer.ts';
+export { examState, pauseExamTimer, resumeExamTimer, setExamTimer, useExamTimer } from './lib/exam-timer.ts';
 export type { ExamState, ExamTimer } from './lib/exam-timer.ts';
 export { Toaster, toast } from './components/ui/toast.tsx';
 export type { StorageTarget } from './lib/sync-client.ts';

package/framework/lib/exam-timer.ts

@@ -1,6 +1,7 @@
 // Mock-exam clock: pressing Start on /timer pretends it's the exam's start time
 // (e.g. 08:30) right now, then the clock runs forward from there. Kept in
-// localStorage so it survives reloads and is shared by every open tab.
+// localStorage so it survives reloads and is shared by every open tab. Pausing
+// freezes the clock; resuming shifts `startedAt` forward by the paused time.
 // Framework-owned: eject with `qb reveal framework/lib/exam-timer.ts`.
 
 import { useEffect, useState, useSyncExternalStore } from 'react';
@@ -12,10 +13,13 @@ export type ExamTimer = {
   startedAt: number;
   readingMinutes: number;
   writingMinutes: number;
+  /** Set while paused: when Pause was pressed (epoch ms). The clock is frozen at this moment. */
+  pausedAt?: number;
 };
 
 export type ExamState = {
   phase: 'reading' | 'writing' | 'over';
+  paused: boolean;
   /** Mock clock time, "HH:MM". */
   clock: string;
   /** Ms since Start was pressed. */
@@ -28,10 +32,9 @@ const keyFor = (namespace: string) => `${namespace}-question-bank-exam-timer`;
 
 const isTimer = (value: unknown): value is ExamTimer => {
   if (!value || typeof value !== 'object') return false;
-  const { startMinutes, startedAt, readingMinutes, writingMinutes } = value as Record<string, unknown>;
-  return [startMinutes, startedAt, readingMinutes, writingMinutes].every(
-    (n) => typeof n === 'number' && Number.isFinite(n) && n >= 0,
-  );
+  const { startMinutes, startedAt, readingMinutes, writingMinutes, pausedAt } = value as Record<string, unknown>;
+  const isTime = (n: unknown) => typeof n === 'number' && Number.isFinite(n) && n >= 0;
+  return [startMinutes, startedAt, readingMinutes, writingMinutes].every(isTime) && (pausedAt === undefined || isTime(pausedAt));
 };
 
 const parse = (raw: string | null): ExamTimer | null => {
@@ -51,6 +54,19 @@ export function setExamTimer(namespace: string, timer: ExamTimer | null): void {
   window.dispatchEvent(new Event(CHANGE_EVENT));
 }
 
+/** Freeze the clock at `now`. No-op if already paused. */
+export function pauseExamTimer(namespace: string, timer: ExamTimer, now = Date.now()): void {
+  if (timer.pausedAt !== undefined) return;
+  setExamTimer(namespace, { ...timer, pausedAt: now });
+}
+
+/** Carry on from where it was paused, by shifting `startedAt` forward by the time spent paused. */
+export function resumeExamTimer(namespace: string, timer: ExamTimer, now = Date.now()): void {
+  if (timer.pausedAt === undefined) return;
+  const { pausedAt, ...rest } = timer;
+  setExamTimer(namespace, { ...rest, startedAt: rest.startedAt + Math.max(0, now - pausedAt) });
+}
+
 function subscribe(onChange: () => void) {
   window.addEventListener('storage', onChange);
   window.addEventListener(CHANGE_EVENT, onChange);
@@ -76,22 +92,25 @@ export const formatClock = (minutesAfterMidnight: number) => {
 };
 
 export function examState(timer: ExamTimer, now: number): ExamState {
-  const elapsed = Math.max(0, now - timer.startedAt);
+  const paused = timer.pausedAt !== undefined;
+  const elapsed = Math.max(0, (timer.pausedAt ?? now) - timer.startedAt);
   const minutes = elapsed / MINUTE;
   const phase =
     minutes < timer.readingMinutes ? 'reading' : minutes < timer.readingMinutes + timer.writingMinutes ? 'writing' : 'over';
-  return { phase, clock: formatClock(timer.startMinutes + minutes), elapsed };
+  return { phase, paused, clock: formatClock(timer.startMinutes + minutes), elapsed };
 }
 
 /**
  * Current time, re-read each time the mock clock ticks over a minute (and
- * when the tab becomes visible again). Never re-renders more than once a minute.
+ * when the tab becomes visible again). Never re-renders more than once a minute,
+ * and doesn't tick at all while paused.
  */
 export function useExamNow(timer: ExamTimer | null): number {
   const [now, setNow] = useState(() => Date.now());
   const startedAt = timer?.startedAt;
+  const paused = timer?.pausedAt !== undefined;
   useEffect(() => {
-    if (startedAt === undefined) return;
+    if (startedAt === undefined || paused) return;
     let timeout: ReturnType<typeof setTimeout>;
     const tick = () => {
       const current = Date.now();
@@ -110,6 +129,6 @@ export function useExamNow(timer: ExamTimer | null): number {
       clearTimeout(timeout);
       document.removeEventListener('visibilitychange', onVisible);
     };
-  }, [startedAt]);
+  }, [startedAt, paused]);
   return now;
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "question-bank-framework",
-  "version": "0.9.0",
+  "version": "0.10.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",