@exxatdesignux/ui 0.5.10 → 0.5.12

package/template-vite/.cursor/skills/exxat-ds-skill/references/data-table-pattern.md

@@ -0,0 +1,392 @@
+# Data Table Pattern — Full Implementation Guide
+
+**Primary hub stack:** `ListPageTemplate` → **`HubTable`** (not raw `DataTable` inside hubs).
+
+**Add view parity:** `FULL_HUB_SUPPORTED_VIEWS` on **`ListPageTemplate`** + **`HubTable`**; implement every allowed view — **`.cursor/rules/exxat-hub-supported-views.mdc`**, **`apps/web/docs/hub-supported-views-pattern.md`**.
+
+**Reference implementations:**
+- `components/library-table.tsx` + `library-client.tsx` — canonical seven-view hub
+- `components/columns-showcase.tsx` — `LibraryTable` + custom `columnDefs`
+- `components/tokens-themes-client.tsx` + `tokens-hub-auxiliary-views.tsx`
+- `components/team-table.tsx`, `components/placements-table.tsx` — entity hubs
+
+---
+
+## Stack Summary
+
+```
+HubTable (inside ListPageTemplate)  ← canonical hub wrapper
+  └── DataTable                     ← base table component
+  └── useTableState                 ← sort/filter/column/group state
+  └── toolbarSlot                   ← properties button + filter chips + search
+        └── TablePropertiesDrawer
+  └── renderListRow / renderers     ← list, board, dashboard, folder, panel, tree
+```
+
+All imports:
+```ts
+import { DataTable } from "@/components/data-table"
+import type { ColumnDef } from "@/components/data-table/types"
+import { useTableState } from "@/components/data-table/use-table-state"
+import { TablePropertiesDrawer } from "@/components/table-properties"
+import type {
+  ConditionalRule,
+  FilterFieldDef,
+  FilterOperator,
+} from "@/components/table-properties/types"
+import {
+  DEFAULT_DATA_LIST_DISPLAY_OPTIONS,
+  type DataListDisplayOptions,
+} from "@/lib/data-list-display-options"
+```
+
+---
+
+## Column Definition Patterns
+
+### Text column with filter
+```ts
+{
+  key: "name",
+  label: "Name",
+  width: 240,
+  minWidth: 160,
+  sortable: true,
+  sortKey: "name",
+  defaultPin: "left",          // pin to left (optional)
+  filter: {
+    type: "text",
+    icon: "fa-user",
+    operators: ["contains", "not_contains"],
+  },
+  cell: row => (
+    <span className="text-sm font-medium text-foreground truncate">{row.name}</span>
+  ),
+}
+```
+
+### Select (enum) column with filter
+```ts
+{
+  key: "status",
+  label: "Status",
+  width: 120,
+  minWidth: 100,
+  sortable: true,
+  sortKey: "status",
+  filter: {
+    type: "select",
+    icon: "fa-circle-dot",
+    operators: ["is", "is_not"],
+    options: [
+      { value: "active", label: "Active" },
+      { value: "inactive", label: "Inactive" },
+    ],
+  },
+  cell: row => (
+    <Badge variant="outline" className={cn("text-[10px] font-medium uppercase tracking-wide", STATUS_BADGE[row.status])}>
+      {STATUS_LABEL[row.status]}
+    </Badge>
+  ),
+}
+```
+
+### Select column (pinned right, no filter)
+```ts
+{
+  key: "select",
+  label: "",
+  width: 40,
+  minWidth: 40,
+  defaultPin: "left",
+  lockPin: true,
+}
+```
+
+### Actions column (pinned right)
+```ts
+{
+  key: "actions",
+  label: "",
+  width: 48,
+  minWidth: 48,
+  defaultPin: "right",
+  lockPin: true,
+  cell: row => (
+    <div className="flex items-center justify-center">
+      <DropdownMenu>
+        <DropdownMenuTrigger asChild>
+          <Button size="icon-sm" variant="ghost" aria-label={`Actions for ${row.name}`}>
+            <i className="fa-light fa-ellipsis text-sm" aria-hidden="true" />
+          </Button>
+        </DropdownMenuTrigger>
+        <DropdownMenuContent align="end" className="w-40">
+          <DropdownMenuItem disabled>
+            <i className="fa-light fa-pen" aria-hidden="true" />
+            Edit
+          </DropdownMenuItem>
+        </DropdownMenuContent>
+      </DropdownMenu>
+    </div>
+  ),
+}
+```
+
+---
+
+## Status Badge Pattern
+
+```ts
+const STATUS_LABEL: Record<MyType["status"], string> = {
+  active: "Active",
+  inactive: "Inactive",
+  pending: "Pending",
+}
+
+const STATUS_BADGE: Record<MyType["status"], string> = {
+  active:   "bg-emerald-500/15 text-emerald-800 dark:text-emerald-200 border-emerald-500/20",
+  inactive: "bg-slate-500/10 text-slate-700 dark:text-slate-200 border-border",
+  pending:  "bg-amber-500/15 text-amber-900 dark:text-amber-100 border-amber-500/20",
+}
+```
+
+---
+
+## Filter Field Derivation
+
+Convert column defs to filter field defs for the drawer:
+
+```ts
+function columnToFilterFieldDef(c: ColumnDef<T>): FilterFieldDef | null {
+  if (!c.filter) return null
+  const f = c.filter
+  const defaultOps: FilterOperator[] =
+    f.type === "select" || f.type === "date" ? ["is", "is_not"] : ["contains", "not_contains"]
+  return {
+    key: c.key,
+    label: c.label,
+    icon: f.icon ?? "fa-filter",
+    type: f.type,
+    operators: (f.operators ?? defaultOps) as FilterOperator[],
+    options: f.options,
+  }
+}
+```
+
+---
+
+## Drawer Toolbar Component
+
+The `toolbarSlot` renders the Properties button and the drawer. Full pattern:
+
+```tsx
+function FooDrawerToolbar({ state, totalRows, filterFields, fieldDefinitionsForDrawer, resolveColumnLabel, displayOptions, onDisplayOptionsChange, conditionalRules, onAddConditionalRule, onRemoveConditionalRule, onUpdateConditionalRule }) {
+  const { sheetOpen, setSheetOpen, showGridlines, setShowGridlines, rowHeight, setRowHeight,
+    activeFilters, addFilter, updateFilter, removeFilter, getConnector, toggleConnector,
+    filterBarVisible, setFilterBarVisible, drawerExpandedFilters, setDrawerExpandedFilters,
+    rows, sortRules, setSortRules, addSortRule, removeSortRule, toggleSortDir,
+    colOrder, setColOrder, hiddenCols, toggleColVisibility, moveCol, groupBy, setGroupBy, sortKey,
+  } = state
+
+  return (
+    <>
+      <TooltipProvider>
+        <Tooltip>
+          <TooltipTrigger asChild>
+            <Button
+              type="button" variant="ghost" size="icon-sm" aria-label="Properties"
+              onClick={() => setSheetOpen(true)}
+              className={cn(sheetOpen ? "bg-accent text-accent-foreground" : "text-muted-foreground hover:text-interactive-hover-foreground hover:bg-interactive-hover")}
+            >
+              <i className="fa-light fa-sliders text-[13px]" aria-hidden="true" />
+            </Button>
+          </TooltipTrigger>
+          <TooltipContent side="bottom">Properties</TooltipContent>
+        </Tooltip>
+      </TooltipProvider>
+
+      <TablePropertiesDrawer
+        open={sheetOpen} onOpenChange={setSheetOpen}
+        showGridlines={showGridlines} onShowGridlinesChange={setShowGridlines}
+        rowHeight={rowHeight} onRowHeightChange={setRowHeight}
+        pagination={false} onPaginationChange={() => {}}
+        activeFilters={activeFilters} onAddFilter={k => addFilter(k, true)}
+        onUpdateFilter={updateFilter} onRemoveFilter={removeFilter}
+        getFilterConnector={getConnector} onToggleFilterConnector={toggleConnector}
+        filterBarVisible={filterBarVisible} onFilterBarVisibleChange={setFilterBarVisible}
+        drawerExpandedFilters={drawerExpandedFilters} onDrawerExpandedFiltersChange={setDrawerExpandedFilters}
+        totalRows={totalRows} filteredRows={rows.length}
+        sortRules={sortRules} onSortRulesChange={setSortRules}
+        onAddSortRule={addSortRule} onRemoveSortRule={removeSortRule} onToggleSortDir={toggleSortDir}
+        colOrder={colOrder} onColOrderChange={setColOrder}
+        hiddenCols={hiddenCols} onToggleColVisibility={toggleColVisibility} onMoveCol={moveCol}
+        groupBy={groupBy} onGroupByChange={setGroupBy} primarySortKey={sortKey}
+        conditionalRules={conditionalRules}
+        onAddConditionalRule={onAddConditionalRule}
+        onRemoveConditionalRule={onRemoveConditionalRule}
+        onUpdateConditionalRule={onUpdateConditionalRule}
+        filterFields={filterFields}
+        lifecycleTabLabel="Foo"      // ← change to entity name
+        fieldDefinitions={fieldDefinitionsForDrawer}
+        resolveColumnLabel={resolveColumnLabel}
+        displayOptions={displayOptions}
+        onDisplayOptionsChange={onDisplayOptionsChange}
+      />
+    </>
+  )
+}
+```
+
+---
+
+## Full Table Component Skeleton
+
+```tsx
+"use client"
+
+import * as React from "react"
+// ... all imports above
+
+export interface FooTableHandle {
+  openPropertiesDrawer: () => void
+}
+
+export const FooTable = React.forwardRef<FooTableHandle, { items: Foo[] }>(
+  function FooTable({ items }, ref) {
+    const columns = React.useMemo(() => buildFooColumns(), [])
+    const filterFields = React.useMemo(() => columnsToFilterFields(columns), [columns])
+    const fieldDefinitionsForDrawer = React.useMemo(
+      () => columns.filter(c => c.key !== "select" && c.key !== "actions")
+                   .map(c => ({ key: c.key, label: c.label, sortable: !!(c.sortable && (c.sortKey ?? c.key)) })),
+      [columns],
+    )
+    const resolveColumnLabel = React.useCallback((key: string) => columns.find(c => c.key === key)?.label ?? key, [columns])
+
+    const [displayOptions, setDisplayOptions] = React.useState<DataListDisplayOptions>(DEFAULT_DATA_LIST_DISPLAY_OPTIONS)
+    const patchDisplay = React.useCallback((patch: Partial<DataListDisplayOptions>) => setDisplayOptions(prev => ({ ...prev, ...patch })), [])
+
+    const [conditionalRules, setConditionalRules] = React.useState<ConditionalRule[]>([])
+    const addConditionalRule = React.useCallback((rule: Omit<ConditionalRule, "id">) => setConditionalRules(prev => [...prev, { ...rule, id: `cr-${Date.now()}` }]), [])
+    const removeConditionalRule = React.useCallback((id: string) => setConditionalRules(prev => prev.filter(r => r.id !== id)), [])
+    const updateConditionalRule = React.useCallback((id: string, patch: Partial<ConditionalRule>) => setConditionalRules(prev => prev.map(r => r.id === id ? { ...r, ...patch } : r)), [])
+
+    const tableState = useTableState(items, columns, { key: "name", dir: "asc" })
+
+    React.useImperativeHandle(ref, () => ({
+      openPropertiesDrawer: () => tableState.setSheetOpen(true),
+    }), [tableState.setSheetOpen])
+
+    return (
+      <div className="pb-6">
+        <DataTable<Foo>
+          data={items}
+          columns={columns}
+          getRowId={row => row.id}
+          getRowSelectionLabel={row => row.name}
+          selectable
+          searchable={displayOptions.showToolbarSearch}
+          showColumnHeaders={displayOptions.showColumnLabels}
+          groupable
+          defaultSort={{ key: "name", dir: "asc" as const }}
+          emptyState={<p className="text-sm text-muted-foreground">No items found.</p>}
+          conditionalRules={conditionalRules}
+          state={tableState}
+          toolbarSlot={s => (
+            <FooDrawerToolbar
+              state={s} totalRows={items.length} filterFields={filterFields}
+              fieldDefinitionsForDrawer={fieldDefinitionsForDrawer} resolveColumnLabel={resolveColumnLabel}
+              displayOptions={displayOptions} onDisplayOptionsChange={patchDisplay}
+              conditionalRules={conditionalRules} onAddConditionalRule={addConditionalRule}
+              onRemoveConditionalRule={removeConditionalRule} onUpdateConditionalRule={updateConditionalRule}
+            />
+          )}
+          bulkActionsSlot={selected => {
+            if (selected.size === 0) return null
+            return (
+              <>
+                <span className="sr-only">{selected.size} selected</span>
+                <Tip label="Export selection (demo)">
+                  <Button size="sm" variant="outline" type="button">
+                    <i className="fa-light fa-arrow-down-to-line" aria-hidden="true" />
+                    Export
+                  </Button>
+                </Tip>
+              </>
+            )
+          }}
+        />
+      </div>
+    )
+  }
+)
+
+FooTable.displayName = "FooTable"
+```
+
+---
+
+## ListPageTemplate Client Skeleton
+
+```tsx
+"use client"
+
+import * as React from "react"
+import { ListPageTemplate, type ViewTab } from "@/components/templates/list-page"
+import { FooPageHeader } from "@/components/foo-page-header"
+import { FooTable, type FooTableHandle } from "@/components/foo-table"
+import { KeyMetrics } from "@/components/key-metrics"
+import { FOO_ITEMS } from "@/lib/mock/foo"
+import { fooKpiInsight, fooKpiMetrics } from "@/lib/mock/foo-kpi"
+import { dataListViewIcon } from "@/lib/data-list-view"
+import { Button } from "@/components/ui/button"
+
+const DEFAULT_TABS: ViewTab[] = [
+  { id: "all", label: "All Foos", viewType: "table", icon: "fa-table", filterId: "all" },
+]
+
+export function FooClient() {
+  const [exportOpen, setExportOpen] = React.useState(false)
+  const [showMetrics, setShowMetrics] = React.useState(true)
+  const tableRef = React.useRef<FooTableHandle>(null)
+
+  const metrics = React.useMemo(() => fooKpiMetrics(FOO_ITEMS), [])
+  const insight = React.useMemo(() => fooKpiInsight(FOO_ITEMS), [])
+
+  return (
+    <ListPageTemplate
+      defaultTabs={DEFAULT_TABS}
+      getTabCount={() => FOO_ITEMS.length}
+      onEditView={(tab, { updateTab }) => {
+        const mustSwitch = tab.viewType !== "table" && tab.viewType !== "list" && tab.viewType !== "board"
+        if (mustSwitch) updateTab({ viewType: "table", icon: dataListViewIcon("table") })
+        window.setTimeout(() => tableRef.current?.openPropertiesDrawer(), mustSwitch ? 160 : 0)
+      }}
+      header={
+        <FooPageHeader
+          itemCount={FOO_ITEMS.length}
+          onAdd={() => {}}
+          onExport={() => setExportOpen(true)}
+          showMetrics={showMetrics}
+          onToggleMetrics={() => setShowMetrics(v => !v)}
+        />
+      }
+      metrics={<KeyMetrics variant="flat" metrics={metrics} insight={insight} showHeader={false} metricsSingleRow />}
+      showMetrics={showMetrics}
+      exportOpen={exportOpen}
+      onExportOpenChange={setExportOpen}
+      exportTotalRows={FOO_ITEMS.length}
+      renderContent={(tab, updateTab) => {
+        if (tab.viewType === "table") return <FooTable key={tab.id} ref={tableRef} items={FOO_ITEMS} />
+        return (
+          <div className="px-4 py-12 text-center lg:px-6">
+            <p className="text-sm font-medium text-foreground">{tab.viewType === "list" ? "List" : "Board"} view is not wired in this demo.</p>
+            <Button type="button" className="mt-4" size="sm" onClick={() => updateTab({ viewType: "table", icon: dataListViewIcon("table") })}>
+              Switch to table
+            </Button>
+          </div>
+        )
+      }}
+    />
+  )
+}
+```

