@exxatdesignux/ui 0.2.16 → 0.2.18

package/template/lib/question-bank-authoring.ts

@@ -0,0 +1,308 @@
+/**
+ * Question bank authoring — health-science domain constants for `NewQuestionAuthoring`.
+ *
+ * Storage in `lib/mock/question-bank.ts` keeps the simple `QuestionBankType` enum
+ * (`multiple_choice` | `true_false` | `short_answer`). The authoring surface
+ * exposes the richer item-writer model that health-science assessments rely on
+ * (NBME / NCLEX / OSCE style) and maps back to that base enum on save.
+ */
+
+import type { QuestionBankType, QuestionBankBloomLevel } from "@/lib/mock/question-bank"
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Question type
+// ─────────────────────────────────────────────────────────────────────────────
+
+/** Authoring-time question type — richer than the storage enum. */
+export type AuthoringQuestionType =
+  | "mcq_single"
+  | "mcq_multiple"
+  | "true_false"
+  | "short_answer"
+  | "numeric"
+  | "essay"
+  | "fill_blank"
+  | "matching"
+  | "ordering"
+  | "hotspot"
+
+export interface AuthoringQuestionTypeOption {
+  value: AuthoringQuestionType
+  label: string
+  shortLabel: string
+  icon: string
+  /** Long, sentence-form description for the inspector caption. */
+  description: string
+  /** Compact one-liner shown under the title in `SelectionTileGrid` tiles. */
+  tileSummary: string
+  /** "Single best answer", "Multiple response", etc. — appears under the title. */
+  badge?: string
+  /** Maps to the storage type when persisting. */
+  storageType: QuestionBankType
+}
+
+export const AUTHORING_QUESTION_TYPES: readonly AuthoringQuestionTypeOption[] = [
+  {
+    value: "mcq_single",
+    label: "Multiple choice",
+    shortLabel: "Multiple choice",
+    icon: "fa-list-radio",
+    description:
+      "NBME-style. Stem describes a clinical scenario; pick the one best option. Default 5 distractors.",
+    tileSummary: "Single correct answer from a set of options",
+    badge: "Single best answer",
+    storageType: "multiple_choice",
+  },
+  {
+    value: "mcq_multiple",
+    label: "Multi-select",
+    shortLabel: "Multi-select",
+    icon: "fa-list-check",
+    description:
+      "NCLEX-style. Learner selects every correct option from the list. Common for safety and prioritisation items.",
+    tileSummary: "One or more correct answers — partial credit",
+    badge: "Multiple response",
+    storageType: "multiple_choice",
+  },
+  {
+    value: "true_false",
+    label: "True / False",
+    shortLabel: "True / False",
+    icon: "fa-circle-half-stroke",
+    description:
+      "Use sparingly — best for unambiguous facts. Avoid for nuanced clinical judgment.",
+    tileSummary: "Binary statement — quick recall",
+    storageType: "true_false",
+  },
+  {
+    value: "short_answer",
+    label: "Short answer",
+    shortLabel: "Short answer",
+    icon: "fa-input-text",
+    description:
+      "Free-text response with a model answer + acceptable variants. Good for definitions and one-line answers.",
+    tileSummary: "Single word or short phrase, exact-match",
+    storageType: "short_answer",
+  },
+  {
+    value: "numeric",
+    label: "Numeric",
+    shortLabel: "Numeric",
+    icon: "fa-input-numeric",
+    description:
+      "Number-only response with optional units and a ± tolerance band. Auto-graded on submission.",
+    tileSummary: "Number with units and tolerance band",
+    badge: "Auto-graded",
+    storageType: "short_answer",
+  },
+  {
+    value: "essay",
+    label: "Essay",
+    shortLabel: "Essay",
+    icon: "fa-paragraph",
+    description:
+      "Long-form response graded against a rubric. Use for clinical reasoning and care-plan items.",
+    tileSummary: "Long response — rubric-graded",
+    badge: "Rubric",
+    storageType: "short_answer",
+  },
+  {
+    value: "fill_blank",
+    label: "Fill in the blank",
+    shortLabel: "Fill in the blank",
+    icon: "fa-text-size",
+    description:
+      "Sentence with one or more {{blanks}}; learners type the missing word(s). List accepted answers per blank.",
+    tileSummary: "Sentence with one or more blanks to fill",
+    storageType: "short_answer",
+  },
+  {
+    value: "matching",
+    label: "Matching",
+    shortLabel: "Matching",
+    icon: "fa-arrow-right-arrow-left",
+    description:
+      "Two columns — pair each prompt on the left to its correct match on the right.",
+    tileSummary: "Pair terms on the left to definitions on the right",
+    storageType: "multiple_choice",
+  },
+  {
+    value: "ordering",
+    label: "Ordering",
+    shortLabel: "Ordering",
+    icon: "fa-list-ol",
+    description:
+      "Show the steps; the learner re-orders them into the correct sequence (e.g. ACLS algorithm steps).",
+    tileSummary: "Place items in the correct sequence",
+    storageType: "multiple_choice",
+  },
+  {
+    value: "hotspot",
+    label: "Hotspot",
+    shortLabel: "Hotspot",
+    icon: "fa-bullseye-pointer",
+    description:
+      "Image-based item — learner clicks the correct region (e.g. anatomy, x-ray, ECG).",
+    tileSummary: "Click the correct region of an image",
+    badge: "Image-based",
+    storageType: "multiple_choice",
+  },
+] as const
+
+export function authoringQuestionType(value: AuthoringQuestionType): AuthoringQuestionTypeOption {
+  return AUTHORING_QUESTION_TYPES.find(t => t.value === value) ?? AUTHORING_QUESTION_TYPES[0]
+}
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Difficulty + Bloom + cognitive level (NBME)
+// ─────────────────────────────────────────────────────────────────────────────
+
+export const AUTHORING_DIFFICULTY_OPTIONS = [
+  { value: "easy", label: "Easy", description: "Recall · expected ≥ 80% correct" },
+  { value: "medium", label: "Medium", description: "Application · 50–80% correct" },
+  { value: "hard", label: "Hard", description: "Analysis · ≤ 50% correct" },
+] as const
+
+export const AUTHORING_BLOOM_OPTIONS: readonly { value: QuestionBankBloomLevel; label: string; hint: string }[] = [
+  { value: "Remember", label: "Remember", hint: "Recall facts, terms, basic concepts" },
+  { value: "Understand", label: "Understand", hint: "Explain, summarise, classify" },
+  { value: "Apply", label: "Apply", hint: "Use knowledge in a new situation" },
+  { value: "Analyze", label: "Analyze", hint: "Break information apart, examine relationships" },
+  { value: "Evaluate", label: "Evaluate", hint: "Justify a stand, defend a decision" },
+  { value: "Create", label: "Create", hint: "Produce new or original work" },
+] as const
+
+/** NBME-aligned cognitive level — separate from Bloom (broader). */
+export const AUTHORING_COG_LEVEL_OPTIONS = [
+  { value: "recall", label: "Recall", hint: "Definitions, mechanisms, anatomy" },
+  { value: "application", label: "Application", hint: "Apply concept to a new patient scenario" },
+  { value: "analysis", label: "Analysis", hint: "Compare, evaluate, synthesise findings" },
+] as const
+export type AuthoringCogLevel = typeof AUTHORING_COG_LEVEL_OPTIONS[number]["value"]
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Subject area / body system / discipline / phase
+// ─────────────────────────────────────────────────────────────────────────────
+
+export const AUTHORING_SUBJECT_AREAS = [
+  "Anatomy",
+  "Physiology",
+  "Pathology",
+  "Pharmacology",
+  "Microbiology & immunology",
+  "Behavioral science",
+  "Biochemistry & genetics",
+  "Public health & epidemiology",
+  "Clinical skills",
+  "Communication & ethics",
+] as const
+export type AuthoringSubjectArea = typeof AUTHORING_SUBJECT_AREAS[number]
+
+export const AUTHORING_BODY_SYSTEMS = [
+  { value: "cardiovascular", label: "Cardiovascular", icon: "fa-heart-pulse" },
+  { value: "respiratory", label: "Respiratory", icon: "fa-lungs" },
+  { value: "renal", label: "Renal & urinary", icon: "fa-droplet" },
+  { value: "gastrointestinal", label: "Gastrointestinal", icon: "fa-stomach" },
+  { value: "endocrine", label: "Endocrine", icon: "fa-flask" },
+  { value: "musculoskeletal", label: "Musculoskeletal", icon: "fa-bone" },
+  { value: "nervous", label: "Nervous", icon: "fa-brain" },
+  { value: "reproductive", label: "Reproductive", icon: "fa-venus-mars" },
+  { value: "hematologic", label: "Hematologic & oncologic", icon: "fa-vial" },
+  { value: "immune", label: "Immune", icon: "fa-shield-virus" },
+  { value: "skin", label: "Skin & subcutaneous", icon: "fa-hand-dots" },
+  { value: "behavioral_psych", label: "Behavioral / psych", icon: "fa-comments" },
+  { value: "multisystem", label: "Multisystem", icon: "fa-circle-nodes" },
+] as const
+export type AuthoringBodySystem = typeof AUTHORING_BODY_SYSTEMS[number]["value"]
+
+export const AUTHORING_DISCIPLINES = [
+  "Medicine (MD / DO)",
+  "Nursing (BSN / MSN)",
+  "Pharmacy (PharmD)",
+  "Dental (DMD / DDS)",
+  "Physical therapy (DPT)",
+  "Occupational therapy",
+  "Physician assistant",
+  "Respiratory therapy",
+  "Medical lab science",
+  "Radiologic sciences",
+  "Public health (MPH)",
+] as const
+export type AuthoringDiscipline = typeof AUTHORING_DISCIPLINES[number]
+
+export const AUTHORING_PHASES = [
+  { value: "preclinical", label: "Pre-clinical", hint: "Foundational sciences" },
+  { value: "clinical", label: "Clinical", hint: "Clerkships / practicum" },
+  { value: "residency", label: "Residency / fellowship", hint: "Post-graduate training" },
+  { value: "ce", label: "Continuing education", hint: "Practising clinicians" },
+] as const
+export type AuthoringPhase = typeof AUTHORING_PHASES[number]["value"]
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Workflow status
+// ─────────────────────────────────────────────────────────────────────────────
+
+export type AuthoringStatus = "draft" | "in_review" | "approved" | "published" | "retired"
+
+export const AUTHORING_STATUS_OPTIONS: readonly { value: AuthoringStatus; label: string; description: string; icon: string }[] = [
+  {
+    value: "draft",
+    label: "Draft",
+    description: "Visible only to authors. Not eligible for assessments.",
+    icon: "fa-file-pen",
+  },
+  {
+    value: "in_review",
+    label: "In review",
+    description: "Awaiting subject-matter expert peer review.",
+    icon: "fa-magnifying-glass",
+  },
+  {
+    value: "approved",
+    label: "Approved",
+    description: "SME signed off. Ready to publish to the live bank.",
+    icon: "fa-circle-check",
+  },
+  {
+    value: "published",
+    label: "Published",
+    description: "Live in the bank. Available for exam / quiz selection.",
+    icon: "fa-broadcast-tower",
+  },
+  {
+    value: "retired",
+    label: "Retired",
+    description: "Removed from active use. Kept for audit and reuse history.",
+    icon: "fa-box-archive",
+  },
+] as const
+
+// ─────────────────────────────────────────────────────────────────────────────
+// Defaults
+// ─────────────────────────────────────────────────────────────────────────────
+
+export const AUTHORING_DEFAULT_OPTION_COUNT = 5
+export const AUTHORING_MIN_OPTION_COUNT = 2
+export const AUTHORING_MAX_OPTION_COUNT = 8
+
+/** Stem placeholder — modelled on a typical NBME / clerkship vignette. */
+export const AUTHORING_STEM_PLACEHOLDER = `A 58-year-old man presents to the emergency department with substernal chest pressure that began two hours ago while mowing the lawn. The pain radiates to the left jaw and is associated with diaphoresis and nausea. Past medical history is significant for hypertension and type 2 diabetes mellitus. Vital signs show blood pressure 158/92 mm Hg, heart rate 102/min, respirations 20/min. Physical examination is notable for an S4 gallop. ECG shows 2 mm ST-segment elevation in leads II, III, and aVF.`
+
+export const AUTHORING_LEAD_IN_PLACEHOLDER =
+  "Which of the following is the most likely diagnosis?"
+
+/** Best-practice rationale prompt — author-side, not student-facing. */
+export const AUTHORING_RATIONALE_PLACEHOLDER =
+  "Explain why this option is correct (or why this distractor is plausible). Cite mechanism, guideline, or reference where possible."
+
+/**
+ * Draft question handle assigned when the composer route loads.
+ * Format: `Q-YYMM-XXXX` (e.g. `Q-2605-A3F2`). Generate on the server and pass
+ * into `NewQuestionComposer` so SSR and hydration share one value.
+ */
+export function generateDraftQuestionId(now = new Date()): string {
+  const yy = String(now.getFullYear()).slice(-2)
+  const mm = String(now.getMonth() + 1).padStart(2, "0")
+  const rand = Math.random().toString(16).slice(2, 6).toUpperCase().padEnd(4, "0")
+  return `Q-${yy}${mm}-${rand}`
+}

