@exxatdesignux/ui 0.2.18 → 0.2.19

package/template/components/templates/page-loading-shell.tsx

@@ -0,0 +1,262 @@
+import * as React from "react"
+
+import { Skeleton } from "@/components/ui/skeleton"
+import { SidebarInset } from "@/components/ui/sidebar"
+import {
+  FOCUSED_WORKFLOW_CONTENT_PADDING_CLASS,
+  FOCUSED_WORKFLOW_MAX_WIDTH,
+} from "@/components/templates/focused-workflow-page-template"
+import { FOCUSED_WORKFLOW_SIDEBAR_SECTIONS_GRID_CLASS } from "@/components/templates/focused-workflow-layouts"
+import { PRIMARY_PAGE_MAX_WIDTH_CLASS } from "@/components/templates/primary-page-template"
+import type { PageLoadingVariant } from "@/lib/page-loading-variant"
+import { cn } from "@/lib/utils"
+
+/** Breadcrumb bar placeholder — matches `SiteHeader` footprint without client hooks. */
+function SiteHeaderSkeleton() {
+  return (
+    <div className="sticky top-0 z-30 bg-transparent">
+      <header
+        role="presentation"
+        className="flex h-(--header-height) shrink-0 items-center gap-2 rounded-t-xl bg-background ps-4 pe-2 lg:gap-2 lg:ps-6 lg:pe-2"
+      >
+        <Skeleton className="size-8 shrink-0 rounded-md" />
+        <Skeleton className="h-4 w-36 max-w-[50vw] rounded-md" />
+        <div className="ms-auto flex items-center gap-2">
+          <Skeleton className="h-8 w-16 rounded-md" />
+          <Skeleton className="size-8 rounded-md" />
+        </div>
+      </header>
+    </div>
+  )
+}
+
+interface PageLoadingChromeProps {
+  children: React.ReactNode
+  maxWidthClassName?: string
+  contentClassName?: string
+  paddingClassName?: string
+}
+
+function PageLoadingChrome({
+  children,
+  maxWidthClassName = PRIMARY_PAGE_MAX_WIDTH_CLASS,
+  contentClassName,
+  paddingClassName = "px-4 pt-2 pb-32 sm:px-6 lg:px-8",
+}: PageLoadingChromeProps) {
+  return (
+    <SidebarInset id="main-content" tabIndex={-1} aria-busy="true" aria-label="Loading page">
+      <SiteHeaderSkeleton />
+      <div className="flex min-h-0 flex-1 flex-col outline-none">
+        <div
+          className={cn(
+            "@container/main mx-auto flex min-h-0 w-full min-w-0 flex-1 flex-col",
+            maxWidthClassName,
+            paddingClassName,
+            contentClassName,
+          )}
+        >
+          {children}
+        </div>
+      </div>
+    </SidebarInset>
+  )
+}
+
+/** List hub — header, KPI band, toolbar, table rows. */
+export function PrimaryListHubLoadingBody() {
+  return (
+    <div className="flex flex-col gap-6">
+      <div className="flex flex-col gap-3 sm:flex-row sm:items-start sm:justify-between">
+        <div className="space-y-2">
+          <Skeleton className="h-9 w-56 max-w-full rounded-md" />
+          <Skeleton className="h-4 w-72 max-w-full rounded-md" />
+        </div>
+        <div className="flex shrink-0 gap-2">
+          <Skeleton className="h-9 w-28 rounded-md" />
+          <Skeleton className="h-9 w-9 rounded-md" />
+        </div>
+      </div>
+      <div className="grid grid-cols-2 gap-px overflow-hidden rounded-xl border border-border bg-border sm:grid-cols-4">
+        {Array.from({ length: 4 }).map((_, i) => (
+          <Skeleton key={i} className="h-[4.75rem] rounded-none bg-card" />
+        ))}
+      </div>
+      <div className="flex flex-wrap items-center gap-2">
+        <Skeleton className="h-9 min-w-[12rem] flex-1 rounded-md sm:max-w-xs" />
+        <Skeleton className="h-9 w-24 rounded-md" />
+        <Skeleton className="h-9 w-9 rounded-md" />
+      </div>
+      <div className="space-y-2 rounded-xl border border-border bg-card p-2">
+        <Skeleton className="h-10 w-full rounded-md" />
+        {Array.from({ length: 8 }).map((_, i) => (
+          <Skeleton key={i} className="h-11 w-full rounded-md" />
+        ))}
+      </div>
+    </div>
+  )
+}
+
+export function PrimaryListHubLoadingFallback() {
+  return (
+    <PageLoadingChrome>
+      <PrimaryListHubLoadingBody />
+    </PageLoadingChrome>
+  )
+}
+
+/** Question bank discovery hub — composer + folder grid. */
+export function QuestionBankHubLoadingBody() {
+  return (
+    <div className="flex flex-col gap-10">
+      <div className="mx-auto flex w-full max-w-3xl flex-col gap-4 py-6">
+        <Skeleton className="mx-auto h-10 w-64 max-w-full rounded-md" />
+        <Skeleton className="h-12 w-full rounded-xl" />
+        <Skeleton className="h-4 w-48 rounded-md" />
+      </div>
+      <div className="grid gap-4 sm:grid-cols-2 lg:grid-cols-3">
+        {Array.from({ length: 6 }).map((_, i) => (
+          <Skeleton key={i} className="h-28 rounded-xl" />
+        ))}
+      </div>
+    </div>
+  )
+}
+
+export function QuestionBankHubLoadingFallback() {
+  return (
+    <PageLoadingChrome>
+      <QuestionBankHubLoadingBody />
+    </PageLoadingChrome>
+  )
+}
+
+/** Dedicated search landing / results (`?q=`). */
+export function DedicatedSearchLoadingBody() {
+  return (
+    <div className="mx-auto flex min-h-[min(52vh,28rem)] w-full max-w-3xl flex-col justify-center gap-6 py-10">
+      <Skeleton className="h-10 w-72 max-w-full rounded-md" />
+      <Skeleton className="h-12 w-full rounded-xl" />
+      <div className="flex flex-wrap gap-2">
+        <Skeleton className="h-8 w-24 rounded-full" />
+        <Skeleton className="h-8 w-32 rounded-full" />
+        <Skeleton className="h-8 w-20 rounded-full" />
+      </div>
+    </div>
+  )
+}
+
+export function DedicatedSearchLoadingFallback() {
+  return (
+    <PageLoadingChrome maxWidthClassName="max-w-5xl">
+      <DedicatedSearchLoadingBody />
+    </PageLoadingChrome>
+  )
+}
+
+/** Dashboard tabs — KPI row + chart block. */
+export function DashboardLoadingBody() {
+  return (
+    <div className="flex flex-col gap-6">
+      <div className="space-y-2">
+        <Skeleton className="h-9 w-56 max-w-full rounded-md" />
+        <Skeleton className="h-4 w-80 max-w-full rounded-md" />
+      </div>
+      <Skeleton className="h-11 w-full max-w-xl rounded-md" />
+      <div className="grid gap-3 sm:grid-cols-2 lg:grid-cols-4">
+        {Array.from({ length: 4 }).map((_, i) => (
+          <Skeleton key={i} className="h-24 rounded-xl" />
+        ))}
+      </div>
+      <Skeleton className="min-h-[320px] w-full rounded-xl" />
+    </div>
+  )
+}
+
+export function DashboardLoadingFallback() {
+  return (
+    <PageLoadingChrome maxWidthClassName={PRIMARY_PAGE_MAX_WIDTH_CLASS}>
+      <DashboardLoadingBody />
+    </PageLoadingChrome>
+  )
+}
+
+/** Focused workflow — single column form/settings sections. */
+export function FocusedWorkflowLoadingBody({ withSidebar = false }: { withSidebar?: boolean }) {
+  if (withSidebar) {
+    return (
+      <div className={cn("flex flex-col gap-8", FOCUSED_WORKFLOW_SIDEBAR_SECTIONS_GRID_CLASS)}>
+        <div className="space-y-2 lg:col-span-2">
+          <Skeleton className="h-9 w-40 max-w-full rounded-md" />
+          <Skeleton className="h-4 w-full max-w-xl rounded-md" />
+        </div>
+        <div className="flex flex-col gap-1">
+          {Array.from({ length: 5 }).map((_, i) => (
+            <Skeleton key={i} className="h-9 w-full rounded-md" />
+          ))}
+        </div>
+        <div className="flex flex-col gap-8">
+          <Skeleton className="h-24 w-full rounded-xl" />
+          <Skeleton className="h-48 w-full rounded-xl" />
+          <Skeleton className="h-32 w-full rounded-xl" />
+        </div>
+      </div>
+    )
+  }
+
+  return (
+    <div className="flex flex-col gap-8">
+      <div className="space-y-2">
+        <Skeleton className="h-9 w-48 max-w-full rounded-md" />
+        <Skeleton className="h-4 w-full max-w-lg rounded-md" />
+      </div>
+      <Skeleton className="h-40 w-full rounded-xl" />
+      <Skeleton className="h-56 w-full rounded-xl" />
+    </div>
+  )
+}
+
+export function FocusedWorkflowLoadingFallback({ withSidebar = false }: { withSidebar?: boolean }) {
+  return (
+    <PageLoadingChrome
+      maxWidthClassName={FOCUSED_WORKFLOW_MAX_WIDTH.lg}
+      paddingClassName={FOCUSED_WORKFLOW_CONTENT_PADDING_CLASS}
+    >
+      <FocusedWorkflowLoadingBody withSidebar={withSidebar} />
+    </PageLoadingChrome>
+  )
+}
+
+export function SimplePageLoadingBody() {
+  return (
+    <div className="flex max-w-xl flex-col gap-4 py-4">
+      <Skeleton className="h-4 w-full rounded-md" />
+      <Skeleton className="h-4 w-5/6 rounded-md" />
+      <div className="flex gap-3 pt-2">
+        <Skeleton className="h-9 w-36 rounded-md" />
+        <Skeleton className="h-9 w-28 rounded-md" />
+      </div>
+    </div>
+  )
+}
+
+export function SimplePageLoadingFallback() {
+  return (
+    <PageLoadingChrome maxWidthClassName="max-w-3xl">
+      <SimplePageLoadingBody />
+    </PageLoadingChrome>
+  )
+}
+
+const FALLBACK_BY_VARIANT: Record<PageLoadingVariant, React.ReactNode> = {
+  dashboard: <DashboardLoadingFallback />,
+  "primary-list-hub": <PrimaryListHubLoadingFallback />,
+  "question-bank-hub": <QuestionBankHubLoadingFallback />,
+  "dedicated-search": <DedicatedSearchLoadingFallback />,
+  "focused-workflow": <FocusedWorkflowLoadingFallback />,
+  "focused-workflow-sidebar": <FocusedWorkflowLoadingFallback withSidebar />,
+  simple: <SimplePageLoadingFallback />,
+}
+
+export function PageLoadingByVariant({ variant }: { variant: PageLoadingVariant }) {
+  return FALLBACK_BY_VARIANT[variant]
+}

