@exxatdesignux/ui 0.2.17 → 0.2.19

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/kpi-flat-band-pattern.md

@@ -0,0 +1,57 @@
+# KPI flat band (`KeyMetrics` `variant="flat"`)
+
+> **Component:** `components/key-metrics.tsx` — **`flatMetricsHairlineClass`**, **`flatBandStyle`**.  
+> **Tokens:** `app/globals.css` — `--key-metrics-flat-*`.  
+> **Cursor:** `.cursor/rules/exxat-kpi-flat-band.mdc` · `.cursor/skills/exxat-kpi-flat-band/SKILL.md`  
+> **Related:** `docs/kpi-strip-max-four-pattern.md`, `docs/kpi-trend-pattern.md`
+
+## Intent
+
+List hubs and the main dashboard mix view use **`KeyMetrics variant="flat"`** as a **metrics strip without a surface**: users see KPI copy and deltas on the **page canvas**, with a **brand-colored glow** under the band only. This is **not** a card, tinted panel, or `gap-px` grid fill.
+
+## MUST
+
+1. **No band surface** — The `<section>` background is **only** `var(--key-metrics-flat-band-radial)`. **Do not** stack `--key-metrics-flat-band-linear`, opaque gradients, or `box-shadow` fills that read as a grey/lavender box.
+2. **Transparent cells** — `metricsCellSurfaceClassName` is **`bg-transparent`** for `variant="flat"`. **Do not** use `bg-background`, `bg-card`, or `gap-px` + `bg-border` / `bg-foreground/*` on the grid (that paints tile surfaces).
+3. **Hairlines = borders only** — Use **`flatMetricsHairlineClass(itemCount, metricsHalfWidthLayout)`** in `key-metrics.tsx`:
+   - **2 tiles:** `border-r` on the first cell only.
+   - **4 tiles, wide strip (default):** `border-r` on cells 1–3 (verticals between all columns); **no** horizontal rule.
+   - **4 tiles, narrow `@container` (&lt; 30rem, 2×2 grid):** odd-column `border-r` + `border-b` on the top row only (via `@[max-width:29.99rem]` overrides).
+4. **Divider color (OKLCH)** — `--key-metrics-flat-divider: color-mix(in oklch, var(--sidebar-border) 55%, transparent)`; apply on children with `[&>*]:border-[color:var(--key-metrics-flat-divider)]`. Dividers follow **active product** hue (`--sidebar-border`), not neutral grey alone.
+5. **Glow (OKLCH)** — Radial stops use `color-mix(in oklch, var(--brand-color) …%, transparent)` so **Exxat One / Prism / Assessment / `theme-custom`** each tint correctly. **Do not** hardcode rose/indigo literals on theme blocks unless documenting a one-off.
+6. **List page usage** — Prefer **`showHeader={false}`**, **`metricsSingleRow`** when four KPIs share one row; pass **`insight`** only when the insight rail is product-required (same row uses `lg:grid-cols-[3fr_2fr]`).
+7. **Cap at four tiles** — See **`docs/kpi-strip-max-four-pattern.md`**.
+
+## MUST NOT
+
+- Add **`--key-metrics-flat-band-linear`** back into `flatBandStyle` or hub inline styles (e.g. question-bank hub hero).
+- Use **`variant="card"`** on **`ListPageTemplate`** metrics when the design calls for a **flat strip** on the page background.
+- Duplicate KPI numbers in ad-hoc **`Card`** grids on the same hub.
+- Set **`variant="mutedSuffix"`** on product wordmarks to grey out the **suffix** in dark mode — suffix stays **Exxat pink** (`wordmarkColor`); see **`lib/product-brand.ts`**.
+
+## Tokens (`app/globals.css`)
+
+| Token | Role |
+|--------|------|
+| `--key-metrics-flat-band-radial` | Bottom brand glow (only layer on flat `<section>`) |
+| `--key-metrics-flat-band-shadow` | **`none`** for flat band (no faux surface lift) |
+| `--key-metrics-flat-cell-bg` | **`transparent`** |
+| `--key-metrics-flat-divider` | OKLCH hairline between cells |
+
+Dark mode (`.dark`): same rules — transparent cells, radial glow only, no linear fill to `--background`.
+
+## Reference implementations
+
+- `components/question-bank-client.tsx` — `KeyMetrics variant="flat" metricsSingleRow`
+- `components/dashboard-tabs.tsx` — mix view flat band + insight
+- `components/placements-client.tsx`, `team-client.tsx`, `compliance-client.tsx` — list hub metrics slot
+
+## Insight rail (flat + side-by-side)
+
+When **`insight`** is shown beside KPIs, the insight **`Card`** may keep its own surface; the **KPI grid** stays transparent. **Do not** add `lg:border-l` on the insight column for flat band — the insight card ring is the separator (`key-metrics.tsx`).
+
+## See also
+
+- **`docs/kpi-strip-max-four-pattern.md`**
+- **`docs/kpi-trend-pattern.md`**
+- **`docs/shell-surface-elevation-pattern.md`** — sidebar / secondary panel / page stack

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

