@exxatdesignux/ui 0.0.6 → 0.0.7

package/template/components/ui/payment-card-fields.tsx

@@ -0,0 +1 @@
+export * from "../../../../packages/ui/src/components/ui/payment-card-fields"

package/template/components/ui/popover.tsx

@@ -0,0 +1 @@
+export * from "../../../../packages/ui/src/components/ui/popover"

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

@@ -0,0 +1 @@
+export * from "../../../../packages/ui/src/components/ui/radio-group"

package/template/components/ui/select.tsx

@@ -0,0 +1 @@
+export * from "../../../../packages/ui/src/components/ui/select"

package/template/components/ui/selection-tile-grid.tsx

@@ -0,0 +1 @@
+export * from "../../../../packages/ui/src/components/ui/selection-tile-grid"

package/template/components/ui/separator.tsx

@@ -0,0 +1 @@
+export * from "../../../../packages/ui/src/components/ui/separator"

package/template/components/ui/sheet.tsx

@@ -0,0 +1 @@
+export * from "../../../../packages/ui/src/components/ui/sheet"

package/template/components/ui/sidebar.tsx

@@ -0,0 +1 @@
+export * from "../../../../packages/ui/src/components/ui/sidebar"

package/template/components/ui/skeleton.tsx

@@ -0,0 +1 @@
+export * from "../../../../packages/ui/src/components/ui/skeleton"

package/template/components/ui/sonner.tsx

@@ -0,0 +1 @@
+export * from "../../../../packages/ui/src/components/ui/sonner"

package/template/components/ui/status-badge.tsx

@@ -0,0 +1 @@
+export * from "../../../../packages/ui/src/components/ui/status-badge"

package/template/components/ui/table.tsx

@@ -0,0 +1 @@
+export * from "../../../../packages/ui/src/components/ui/table"

package/template/components/ui/tabs.tsx

@@ -0,0 +1 @@
+export * from "../../../../packages/ui/src/components/ui/tabs"

package/template/components/ui/textarea.tsx

@@ -0,0 +1 @@
+export * from "../../../../packages/ui/src/components/ui/textarea"

package/template/components/ui/tip.tsx

@@ -0,0 +1 @@
+export * from "../../../../packages/ui/src/components/ui/tip"

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

@@ -0,0 +1 @@
+export * from "../../../../packages/ui/src/components/ui/toggle-group"

package/template/components/ui/toggle-switch.tsx

@@ -0,0 +1 @@
+export * from "../../../../packages/ui/src/components/ui/toggle-switch"

package/template/components/ui/toggle.tsx

@@ -0,0 +1 @@
+export * from "../../../../packages/ui/src/components/ui/toggle"

package/template/components/ui/tooltip.tsx

@@ -0,0 +1 @@
+export * from "../../../../packages/ui/src/components/ui/tooltip"

package/template/components/ui/view-segmented-control.tsx

@@ -0,0 +1 @@
+export * from "../../../../packages/ui/src/components/ui/view-segmented-control"

package/template/components.json

@@ -0,0 +1,27 @@
+{
+  "$schema": "https://ui.shadcn.com/schema.json",
+  "style": "radix-nova",
+  "rsc": true,
+  "tsx": true,
+  "tailwind": {
+    "config": "",
+    "css": "app/globals.css",
+    "baseColor": "mist",
+    "cssVariables": true,
+    "prefix": ""
+  },
+  "iconLibrary": "lucide",
+  "rtl": true,
+  "menuColor": "default",
+  "menuAccent": "subtle",
+  "aliases": {
+    "components": "@/components",
+    "utils": "@/lib/utils",
+    "ui": "@/components/ui",
+    "lib": "@/lib",
+    "hooks": "@/hooks"
+  },
+  "registries": {
+    "@blocks-so": "https://blocks.so/r/{name}.json"
+  }
+}

package/template/contexts/chart-variant-context.tsx

