@exxatdesignux/ui 0.2.8 → 0.2.10

package/template/docs/drawer-vs-dialog-pattern.md

@@ -0,0 +1,50 @@
+# Drawer vs dialog vs route
+
+> **Related:** `docs/data-views-pattern.md` (Page vs drawer), **`AGENTS.md` §6.4**, **`.cursor/rules/exxat-page-vs-drawer.mdc`**. **This doc** splits **drawer/sheet** vs **modal dialog** when both stay on the same route.
+
+## Drawer / sheet (side panel)
+
+**Use when:**
+
+- The **list or hub behind the panel** still matters (user compares, copies, or dismisses and continues browsing).
+- The flow is **medium length** — export options, table/column properties, invite collaborators, filters that mirror the grid.
+- **Width** helps — tables of options, multi-field forms that would feel cramped in a narrow dialog.
+
+**Examples in repo:** `TablePropertiesDrawer`, `ExportDrawer`, `InviteCollaboratorsDrawer`, `Drawer` shells that slide from the edge.
+
+**Avoid when:** The task is the **only** thing the user should focus on and the parent would distract (prefer **dialog** for a sharp confirm, or **route** for a full wizard).
+
+## Dialog (modal)
+
+**Use when:**
+
+- You need a **hard stop** — user must answer or dismiss before interacting with the page again (confirm delete, acknowledge legal, pick a single blocking choice).
+- The content is **short and focused** — one decision, one form step, or a compact message with primary/secondary actions.
+- **Destructive or irreversible** actions — pair with clear copy; **Esc** / Cancel returns safely.
+
+**Examples:** `AlertDialog`, confirm-before-remove, “Save changes?” when navigating away.
+
+**Avoid when:** Users need to **reference** the grid or copy values from the page while the panel is open — use a **drawer** or **inline** pattern instead.
+
+## Route (new page)
+
+Use when the work is **primary**, **long**, **multi-step**, or deserves its **own URL** — see **`exxat-page-vs-drawer.mdc`** and **`AGENTS.md` §6.4**.
+
+## Quick matrix
+
+| Need | Drawer | Dialog | Route |
+| --- | --- | --- | --- |
+| Keep hub visible | Yes | No (blocks) | No |
+| Short confirm / alert | Rare | Yes | Overkill |
+| Long form / wizard | Cramped | No | Yes |
+| Properties tied to a table | Yes | Too small | Optional |
+
+## Accessibility
+
+- **Dialog / drawer / sheet:** Must expose a **title** (`DialogTitle`, `SheetTitle`, `DrawerTitle`) — use `sr-only` if visually hidden.
+- **Focus trap** is expected in dialogs; drawers should still **restore focus** on close to the invoking control.
+
+## See also
+
+- **`.cursor/rules/exxat-drawer-vs-dialog.mdc`**, **`.cursor/skills/exxat-drawer-vs-dialog/SKILL.md`**
+- **`exxat-no-toast.mdc`** — use dialog/banner/inline, not toasts, for outcomes that need acknowledgment.

package/template/docs/kpi-strip-max-four-pattern.md

