@exxatdesignux/ui 0.2.17 → 0.2.19

package/template/components/templates/focused-workflow-page-template.tsx

@@ -0,0 +1,69 @@
+import * as React from "react"
+
+import { SiteHeader, type SiteHeaderProps } from "@/components/site-header"
+import { SidebarInset } from "@/components/ui/sidebar"
+import { cn } from "@/lib/utils"
+
+/** Default horizontal padding for focused workflow routes (forms, wizards, authoring). */
+export const FOCUSED_WORKFLOW_CONTENT_PADDING_CLASS =
+  "px-4 pt-6 pb-32 sm:px-6 lg:px-8"
+
+/** Max-width presets — narrower than primary list hubs (`max-w-[1440px]`). */
+export const FOCUSED_WORKFLOW_MAX_WIDTH = {
+  md: "max-w-3xl",
+  lg: "max-w-4xl",
+  xl: "max-w-5xl",
+} as const
+
+export type FocusedWorkflowMaxWidth = keyof typeof FOCUSED_WORKFLOW_MAX_WIDTH
+
+export interface FocusedWorkflowPageTemplateProps {
+  /** e.g. `SidebarAutoCollapse` on long-form routes. */
+  beforeSiteHeader?: React.ReactNode
+  /** Breadcrumb back link + title; parent context stays in `SiteHeader`. */
+  siteHeader: SiteHeaderProps
+  children: React.ReactNode
+  maxWidth?: FocusedWorkflowMaxWidth
+  /** Merged with default content padding. */
+  contentClassName?: string
+  bodyClassName?: string
+}
+
+/**
+ * Dedicated-route shell for **large or multi-step work** — create/edit flows, wizards,
+ * and sectioned settings. **Not** for list hubs (use `PrimaryPageTemplate`) and **not**
+ * for Miller-column / split-panel explorers (use `ListPageSplitHubChrome`).
+ *
+ * Pair body layouts with `FocusedWorkflowSingleColumn`, `FocusedWorkflowStepForm`,
+ * `FocusedWorkflowSidebarSections`, or `FocusedWorkflowEmptyState`.
+ *
+ * @see `docs/focused-workflow-page-pattern.md`
+ */
+export function FocusedWorkflowPageTemplate({
+  beforeSiteHeader,
+  siteHeader,
+  children,
+  maxWidth = "md",
+  contentClassName,
+  bodyClassName,
+}: FocusedWorkflowPageTemplateProps) {
+  return (
+    <SidebarInset id="main-content" tabIndex={-1}>
+      {beforeSiteHeader}
+      <SiteHeader {...siteHeader} />
+      <div className={cn("flex min-h-0 flex-1 flex-col outline-none", bodyClassName)}>
+        <div
+          className={cn(
+            "@container/main mx-auto flex min-h-0 w-full min-w-0 flex-1 flex-col",
+            FOCUSED_WORKFLOW_MAX_WIDTH[maxWidth],
+            FOCUSED_WORKFLOW_CONTENT_PADDING_CLASS,
+            contentClassName,
+          )}
+        >
+          {children}
+        </div>
+      </div>
+    </SidebarInset>
+  )
+}
+

package/template/components/templates/list-page.tsx

@@ -47,7 +47,11 @@ import {
   Shortcut,
 } from "@/components/ui/dropdown-menu"
 import type { DataListViewType } from "@/lib/data-list-view"