@@ -0,0 +1,35 @@
+"use client"
+
+/**
+ * ChartVariantContext
+ * Shared state for the active chart card style on the dashboard.
+ * Consumed by NavUser (sidebar profile menu) and DashboardTabs (page content).
+ */
+
+import * as React from "react"
+
+export type ChartVariant = "normal" | "tabs" | "selector" | "metrics-tabs" | "kpi-chart"
+
+interface ChartVariantContextValue {
+  chartVariant: ChartVariant
+  setChartVariant: (v: ChartVariant) => void
+}
+
+export const ChartVariantContext = React.createContext<ChartVariantContextValue>({
+  chartVariant: "normal",
+  setChartVariant: () => {},
+})
+
+export function ChartVariantProvider({ children }: { children: React.ReactNode }) {
+  const [chartVariant, setChartVariant] = React.useState<ChartVariant>("kpi-chart")
+  const value = React.useMemo(() => ({ chartVariant, setChartVariant }), [chartVariant])
+  return (
+    <ChartVariantContext.Provider value={value}>
+      {children}
+    </ChartVariantContext.Provider>
+  )
+}
+
+export function useChartVariant() {
+  return React.useContext(ChartVariantContext)
+}

package/template/contexts/command-menu-context.tsx

@@ -0,0 +1,28 @@
+"use client"
+
+import * as React from "react"
+import type { CommandMenuConfig } from "@/lib/command-menu-config"
+
+const CommandMenuContext = React.createContext<CommandMenuConfig | null>(null)
+
+export function CommandMenuProvider({
+  value,
+  children,
+}: {
+  value: CommandMenuConfig
+  children: React.ReactNode
+}) {
+  return (
+    <CommandMenuContext.Provider value={value}>{children}</CommandMenuContext.Provider>
+  )
+}
+
+export function useCommandMenuConfig(): CommandMenuConfig {
+  const ctx = React.useContext(CommandMenuContext)
+  if (!ctx) {
+    throw new Error(
+      "useCommandMenuConfig must be used within CommandMenuProvider (wrap the app shell and pass command menu config).",
+    )
+  }
+  return ctx
+}

package/template/contexts/dashboard-view-context.tsx

@@ -0,0 +1,35 @@
+"use client"
+
+/**
+ * DashboardViewContext
+ * Shared state for the active dashboard view (report | simple | mix).
+ * Consumed by NavUser (sidebar profile menu) and DashboardTabs (page content).
+ */
+
+import * as React from "react"
+
+export type DashboardView = "report" | "simple" | "mix"
+
+interface DashboardViewContextValue {
+  activeView: DashboardView
+  setActiveView: (v: DashboardView) => void
+}
+
+export const DashboardViewContext = React.createContext<DashboardViewContextValue>({
+  activeView: "report",
+  setActiveView: () => {},
+})
+
+export function useDashboardView() {
+  return React.useContext(DashboardViewContext)
+}
+
+export function DashboardViewProvider({ children }: { children: React.ReactNode }) {
+  const [activeView, setActiveView] = React.useState<DashboardView>("report")
+  const value = React.useMemo(() => ({ activeView, setActiveView }), [activeView])
+  return (
+    <DashboardViewContext.Provider value={value}>
+      {children}
+    </DashboardViewContext.Provider>
+  )
+}

package/template/contexts/product-context.tsx

@@ -0,0 +1,38 @@
+"use client"
+
+/**
+ * ProductProvider — rehydrates the Zustand app store from localStorage after
+ * mount, then keeps the <html> theme class in sync with the active product.
+ *
+ * `useProduct()` is a thin convenience hook over useAppStore so all existing
+ * call-sites continue to work without any changes.
+ */
+
+import * as React from "react"
+import { useAppStore, type Product } from "@/stores/app-store"
+
+export type { Product }
+
+export function useProduct() {
+  const product    = useAppStore(s => s.product)
+  const setProduct = useAppStore(s => s.setProduct)
+  return { product, setProduct }
+}
+
+export function ProductProvider({ children }: { children: React.ReactNode }) {
+  const product = useAppStore(s => s.product)
+
+  // Rehydrate from localStorage once — keeps SSR render matching server output.
+  React.useEffect(() => {
+    void useAppStore.persist.rehydrate()
+  }, [])
+
+  // Sync theme class to <html> whenever product changes.
+  React.useEffect(() => {
+    const html = document.documentElement
+    html.classList.remove("theme-one", "theme-prism")
+    html.classList.add(product === "exxat-one" ? "theme-one" : "theme-prism")
+  }, [product])
+
+  return <>{children}</>
+}

package/template/contexts/system-banner-context.tsx