@@ -0,0 +1,29 @@
+# KPI strip — maximum four tiles
+
+> **Code:** `lib/dashboard-layout-merge.ts` — **`KEY_METRICS_KPI_COUNT_MIN`**, **`KEY_METRICS_KPI_COUNT_MAX`** (4), **`clampKeyMetricsKpiCount`**. **Component:** `KeyMetrics` in `components/key-metrics.tsx`.
+
+## Rule
+
+On **primary list hubs** (`ListPageTemplate` metrics slot) and on **dashboard “key metrics” cards** (Data tab chart bundles), **show at most four** `MetricItem` tiles at once.
+
+## Why four
+
+- **Scanning** — More than four headline numbers compete; users miss deltas and period context.
+- **Layout** — `KeyMetrics` wraps to multiple rows; four keeps one or two clean rows on common breakpoints (including **`metricsHalfWidthLayout`** on span-1 cards).
+- **Persistence** — Dashboard layout already stores **`keyMetricsKpiCount`** in **`1…4`**; list-page KPI helpers should **not** return a fifth tile expecting it to display.
+
+## Implementation
+
+1. **KPI builders** (`lib/mock/*-kpi.ts`) — Return **≤ 4** items, or **`.slice(0, 4)`** after prioritizing (hero total + top three drivers). Merge extras into **`MetricInsight`** copy instead of a fifth tile when possible.
+2. **Dashboard canvas** — Never raise **`KEY_METRICS_KPI_COUNT_MAX`**; use **`clampKeyMetricsKpiCount`** when reading saved JSON.
+3. **Full-page dashboards** — If more summaries are needed, add **sections** (charts, tables, secondary cards), not a fifth KPI in the same strip.
+
+## MUST NOT
+
+- Ship **five+** `MetricItem` entries in a single **`KeyMetrics`** band meant as the **primary** KPI row for a hub or the **key-metrics** dashboard card.
+- Duplicate the same metric as two tiles to pad count — prefer **insight rail** or **`MetricInsight`**.
+
+## See also
+
+- **`docs/kpi-trend-pattern.md`** — deltas, arrows, **`trendPolarity`**.
+- **`.cursor/rules/exxat-kpi-max-four.mdc`**, **`.cursor/skills/exxat-kpi-max-four/SKILL.md`**

package/template/docs/kpi-trend-pattern.md

@@ -0,0 +1,43 @@
+# KPI trend arrows and deltas (`KeyMetrics`)
+
+> **Handbook:** [`AGENTS.md`](../AGENTS.md) (mock KPI helpers, `KeyMetrics`). **Component:** [`components/key-metrics.tsx`](../components/key-metrics.tsx). **Cursor:** [`.cursor/rules/exxat-kpi-trends.mdc`](../../.cursor/rules/exxat-kpi-trends.mdc). **Skill:** [`.cursor/skills/exxat-kpi-trends/SKILL.md`](../../.cursor/skills/exxat-kpi-trends/SKILL.md).
+
+## Goals
+
+1. **Contextual** — The **label**, **value format** (count, %, currency, days), and **comparison period** (e.g. “vs last week”) must read as one story. Do not paste a generic “+12%” without tying it to what moved.
+2. **Honest direction** — **`trend`** (`up` | `down` | `neutral`) always matches the **signed change** in the underlying metric so the **arrow** reflects reality.
+3. **Correct sentiment** — **`trendPolarity`** decides whether “up” is **good news** (tint + assistive copy), **bad news**, or **informational** (muted — direction only).
+
+## `MetricItem` fields
+
+| Field | Role |
+| --- | --- |
+| `value` | Current bucket total or rate (formatted string or number). |
+| `delta` | Human-readable delta for the selected period, e.g. `+5`, `-3`, `+12%`, `—` when no comparison. |
+| `trend` | **Visual direction** of that delta: more → `up`, less → `down`, flat / N/A → `neutral`. |
+| `trendPolarity` | Optional. **`higher_is_better`** (default) \| **`lower_is_better`** \| **`informational`**. |
+
+## Polarity cheat sheet
+
+| `trendPolarity` | Use when | Up arrow tint | Down arrow tint |
+| --- | --- | --- | --- |
+| **`higher_is_better`** (default) | Revenue, pass rate, completions, enrolled count, positive CSAT | Favorable (brand / chart positive token) | Unfavorable (destructive) |
+| **`lower_is_better`** | Error rate, overdue tasks, **low PBI / item quality flags**, time-on-task when minimizing, spend when cutting cost | Unfavorable | Favorable |
+| **`informational`** | Library size, mix %, neutral volume | Muted | Muted |
+
+**Psychometrics example:** Point-biserial (PBI) **dropping** usually helps discrimination — often good (`lower_is_better` on a *“low quality” count* is clearer: **count of items below a review threshold** rising → `trend: "up"` + `trendPolarity: "lower_is_better"` → arrow up with **unfavorable** tint).
+
+## Accessibility
+
+- **Never colour alone:** `KeyMetrics` keeps **icon + numeric delta**; `aria-label` on the chip uses **`metricTrendAriaQualifier`** (e.g. “increased, unfavorable +1”).
+- **Decorative icons** stay `aria-hidden`; meaning lives in the chip’s **`aria-label`** and visible delta text.
+
+## Anti-patterns
+
+- Forcing **`trend: "up"`** green because “up feels good” when the metric is **defects** or **flags** — set **`lower_is_better`** instead.
+- Hiding a worsening metric by flipping the arrow without changing **`trend`** — arrows must match the data.
+- Using **`informational`** for KPIs that **do** have an agreed quality bar — pick a polarity or omit the trend chip (`delta: "—"`, `trend: "neutral"`).
+
+## Related surfaces
+
+- **`ChartCard`** `miniMetrics` / `kpi-chart` variant — optional **`trendPolarity`** on each mini metric; uses the same **`metricTrendTone`** helper from `key-metrics.tsx`.