package/template/lib/question-bank-nav.ts

@@ -130,6 +130,50 @@ export interface QuestionBankHubHeaderModel {
   breadcrumbs?: { label: string; href?: string }[]
 }
 
+/** Back link for `/question-bank/new` — icon + parent label in `SiteHeader` (`back` prop). */
+export function newQuestionBackNav(
+  folders: QuestionBankFolder[],
+  folderId?: string,
+): { label: string; href: string } {
+  if (folderId) {
+    const folder = folders.find(f => f.id === folderId)
+    if (folder) {
+      return {
+        label: folder.name,
+        href: questionBankNavHref({ scope: "folder", folderId: folder.id }),
+      }
+    }
+  }
+  return {
+    label: QUESTION_BANK_HUB_BREADCRUMB.label,
+    href: questionBankNavHref({ scope: "all" }),
+  }
+}
+
+/** Ancestor-only breadcrumbs for `/question-bank/new` (current page is the PageHeader title). */
+export function newQuestionBreadcrumbs(
+  folders: QuestionBankFolder[],
+  folderId?: string,
+): { label: string; href: string }[] {
+  if (folderId) {
+    const folder = folders.find(f => f.id === folderId)
+    if (folder) {
+      return [
+        {
+          label: folder.name,
+          href: questionBankNavHref({ scope: "folder", folderId: folder.id }),
+        },
+      ]
+    }
+  }
+  return [
+    {
+      label: QUESTION_BANK_HUB_BREADCRUMB.label,
+      href: QUESTION_BANK_HUB_BREADCRUMB.href,
+    },
+  ]
+}
+
 export function questionBankHubHeaderModel(
   folders: QuestionBankFolder[],
   nav: QuestionBankNavState,

package/template/lib/raf-throttle.ts

@@ -0,0 +1,45 @@
+/**
+ * Coalesce many calls to `fn` into one per animation frame.
+ *
+ * Use for high-frequency layout-reading event handlers (scroll, resize,
+ * visualViewport, ResizeObserver) where the work must happen in a frame but
+ * doing it on every event call (60+/s for resize, hundreds/s for capture
+ * scrolls) wastes layout/paint cycles. The returned function exposes
+ * `.cancel()` so effect cleanup can drop a pending frame.
+ *
+ * Pattern:
+ *   const apply = () => { ...layout reads + setState... }
+ *   const scheduled = rafThrottle(apply)
+ *   window.addEventListener("scroll", scheduled, { passive: true, capture: true })
+ *   return () => {
+ *     scheduled.cancel()
+ *     window.removeEventListener("scroll", scheduled, { capture: true })
+ *   }
+ */
+export function rafThrottle<TArgs extends unknown[]>(
+  fn: (...args: TArgs) => void,
+): ((...args: TArgs) => void) & { cancel: () => void } {
+  let rafId = 0
+  let lastArgs: TArgs | null = null
+
+  const scheduled = ((...args: TArgs) => {
+    lastArgs = args
+    if (rafId !== 0) return
+    rafId = requestAnimationFrame(() => {
+      rafId = 0
+      const a = lastArgs
+      lastArgs = null
+      if (a) fn(...a)
+    })
+  }) as ((...args: TArgs) => void) & { cancel: () => void }
+
+  scheduled.cancel = () => {
+    if (rafId !== 0) {
+      cancelAnimationFrame(rafId)
+      rafId = 0
+    }
+    lastArgs = null
+  }
+
+  return scheduled
+}

package/template/lib/sidebar-state-cookie.ts

@@ -0,0 +1,9 @@
+/** Cookie name persisted by `@exxatdesignux/ui` `SidebarProvider` (`setOpen`). */
+export const SIDEBAR_STATE_COOKIE_NAME = "sidebar_state"
+
+/** Read desktop sidebar expanded state for SSR `defaultOpen` (matches client cookie restore). */
+export function sidebarDefaultOpenFromCookie(
+  value: string | undefined,
+): boolean {
+  return value !== "false"
+}