@@ -0,0 +1,127 @@
+"use client"
+
+/**
+ * SystemBannerContext — the top-of-app system banner is now user-configurable
+ * from Settings. We persist the config in `localStorage` so a product owner
+ * (or a demo) can preview "maintenance notice", "new feature", "promo", etc.
+ * without a redeploy. In production this would be backed by an admin API, but
+ * the storage shape + provider surface already match what that API would need.
+ *
+ * Usage:
+ *   - `<SystemBannerProvider>` wraps the app in (app)/layout.tsx.
+ *   - Layout reads the config via `useSystemBanner()` and renders `<SystemBanner>` only when enabled.
+ *   - Settings page calls `updateConfig()` / `setEnabled()` to change it.
+ */
+
+import * as React from "react"
+
+export type SystemBannerVariant = "info" | "warning" | "error" | "success" | "promo"
+
+export type SystemBannerEmphasis = "prominent" | "subtle"
+
+export interface SystemBannerConfig {
+  enabled: boolean
+  variant: SystemBannerVariant
+  emphasis: SystemBannerEmphasis
+  title: string
+  message: string
+  actionLabel?: string
+  actionHref?: string
+  dismissible: boolean
+}
+
+export const DEFAULT_SYSTEM_BANNER_CONFIG: SystemBannerConfig = {
+  enabled: true,
+  variant: "promo",
+  emphasis: "prominent",
+  title: "Exxat One Premium",
+  message: "Unlock advanced analytics, AI insights, and priority support.",
+  actionLabel: "Learn more",
+  actionHref: "#",
+  dismissible: true,
+}
+
+const STORAGE_KEY = "exxat:system-banner-config"
+
+interface SystemBannerContextValue {
+  config: SystemBannerConfig
+  updateConfig: (patch: Partial<SystemBannerConfig>) => void
+  setEnabled: (enabled: boolean) => void
+  /** Apply an arbitrary config snapshot wholesale (used by Settings "Apply" button). */
+  applyConfig: (next: SystemBannerConfig) => void
+  /** Restore the shipped default. */
+  reset: () => void
+}
+
+const SystemBannerContext = React.createContext<SystemBannerContextValue>({
+  config: DEFAULT_SYSTEM_BANNER_CONFIG,
+  updateConfig: () => {},
+  setEnabled: () => {},
+  applyConfig: () => {},
+  reset: () => {},
+})
+
+function readStored(): SystemBannerConfig {
+  if (typeof window === "undefined") return DEFAULT_SYSTEM_BANNER_CONFIG
+  try {
+    const raw = window.localStorage.getItem(STORAGE_KEY)
+    if (!raw) return DEFAULT_SYSTEM_BANNER_CONFIG
+    const parsed = JSON.parse(raw) as Partial<SystemBannerConfig>
+    // Merge so newly-added fields in the default keep working for old payloads.
+    return { ...DEFAULT_SYSTEM_BANNER_CONFIG, ...parsed }
+  } catch {
+    return DEFAULT_SYSTEM_BANNER_CONFIG
+  }
+}
+
+export function SystemBannerProvider({ children }: { children: React.ReactNode }) {
+  // Start from default on SSR; hydrate from storage on mount so server and client markup match.
+  const [config, setConfig] = React.useState<SystemBannerConfig>(DEFAULT_SYSTEM_BANNER_CONFIG)
+  const [hydrated, setHydrated] = React.useState(false)
+
+  React.useEffect(() => {
+    setConfig(readStored())
+    setHydrated(true)
+  }, [])
+
+  // Persist whenever config changes post-hydration.
+  React.useEffect(() => {
+    if (!hydrated) return
+    try {
+      window.localStorage.setItem(STORAGE_KEY, JSON.stringify(config))
+    } catch {
+      /* storage full / disabled — silently ignore, the UI still works for the session. */
+    }
+  }, [config, hydrated])
+
+  // Cross-tab sync — if you change the banner in one tab, others follow.
+  React.useEffect(() => {
+    function onStorage(e: StorageEvent) {
+      if (e.key !== STORAGE_KEY || !e.newValue) return
+      try {
+        setConfig({ ...DEFAULT_SYSTEM_BANNER_CONFIG, ...JSON.parse(e.newValue) })
+      } catch {
+        /* ignore malformed payloads */
+      }
+    }
+    window.addEventListener("storage", onStorage)
+    return () => window.removeEventListener("storage", onStorage)
+  }, [])
+
+  const value = React.useMemo<SystemBannerContextValue>(
+    () => ({
+      config,
+      updateConfig: (patch) => setConfig((prev) => ({ ...prev, ...patch })),
+      setEnabled: (enabled) => setConfig((prev) => ({ ...prev, enabled })),
+      applyConfig: (next) => setConfig(next),
+      reset: () => setConfig(DEFAULT_SYSTEM_BANNER_CONFIG),
+    }),
+    [config],
+  )
+
+  return <SystemBannerContext.Provider value={value}>{children}</SystemBannerContext.Provider>
+}
+
+export function useSystemBanner() {
+  return React.useContext(SystemBannerContext)
+}