-import { DATA_LIST_VIEW_TILES } from "@/lib/data-list-view"
+import {
+  dataListViewTilesForHub,
+  showsListPageHubMetricsStrip,
+} from "@/lib/data-list-view-registry"
+import { DATA_LIST_VIEW_TILES, dataListViewAddShortcut } from "@/lib/data-list-view"
 import {
   createListPageEditViewHandler,
   type OpenTablePropertiesHandle,
@@ -126,6 +130,11 @@ export interface ListPageTemplateProps {
   tablePropertiesRef?: React.RefObject<OpenTablePropertiesHandle | null>
   /** When true, hide the views tab strip (tabs + add view) — e.g. search landing with a single table surface. */
   hideViewsToolbar?: boolean
+  /**
+   * View types this hub can render. Limits **Add view** and documents intent; table components
+   * should still implement each kind via `ListPageConnectedViewBody`. Defaults to all registry views.
+   */
+  supportedViewTypes?: readonly DataListViewType[]
 }
 
 /** Collision-proof id for a dynamically-added tab. Module-level counters reset
@@ -180,6 +189,7 @@ export function ListPageTemplate({
   onEditView,
   tablePropertiesRef,
   hideViewsToolbar = false,
+  supportedViewTypes,
 }: ListPageTemplateProps) {
   const controlled =
     tabsProp !== undefined &&
@@ -212,6 +222,20 @@ export function ListPageTemplate({
 
   const activeTab = tabs.find(t => t.id === activeTabId) ?? tabs[0]
 
+  const addableViewTypes = React.useMemo(
+    () =>
+      supportedViewTypes != null
+        ? dataListViewTilesForHub(supportedViewTypes)
+        : VIEW_TYPES,
+    [supportedViewTypes],
+  )
+
+  const metricsVisible =
+    showMetrics
+    && metrics != null
+    && activeTab != null
+    && showsListPageHubMetricsStrip(activeTab.viewType)
+
   const editViewFromRef = React.useMemo(
     () => (tablePropertiesRef ? createListPageEditViewHandler(tablePropertiesRef) : undefined),
     [tablePropertiesRef]
@@ -272,14 +296,17 @@ export function ListPageTemplate({
   }
 
   return (
-    <>
-      {!hideViewsToolbar && VIEW_TYPES.slice(0, 9).map((v, i) => (
-        <Shortcut
-          key={v.type}
-          keys={`⌘⇧${i + 1}`}
-          onInvoke={() => addView(v.type)}
-        />
-      ))}
+    <div className="flex min-h-0 w-full min-w-0 flex-1 flex-col">
+      {!hideViewsToolbar && addableViewTypes.slice(0, 9).map((v, i) => {
+        const keys = dataListViewAddShortcut(i)
+        return keys ? (
+          <Shortcut
+            key={v.type}
+            keys={keys}
+            onInvoke={() => addView(v.type)}
+          />
+        ) : null
+      })}
       {activeTab && !hideViewsToolbar && (
         <>
           <Shortcut keys="F2" onInvoke={() => openRename(activeTab)} />
@@ -299,7 +326,7 @@ export function ListPageTemplate({
       )}
       {header}
 
-      {showMetrics && metrics}
+      {metricsVisible ? metrics : null}
 
       {/* ── Views toolbar (not tablist: settings/close are not tabs — WCAG 1.3.1 / ARIA) ── */}
       {!hideViewsToolbar && (
@@ -477,10 +504,10 @@ export function ListPageTemplate({
             <DropdownMenuContent align="start">
               <DropdownMenuLabel className="text-xs">Add a view</DropdownMenuLabel>
               <DropdownMenuSeparator />
-              {VIEW_TYPES.map((v, i) => (
+              {addableViewTypes.map((v, i) => (
                 <DropdownMenuItem
                   key={v.type}
-                  shortcut={i < 9 ? `⌘⇧${i + 1}` : undefined}
+                  shortcut={dataListViewAddShortcut(i)}
                   onSelect={() => addView(v.type)}
                 >
                   <i className={`fa-light ${v.icon}`} aria-hidden="true" />
@@ -576,6 +603,6 @@ export function ListPageTemplate({
           </DialogFooter>
         </DialogContent>
       </Dialog>
-    </>
+    </div>
   )
 }

package/template/components/templates/nested-secondary-panel-shell.tsx

@@ -15,7 +15,7 @@ export interface NestedSecondaryPanelShellProps {
 
 /**
  * Shared chrome for a nested hub rail — full width vs icon rail.
- * Fill uses `--secondary-panel-bg` (soft brand wash on `--background`).
+ * Fill uses `--secondary-panel-bg` — one step lighter than `--sidebar` (elevation 1).
  */
 export function NestedSecondaryPanelShell({
   open,
@@ -27,6 +27,7 @@ export function NestedSecondaryPanelShell({
   return (
     <nav
       aria-label={ariaLabel}
+      data-slot="secondary-panel"
       data-state={open ? "open" : "closed"}
       data-layout={open ? (compact ? "icon" : "expanded") : "closed"}
       className={cn(
@@ -40,7 +41,7 @@ export function NestedSecondaryPanelShell({
               // 2rem on mobile where the panel scrolls inline and we leave
               // a little more breathing room). No upper cap so tall screens
               // get a fully-extended rail.
-              "shrink-0 m-2 mx-2 rounded-xl ring-1 ring-border shadow-sm relative md:sticky md:top-2 bg-[var(--secondary-panel-bg)]",
+              "shrink-0 m-2 mx-2 rounded-xl border border-sidebar-border bg-secondary-panel-bg shadow-sm relative md:sticky md:top-2",
               compact
                 ? "w-12 min-w-12 max-w-12 h-[calc(100svh-2rem)] md:h-[calc(100svh-1rem)]"
                 : "w-64 min-w-64 max-w-64 h-[calc(100svh-2rem)] md:h-[calc(100svh-1rem)]",

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/contexts/product-context.tsx

@@ -10,7 +10,26 @@
 
 import * as React from "react"
 import { useAppStore, type Product } from "@/stores/app-store"
-import { brandForProduct } from "@/lib/product-brand"
+import {
+  brandForProduct,
+  EXXAT_ASSESSMENT_BRAND,
+  EXXAT_ONE_BRAND,
+  EXXAT_PRISM_BRAND,
+} from "@/lib/product-brand"
+
+const DEFAULT_PRODUCT_ACCENT: Record<Product, string> = {
+  "exxat-one": EXXAT_ONE_BRAND.brandColor,
+  "exxat-prism": EXXAT_PRISM_BRAND.brandColor,
+  "exxat-assessment": EXXAT_ASSESSMENT_BRAND.brandColor,
+  "exxat-custom": "",
+}
+
+function accentOverrideActive(product: Product, override: string | undefined): boolean {
+  if (!override?.trim()) return false
+  const defaultAccent = DEFAULT_PRODUCT_ACCENT[product]?.trim()
+  if (!defaultAccent) return true
+  return override.trim().toLowerCase() !== defaultAccent.toLowerCase()
+}
 
 export type { Product }
 
@@ -62,7 +81,7 @@ export function ProductProvider({ children }: { children: React.ReactNode }) {
     // / theme-assessment` classes (with bespoke hue formulas in
     // `globals.css`) are still used for the **default** look of each
     // built-in.
-    const hasAccentOverride = Boolean(productBrandColors[product])
+    const hasAccentOverride = accentOverrideActive(product, productBrandColors[product])
     let themeClass: "theme-one" | "theme-prism" | "theme-assessment" | "theme-custom"
     if (hasAccentOverride) {
       themeClass = "theme-custom"

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

@@ -18,6 +18,8 @@ This document describes how list pages combine **views**, **toolbar** behavior,
 | **Team page (primary template)** | `TeamClient` = `ListPageTemplate` + `KeyMetrics` + `TeamPageHeader` + `TeamTable` (same composition as `DataListClient`) | `components/team-client.tsx`, `lib/mock/team-kpi.ts` |
 | **Team roster** | `TeamTable` — `DataTable` + `useTableState` + `TablePropertiesDrawer`; list/board/dashboard read **`tableState.rows`** | `components/team-table.tsx` |
 | **Dashboard view (list tab)** | **`KeyMetrics`** (`variant="flat"` or `"card"`) — same KPI system as the template metrics strip; **do not** add ad-hoc `Card` grids for entity summaries | `TeamTable` dashboard branch, `lib/mock/team-kpi.ts` |
+| **List hub metrics strip** | **`KeyMetrics variant="flat"`** — transparent cells, OKLCH brand glow only, border hairlines (**no** grey panel) | **`docs/kpi-flat-band-pattern.md`**, Placements / Team / Question bank clients |
+| **Secondary panel chrome** | **`--secondary-panel-bg`** on **`NestedSecondaryPanelShell`** (lighter than sidebar, follows active product) | **`docs/shell-surface-elevation-pattern.md`**, Question bank |
 | **Export** | `ExportDrawer` | `ListPageTemplate` export props; `DataListClient` |
 | **View body layout** (gutter + centered max-width for folder / icon / panel-style content) | **`ListPageViewFrame`** (`components/data-views/list-page-view-frame.tsx`, re-exported from `components/data-views`) | **`FolderGridView`** (uses the frame); **`QuestionBankOsFolderView`** — see **`AGENTS.md` §4.5** |
 
@@ -36,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`.
@@ -144,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`**.
 
 ---
 
@@ -168,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