package/template-vite/.cursor/skills/exxat-fontawesome-icons/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: exxat-fontawesome-icons
+description: Font Awesome Pro in Exxat DS — Kit script, fa-light/fa-solid, subset audit (fa:subset-audit), aria-hidden on decorative icons, no parallel icon libraries for product chrome. Use when adding or changing icons, nav glyphs, table toolbar icons, or debugging missing kit glyphs.
+user-invocable: true
+---
+
+# Exxat DS — Font Awesome icons
+
+**Cursor rule:** `.cursor/rules/exxat-fontawesome-icons.mdc`  
+**Handbook:** `apps/web/AGENTS.md` §1 (item 8), §8 accessibility for icon-only / informational cases.
+
+## Stack
+
+- **Kit:** `apps/web/app/layout.tsx` loads the Font Awesome Pro kit (subset via `fontawesome-subset.manifest.json`).
+- **Audit:** `pnpm --filter web fa:subset-audit` — refresh kit icon selection when adding new glyph names.
+
+## MUST
+
+1. **`<i className="fa-light fa-…" aria-hidden="true" />`** when a parent provides the accessible name (`Button` + `aria-label`, `Tip`, adjacent visible text).
+2. **`fa-light`** for default; **`fa-solid`** for active/selected where the app already does (sidebar rows, tabs).
+3. **Static** `className` strings where possible so the audit script can find class names.
+
+## MUST NOT
+
+- Introduce a **second** icon library for the same surfaces (duplicate Lucide/Heroicons for nav, hubs, toolbars).
+- Put the **only** accessible name on `<i>` without parent labelling — see **exxat-accessibility** Case B/C.
+
+## See also
+
+- `.cursor/rules/exxat-accessibility.mdc`
+- `.cursor/skills/exxat-accessibility/SKILL.md`