package/template/docs/command-menu-pattern.md

@@ -0,0 +1,45 @@
+# Global command palette (⌘K)
+
+**Code:** `components/command-menu.tsx`, config **`buildCommandMenuConfig()`** in **`lib/command-menu-config.ts`**, wired in **`app/(app)/layout.tsx`** via **`CommandMenuProvider`**. Searchable row data is built in **`lib/command-menu-search-data.ts`** (not inside the shell component).
+
+## Role
+
+The command menu is the app’s **global search and AI entry**—one place to jump to routes, library pages, patterns, and AI starters. It is **not** a duplicate of the left sidebar; it **indexes** product surfaces for fast discovery.
+
+## User model
+
+| Need | Where it lives |
+|------|----------------|
+| **Find a page, component, or pattern** | Palette — filterable list, **Enter** to navigate. |
+| **Quick AI / natural language** | Prefer **short answers or “research” snippets inside the palette** when the product can return compact, citeable results without leaving the flow. |
+| **Long or complex answers** | **Ask Leo** right sidebar — multi-step reasoning, long-form help, or anything that does not fit a small results surface. |
+
+**Design rule:** Treat the palette as **progressive disclosure**—lightweight results first in-menu; **escalate** to Ask Leo when the answer is too large or needs a dedicated conversation surface.
+
+## Keyboard
+
+- **⌘K / Ctrl+K** — open / toggle the palette (global listener in `CommandMenu`).
+- **Ask Leo** remains **⌘⌥K / Ctrl+Alt+K** (see `.cursor/rules/exxat-kbd-shortcuts.mdc`) so it does not collide with table search where both exist.
+
+## Configuration
+
+- **Static groups** (AI suggestions, Navigation, Components, Patterns) live in **`lib/command-menu-config.ts`**.
+- Optional **`dataGroups`** are passed to **`buildCommandMenuConfig({ dataGroups })`** from the app shell. **Implementation:** **`getCommandMenuSearchDataGroups()`** in **`lib/command-menu-search-data.ts`** maps mock/API rows (e.g. placements with student names) to **`CommandMenuItem`** rows with **`label`**, **`href`**, and **`keywords`** for cmdk filtering. The layout uses **`buildCommandMenuConfig({ dataGroups: getCommandMenuSearchDataGroups() })`**. Keep domain mapping **outside** `command-menu.tsx` so data sources can change without editing the shell.
+- **`searchOnly` on `CommandMenuGroup`:** cmdk shows **every** mounted item when the search box is empty. For large indexes (hundreds of placements), set **`searchOnly: true`** on that group so **`command-menu.tsx`** does not render it until the user has typed a non-empty query. Static groups (AI, Navigation, …) stay visible on open; the data group appears once the user searches.
+
+## Files (quick reference)
+
+| Piece | Location |
+|-------|----------|
+| Palette UI | `components/command-menu.tsx` |
+| Static groups + `buildCommandMenuConfig` | `lib/command-menu-config.ts` (`CommandMenuGroup.searchOnly`) |
+| Row → menu items (placements, etc.) | `lib/command-menu-search-data.ts` |
+| Provider + `dataGroups` | `app/(app)/layout.tsx` |
+
+## Sidebar
+
+**“Search or ask Leo”** in the sidebar opens the same palette; shortcuts and copy should stay aligned with **`AGENTS.md` §7.1**.
+
+---
+
+Keep this document aligned with **`exxat-ds/AGENTS.md` §7.1** when behavior or copy changes.

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