package/template/components/ui/button-group.tsx

@@ -0,0 +1 @@
+export * from "@exxatdesignux/ui/components/button-group"

package/template/docs/consumer-app-pattern.md

@@ -0,0 +1,39 @@
+# Consumer app pattern (`@exxatdesignux/ui`)
+
+> **Audience:** Product repos that **install** the design system from npm — not the `apps/web` monorepo reference app.  
+> **Handbook:** `packages/ui/consumer-extras/AGENTS.md` · **Upgrade:** `consumer-upgrade-checklist.md` · **Skill:** `.cursor/skills/exxat-consumer-app/SKILL.md`
+
+## Intent
+
+A **consumer app** composes **`@exxatdesignux/ui`** primitives and copies **patterns** from the published **`template/`** tree. It does **not** fork parallel table stacks, view routers, or shell tokens.
+
+## MUST
+
+1. **Install** — `@exxatdesignux/ui` + peers; import DS CSS once (`@exxatdesignux/ui/globals.css` or documented entry).
+2. **Sync extras** — After version bumps: `npx --package=@exxatdesignux/ui@latest exxat-ui sync-extras` → `.cursor/skills/exxat-*` + `docs/exxat-ds/*.md`.
+3. **Diff template** — Compare `node_modules/@exxatdesignux/ui/template/` for new files (layouts, `ListPageConnectedViewBody`, `FocusedWorkflowPageTemplate`, mocks).
+4. **List hubs** — One **`useTableState`** row bag; **`ListPageConnectedViewBody`** + **`defineHubViewRenderers`**; same **`supportedViewTypes`** on **`ListPageTemplate`** and **`TablePropertiesDrawer`**.
+5. **Shell tokens** — Sidebar / secondary panel / page elevation via **`--sidebar`**, **`--secondary-panel-bg`**, **`--background`** — see **`shell-surface-elevation-pattern.md`**.
+6. **Focused workflows** — Dedicated create/edit/settings routes use **`FocusedWorkflowPageTemplate`** — **`focused-workflow-page-pattern.md`**.
+
+## MUST NOT
+
+- Copy only components without porting **AGENTS**, **rules**, and **pattern docs** when behavior changes.
+- Ship hub view tabs with long **`if (view === "table")`** chains instead of **`ListPageConnectedViewBody`**.
+- Keep a second mock array per view while the grid uses **`useTableState`**.
+- Set secondary panel to **`bg-sidebar`** or light **`--brand-tint`** mixes in dark mode.
+
+## Checklist (new consumer feature)
+
+- [ ] Read **`consumer-upgrade-checklist.md`** for the installed UI version.
+- [ ] Run **`exxat-ui sync-extras`** if skills/patterns are stale.
+- [ ] Find the closest **`template/`** hub or page; port file names and imports to your app paths.
+- [ ] **List hub:** `lib/<hub>-supported-views.ts`, `lib/data-list-view-registry.ts`, `ListPageConnectedViewBody`, centralized **`tableState.rows`**.
+- [ ] **Form route:** `FocusedWorkflowPageTemplate` + one body layout from **`focused-workflow-layouts.tsx`**.
+- [ ] **Nav + secondary panel:** `secondaryPanel` on nav item, `PANELS` registry, `useAutoPanel` — **`exxat-primary-nav-secondary-panel`** skill.
+- [ ] Re-run **`fa:subset-audit`** when adding Font Awesome glyphs.
+
+## See also
+
+- Monorepo reference: `apps/web/` (full product demo)
+- **`.cursor/rules/exxat-consumer-app.mdc`** (when working inside a consumer repo that synced rules)