package/template/fontawesome-subset.manifest.json

@@ -14,7 +14,7 @@
   "iconCount": 166,
   "icons": [
     "arrow-down",
-    "arrow-down-az",
+    "arrow-down-a-z",
     "arrow-down-to-line",
     "arrow-left",
     "arrow-left-to-line",
@@ -26,7 +26,7 @@
     "arrow-trend-up",
     "arrow-up",
     "arrow-up-arrow-down",
-    "arrow-up-az",
+    "arrow-up-a-z",
     "arrow-up-right",
     "arrow-up-right-from-square",
     "arrows-rotate",

package/template/hooks/use-location-hash.ts

@@ -2,14 +2,20 @@
 
 import * as React from "react"
 
+function subscribeHash(callback: () => void) {
+  window.addEventListener("hashchange", callback)
+  return () => window.removeEventListener("hashchange", callback)
+}
+
+function getHashSnapshot() {
+  return window.location.hash
+}
+
+function getServerHashSnapshot() {
+  return ""
+}
+
 /** Current `window.location.hash` (including `#`), updated on `hashchange`. */
 export function useLocationHash(): string {
-  const [hash, setHash] = React.useState("")
-  React.useEffect(() => {
-    const read = () => setHash(typeof window !== "undefined" ? window.location.hash : "")
-    read()
-    window.addEventListener("hashchange", read)
-    return () => window.removeEventListener("hashchange", read)
-  }, [])
-  return hash
+  return React.useSyncExternalStore(subscribeHash, getHashSnapshot, getServerHashSnapshot)
 }

package/template/hooks/use-secondary-panel-hub-nav.ts

@@ -0,0 +1,98 @@
+"use client"
+
+import * as React from "react"
+import { usePathname, useRouter, useSearchParams } from "next/navigation"
+
+import { useSecondaryPanel } from "@/components/secondary-panel"
+import { QUESTION_BANK_HUB_FIND_PATH, QUESTION_BANK_LIBRARY_PATH, QUESTION_BANK_LIST_PATH } from "@/lib/question-bank-nav"
+
+function rewriteLibraryCanonicalToDedicatedSurface(pathname: string, nextHref: string, hash: string): string {
+  if (!nextHref.startsWith(QUESTION_BANK_LIBRARY_PATH)) return `${nextHref}${hash}`
+  const tail = nextHref.slice(QUESTION_BANK_LIBRARY_PATH.length)
+  if (pathname === QUESTION_BANK_LIST_PATH) return `${QUESTION_BANK_LIST_PATH}${tail}${hash}`
+  if (pathname === QUESTION_BANK_HUB_FIND_PATH) return `${QUESTION_BANK_HUB_FIND_PATH}${tail}${hash}`
+  return `${nextHref}${hash}`
+}
+
+function questionBankSearchParamsEqual(a: URLSearchParams, b: URLSearchParams): boolean {
+  const keys = new Set([...a.keys(), ...b.keys()])
+  for (const k of keys) {
+    const av = a.getAll(k).join("\u0000")
+    const bv = b.getAll(k).join("\u0000")
+    if (av !== bv) return false
+  }
+  return true
+}
+
+export interface UseSecondaryPanelHubNavOptions<TNav> {
+  /** Primary hub pathname (e.g. `/question-bank/library`). */
+  hubPathname: string
+  /** When set, these pathnames are treated as the same hub (e.g. library + list search surface). */
+  hubPathnames?: readonly string[]
+  /** `PANELS` / `useAutoPanel` id (e.g. `question-bank`). */
+  panelId: string
+  parseNav: (searchParams: URLSearchParams) => TNav
+  /** When non-null, the hub URL is rewritten (keeps the current hash). */
+  canonicalHref?: (searchParams: URLSearchParams) => string | null
+  /** Re-open the secondary panel when the user returns to the default scope (e.g. All questions). */
+  shouldReopenPanel?: (nav: TNav) => boolean
+}
+
+/**
+ * URL scope for a primary hub with a nested secondary panel — shared between panel nav and main content.
+ */
+export function useSecondaryPanelHubNav<TNav>({
+  hubPathname,
+  hubPathnames,
+  panelId,
+  parseNav,
+  canonicalHref,
+  shouldReopenPanel,
+}: UseSecondaryPanelHubNavOptions<TNav>) {
+  const pathname = usePathname()
+  const router = useRouter()
+  const searchParams = useSearchParams()
+  const { openPanel, activePanel } = useSecondaryPanel()
+
+  const hubPaths = React.useMemo(
+    () => (hubPathnames?.length ? [...hubPathnames] : [hubPathname]),
+    [hubPathname, hubPathnames],
+  )
+  const isHubPath = hubPaths.includes(pathname)
+  const hubBasePath = hubPaths.includes(pathname) ? pathname : hubPathname
+
+  const searchParamsKey = searchParams.toString()
+  const navState = React.useMemo(
+    () => parseNav(new URLSearchParams(searchParamsKey)),
+    [parseNav, searchParamsKey],
+  )
+
+  React.useEffect(() => {
+    if (!isHubPath || !canonicalHref) return
+    const nextHref = canonicalHref(new URLSearchParams(searchParamsKey))
+    if (!nextHref) return
+    const hash = typeof window !== "undefined" ? window.location.hash : ""
+    let target = `${nextHref}${hash}`
+    if (pathname === QUESTION_BANK_LIST_PATH || pathname === QUESTION_BANK_HUB_FIND_PATH) {
+      target = rewriteLibraryCanonicalToDedicatedSurface(pathname, nextHref, hash)
+    }
+    try {
+      const origin = typeof window !== "undefined" ? window.location.origin : "http://localhost"
+      const u = new URL(target, origin)
+      const want = u.searchParams
+      const cur = new URLSearchParams(searchParamsKey)
+      if (u.pathname === pathname && questionBankSearchParamsEqual(want, cur)) return
+    } catch {
+      /* ignore parse errors — fall through to replace */
+    }
+    router.replace(target, { scroll: false })
+  }, [canonicalHref, isHubPath, pathname, router, searchParamsKey])
+
+  React.useEffect(() => {
+    if (!isHubPath || !shouldReopenPanel?.(navState)) return
+    if (activePanel === panelId) return
+    openPanel(panelId)
+  }, [activePanel, isHubPath, navState, openPanel, panelId, shouldReopenPanel])
+
+  return { navState, searchParamsKey, hubPathname, hubBasePath, pathname, isHubPath }
+}

package/template/lib/ask-leo-route-context.ts

@@ -78,6 +78,30 @@ export function getAskLeoRouteContext(pathname: string | null): AskLeoRouteConte
     }
   }
 