package/template-vite/.cursor/skills/exxat-kpi-flat-band/SKILL.md

@@ -0,0 +1,38 @@
+---
+name: exxat-kpi-flat-band
+description: KeyMetrics variant flat — transparent KPI strip, OKLCH brand glow only, cell-border hairlines (no grid surface). Use when wiring ListPageTemplate metrics, dashboard mix KPIs, or fixing flat band looking like a grey box.
+user-invocable: true
+---
+
+# Exxat DS — KPI flat band
+
+**Rule:** `.cursor/rules/exxat-kpi-flat-band.mdc`  
+**Doc:** `apps/web/docs/kpi-flat-band-pattern.md`
+
+## Checklist
+
+- [ ] `variant="flat"` on hub / mix view — not `card` for list-page strip.
+- [ ] `flatBandStyle` = **only** `var(--key-metrics-flat-band-radial)`; shadow **`none`**.
+- [ ] No `--key-metrics-flat-band-linear` in component or hub inline `style`.
+- [ ] Cells **`bg-transparent`**; grid uses **`flatMetricsHairlineClass(count, halfLayout)`** — borders only, **no** `gap-px` fill.
+- [ ] **4 KPIs:** verticals between 1|2|3|4 when wide; 2×2 dividers only below `@[max-width:29.99rem]` container.
+- [ ] Divider + glow tokens stay **OKLCH** (`--key-metrics-flat-divider`, `color-mix(in oklch, var(--brand-color) …)`).
+- [ ] **≤ 4** `MetricItem` — `docs/kpi-strip-max-four-pattern.md`.
+- [ ] KPI helpers use **`tableState.rows`** on connected hubs.
+
+## MUST NOT
+
+- Grey/lavender **panel** behind metrics (removed linear wash + gap fill).
+- Duplicate KPI **`Card`** wall for same numbers.
+- Mute product suffix to grey in dark (`mutedSuffix` does **not** change `wordmarkColor`).
+
+## Code pointers
+
+- `apps/web/components/key-metrics.tsx` — `flatMetricsHairlineClass`, `flatBandStyle`
+- `apps/web/app/globals.css` — `--key-metrics-flat-*`
+- `library-client.tsx`, `dashboard-tabs.tsx` — reference usage
+
+## Pair with
+
+- `exxat-kpi-max-four`, `exxat-kpi-trends`, `exxat-list-page-connected-views`
+- `docs/shell-surface-elevation-pattern.md` — sidebar vs page (not the KPI band)