package/template/docs/data-views-pattern.md

@@ -38,6 +38,41 @@ Non-table view branches (e.g. **folder** icon grid, **panel** finder, OS-style f
 
 **Handbook:** **`AGENTS.md` §4.5**. **Cursor:** **`.cursor/rules/exxat-list-page-view-shells.mdc`**. **Skill:** **`.cursor/skills/exxat-list-page-view-shells/SKILL.md`**. **Do not** wrap **`DataTable`** in the frame if that stacks padding with the table toolbar (**`AGENTS.md` §5**).
 
+## View registry and connected bodies (extensibility)
+
+To add a **new view type** without breaking existing hubs:
+
+1. **Register once** — Add a tile in `lib/data-list-view.ts` (`DATA_LIST_VIEW_TILES`). Capabilities (hub KPI strip, render kind) derive automatically in `lib/data-list-view-registry.ts`.
+2. **Build the body once** — Add or extend a generic surface under `components/data-views/` (e.g. `ListPageCalendarView`). Entity-specific wiring stays in props (`getEventDate`, board `renderCard`), not a second calendar implementation per hub.
+3. **Declare what each hub supports** — `lib/<hub>-supported-views.ts` exports a `const` array; pass the same array to **`ListPageTemplate`** (`supportedViewTypes`), the hub table (`supportedViewTypes` → `TablePropertiesDrawerButton`), and rely on defaults if omitted. **Add view**, **⌘1–9** shortcuts, and **Properties → View type** tiles all use `dataListViewTilesForHub` / `dataListViewSelectionTilesForHub` so users cannot pick a view the hub never implemented.
+4. **Route in the hub table with `ListPageConnectedViewBody`** — Switch on **`getDataListViewRenderKind(view)`**, not raw `view === "…"` chains. Pass one renderer per kind the hub supports via **`defineHubViewRenderers(MY_HUB_SUPPORTED_VIEWS, { … })`** (`lib/hub-connected-view-renderers.ts`) so dev builds warn when a supported view has no body. **Do not** use a default branch that renders dashboard/KPIs; missing renderers show `ListPageViewNotConfigured`.
+5. **Let the template own hub chrome** — `ListPageTemplate` hides the metrics strip on calendar/dashboard via `showsListPageHubMetricsStrip(activeTab.viewType)`. Hub clients pass `showMetrics` only; they do not reimplement per-tab KPI visibility.
+6. **Panel / Miller columns** — Reuse **`ListPageFolderColumnsPanel`** (`components/data-views/list-page-folder-columns-panel.tsx`) for folder + record columns; hub-specific chrome (folder colors, actions) lives in a thin wrapper (e.g. `QuestionBankFolderColumnsPanel`). **Do not** export question-bank-only tree/folder nav from the generic `data-views` barrel.
+
+```tsx
+// lib/my-hub-supported-views.ts
+export const MY_HUB_SUPPORTED_VIEWS = ["table", "list", "calendar"] as const satisfies readonly DataListViewType[]
+
+// my-hub-client.tsx
+<ListPageTemplate supportedViewTypes={MY_HUB_SUPPORTED_VIEWS} showMetrics={showMetrics} … />
+
+// my-hub-table.tsx
+import { defineHubViewRenderers } from "@/lib/hub-connected-view-renderers"
+
+return (
+  <ListPageConnectedViewBody
+    view={view}
+    hubLabel="My hub"
+    renderers={defineHubViewRenderers(MY_HUB_SUPPORTED_VIEWS, {
+      "data-table": <DataTable … />,
+      "calendar-with-toolbar": toolbarShell(<ListPageCalendarView rows={tableState.rows} getEventDate={…} />),
+    })}
+  />
+)
+```
+
+**Checklist for a new view type:** registry tile → `data-views/` component → update each `*-supported-views.ts` that should expose it → add renderer in each `*-table.tsx` (via `defineHubViewRenderers`) → Properties drawer copy in `table-properties/drawer.tsx` if needed → `table-state-lifecycle` picks up types via `DATA_LIST_VIEW_TILES` (no separate allowlist).
+
 ## Architecture
 
 - **Page shell** — `ListPageTemplate` owns the views toolbar (tabs), optional metrics, and export drawer. Content for the active tab is rendered via `renderContent`.
@@ -146,11 +181,13 @@ Reference: `components/placements-page-header.tsx`, `components/team-page-header
 
 **When to use a new page (route):** The flow is **primary**, **long-form**, **multi-step**, or should have its **own URL** / bookmark / history **without** the parent page behind it — e.g. full create/edit, wizards, or detail that *is* the task.
 
-**Rule of thumb:** **Context + quick** → **drawer**; **blocking short choice** → **dialog**; **otherwise** → **new page**.
+**Focused workflow shell:** For dedicated create/edit, wizards, and sectioned settings, use **`FocusedWorkflowPageTemplate`** + layouts in **`focused-workflow-layouts.tsx`** — see **`docs/focused-workflow-page-pattern.md`** and **`AGENTS.md` §14**. **Not** for list hubs (**`ListPageTemplate`**) or Miller-column explorers.
+
+**Rule of thumb:** **Context + quick** → **drawer**; **blocking short choice** → **dialog**; **primary / long / wizard / settings** → **focused workflow route** (or other dedicated page).
 
 **Modal vs side panel (same route):** When the overlay stays on the same URL, prefer **`docs/drawer-vs-dialog-pattern.md`** and **`.cursor/rules/exxat-drawer-vs-dialog.mdc`** — drawers keep the hub visible; dialogs trap focus for confirms.
 
-Canonical rules: **`AGENTS.md` §6.4**, root **`.cursor/rules/exxat-page-vs-drawer.mdc`**, **`.cursor/rules/exxat-drawer-vs-dialog.mdc`**.
+Canonical rules: **`AGENTS.md` §6.4**, **§14**, root **`.cursor/rules/exxat-page-vs-drawer.mdc`**, **`.cursor/rules/exxat-drawer-vs-dialog.mdc`**, **`.cursor/rules/exxat-focused-workflow-page.mdc`**.
 
 ---
 
@@ -170,7 +207,7 @@ When a route is a **primary** destination in nav (main hub for an entity) **and*
 - [ ] **>10 items** → search, filter, sort, properties (per surface type above).
 - [ ] **Has data to export** → **More** menu with **Export** + shared `ExportDrawer` pattern.
 - [ ] **Primary + large / main hub** → `ListPageTemplate`-style shell where applicable.
-- [ ] **Page vs drawer vs dialog (§6.4)** — Quick with parent **context** → drawer/sheet; **blocking** confirm → **dialog**; primary or long flows → **new route** (`docs/drawer-vs-dialog-pattern.md`).
+- [ ] **Page vs drawer vs dialog (§6.4)** — Quick with parent **context** → drawer/sheet; **blocking** confirm → **dialog**; primary or long flows → **focused workflow route** (`docs/focused-workflow-page-pattern.md`, **§14**) or other dedicated page (`docs/drawer-vs-dialog-pattern.md`).
 - [ ] **Primary button** → `Button` default variant (`size="lg"` for parity with Placements), not outline.
 - [ ] **Dashboard view tab** → `KeyMetrics` + shared KPI helpers from **`tableState.rows`**; no duplicate one-off metric cards.
 - [ ] **Data view charts** → `ChartFigure` + `chart-keyboard-selection`; layout persistence via **`data-view-dashboard-storage`** (see `AGENTS.md` §4.3).

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

@@ -30,13 +30,15 @@
 
 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**.
 
+For **large forms, wizards, and sectioned settings**, use **`FocusedWorkflowPageTemplate`** and body layouts — **`docs/focused-workflow-page-pattern.md`**, **`AGENTS.md` §14**, **`.cursor/skills/exxat-focused-workflow-page/SKILL.md`**.
+
 ## 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 |
+| Long form / wizard | Cramped | No | Yes — **`FocusedWorkflowPageTemplate`** |
 | Properties tied to a table | Yes | Too small | Optional |
 
 ## Accessibility

package/template/docs/focused-workflow-page-pattern.md

@@ -0,0 +1,84 @@
+# Focused workflow page (dedicated routes)
+
+> **Related:** **`AGENTS.md` §6.4** (page vs drawer vs dialog), **§14** (AI checklist), **`docs/drawer-vs-dialog-pattern.md`**, **`.cursor/rules/exxat-page-vs-drawer.mdc`**, **`.cursor/rules/exxat-focused-workflow-page.mdc`**, **`.cursor/skills/exxat-focused-workflow-page/SKILL.md`**.
+
+## Intent
+
+Use **`FocusedWorkflowPageTemplate`** for **large or multi-step work** on its **own route** — create/edit forms, wizards, and sectioned settings. The shell is **narrower** than list hubs and **does not** use Miller-column / split-panel explorers.
+
+| Surface | Use instead |
+| --- | --- |
+| Browsable record hubs (table, board, dashboard tabs) | **`PrimaryPageTemplate`** + **`ListPageTemplate`** |
+| Finder / folder columns / split hub chrome | **`ListPageSplitHubChrome`**, **`ListPageFolderColumnsPanel`** |
+| Quick properties or export beside a grid | **Drawer** (`TablePropertiesDrawer`, `ExportDrawer`) |
+| Blocking confirm on the same route | **Dialog** |
+
+## Surface matrix (§6.4)
+
+| Need | Drawer | Dialog | **Focused workflow route** |
+| --- | --- | --- | --- |
+| Keep hub visible while acting | Yes | No | No |
+| Own URL / bookmark / history | Rare | No | **Yes** |
+| Multi-step wizard | Cramped | No | **Yes** |
+| Sectioned settings (left nav) | Awkward | No | **Yes** |
+| Short delete confirm | No | **Yes** | Overkill |
+
+## Shell
+
+**`FocusedWorkflowPageTemplate`** (`components/templates/focused-workflow-page-template.tsx`):
+
+- **`SidebarInset`** + **`SiteHeader`** (breadcrumb back link + title).
+- Centered column: **`max-w-3xl` / `max-w-4xl` / `max-w-5xl`** via **`maxWidth`** (`md` | `lg` | `xl`).
+- Default padding: **`FOCUSED_WORKFLOW_CONTENT_PADDING_CLASS`**.
+
+Optional **`beforeSiteHeader`** (e.g. **`SidebarAutoCollapse`** on long forms).
+
+## Body layouts
+
+Import from **`components/templates/focused-workflow-layouts.tsx`**:
+
+| Layout | When |
+| --- | --- |
+| **`FocusedWorkflowSingleColumn`** | Default stack — header, form sections, footer actions (e.g. question authoring). |
+| **`FocusedWorkflowStepForm`** + **`FocusedWorkflowWizardFooter`** | Multi-step wizard with progress list and sticky footer (placement-style flows). |
+| **`FocusedWorkflowSidebarSections`** | Sectioned form with **left nav rail** (settings-style); put **`id`** on each `<section>` matching **`sections[].id`**. |
+| **`FocusedWorkflowEmptyState`** | Placeholder / not-yet-configured route body. |
+| **`FocusedWorkflowActionFooter`** | Single-step Cancel (Esc) + primary (Enter) without step chrome. |
+
+Keyboard: wizard and action footers pair **`Shortcut`** with inline **`<Kbd variant="bare">`** per **`.cursor/rules/exxat-kbd-shortcuts.mdc`**.
+
+## Golden references
+
+| Route | Variant |
+| --- | --- |
+| **`/question-bank/new`** | Shell + **`FocusedWorkflowSingleColumn`** + domain composer |
+| **`/settings`** | Shell (`maxWidth="lg"`) + **`FocusedWorkflowSidebarSections`** |
+| **`/examples/focused-workflow`** | Showcase: empty, steps, sidebar (toggle) |
+
+## Wiring checklist (implementers)
+
+1. **Route** under **`app/(app)/…/page.tsx`** — thin server page; heavy UI in a **client** component.
+2. **`siteHeader`**: **`back`** or **`breadcrumbs`** + **`title`**; avoid duplicating the trail in the body.
+3. Pick **`maxWidth`**: **`md`** for simple forms, **`lg`** for settings / wide fields.
+4. Choose **one** body layout; do **not** nest Miller columns or **`ListPageTemplate`** view tabs inside this shell.
+5. Domain logic stays in **`*-composer.tsx`** / **`*-client.tsx`**; templates stay generic **`FocusedWorkflow*`**.
+6. Run **§14** in **`AGENTS.md`** when reviewing.
+
+## AI execution checklist (copy for PRs)
+
+- [ ] **`FocusedWorkflowPageTemplate`** on the route — not ad-hoc **`SidebarInset`** / list-hub shell.
+- [ ] Correct body variant: **single column** | **step form** | **sidebar sections** | **empty**.
+- [ ] Wizard/action footers use **`Shortcut`** + bare **`Kbd`** in buttons.
+- [ ] **No** list-hub view tabs, **no** folder-column explorer inside the page.
+- [ ] Template/component names remain **generic** (not tied to one entity).
+- [ ] **§6.5** — no toast for product feedback.
+
+## Pair with
+
+- **`exxat-page-vs-drawer.mdc`**, **`exxat-drawer-vs-dialog.mdc`**, **`exxat-kbd-shortcuts.mdc`**
+- **`exxat-reuse-before-custom.mdc`** — extend **`focused-workflow-layouts.tsx`** before forking a second shell
+
+## See also
+
+- **`components/examples/focused-workflow-showcase.tsx`**
+- **`packages/ui/consumer-extras/patterns/focused-workflow-page-pattern.md`** (npm consumers)

package/template/docs/shell-surface-elevation-pattern.md

@@ -1,7 +1,7 @@
 # Shell surface elevation (sidebar · secondary panel · page)
 
 > **Tokens:** `app/globals.css` — `--sidebar`, `--secondary-panel-bg`, `--background`, `--brand-tint*`.  
-> **Shell:** `components/templates/nested-secondary-panel-shell.tsx` — `bg-[var(--secondary-panel-bg)]`.  
+> **Shell:** `components/templates/nested-secondary-panel-shell.tsx` — `bg-secondary-panel-bg` + `[data-slot="secondary-panel"]` rule in `globals.css`.  
 > **Cursor:** `.cursor/rules/exxat-primary-nav-secondary-panel.mdc` · `.cursor/skills/exxat-primary-nav-secondary-panel/SKILL.md`
 
 ## Stack (back → front)
@@ -24,14 +24,16 @@
 ## OKLCH formulas (dark)
 
 ```css
---secondary-panel-bg: color-mix(in oklch, var(--card) 32%, var(--brand-tint) 68%);
+--secondary-panel-bg: color-mix(in oklch, var(--background) 32%, var(--sidebar-accent) 68%);
 ```
 
+**Do not** mix with light-mode **`--brand-tint`** in dark — product theme classes keep a light **`--brand-tint`** for logos/KPI glow; the secondary rail must use **`--sidebar-accent`** so the Library panel stays on-hue and dark.
+
 Per-product **dark** theme blocks (`.theme-one.dark`, `.theme-prism.dark`, …) set **`--brand-tint-light`** where needed so mixes stay on-hue.
 
 ## Implementation
 
-- **`NestedSecondaryPanelShell`** — `bg-[var(--secondary-panel-bg)]`, `ring-sidebar-border` (not generic `ring-border` alone).
+- **`NestedSecondaryPanelShell`** — `bg-secondary-panel-bg` (token + `[data-slot="secondary-panel"][data-state="open"]` in `globals.css`), `border-sidebar-border` (not generic `ring-border` alone).
 - **Do not** set secondary panel to `bg-sidebar` (same as level 0 — loses elevation).
 - **Do not** use `color-mix(… var(--sidebar) …)` without brand tokens if it drifts from active product theme.
 

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

@@ -3,36 +3,21 @@
  */
 
 import type { CommandMenuGroup, CommandMenuItem } from "@/lib/command-menu-config"
-import { ALL_PLACEMENTS } from "@/lib/mock/placements"
+import { LIST_HUB_DIRECTORY } from "@/lib/mock/list-hub-directory"
 
 function sampleRowSearchItems(): CommandMenuItem[] {
-  return ALL_PLACEMENTS.map((p) => {
-    const nameParts = p.student.trim().split(/\s+/)
-    return {
-      id: `sample-row-${p.id}`,
-      label: `Row ${p.id} — ${p.student}`,
-      icon: "fa-light fa-table",
-      href: `/data-list/${p.id}`,
-      keywords: [
-        `row ${p.id}`,
-        p.student,
-        ...nameParts,
-        p.program,
-        p.site,
-        p.internship,
-        p.specialization,
-        p.email,
-        p.supervisor,
-        p.status,
-        p.compliance,
-      ]
-        .filter(Boolean)
-        .join(" "),
-    }
-  })
+  return LIST_HUB_DIRECTORY.map(row => ({
+    id: `sample-row-${row.id}`,
+    label: row.title,
+    icon: "fa-light fa-calendar-days",
+    href: "/data-list",
+    keywords: [row.id, row.title, row.category, row.eventDate, "list hub", "calendar"]
+      .filter(Boolean)
+      .join(" "),
+  }))
 }
 
-/** Built once at module load — avoids remapping all placement rows on every layout render. */
+/** Built once at module load — avoids remapping rows on every layout render. */
 export const COMMAND_MENU_SEARCH_DATA_GROUPS: CommandMenuGroup[] = [
   {
     id: "sample-rows",
@@ -42,7 +27,6 @@ export const COMMAND_MENU_SEARCH_DATA_GROUPS: CommandMenuGroup[] = [
   },
 ]
 
-/** Demo rows for the list hub — search-only so the palette stays lightweight on open. */
 export function getCommandMenuSearchDataGroups(): CommandMenuGroup[] {
   return COMMAND_MENU_SEARCH_DATA_GROUPS
 }

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

@@ -1,10 +1,13 @@
 /**
- * Display options for Data list (table / board / etc.) — shared across view types
+ * Display options for Data list (table / board / calendar / etc.) — shared across view types
  * so hide/show preferences persist when switching views.
  */
 
 export type BoardLineCount = 1 | 2 | 3
 
+/** Right-hand calendar body: month grid vs week rows (scroll stack uses the same months). */
+export type CalendarMainView = "month" | "week"
+
 export interface DataListDisplayOptions {
   /**
    * Board swimlanes: dataset field (table column key) used to split cards into columns.
@@ -13,7 +16,7 @@ export interface DataListDisplayOptions {
   boardGroupByColumnKey: string
   /** Max lines for primary text blocks on board cards */
   boardLineCount: BoardLineCount
-  /** Page title block (Placements + subtitle) */
+  /** Page title block */
   showViewTitle: boolean
   /** Board: phase column titles + descriptions. Table: column header row. */
   showColumnLabels: boolean
@@ -22,6 +25,10 @@ export interface DataListDisplayOptions {
   boardNewCardAbove: boolean
   /** Toolbar search control (table view) */
   showToolbarSearch: boolean
+  /** Calendar: left column — mini month, event list, layout tiles */
+  showCalendarSummaryPanel: boolean
+  /** Calendar: main scrollable body layout */
+  calendarMainView: CalendarMainView
 }
 
 export const DEFAULT_DATA_LIST_DISPLAY_OPTIONS: DataListDisplayOptions = {
@@ -32,4 +39,11 @@ export const DEFAULT_DATA_LIST_DISPLAY_OPTIONS: DataListDisplayOptions = {
   showBoardColumnCounts: true,
   boardNewCardAbove: true,
   showToolbarSearch: true,
+  showCalendarSummaryPanel: false,
+  calendarMainView: "month",
 }
+
+export const CALENDAR_MAIN_VIEW_TILES = [
+  { value: "month" as const, label: "Month", icon: "fa-calendar-days" },
+  { value: "week" as const, label: "Week", icon: "fa-calendar-week" },
+]