+  if (pathname.startsWith("/question-bank/library") || pathname.startsWith("/question-bank/list") || pathname.startsWith("/question-bank/find")) {
+    return {
+      title: "Question library",
+      description: "Browse folders, views, and mock assessment items.",
+      suggestions: [
+        "Summarize questions in the active folder scope",
+        "Suggest folders for a new pediatrics module",
+        "How do panel and tree views relate to the same dataset?",
+      ],
+    }
+  }
+
+  if (pathname.startsWith("/question-bank")) {
+    return {
+      title: "Question bank",
+      description: "Search in plain language, draft items with AI, or open the full library.",
+      suggestions: [
+        "Draft a multiple-choice question on clinical reasoning",
+        "Outline a new question bank for a course module",
+        "Rewrite this stem for clarity and bias-free wording",
+      ],
+    }
+  }
+
   if (pathname.startsWith("/help")) {
     return {
       title: "Get help",

package/template/lib/collaborator-access.ts

@@ -0,0 +1,92 @@
+/** Library access roles for shared hubs — see `docs/collaboration-access-pattern.md`. */
+export type CollaboratorAccessRole = "owner" | "editor" | "commenter" | "viewer"
+
+export const COLLABORATOR_ACCESS_LABELS: Record<CollaboratorAccessRole, string> = {
+  owner: "Owner",
+  editor: "Editor",
+  commenter: "Commenter",
+  viewer: "Viewer",
+}
+
+/** Decorative FA icon names (`fa-light fa-*`) for library access chips and menus. */
+export const COLLABORATOR_ACCESS_ICON_LIGHT: Record<CollaboratorAccessRole, string> = {
+  owner: "fa-crown",
+  editor: "fa-pen-to-square",
+  commenter: "fa-comment",
+  viewer: "fa-eye",
+}
+
+export type InviteCollaboratorAccessRole = Exclude<CollaboratorAccessRole, "owner">
+
+export const INVITE_COLLABORATOR_ACCESS_OPTIONS: {
+  value: InviteCollaboratorAccessRole
+  label: string
+  description: string
+}[] = [
+  {
+    value: "editor",
+    label: "Editor",
+    description: "Can add and edit questions in this library.",
+  },
+  {
+    value: "commenter",
+    label: "Commenter",
+    description: "Can review and comment without editing.",
+  },
+  {
+    value: "viewer",
+    label: "Viewer",
+    description: "Can view questions only.",
+  },
+]
+
+/** Roster access menu — includes Owner for existing collaborators. */
+export const ROSTER_COLLABORATOR_ACCESS_OPTIONS: {
+  value: CollaboratorAccessRole
+  label: string
+}[] = (["owner", "editor", "commenter", "viewer"] as const).map(value => ({
+  value,
+  label: COLLABORATOR_ACCESS_LABELS[value],
+}))
+
+export function rosterOwnerCount(collaborators: readonly { access?: CollaboratorAccessRole }[]) {
+  return collaborators.filter(person => person.access === "owner").length
+}
+
+export function canRemoveCollaboratorFromRoster(
+  person: { access?: CollaboratorAccessRole },
+  collaborators: readonly { access?: CollaboratorAccessRole }[],
+) {
+  if (person.access !== "owner") return true
+  return rosterOwnerCount(collaborators) > 1
+}
+
+export function canSetCollaboratorAccessRole(
+  person: { access?: CollaboratorAccessRole },
+  collaborators: readonly { access?: CollaboratorAccessRole }[],
+  nextAccess: CollaboratorAccessRole,
+) {
+  if (person.access === nextAccess) return false
+  if (person.access === "owner" && rosterOwnerCount(collaborators) === 1 && nextAccess !== "owner") {
+    return false
+  }
+  return true
+}
+
+export function collaboratorRemoveBlockedReason(
+  person: { access?: CollaboratorAccessRole },
+  collaborators: readonly { access?: CollaboratorAccessRole }[],
+) {
+  if (canRemoveCollaboratorFromRoster(person, collaborators)) return undefined
+  return "This person is the only owner."
+}
+
+/** Default label for the collaboration header when the roster is empty. */
+export const COLLABORATION_HEADER_ADD_LABEL = "Add collaborator"
+
+export function displayNameFromInviteEmail(email: string) {
+  const local = email.split("@")[0] ?? email
+  return local
+    .replace(/[._-]+/g, " ")
+    .replace(/\b\w/g, char => char.toUpperCase())
+}

package/template/lib/command-menu-config.ts

@@ -99,7 +99,14 @@ const STATIC_COMMAND_GROUPS: CommandMenuGroup[] = [
         icon: "fa-light fa-books",
         label: "Question bank",
         href: "/question-bank",
-        keywords: "folders assessment items tree panel",
+        keywords: "search ai create ask leo discovery hub",
+      },
+      {
+        id: "nav-question-bank-library",
+        icon: "fa-light fa-table-list",
+        label: "Question library",
+        href: "/question-bank/library",
+        keywords: "folders assessment items tree panel table",
       },
       { id: "nav-data-list", icon: "fa-light fa-table", label: "List hub", href: "/data-list" },
       { id: "nav-settings", icon: "fa-light fa-gear", label: "Settings", href: "/settings" },

package/template/lib/command-menu-search-data.ts

@@ -32,14 +32,17 @@ function sampleRowSearchItems(): CommandMenuItem[] {
   })
 }
 