package/template-vite/.cursor/skills/exxat-kpi-max-four/SKILL.md

@@ -0,0 +1,19 @@
+# Exxat DS — KPI strip (max four)
+
+Use when building **`KeyMetrics`** on **`ListPageTemplate`** or **Data tab** key-metrics cards.
+
+## Read first
+
+- **`docs/kpi-strip-max-four-pattern.md`**
+- **`lib/dashboard-layout-merge.ts`** — `KEY_METRICS_KPI_COUNT_MAX`, `clampKeyMetricsKpiCount`
+- **`.cursor/rules/exxat-kpi-max-four.mdc`**
+
+## Checklist
+
+1. **`entityKpiMetrics`** returns **at most four** `MetricItem` for those surfaces (or `.slice(0, 4)` after priority sort).
+2. **Extra metrics** → `MetricInsight` description, a chart, or another card — not a fifth tile.
+3. **Dashboard persistence** — Respect clamped `keyMetricsKpiCount` (1–4); never bump max without design approval.
+
+## Related
+
+- **`docs/kpi-trend-pattern.md`** — deltas and `trendPolarity`.

package/template-vite/.cursor/skills/exxat-kpi-trends/SKILL.md

@@ -0,0 +1,29 @@
+# Exxat DS — KPI trend arrows and polarity
+
+Use when adding or reviewing **`KeyMetrics`**, **`lib/mock/*-kpi.ts`** helpers, or **`ChartCard`** **`miniMetrics`** / **`kpi-chart`** trends.
+
+## Authoritative references
+
+- **`apps/web/docs/kpi-trend-pattern.md`** — product table + psychometrics example (PBI).
+- **`.cursor/rules/exxat-kpi-trends.mdc`** — binding MUST/MUST NOT.
+- **`apps/web/components/key-metrics.tsx`** — `MetricTrendPolarity`, `metricTrendTone`, `metricTrendAriaQualifier`, `MetricCell` rendering.
+
+## Checklist (new or changed KPI)
+
+1. **Delta honest?** `trend` follows the sign of the change vs the comparison period.
+2. **Polarity correct?** If “more” is bad → **`trendPolarity: "lower_is_better"`**. If no value judgment → **`"informational"`** (muted tints).
+3. **Delta is a count, not prose.** **`delta`** is `"+5"`, `"-3"`, `"+12%"`. Captions like `"left + right"`, `"vs last week"`, `"scheduled for removal"` go in **`description`** (renders **below** the value, muted).
+4. **No empty `—` chip.** If there’s no direction *and* no count, leave **`delta: ""`** + **`trend: "neutral"`** — **`KeyMetrics`** hides the chip. Don’t hand-roll a placeholder.
+5. **Copy contextual?** Label + value + (delta when present) + description tell users *what* moved, not only *how much*.
+6. **Screen readers** — Chip keeps icon + visible delta; `aria-label` reflects favorable / unfavorable wording automatically when polarity is set.
+7. **Chart cards** — When using **`ChartCard`** `miniMetrics`, pass **`trendPolarity`** the same way as on **`MetricItem`**.
+
+## Quick examples
+
+| Metric | More is… | `trendPolarity` |
+| --- | --- | --- |
+| Total placements | Better (capacity) | default / `higher_is_better` |
+| Pass rate | Better | `higher_is_better` |
+| Open incidents | Worse | `lower_is_better` |
+| Low PBI / review flags | Worse | `lower_is_better` |
+| Items by type (mix %) | Neutral | `informational` |