@@ -26,4 +26,5 @@ On **primary list hubs** (`ListPageTemplate` metrics slot) and on **dashboard
 ## See also
 
 - **`docs/kpi-trend-pattern.md`** — deltas, arrows, **`trendPolarity`**.
+- **`docs/kpi-flat-band-pattern.md`** — **`variant="flat"`** presentation (orthogonal to tile count).
 - **`.cursor/rules/exxat-kpi-max-four.mdc`**, **`.cursor/skills/exxat-kpi-max-four/SKILL.md`**

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

@@ -0,0 +1,54 @@
+# 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-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)
+
+| Level | Surface | Token / class | Notes |
+|-------|---------|---------------|--------|
+| **0** | Primary icon rail + app chrome | `--sidebar` (= `--brand-tint` on light product themes) | Darkest brand wash in the shell |
+| **1** | Nested secondary panel (Library, etc.) | `--secondary-panel-bg` | **Lighter** than level 0; **same product hue** |
+| **2** | Main page / inset content | `--background` | Lightest (white canvas light; dark charcoal dark) |
+
+**MUST** derive secondary panel fill from **`--brand-tint` / `--brand-tint-light`**, not a fixed rose or neutral grey. When the user selects **Exxat One**, both levels use **indigo hue ~286**; **Prism** uses **rose ~342**; **`theme-custom`** follows `--custom-product-brand-color` via `ProductProvider`.
+
+## OKLCH formulas (light)
+
+```css
+--sidebar: var(--brand-tint);
+--secondary-panel-bg: color-mix(in oklch, var(--background) 40%, var(--brand-tint-light) 60%);
+```
+
+## OKLCH formulas (dark)
+
+```css
+--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-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.
+
+## Product theme classes
+
+- **`theme-one`** / **`theme-prism`** / **`theme-assessment`** — built-in OKLCH brand scales in `globals.css`.
+- **`theme-custom`** — when user picks an accent in Settings; driven by `--custom-product-brand-color`.
+- **`ProductProvider`** — applies `theme-one` vs `theme-prism` vs `theme-custom`; accent override only when it **differs** from the product default (see `accentOverrideActive` in `contexts/product-context.tsx`).
+
+## Logo vs chrome
+
+- **Chrome** (sidebar, secondary panel, KPI glow) follows **`--brand-tint` / `--brand-color`** per product.
+- **Logo art** (mark + suffix) stays **Exxat pink** via `wordmarkColor` / `markGradient` in `lib/product-brand.ts` — recolouring a product in Settings changes **theme accent**, not corporate logo pink.
+
+## See also
+
+- **`docs/kpi-flat-band-pattern.md`** — flat KPI strip uses brand glow only, no surface
+- **`apps/web/AGENTS.md` §4.6** — secondary panel wiring

package/template/lib/chunk-load-error.ts

@@ -0,0 +1,13 @@
+/** Detect stale Turbopack / webpack chunk failures after dev-server rebuilds. */
+export function isChunkLoadError(error: unknown): boolean {
+  if (!error || typeof error !== "object") return false
+  const err = error as { name?: string; message?: string }
+  const name = err.name ?? ""
+  const msg = err.message ?? ""
+  return (
+    name === "ChunkLoadError" ||
+    msg.includes("Failed to load chunk") ||
+    msg.includes("Loading chunk") ||
+    msg.includes("ChunkLoadError")
+  )
+}

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/conditional-rule-match.ts

@@ -1,32 +1,97 @@
-import type { ConditionalRule } from "@/components/table-properties/types"
+import type { ConditionalRule, FilterTextMask } from "@/components/table-properties/types"
 
-/** First matching conditional rule background for a row (same logic as DataTable cells). */
+export type ConditionalColumnHint = {
+  key: string
+  sortKey?: string
+  filter?: { type?: string; textMask?: FilterTextMask }
+}
+
+function rowValueForRule<T extends Record<string, unknown>>(
+  row: T,
+  rule: ConditionalRule,
+  columns?: ConditionalColumnHint[],
+): string {
+  const col = columns?.find(c => c.key === rule.fieldKey)
+  const dataKey = (col?.sortKey ?? rule.fieldKey) as keyof T
+  return String(row[dataKey] ?? "")
+}
+
+function ruleHasActiveValues(
+  rule: ConditionalRule,
+  columns?: ConditionalColumnHint[],
+): boolean {
+  if (rule.values.length === 0) return false
+  const col = columns?.find(c => c.key === rule.fieldKey)
+  if (col?.filter?.type === "text") return (rule.values[0] ?? "").trim().length > 0
+  return true
+}
+
+function conditionalTextMatches(
+  cellVal: string,
+  needle: string,
+  op: "contains" | "not_contains",
+  textMask: FilterTextMask | undefined,
+) {
+  const v = cellVal.trim()
+  const n = needle.trim()
+  if (!n) return op === "not_contains"
+  if (textMask === "phone" || textMask === "zip") {
+    const nd = n.replace(/\D/g, "")
+    const hay = v.replace(/\D/g, "")
+    if (!nd) return op === "not_contains"
+    const hit = hay.includes(nd)
+    return op === "contains" ? hit : !hit
+  }
+  const hit = v.toLowerCase().includes(n.toLowerCase())
+  return op === "contains" ? hit : !hit
+}
+
+/** Whether a conditional rule matches a row (same logic as DataTable cells). */
+export function conditionalRuleMatchesRow<T extends Record<string, unknown>>(
+  row: T,
+  rule: ConditionalRule,
+  columns?: ConditionalColumnHint[],
+): boolean {
+  if (!ruleHasActiveValues(rule, columns)) return false
+  const v = rowValueForRule(row, rule, columns).trim()
+  const col = columns?.find(c => c.key === rule.fieldKey)
+  const textMask = col?.filter?.type === "text" ? col.filter.textMask : undefined
+  switch (rule.operator) {
+    case "is":
+      return rule.values.includes(v)
+    case "is_not":
+      return !rule.values.includes(v)
+    case "contains":
+      return rule.values.some(val => conditionalTextMatches(v, val, "contains", textMask))
+    case "not_contains":
+      return !rule.values.some(val => conditionalTextMatches(v, val, "contains", textMask))
+    default:
+      return false
+  }
+}
+
+/** First matching conditional rule background for a row (list/board row tint). */
 export function getConditionalRowBackground<T extends Record<string, unknown>>(
   row: T,
   rules: ConditionalRule[] | undefined,
+  columns?: ConditionalColumnHint[],
 ): string | undefined {
   if (!rules?.length) return undefined
   for (const rule of rules) {
-    const cellVal = String(row[rule.fieldKey as keyof T] ?? "")
-    const v = cellVal.trim()
-    switch (rule.operator) {
-      case "is":
-        if (rule.values.length > 0 && rule.values.includes(v)) return rule.bgColor
-        break
-      case "is_not":
-        if (rule.values.length > 0 && !rule.values.includes(v)) return rule.bgColor
-        break
-      case "contains":
-        if (rule.values.length > 0 && rule.values.some(val => v.toLowerCase().includes(val.toLowerCase())))
-          return rule.bgColor
-        break
-      case "not_contains":
-        if (rule.values.length > 0 && !rule.values.some(val => v.toLowerCase().includes(val.toLowerCase())))
-          return rule.bgColor
-        break
-      default:
-        break
-    }
+    if (conditionalRuleMatchesRow(row, rule, columns)) return rule.bgColor
   }
   return undefined
 }
+
+/** Background for one table cell from conditional rules on that column. */
+export function getConditionalCellBackground<T extends Record<string, unknown>>(
+  row: T,
+  colKey: string,
+  rules: ConditionalRule[] | undefined,
+  columns?: ConditionalColumnHint[],
+): string | undefined {
+  if (!rules?.length) return undefined
+  const rule = rules.find(r => r.fieldKey === colKey)
+  if (!rule || !conditionalRuleMatchesRow(row, rule, columns)) return undefined
+  return rule.bgColor
+}

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" },
+]

package/template/lib/data-list-view-registry.ts

@@ -0,0 +1,104 @@
+/**
+ * Central registry for list-page view types — labels, render kinds, and hub chrome rules.
+ *
+ * **Add a new view once here** (plus a body in `components/data-views/`). Hubs declare
+ * `supportedViewTypes` on `ListPageTemplate`; table components branch with
+ * `getDataListViewRenderKind` + `ListPageConnectedViewBody` (never a dashboard fallback).
+ *
+ * @see `docs/data-views-pattern.md` — "View registry and connected bodies"
+ */
+
+import {
+  DATA_LIST_VIEW_TILES,
+  type DataListViewType,
+  dataListViewAddShortcut,
+  dataListViewIcon,
+  dataListViewLabel,
+} from "@/lib/data-list-view"
+import {
+  getDataListViewRenderKind,
+  type DataListViewRenderKind,
+} from "@/lib/data-list-view-surface"
+
+export interface DataListViewDefinition {
+  value: DataListViewType
+  label: string
+  icon: string
+  renderKind: DataListViewRenderKind
+  /** `ListPageTemplate` metrics slot above the views toolbar. */
+  hubMetricsStrip: boolean
+}
+
+const DEFINITIONS: DataListViewDefinition[] = DATA_LIST_VIEW_TILES.map(tile => {
+  const renderKind = getDataListViewRenderKind(tile.value)
+  const hubMetricsStrip = renderKind !== "calendar-with-toolbar" && renderKind !== "dashboard-with-toolbar"
+  return {
+    value: tile.value,
+    label: tile.label,
+    icon: tile.icon,
+    renderKind,
+    hubMetricsStrip,
+  }
+})
+
+const BY_VALUE = new Map<DataListViewType, DataListViewDefinition>(
+  DEFINITIONS.map(d => [d.value, d]),
+)
+
+export const DATA_LIST_VIEW_REGISTRY: readonly DataListViewDefinition[] = DEFINITIONS
+
+export function dataListViewDefinition(view: DataListViewType): DataListViewDefinition {
+  const def = BY_VALUE.get(view)
+  if (!def) {
+    throw new Error(`Unknown DataListViewType: ${view}`)
+  }
+  return def
+}
+
+/** `ListPageTemplate` hub KPI strip — false for calendar and dashboard (inline KPIs). */
+export function showsListPageHubMetricsStrip(view: DataListViewType): boolean {
+  return dataListViewDefinition(view).hubMetricsStrip
+}
+
+/** Tiles for Add view + Properties when a hub only supports a subset of views. */
+export function dataListViewTilesForHub(supported: readonly DataListViewType[]) {
+  const allowed = new Set(supported)
+  return DATA_LIST_VIEW_REGISTRY.filter(d => allowed.has(d.value)).map(d => ({
+    type: d.value,
+    label: d.label,
+    icon: d.icon,
+  }))
+}
+
+/** `SelectionTileGrid` options for Properties when a hub supports a subset of views. */
+export function dataListViewSelectionTilesForHub(supported: readonly DataListViewType[]) {
+  return dataListViewTilesForHub(supported).map(t => ({
+    value: t.type,
+    label: t.label,
+    icon: t.icon,
+  }))
+}
+
+/** View types that expose Table Properties (all registered `DataListViewType` values). */
+export const DATA_LIST_SURFACE_VIEW_TYPES: ReadonlySet<DataListViewType> = new Set(
+  DATA_LIST_VIEW_REGISTRY.map(d => d.value),
+)
+
+export function isDataListSurfaceViewType(viewType: string): viewType is DataListViewType {
+  return DATA_LIST_SURFACE_VIEW_TYPES.has(viewType as DataListViewType)
+}
+
+export function isDataListViewTypeSupported(
+  view: DataListViewType,
+  supported: readonly DataListViewType[],
+): boolean {
+  return supported.includes(view)
+}
+
+export {
+  dataListViewAddShortcut,
+  dataListViewIcon,
+  dataListViewLabel,
+  getDataListViewRenderKind,
+  type DataListViewRenderKind,
+}

package/template/lib/data-list-view-surface.ts

@@ -11,18 +11,22 @@
  * | `list`     | `DataTableToolbar` + list layout |
  * | `board`    | `DataTableToolbar` + board / kanban |
  * | `dashboard`| `DataTableToolbar` + KPI (`KeyMetrics`) + optional charts (`ChartCard`, Recharts, etc.) |
+ * | `calendar` | `DataTableToolbar` + `ListPageCalendarView` (month grid + day detail) |
  * | `folder`   | `DataTableToolbar` + icon grid (macOS-Finder-style) |
  * | `panel`    | `DataTableToolbar` + resizable split (list / tree column + detail inspector) |
  */
 
 import type { DataListViewType } from "@/lib/data-list-view"
 
+export { showsListPageHubMetricsStrip } from "@/lib/data-list-view-registry"
+
 /** What to render for the active view tab (routing / branching). */
 export type DataListViewRenderKind =
   | "data-table"
   | "list-with-toolbar"
   | "board-with-toolbar"
   | "dashboard-with-toolbar"
+  | "calendar-with-toolbar"
   | "folder-with-toolbar"
   | "panel-with-toolbar"
   | "tree-panel-with-toolbar"
@@ -41,6 +45,8 @@ export function getDataListViewRenderKind(view: DataListViewType): DataListViewR
       return "board-with-toolbar"
     case "dashboard":
       return "dashboard-with-toolbar"
+    case "calendar":
+      return "calendar-with-toolbar"
     case "folder":
       return "folder-with-toolbar"
     case "panel":
@@ -65,5 +71,13 @@ export function usesDashboardSurface(view: DataListViewType): boolean {
 
 /** Shared toolbar (search, filters, properties); body differs by view. */
 export function usesToolbarWithFilteredRows(view: DataListViewType): boolean {
-  return view === "list" || view === "board" || view === "dashboard" || view === "folder" || view === "panel" || view === "tree-panel"
+  return (
+    view === "list" ||
+    view === "board" ||
+    view === "dashboard" ||
+    view === "calendar" ||
+    view === "folder" ||
+    view === "panel" ||
+    view === "tree-panel"
+  )
 }

package/template/lib/data-list-view.ts

@@ -5,7 +5,15 @@
  * `dataListViewLabel` / `dataListViewIcon` on every page so Table / List / Board / Dashboard
  * stay consistent and stay wired to the same `useTableState` dataset (see `docs/data-views-pattern.md`).
  */
-export type DataListViewType = "table" | "list" | "board" | "dashboard" | "folder" | "panel" | "tree-panel"
+export type DataListViewType =
+  | "table"
+  | "list"
+  | "board"
+  | "dashboard"
+  | "calendar"
+  | "folder"
+  | "panel"
+  | "tree-panel"
 
 export const DATA_LIST_VIEW_TILES: readonly {
   value: DataListViewType
@@ -16,6 +24,7 @@ export const DATA_LIST_VIEW_TILES: readonly {
   { value: "list",      icon: "fa-list",          label: "List view" },
   { value: "board",     icon: "fa-table-columns", label: "Board view" },
   { value: "dashboard", icon: "fa-chart-mixed",   label: "Dashboard view" },
+  { value: "calendar",  icon: "fa-calendar-days", label: "Calendar view" },
   { value: "folder",    icon: "fa-grid-2",        label: "Folder view" },
   { value: "panel",      icon: "fa-sidebar",      label: "List & details" },
   { value: "tree-panel", icon: "fa-sitemap",      label: "Tree & details" },
@@ -30,3 +39,9 @@ export function dataListViewLabel(view: DataListViewType): string {
 export function dataListViewIcon(view: DataListViewType): string {
   return DATA_LIST_VIEW_TILES.find(t => t.value === view)?.icon ?? "fa-table"
 }
+
+/** Add-view menu hint + `<Shortcut>` keys (1–9). Skipped in inputs via `useShortcut`. */
+export function dataListViewAddShortcut(index: number): string | undefined {
+  if (index < 0 || index > 8) return undefined
+  return String(index + 1)
+}