+/** Built once at module load — avoids remapping all placement rows on every layout render. */
+export const COMMAND_MENU_SEARCH_DATA_GROUPS: CommandMenuGroup[] = [
+  {
+    id: "sample-rows",
+    heading: "Demo rows",
+    items: sampleRowSearchItems(),
+    searchOnly: true,
+  },
+]
+
 /** Demo rows for the list hub — search-only so the palette stays lightweight on open. */
 export function getCommandMenuSearchDataGroups(): CommandMenuGroup[] {
-  return [
-    {
-      id: "sample-rows",
-      heading: "Demo rows",
-      items: sampleRowSearchItems(),
-      searchOnly: true,
-    },
-  ]
+  return COMMAND_MENU_SEARCH_DATA_GROUPS
 }

package/template/lib/data-list-display-options.ts

@@ -25,7 +25,7 @@ export interface DataListDisplayOptions {
 }
 
 export const DEFAULT_DATA_LIST_DISPLAY_OPTIONS: DataListDisplayOptions = {
-  boardGroupByColumnKey: "status",
+  boardGroupByColumnKey: "topic",
   boardLineCount: 2,
   showViewTitle: true,
   showColumnLabels: true,

package/template/lib/data-view-dashboard-placements-layout.ts

@@ -0,0 +1,215 @@
+/**
+ * Placements **Data** view dashboard — card ids, defaults, and persistence.
+ * Split from `data-view-dashboard-charts.tsx` so list-hub code can import layout
+ * without pulling Recharts / chart canvas into the main chunk.
+ */
+
+import {
+  KEY_METRICS_KPI_COUNT_DEFAULT,
+  mergeDashboardLayoutGeneric,
+} from "@/lib/dashboard-layout-merge"
+import {
+  loadDataViewLayout as loadStoredDataViewLayout,
+  saveDataViewLayout as saveStoredDataViewLayout,
+} from "@/lib/data-view-dashboard-storage"
+
+export type ChartType =
+  | "bar"
+  | "horizontal-bar"
+  | "pie"
+  | "area"
+  | "line"
+  | "radial"
+  | "stacked-bar"
+
+export interface ChartTypeOption {
+  type: ChartType
+  label: string
+  icon: string
+}
+
+export interface DashboardCardDef {
+  id: string
+  title: string
+  description: string
+  defaultSpan: 1 | 2
+  defaultChartType: ChartType
+  chartTypes: ChartTypeOption[]
+}
+
+/** Virtual “card” for the KPI strip — reorderable with charts in edit mode */
+export const KEY_METRICS_CARD_ID = "key-metrics"
+
+export const ALL_DASHBOARD_CARDS: DashboardCardDef[] = [
+  {
+    id: KEY_METRICS_CARD_ID,
+    title: "Key metrics",
+    description: "Summary KPIs for filtered placements",
+    defaultSpan: 1,
+    defaultChartType: "bar",
+    chartTypes: [],
+  },
+  {
+    id: "status-pipeline",
+    title: "Status Pipeline",
+    description: "Where placements are in the workflow",
+    defaultSpan: 1,
+    defaultChartType: "bar",
+    chartTypes: [
+      { type: "bar", label: "Bar", icon: "fa-light fa-chart-bar" },
+      { type: "horizontal-bar", label: "Horizontal Bar", icon: "fa-light fa-chart-bar fa-rotate-90" },
+      { type: "pie", label: "Donut", icon: "fa-light fa-chart-pie" },
+    ],
+  },
+  {
+    id: "program-mix",
+    title: "Placements by Program",
+    description: "Distribution across active programs",
+    defaultSpan: 1,
+    defaultChartType: "pie",
+    chartTypes: [
+      { type: "pie", label: "Donut", icon: "fa-light fa-chart-pie" },
+      { type: "bar", label: "Bar", icon: "fa-light fa-chart-bar" },
+      { type: "horizontal-bar", label: "Horizontal Bar", icon: "fa-light fa-chart-bar fa-rotate-90" },
+    ],
+  },
+  {
+    id: "compliance-status",
+    title: "Compliance Status",
+    description: "Document readiness for upcoming placements",
+    defaultSpan: 1,
+    defaultChartType: "horizontal-bar",
+    chartTypes: [
+      { type: "horizontal-bar", label: "Horizontal Bar", icon: "fa-light fa-chart-bar fa-rotate-90" },
+      { type: "bar", label: "Bar", icon: "fa-light fa-chart-bar" },
+      { type: "pie", label: "Donut", icon: "fa-light fa-chart-pie" },
+    ],
+  },
+  {
+    id: "readiness-overview",
+    title: "Student Readiness",
+    description: "How prepared students are for their placements",
+    defaultSpan: 1,
+    defaultChartType: "bar",
+    chartTypes: [
+      { type: "bar", label: "Bar", icon: "fa-light fa-chart-bar" },
+      { type: "horizontal-bar", label: "Horizontal Bar", icon: "fa-light fa-chart-bar fa-rotate-90" },
+      { type: "pie", label: "Donut", icon: "fa-light fa-chart-pie" },
+    ],
+  },
+  {
+    id: "progress-tracker",
+    title: "Ongoing Progress",
+    description: "How far along each ongoing placement is",
+    defaultSpan: 2,
+    defaultChartType: "stacked-bar",
+    chartTypes: [
+      { type: "stacked-bar", label: "Stacked Bar", icon: "fa-light fa-layer-group" },
+      { type: "bar", label: "Bar", icon: "fa-light fa-chart-bar" },
+    ],
+  },
+  {
+    id: "site-utilisation",
+    title: "Site Utilisation",
+    description: "Which clinical sites have the most placements",
+    defaultSpan: 1,
+    defaultChartType: "horizontal-bar",
+    chartTypes: [
+      { type: "horizontal-bar", label: "Horizontal Bar", icon: "fa-light fa-chart-bar fa-rotate-90" },
+      { type: "bar", label: "Bar", icon: "fa-light fa-chart-bar" },
+      { type: "pie", label: "Donut", icon: "fa-light fa-chart-pie" },
+    ],
+  },
+  {
+    id: "completion-outcomes",
+    title: "Completion Outcomes",
+    description: "Pass rate and average ratings for completed placements",
+    defaultSpan: 1,
+    defaultChartType: "radial",
+    chartTypes: [
+      { type: "radial", label: "Radial", icon: "fa-light fa-circle-notch" },
+      { type: "bar", label: "Bar", icon: "fa-light fa-chart-bar" },
+    ],
+  },
+  {
+    id: "upcoming-timeline",
+    title: "Upcoming Start Dates",
+    description: "New placements starting in the next 8 weeks",
+    defaultSpan: 2,
+    defaultChartType: "area",
+    chartTypes: [
+      { type: "area", label: "Area", icon: "fa-light fa-chart-area" },
+      { type: "line", label: "Line", icon: "fa-light fa-chart-line" },
+      { type: "bar", label: "Bar", icon: "fa-light fa-chart-bar" },
+    ],
+  },
+]
+
+export const DEFAULT_VISIBLE_CARDS = ALL_DASHBOARD_CARDS.map(c => c.id)
+export const DEFAULT_SPANS: Record<string, 1 | 2> = Object.fromEntries(
+  ALL_DASHBOARD_CARDS.map(c => [c.id, c.defaultSpan]),
+)
+export const DEFAULT_CHART_TYPES: Record<string, ChartType> = Object.fromEntries(
+  ALL_DASHBOARD_CARDS.map(c => [c.id, c.defaultChartType]),
+)
+
+export interface DashboardLayout {
+  visible: string[]
+  order: string[]
+  spans?: Record<string, 1 | 2>
+  chartTypes?: Record<string, ChartType>
+  keyMetricsKpiCount?: number
+}
+
+export function loadDashboardLayout(): DashboardLayout | null {
+  const v = loadStoredDataViewLayout("placements")
+  if (!v) return null
+  return {
+    visible: v.visible,
+    order: v.order,
+    spans: v.spans,
+    chartTypes: v.chartTypes as Record<string, ChartType> | undefined,
+    keyMetricsKpiCount: v.keyMetricsKpiCount,
+  }
+}
+
+export function mergeDashboardLayout(saved: DashboardLayout | null): DashboardLayout {
+  const defaults = {
+    visible: [...DEFAULT_VISIBLE_CARDS],
+    order: ALL_DASHBOARD_CARDS.map(c => c.id),
+    spans: { ...DEFAULT_SPANS },
+    chartTypes: { ...DEFAULT_CHART_TYPES } as Record<string, string>,
+    keyMetricsKpiCount: KEY_METRICS_KPI_COUNT_DEFAULT,
+  }
+  const ids = ALL_DASHBOARD_CARDS.map(c => c.id)
+  const m = mergeDashboardLayoutGeneric(saved, defaults, ids)
+  return {
+    visible: m.visible,
+    order: m.order,
+    spans: m.spans as Record<string, 1 | 2>,
+    chartTypes: m.chartTypes as Record<string, ChartType>,
+    keyMetricsKpiCount: m.keyMetricsKpiCount,
+  }
+}
+
+export function saveDashboardLayout(layout: DashboardLayout) {
+  saveStoredDataViewLayout("placements", {
+    visible: layout.visible,
+    order: layout.order,
+    spans: layout.spans,
+    chartTypes: layout.chartTypes as Record<string, string> | undefined,
+    keyMetricsKpiCount: layout.keyMetricsKpiCount,
+  })
+}
+
+export function applyVisibleReorder(
+  fullOrder: string[],
+  visible: Set<string>,
+  newVisibleOrder: string[],
+): string[] {
+  let vi = 0
+  return fullOrder.map(id => {
+    if (!visible.has(id)) return id
+    return newVisibleOrder[vi++]!
+  })
+}

package/template/lib/date-filter.ts

@@ -1,5 +1,6 @@
 export {
   formatDateUS,
+  formatDateFromDate,
   formatDateTimeUS,
   parseRowDateToYmd,
   formatYmdForDisplay,