package/template-vite/.cursor/skills/exxat-list-page-view-shells/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: exxat-list-page-view-shells
+description: >-
+  Centered, reusable layout for ListPageTemplate view bodies — ListPageViewFrame,
+  data-views/ primitives, and rules to avoid page-tied view markup. Use when adding
+  folder/panel/custom views, fixing wide-viewport layout, or extracting view UI from a single hub.
+---
+
+# List-page view shells (Exxat DS)
+
+## When to use this skill
+
+- Adding or changing **`viewType`** surfaces: **folder**, **panel**, list/board chrome, icon grids, OS-style explorers.
+- User or PR asks for **“centered”**, **“reusable view”**, or **“not tied to one page”** layout.
+- You see **duplicated** `mx-4 lg:mx-6`, `mx-auto max-w-6xl`, or similar wrappers in multiple `*-table.tsx` files.
+
+## Instructions
+
+1. **Gutter + optional max width** — Import **`ListPageViewFrame`** from **`@/components/data-views/list-page-view-frame`** (or **`@/components/data-views`**). Wrap the view body (usually below **`DataTableToolbar`** when the view shares the table toolbar).
+   - Pass **`maxWidthClassName={LIST_PAGE_VIEW_FRAME_MAX_ICON_GRID}`** for dense tile grids.
+   - Pass **`maxWidthClassName={LIST_PAGE_VIEW_FRAME_MAX_WIDE}`** when the view includes toolbar rows + breadcrumbs + grid.
+2. **Do not double-gutter** — If **`DataTable`** already provides horizontal inset for the **table** view, do **not** wrap that branch in **`ListPageViewFrame`**. Use the frame on **sibling** view branches (folder, panel, etc.) only.
+3. **Reuse before inventing** — Prefer **`FolderGridView`**, **`FinderPanelView`**, **`ListPageBoardTemplate`**, **`ListPageViewFrame`**. If a new pattern appears twice, **promote** it to **`components/data-views/`** with domain-agnostic props.
+4. **Entity-specific → generic** — If logic is “any tree + any row type”, build **`components/data-views/<generic-name>.tsx`** and keep **`library-*`** (or similar) as a thin composition + mock types.
+
+## Checklist
+
+- [ ] View body uses **`ListPageViewFrame`** (or a component that uses it internally, e.g. **`FolderGridView`**).
+- [ ] No **extra** horizontal padding around **`DataTable`** vs **`AGENTS.md` §5**.
+- [ ] New grid/shell lives under **`components/data-views/`** when a second hub could reuse it.
+
+## References
+
+- **`apps/web/components/data-views/list-page-view-frame.tsx`** — implementation + exported constants.
+- **`apps/web/AGENTS.md` §4.5** — MUST/MUST NOT.
+- **`.cursor/rules/exxat-list-page-view-shells.mdc`**.

