question-bank-framework 0.8.0 → 0.10.0

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/framework/styles/theme.css

@@ -1,24 +1,35 @@
-/* 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:
+/* Design system for question-bank-framework: shadcn/ui neutral tokens + Inter.
+ * Import this from your app stylesheet after tailwindcss:
  *
  *   @import 'tailwindcss';
- *   @source '../node_modules/question-bank-framework';
  *   @import 'question-bank-framework/framework/styles/theme.css';
  */
 
+/* Generate utilities used by the framework's components (paths resolve
+ * relative to this file, so this also works when the package is linked). */
+@source '..';
+
+/* Inter variable with both axes (wght 100–900, opsz 14–32), upright and italic.
+ * `font-optical-sizing: auto` (below) maps opsz to the font size, so small
+ * text gets Inter Text (open spacing) and headings get Inter Display (tight
+ * spacing, finer details). Don't add negative tracking on top of it. */
+@import '@fontsource-variable/inter/opsz.css';
+@import '@fontsource-variable/inter/opsz-italic.css';
+@import 'tw-animate-css';
 /* KaTeX CSS from the framework's own katex, matching the version that renders
  * math in MarkdownContent. Don't import katex CSS separately in your app. */
 @import 'katex/dist/katex.min.css';
 
+@custom-variant dark (&:is(.dark *));
+
 @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);
+  --font-sans: 'Inter Variable', ui-sans-serif, system-ui, sans-serif;
+  --font-mono: ui-monospace, 'SF Mono', SFMono-Regular, Menlo, Consolas, monospace;
+  --radius-sm: calc(var(--radius) * 0.6);
+  --radius-md: calc(var(--radius) * 0.8);
   --radius-lg: var(--radius);
-  --radius-xl: calc(var(--radius) + 4px);
+  --radius-xl: calc(var(--radius) * 1.4);
+  --radius-2xl: calc(var(--radius) * 1.8);
   --color-background: var(--background);
   --color-foreground: var(--foreground);
   --color-card: var(--card);
@@ -34,6 +45,8 @@
   --color-accent: var(--accent);
   --color-accent-foreground: var(--accent-foreground);
   --color-destructive: var(--destructive);
+  --color-success: var(--success);
+  --color-warning: var(--warning);
   --color-border: var(--border);
   --color-input: var(--input);
   --color-ring: var(--ring);
@@ -41,22 +54,47 @@
 
 :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;
+  --background: oklch(1 0 0);
+  --foreground: oklch(0.145 0 0);
+  --card: oklch(1 0 0);
+  --card-foreground: oklch(0.145 0 0);
+  --popover: oklch(1 0 0);
+  --popover-foreground: oklch(0.145 0 0);
+  --primary: oklch(0.205 0 0);
+  --primary-foreground: oklch(0.985 0 0);
+  --secondary: oklch(0.97 0 0);
+  --secondary-foreground: oklch(0.205 0 0);
+  --muted: oklch(0.97 0 0);
+  --muted-foreground: oklch(0.556 0 0);
+  --accent: oklch(0.97 0 0);
+  --accent-foreground: oklch(0.205 0 0);
+  --destructive: oklch(0.577 0.245 27.325);
+  --success: oklch(0.527 0.154 150.069);
+  --warning: oklch(0.666 0.179 58.318);
+  --border: oklch(0.922 0 0);
+  --input: oklch(0.922 0 0);
+  --ring: oklch(0.708 0 0);
+}
+
+@layer base {
+  * {
+    @apply border-border outline-ring/50;
+  }
+  html {
+    font-optical-sizing: auto;
+    -webkit-font-smoothing: antialiased;
+    -moz-osx-font-smoothing: grayscale;
+    text-rendering: optimizeLegibility;
+  }
+  body {
+    @apply bg-background font-sans text-foreground;
+  }
+  h1,
+  h2,
+  h3 {
+    text-wrap: balance;
+  }
+  p {
+    text-wrap: pretty;
+  }
 }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "question-bank-framework",
-  "version": "0.8.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",
@@ -33,6 +33,7 @@
   },
   "dependencies": {
     "@base-ui/react": "^1.9.0",
+    "@fontsource-variable/inter": "^5.3.0",
     "@tanstack/react-table": "^8.21.3",
     "@tanstack/react-virtual": "^3.14.19",
     "class-variance-authority": "^0.7.1",
@@ -44,6 +45,7 @@
     "remark-gfm": "^4.0.1",
     "remark-math": "^6.0.0",
     "tailwind-merge": "^3.7.0",
+    "tw-animate-css": "^1.4.0",
     "zustand": "^5.0.15"
   },
   "devDependencies": {

package/template/src/routes/__root.tsx

@@ -35,7 +35,7 @@ function RootDocument({ children }: { children: ReactNode }) {
       <head>
         <HeadContent />
       </head>
-      <body className="m-0 min-h-screen bg-[#f5f7f4] font-sans text-[#27392f] antialiased">
+      <body className="min-h-dvh">
         {children}
         <Scripts />
       </body>

package/template/src/routes/styles.css

@@ -1,6 +1,2 @@
-@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 'tailwindcss';
-@import 'tw-animate-css';
 @import 'question-bank-framework/framework/styles/theme.css';
-
-@source '../../node_modules/question-bank-framework';