@@ -0,0 +1,160 @@
+# Data views pattern (table, list, board)
+
+> **Canonical rules for agents (MUST/MUST NOT, checklists):** [`AGENTS.md`](../AGENTS.md) in this package (including **§8 Accessibility**). This file is the long-form narrative; keep both aligned when patterns change.
+
+This document describes how list pages combine **views**, **toolbar** behavior, **filters**, **properties**, and **persistence** in this codebase.
+
+## Reuse existing components (required)
+
+**Prefer composing what already exists** over rebuilding one-off tabs, search, filters, or property panels. The **Placements** flow is the reference implementation; new list/table/board pages should wire the same building blocks with new data and column definitions.
+
+| Need | Reuse | Where Placements uses it |
+| --- | --- | --- |
+| **View tabs** (table / list / board, lifecycle filters) | `ListPageTemplate` (`ViewTab`, `renderContent`, optional metrics + export) | `components/data-list-client.tsx` + `components/templates/list-page.tsx` |
+| **Table shell** (search, filter bar, sort, grouping, columns, pagination) | `DataTable`, `DataTableToolbar`, `useTableState` | `components/data-table/`, `components/data-list-table.tsx` |
+| **Properties drawer** (display, columns, filters, sort, view type tiles) | `TablePropertiesDrawer` from `@/components/table-properties` | `DrawerToolbar` / list–board shells in `data-list-table.tsx` |
+| **Board / list** | `PlacementsBoardView`, `PlacementsListView` + same `useTableState` | `DataListTable` |
+| **Page header** (primary CTA + More ⋯ + export) | `PlacementsPageHeader` or `TeamPageHeader` | `components/placements-page-header.tsx`, `components/team-page-header.tsx` |
+| **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` |
+| **Export** | `ExportDrawer` | `ListPageTemplate` export props; `DataListClient` |
+
+**Rules:** (1) Import and compose these components; pass **props** and **column defs** for your entity. (2) If something is missing, **extend the shared component** under `components/` (e.g. a new optional slot on `DataTableToolbar`) rather than copying markup into a single page. (3) Card-only or lightweight pages may use a smaller **Properties** sheet only when there is **no** table—otherwise use `TablePropertiesDrawer` with `DataTable` (see Team).
+
+### Table pages must use view tabs
+
+If the page uses a **`DataTable`** (or equivalent data grid) as the main surface, it **must** sit under **`ListPageTemplate`** so users get the **views toolbar** (tabs, add view, per-tab settings). The default `ViewTab` entries should include at least one tab whose `viewType` is **`table`** when the primary experience is tabular data. **Do not** render a `DataTable` alone under only `PageHeader` + body.
+
+- **Reference:** `DataListClient` (Placements) and `TeamClient` (Team).
+- **Rationale:** Consistent navigation, saved views, per-tab view type (table / list / board), and export at the template level.
+
+## Architecture
+
+- **Page shell** — `ListPageTemplate` owns the views toolbar (tabs), optional metrics, and export drawer. Content for the active tab is rendered via `renderContent`.
+- **Per–lifecycle (or category) data** — `DataListTable` swaps **columns** and **row sets** based on `lifecycleTabId` (e.g. All / Upcoming / Ongoing / Completed). Each lifecycle tab gets its **own** `DataListTable` instance (`key={tab.filterId}`) so `useTableState` resets correctly when columns change.
+- **Shared table state** — `useTableState` holds sort, search, filters, grouping, column order/visibility/pins/widths, row height, gridlines, and pagination flags. **Table**, **list**, **board**, and **dashboard** all read the same state so switching view type keeps behavior aligned.
+
+## Mock data and connected views
+
+1. **Put entity rows in `lib/mock/<entity>.ts`** — Export a typed array (e.g. `TeamMember[]`, `Placement[]`) and reuse it from the page client and from KPI helpers.
+2. **KPI / summary helpers** — Add `lib/mock/<entity>-kpi.ts` (or next to the mock file) with pure functions **`entityKpiMetrics(rows: T[])`** and **`entityKpiInsight(rows: T[])`** returning `MetricItem[]` and `MetricInsight` from `@/components/key-metrics`. Drive **both** the template **`metrics`** slot and the **dashboard view** from the **same helpers**, passing **`tableState.rows`** in the table component so filters/search apply everywhere.
+3. **Single table component** — One component (e.g. `TeamTable`) receives **`members`** (full mock) + **`view`**. It calls **`useTableState(members, columns, …)`** once. Branch on `view`:
+   - **`table`** → `DataTable` with that state.
+   - **`list` / `board`** → `DataTableToolbar` + list/board UI with **`tableState.rows`**.
+   - **`dashboard`** → `DataTableToolbar` + **`KeyMetrics`** (and/or other **existing** dashboard building blocks — `ChartsOverview` only when charts are product-appropriate) fed by **`teamKpiMetrics(tableState.rows)`** / **`teamKpiInsight(tableState.rows)`** — **not** bespoke `Card` grids duplicating KPIs.
+4. **Client wiring** — `renderContent` always renders the table component with **`view={tab.viewType}`** and **`key={tab.id}`** (not `viewType`) so switching views does not remount state. **Do not** show “not wired” placeholders for list/board/dashboard when the table stack supports those views.
+5. **Full-route dashboards** — The **`/dashboard`** page uses **`DashboardTabs`**, **`KeyMetrics`**, and **`ChartsOverview`** with `lib/mock/dashboard.ts`. List-page **dashboard view** is a **narrower** slice: reuse **`KeyMetrics`** (+ entity KPI helpers) first; add charts only when they match the entity and reuse **`ChartsOverview`** patterns from `components/charts-overview.tsx`.
+
+## Table vs list vs board vs dashboard
+
+| Concern | Table | List | Board | Dashboard (view tab) |
+| --- | --- | --- | --- | --- |
+| Primary surface | `DataTable` | `PlacementsListView` / entity list | `PlacementsBoardView` / entity board | **`KeyMetrics`** (+ optional charts via shared dashboard components) |
+| Data source | `useTableState` | **`tableState.rows`** | **`tableState.rows`** | **`tableState.rows`** via KPI helpers |
+| Column headers / labels | `showColumnLabels` | Same source columns, list layout | Phase columns + optional board column menu | N/A (metrics from same columns/filters) |
+| Row click / navigation | From `DataListTable` | From list shell | Card `onOpen` | N/A |
+| Pagination | Optional `PaginationBar` + `CountSyncer` | Same pattern | N/A (board uses phase columns) | N/A |
+
+## Toolbar and properties
+
+- **Search** — Global quick search lives in table state (`search` / `showToolbarSearch` from display options). Board phase columns can add local search in the board column header.
+- **Filters** — Built from `ColumnDef.filter` and `filterFields` passed to `TablePropertiesDrawer`. Connectors between filters (`and` / `or`) are part of table state.
+- **Sort / group** — Sort rules and `groupBy` are in table state; board menu proxies the same actions when `boardColumnMenu` is wired.
+- **Properties drawer** — `TablePropertiesDrawer` is **generic**: supply `filterFields`, `fieldDefinitionsForDrawer`, `resolveColumnLabel`, `activeFilters`, sort/column handlers, `displayOptions`, and optional view-type tiles. Domain-specific defaults (e.g. `FILTER_FIELDS` in `types.ts`) are optional; new pages can pass their own definitions.
+
+**Import:** `@/components/table-properties` re-exports the drawer and types.
+
+## Board UI reuse
+
+**Handbook:** **`AGENTS.md` §4.4** — board card shell, badge row, shared status maps, and MUST/MUST NOT. **Cursor:** **`.cursor/rules/exxat-board-cards.mdc`**, skill **`.cursor/skills/exxat-board-cards/SKILL.md`**.
+
+- **Card shell** — `components/data-views/list-page-board-card.tsx` — **`ListPageBoardCard`**, **`ListPageBoardCardHeader`**, **`ListPageBoardCardTitleRow`**, **`ListPageBoardCardAvatar`**, **`ListPageBoardCardBadgeRow`**, **`ListPageBoardCardBody`**, **`ListPageBoardCardSecondary`**. All product board cards on list hubs **should** use this shell (same **`Card` `size="sm"`** pattern as Placements).
+- **Primitives** — `components/data-views/board-card-primitives.tsx` — `BoardCardIconRow`, `BoardCardTwoLineBlock` (optional `line2`), `BoardNewCardPlaceholder`, `lineClampClass`.
+- **Status (Team & Compliance)** — `lib/list-status-badges.ts` — single source for label strings + badge `className` tails for **table, list, and board**. Do **not** pair with `uppercase` on the Badge (labels are sentence case, aligned with Placements `BoardStatusBadge`).
+- **Owner initials** — `lib/initials-from-name.ts` when mock rows have a display name but no `initials` field.
+- **Shared column shell** — `components/data-views/list-page-board-template.tsx` — `ListPageBoardTemplate` + `ListPageBoardColumnDef<T>`: define columns with `filter` predicates, `renderCard`, `getRowKey`. Used by **Team** and **Compliance** boards; new hubs should start here before custom chrome.
+- **Placement card** — `components/data-views/placement-board-card.tsx` — `BoardPlacementCard` composes **`ListPageBoardCard`** parts with `ColumnDef<Placement>` and lifecycle layout helpers from `lib/placement-board-card-layout.ts`. Placements keeps richer column headers (search, menus); still uses the same primitives.
+- New entities should add their own card component that composes **`ListPageBoardCard`** + primitives rather than duplicating column scroll/layout or ad-hoc card chrome.
+
+## Dashboard view (list pages)
+
+- **Reuse the dashboard chart bundle** — `components/dashboard-report-charts.tsx` — `DashboardReportCharts`: flat `KeyMetrics` + middle chart section + period comparison `KeyMetrics` card. **`ChartsOverview`** (placement-themed demo gallery) is the default middle section for `/dashboard` and **Placements**. **Team** passes **`chartsSection={<TeamDashboardChartsSection members={tableState.rows} />}`** so charts reflect roster data, not placements. List hubs use `ListPageDashboardCharts` (`metricsSingleRow`). Chart **style** can follow `ChartVariantProvider` when using `ChartsOverview`.
+- **Data tab canvas charts** (`data-view-dashboard-charts*.tsx`) share **`ChartFigure`**, **`ChartCard`**, and **`ChartDataTable`** with `charts-overview.tsx`. **Layout** for Placements / Team / Compliance is stored in one place: **`lib/data-view-dashboard-storage.ts`** (see `AGENTS.md` §4.3). **Keyboard-selected bars/slices** must use **`lib/chart-keyboard-selection.ts`** (`activeBar` / `activeShape`) so behavior matches the gallery — not opacity-only `Cell` dimming.
+
+## Persistence
+
+- **Page-level** (`lib/data-list-persistence.ts`, key `exxat-ds:data-list:page:v1`): `displayOptions`, `showMetrics`, `tabs`, `activeTabId`. Loaded in `DataListClient` with `useLayoutEffect`, saved debounced on change. `ListPageTemplate` runs in **controlled** mode when `tabs` / `onTabsChange` / `activeTabId` / `onActiveTabChange` are passed.
+- **Per–lifecycle tab** (key `exxat-ds:data-list:lifecycle:v1:<filterId>`): sort, search, filters, group by, column order/hidden/widths/pins/wrap, column menu search map, row height, gridlines, filter bar visibility, search popover, conditional rules, pagination toggle and page/size. Hydrated in `DataListTable` with `useLayoutEffect`; saved debounced when those fields change.
+
+To add a new page: copy the `DataListClient` pattern (controlled `ListPageTemplate` + storage key namespace) or call `schedulePageSave` / `scheduleLifecycleSave` with your own keys.
+
+## Rules of thumb
+
+1. **One `useTableState` per logical table** — Remount with `key` when the column set or entity context changes.
+2. **Don’t fork filter/sort UX** — Reuse `TablePropertiesDrawer` and `DataTableToolbar` patterns so accessibility and behavior stay consistent.
+3. **Boards derive from the same columns** — `boardColumns` / `hiddenColKeys` should reflect table `displayCols` so “hide column” and “properties” stay in sync.
+4. **Persist stable JSON** — Version objects with `v: 1` and keep keys namespaced to allow migrations later.
+
+---
+
+## Required UX for dense lists (10+ items)
+
+When a page shows a **list**, **table**, or **card grid** with **more than 10 items**, it must expose:
+
+| Capability | Table / list / board | Card-only pages (no `DataTable`) |
+| --- | --- | --- |
+| **Search** | Toolbar search + column quick-search where applicable | At least one search control filtering the visible set |
+| **Filter** | Filter bar + `TablePropertiesDrawer` filters | Filters in toolbar or in Properties, as appropriate to the content |
+| **Sorting** | Column sort / sort rules in drawer | User-visible sort (e.g. name, date, role) |
+| **Properties** | `TablePropertiesDrawer` (columns, display, filters, sort) | A **Properties** entry point (sheet or drawer) for view options — same *role* as table properties, even if the UI is simpler |
+
+Below the threshold, these may be omitted unless the page is a primary data hub (see below).
+
+---
+
+## Data pages: primary CTA + More + Export
+
+If the page **has exportable data** (rows, members, placements, etc.), follow the **Placements** header pattern:
+
+1. **Primary action** — One default (filled) button for the main task (e.g. **New placement**, **Invite member**). Do **not** use `variant="outline"` for that primary action.
+2. **More (⋯)** — An outline **icon** button opening a menu that includes **Export** (and other overflow actions). Wire **Export** to `ExportDrawer` (or equivalent).
+3. **Subtitle** — Prefer a short line with **count + freshness** (e.g. `24 records · Last updated now`), matching `PlacementsPageHeader`.
+
+Reference: `components/placements-page-header.tsx`, `components/team-page-header.tsx`, `components/team-client.tsx`.
+
+---
+
+## Page vs drawer (actions and auxiliary views)
+
+**When to use a drawer or sheet:** The user needs **the surrounding page** (list, hub, or parent task) to stay **visible for context** *and* they need a **quick view**, **quick actions**, or a **short auxiliary step** — e.g. table properties, export, a brief row summary, or “change one setting and dismiss.”
+
+**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**; **otherwise** → **new page**.
+
+Canonical rules: **`AGENTS.md` §6.4**, root **`.cursor/rules/exxat-page-vs-drawer.mdc`**.
+
+---
+
+## Primary pages with large datasets
+
+When a route is a **primary** destination in nav (main hub for an entity) **and** the dataset is **large** or **highly interactive**:
+
+- Use the **primary page template**: `ListPageTemplate` (tabs, metrics strip, export drawer at template level) + data client pattern as in **`DataListClient`** / **`DataListTable`** — not a minimal `PageHeader`-only layout.
+- Smaller satellite pages may use **`PageHeader` + section content**; once the dataset grows past the dense-list threshold, add the toolbar rules above and consider promoting to the full template if the page becomes a main hub.
+
+---
+
+## Summary checklist
+
+- [ ] **Reuse** — Tabs, search, filters, and property UI come from **`ListPageTemplate`**, **`DataTable` / `useTableState`**, **`TablePropertiesDrawer`**, and related Placements modules—not ad-hoc duplicates.
+- [ ] **Table + tabs** — Any **`DataTable`** is wrapped in **`ListPageTemplate`** (view tabs), not only `PageHeader` + body.
+- [ ] **>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 (§6.4)** — Quick actions with parent **context** → drawer/sheet; primary or long flows → **new route**.
+- [ ] **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).
+- [ ] **Mock + KPIs** → Entity rows in **`lib/mock/`**; **`entityKpiMetrics` / `entityKpiInsight`** consumed by template metrics and dashboard view.

package/template/ecosystem.config.cjs

@@ -0,0 +1,20 @@
+/**
+ * PM2 — keep `next dev` running after the terminal closes; restarts on crash.
+ * Start: `nvm use && npm run dev:daemon`
+ * @see README.md — Development (daemon)
+ */
+module.exports = {
+  apps: [
+    {
+      name: "exxat-ds",
+      script: "npm",
+      args: "run dev",
+      cwd: __dirname,
+      interpreter: "none",
+      autorestart: true,
+      max_restarts: 30,
+      min_uptime: "4s",
+      exp_backoff_restart_delay: 2000,
+    },
+  ],
+}

package/template/eslint.config.mjs

@@ -0,0 +1,18 @@
+import { defineConfig, globalIgnores } from "eslint/config";
+import nextVitals from "eslint-config-next/core-web-vitals";
+import nextTs from "eslint-config-next/typescript";
+
+const eslintConfig = defineConfig([
+  ...nextVitals,
+  ...nextTs,
+  // Override default ignores of eslint-config-next.
+  globalIgnores([
+    // Default ignores of eslint-config-next:
+    ".next/**",
+    "out/**",
+    "build/**",
+    "next-env.d.ts",
+  ]),
+]);
+
+export default eslintConfig;