package/template-vite/.cursor/skills/exxat-mono-ids/SKILL.md

@@ -0,0 +1,56 @@
+---
+name: exxat-mono-ids
+description: Monospace typography for Exxat DS record IDs, question IDs, and system identifiers — font-mono tabular-nums, mixed subtitle lines, table meta. Use when adding or changing questionId, record id columns, header subtitles with IDs, or any copy-pasteable system key in apps/web UI.
+user-invocable: true
+---
+
+# Exxat DS — monospace IDs
+
+**Cursor rule:** `.cursor/rules/exxat-mono-ids.mdc`  
+**Handbook:** `apps/web/AGENTS.md` (§1, §13 checklist)
+
+## Standard classes
+
+```tsx
+// Default secondary ID (table meta, list subline, inspector)
+<span className="font-mono tabular-nums text-xs text-muted-foreground">{id}</span>
+
+// ID in a page subtitle next to sans prose
+<>
+  <span className="font-mono tabular-nums">{questionId}</span>
+  {" · V1 · Last updated just now"}
+</>
+```
+
+Always include **`tabular-nums`** with **`font-mono`** so fixed-width digits align in tables and subtitles.
+
+## MUST
+
+1. **Every visible system ID** in product UI uses **`font-mono tabular-nums`** (plus contextual size/color).
+2. **Mixed lines** — mono only on the identifier substring, not the whole sentence.
+3. **Tables / lists / boards** — ID column or subline under a title: mono + usually **`text-xs text-muted-foreground`**.
+
+## MUST NOT
+
+- Mono on **display names**, **emails** (unless the column is explicitly “Principal ID”), **dates**, **KPI values**, or **status text**.
+- Mono on **UI chrome** that is not an identifier (badges, buttons, nav labels).
+
+## Reference implementations
+
+| Surface | File |
+|---------|------|
+| Library table | `components/library-table.tsx` — `row.questionId` |
+| Library list | `components/library-list-view.tsx` |
+| New question subtitle | `components/new-library-item-form.tsx` — `questionId` in `PageHeader` subtitle |
+| Sites record id | `components/sites-table.tsx` — `row.id` |
+| OS folder tiles | `components/library-os-folder-view.tsx` |
+
+## Review checklist
+
+- [ ] New or changed **ID** fields use **`font-mono tabular-nums`**.
+- [ ] Subtitle / description lines mono-wrap **only** the ID token.
+- [ ] No mono applied to names, statuses, or numeric metrics that are not identifiers.
+
+## See also
+
+- `.cursor/rules/exxat-person-identity-display.mdc` — name + email (sans, not mono for email unless ID column)

package/template-vite/.cursor/skills/exxat-primary-nav-secondary-panel/SKILL.md

@@ -0,0 +1,49 @@
+---
+name: exxat-primary-nav-secondary-panel
+description: Exxat DS pattern — one primary sidebar row opens a nested SecondaryPanel (Library). NavLinkItem.secondaryPanel id, PANELS registry, useAutoPanel on hub, URL scope + same useTableState rows. Use when adding hub scoped nav (All/My/tree) beside content.
+user-invocable: true
+---
+
+# Exxat DS — primary nav → secondary panel
+
+**Cursor rule:** `.cursor/rules/exxat-primary-nav-secondary-panel.mdc`  
+**Handbook:** `apps/web/AGENTS.md` §4.6
+
+## Wiring checklist
+
+1. **`lib/mock/navigation.tsx`** — set **`secondaryPanel: "<id>"`** on the primary **`NavLinkItem`**; **`url`** = hub route.
+2. **`components/secondary-panel.tsx`** — add **`PANELS["<id>"]`** → panel shell (title, optional search) + secondary nav component.
+3. **Hub client** — mount **`*PanelActivator`** with **`useAutoPanel("<id>")`** (same id) for the lifetime of the route (e.g. `LibraryPanelActivator`).
+4. **Data** — keep **one** **`useTableState`** / **`tableState.rows`**; drive scope from **URL** + small helpers (see **`lib/library-nav.ts`**).
+5. **Folder-scoped hub header (Library library)** — When **`scope === "folder"`** in the URL, **`LibraryPageHeader`** **⋯ More** includes **Customize folder**; mount **`LibraryNewFolderSheet`** on **`LibraryClient`** so it works on **all** **`ListPageTemplate`** view tabs — **`.cursor/rules/exxat-library-hub-header.mdc`**, **`docs/library-hub-header-pattern.md`**.
+6. **Collapse control** — the nested rail header uses **`collapseActiveSecondaryPanel()`** (angles-left icon), not “close”, so the panel stays dismissed until **`openPanel`** runs again (nav, scope hook, or hub re-entry). Layout effects that auto-call **`openPanel`** must respect **`secondaryPanelAutoReopenSuppressed`** (see **`app/(app)/library/layout.tsx`** + **`SecondaryPanelProvider`**).
+7. **Surface elevation** — secondary panel = **level 1** (lighter than sidebar, darker than page). Use **`--secondary-panel-bg`** on **`NestedSecondaryPanelShell`**; derive from **`--brand-tint*`** per active product (**One** indigo, **Prism** rose). See **`docs/shell-surface-elevation-pattern.md`**.
+
+## MUST NOT
+
+- Set **`secondaryPanel`** without **`PANELS[id]`** + **`useAutoPanel`** — broken empty rail.
+- Use this for full product areas that belong as **primary** or **collapsible child** rows.
+- Invent a parallel zoom / reflow hook for the secondary rail — reuse **`useSidebarReflowZoom`** (the provider already wires it; see §"High-zoom auto-collapse" below).
+- Set secondary panel **`bg-sidebar`** or a fixed rose mix for every product — breaks **One** indigo chrome.
+
+## High-zoom auto-collapse
+
+`SecondaryPanelProvider` reads **`useSidebarReflowZoom()`** (zoom ≥ 200% or very short viewport — same WCAG 1.4.10 signal the primary sidebar uses). On entering high zoom it sets `secondaryPanelCompact = true` so the 16 rem rail drops to the 3 rem icon variant and frees up content space. The user can still re-expand manually (via the icon rail's "Show labels" affordance or any `openPanel` trigger); the next zoom-out → zoom-in cycle re-collapses it. `openPanel` itself opens directly in compact mode when high zoom is already active so newly-navigated panels don't flash expanded.
+
+Custom panel content (anything you register under `PANELS[id]`) should **read `secondaryPanelCompact` from the provider context** and render an icon-only layout in that branch — `LibraryPanel` / `LibrarySecondaryNav` are the reference.
+
+## Pair with
+
+- **Collapsible parent ↔ children sidebar pattern** (§3.2 of `exxat-ds-skill`) — when the same primary row also lists sub-routes inline.
+
+## Reference
+
+- `components/app-sidebar.tsx` — `openPanel` on same-route primary click.
+- `components/secondary-panel.tsx` — `SecondaryPanelProvider`, `PANELS` registry, **high-zoom auto-collapse**.
+- `hooks/use-sidebar-reflow-zoom.ts` — shared zoom / reflow signal.
+- `components/templates/nested-secondary-panel-shell.tsx` — expanded vs `compact` (icon rail) widths; **`bg-[var(--secondary-panel-bg)]`**.
+- `app/globals.css` — `--secondary-panel-bg`, `--sidebar`, product **`theme-one`** / **`theme-prism`** blocks.
+- `contexts/product-context.tsx` — `accentOverrideActive`, theme class on `<html>`.
+- **`docs/shell-surface-elevation-pattern.md`**
+- `components/library-secondary-nav.tsx` + `lib/library-nav.ts`.
+- **Folder-scoped header customize:** `components/library-page-header.tsx`, `components/library-client.tsx` — **`docs/library-hub-header-pattern.md`**, **`.cursor/rules/exxat-library-hub-header.mdc`**.