@exxatdesignux/ui 0.5.11 → 0.5.13

package/template/docs/blueprints/_template.md

@@ -1,91 +0,0 @@
-# Blueprint: <Name>
-
-> **Status:** Draft / Stable. **Owner:** <team or person>. **Implements:** <SC refs>.
-
-## 1. Intent
-
-What user need does this pattern solve? In one paragraph.
-
-**Use when:**
-- Bullet
-- Bullet
-
-**Do NOT use when:**
-- Bullet
-
-## 2. Anatomy
-
-ASCII / markdown sketch with labelled slots. List every named slot and whether
-it is required, optional, or conditional.
-
-```
-┌──────────────────────────────────────────┐
-│ [icon]  Title                  [actions] │  ← slot: title-row (required)
-│ ───────────────────────────────────────  │
-│ subtitle · ID · meta                     │  ← slot: meta (optional)
-└──────────────────────────────────────────┘
-```
-
-| Slot | Required? | What it carries |
-|---|---|---|
-| `title` | required | Single H1 string |
-| `icon` | optional | FA glyph or product mark |
-| `actions` | optional | Primary CTA + optional `⋯` overflow |
-| `meta` | optional | Count · freshness · sort summary |
-
-## 3. States
-
-| State | Visual / behavior |
-|---|---|
-| Default | … |
-| Loading | … |
-| Empty | … |
-| Error | … |
-| RTL | … |
-
-## 4. Tokens consumed
-
-List every token the blueprint references from
-[`docs/token-taxonomy.md`](../token-taxonomy.md). Be precise — no "a brand
-color"; name `--brand-color`.
-
-| Token | Used for |
-|---|---|
-| `--background` / `--foreground` | Surface + ink |
-| … | … |
-
-## 5. Accessibility
-
-| WCAG SC | How this blueprint complies |
-|---|---|
-| 1.1.1 Non-text content | Icons are decorative (Case A) when adjacent to text; standalone icons follow Case B (label + tooltip) |
-| 1.3.1 Info & relationships | … |
-| 2.1.1 Keyboard | Tab order: … |
-| 2.4.6 Headings / labels | The title slot is the `<h1>` for the route |
-| 2.4.11 Focus visible | Inherits `:focus-visible` ring (≥ 3:1) |
-
-## 6. Variants
-
-| Variant | When to use | Differences from default |
-|---|---|---|
-| `base` | … | — |
-
-## 7. Implementation
-
-| Framework | Component(s) | File |
-|---|---|---|
-| **React (this app)** | `PrimaryComponent` + `RelatedComponent` | `apps/web/components/<file>.tsx` |
-| Mobile | — | — |
-| Figma | — | — |
-
-## 8. Do / Don't
-
-| ✅ Do | ❌ Don't |
-|---|---|
-| Bullet | Bullet |
-
-## 9. References
-
-- `apps/web/docs/<related-narrative>.md`
-- `.cursor/rules/<related-rule>.mdc`
-- `apps/web/AGENTS.md` §<section>

package/template/docs/blueprints/board-card.md

@@ -1,123 +0,0 @@
-# Blueprint: Board card
-
-> **Status:** Stable. **Owner:** Design system. **Implements:** SC 1.1.1, 1.3.1, 2.5.8, 4.1.2.
-
-## 1. Intent
-
-A **board card** is the kanban-tile presentation of a single hub record (e.g.
-one Placement, one Team member, one Question-bank item) when the active view
-is `board`. The card surfaces the most-scannable summary fields — title, owner
-avatar, status chip, 1-3 meta lines — and is sized so a column holds 6-10
-cards on a 1280-wide viewport.
-
-**Use when:**
-
-- The hub's `board` view tab is active.
-- The record has a **status** (or equivalent grouping) that drives column placement.
-- Users compare ~6-30 records side-by-side and would benefit from owner / status visibility.
-
-**Do NOT use when:**
-
-- The record needs ≥ 4 fields to be useful at a glance (use list / table).
-- The dataset has > ~100 records per column (board UX collapses; use table + filters).
-- The hub does not model status / lifecycle (use folder grid or list).
-
-## 2. Anatomy
-
-```
-┌──────────────────────────────────────────────┐
-│  Title row                       [avatar]    │  ← slot: title (required) + trailing (optional)
-│ ──────────────────────────────────────────── │
-│  [status chip]                               │  ← slot: badgeRow (optional, when status exists)
-│ ──────────────────────────────────────────── │
-│  Body — primary stat (large) + sub label     │  ← slot: body (optional)
-│  ▣ row icon · meta label · meta value        │
-│  ▣ row icon · meta label · meta value        │
-└──────────────────────────────────────────────┘
-```
-
-| Slot | Required? | What it carries |
-|---|---|---|
-| `title` | required | `ListPageBoardCardTitleRow` — single-line truncated title |
-| `trailing` | optional | `ListPageBoardCardAvatar` (owner) or another single glyph |
-| `badgeRow` | optional | `ListPageBoardCardBadgeRow` + `ListHubStatusBadge surface="board"` |
-| `body` | optional | `ListPageBoardCardBody` containing `BoardCardTwoLineBlock` / `BoardCardIconRow` |
-| `footer` | optional | Counts, freshness, or a small CTA — kept low-emphasis |
-
-The shell is `ListPageBoardCard` (`Card size="sm"` treatment) — do NOT compose
-a bespoke `<button>` + border-class wrapper for the same pattern.
-
-## 3. States
-
-| State | Visual / behavior |
-|---|---|
-| Default | Surface 2 background, hairline border, no shadow |
-| Hover | Border deepens; subtle elevation shift (matches `Card size="sm"`) |
-| Focused | `:focus-visible` ring on the outer element (≥ 3:1) |
-| Selected (drag source / active drag target) | `data-selected` border + brand tint |
-| Loading | Skeleton shell mirroring title row + badge row + body |
-| Empty column | Column footer shows "+ Add" affordance with `aria-label` per column |
-| RTL | All trailing slots flip; status chip flips alignment |
-
-## 4. Tokens consumed
-
-| Token | Used for |
-|---|---|
-| `--exxat-color-surface-2` / `--card` | Card background |
-| `--exxat-color-border-1` / `--border` | Card hairline |
-| `--exxat-color-ink-1` / `--foreground` | Title text |
-| `--exxat-color-ink-2` / `--muted-foreground` | Meta label text |
-| `--exxat-color-focus-ring` / `--ring` | `:focus-visible` ring |
-| `--exxat-radius-2` / `--radius-md` | Card corners |
-| Status-tint variables (`LIST_HUB_STATUS_TINT_*`) | Status chip background + text |
-
-## 5. Accessibility
-
-| WCAG SC | How this blueprint complies |
-|---|---|
-| 1.1.1 Non-text content | Icons in `BoardCardIconRow` are decorative when paired with a visible label (Case A); standalone glyphs get Case B label + tooltip |
-| 1.3.1 Info & relationships | The card is one `<article>` (or `role="listitem"` inside the column's `role="list"`); status, owner, and meta rows are programmatically related to the title |
-| 2.5.8 Target size | The whole card is the primary click target — ≥ 24×24 CSS px; small icon controls inside use `size-6` (≥ 24px) |
-| 4.1.2 Name / role / value | If the card is interactive (opens detail) it is rendered as `<button>` with an accessible name combining title + status |
-
-## 6. Variants
-
-| Variant | When to use | Differences from default |
-|---|---|---|
-| `base` | Most hubs | Title + status badge + body |
-| `no-status` | Hubs without lifecycle (Library items) | Omit `badgeRow`; body carries the differentiator |
-| `compact` | Dense boards (10+ cards visible) | Drop body; show title + status + avatar only |
-| `with-progress` | Workflow boards with completion bar | Add a `<Progress>` row in the body slot |
-
-## 6.1 List-row counterpart
-
-`ListPageBoardCard layout="row"` is the same component shape rendered as a
-horizontal row for the `list` view tab. Use one renderer for both views so the
-**title / status / owner / meta** mapping stays consistent — never define two
-parallel components for "card" and "row" of the same hub.
-
-## 7. Implementation
-
-| Framework | Component(s) | File |
-|---|---|---|
-| **React (this app)** | `ListPageBoardCard` + `ListPageBoardCardTitleRow` + `ListPageBoardCardBadgeRow` + `ListPageBoardCardBody` + `BoardCardTwoLineBlock` + `BoardCardIconRow` + `ListHubStatusBadge` | `@exxatdesignux/ui/components/data-views` + `apps/web/lib/list-status-badges.ts` |
-| Board template | `ListPageBoardTemplate` (column shells + `renderCard`) | `@exxatdesignux/ui/components/data-views/list-page-board-template` |
-| Mobile | — | — |
-| Figma | "Board card – hub" component in DS library | — |
-
-## 8. Do / Don't
-
-| ✅ Do | ❌ Don't |
-|---|---|
-| Use `ListPageBoardCard` as the shell; compose primitives inside | Wrap a bespoke `<button>` with border / padding utility classes for the same pattern |
-| Status: `ListHubStatusBadge surface="board"` + entity-specific map from `lib/list-status-badges.ts` | Show status as plain body text when the hub uses `ListHubStatusBadge` elsewhere |
-| Pull rows from `tableState.rows` so board honors filters / search | Hydrate cards from a separate `BOARD_MOCK[]` array |
-| Match list-row + table-row + card field choices via one mapper per hub | Define a card-only field projection that diverges from the table |
-| Use `Tip` on any icon-only control inside the card | Rely on `aria-label` alone for icon-only affordances inside the card |
-
-## 9. References
-
-- `apps/web/docs/data-views-pattern.md` — board UI section
-- `.cursor/rules/exxat-board-cards.mdc`, `exxat-centralized-list-dataset.mdc`, `exxat-card-vs-list-rows.mdc`
-- `apps/web/AGENTS.md` §4.4 (board cards), §13 (checklist)
-- `apps/web/lib/list-status-badges.ts` — `LIST_HUB_STATUS_TINT_*` + entity maps

package/template/docs/blueprints/data-table.md

@@ -1,139 +0,0 @@
-# Blueprint: Data Table
-
-> **Status:** Stable. **Owner:** Exxat DS core. **Implements:** WCAG 2.1 AA. **References:** SC 1.3.1, 2.1.1, 2.4.3, 2.4.6, 2.5.8, 4.1.2.
-
-## 1. Intent
-
-A **data table** is the canonical Exxat surface for browsing a homogeneous,
-comparable dataset (placements, team members, questions, compliance records).
-It pairs a **sortable / filterable / columnable grid** with a single state
-object (`useTableState`) that **every connected view** — list, board,
-dashboard, folder, panel — reads from.
-
-**Use when:**
-- The hub shows ≥ ~10 comparable records.
-- Users need to sort, filter, pin columns, change density, or export the data.
-- The hub is a primary nav destination.
-
-**Do NOT use when:**
-- The hub is **visual browse** (kanban, gallery, finder) — use
-  `ListPageBoardCard` + `data-views/` primitives. See
-  [`card-vs-rows-pattern.md`](../card-vs-rows-pattern.md).
-- The data is < ~10 rows and never grows — a simple list (or `<dl>`) suffices.
-- The view is read-only inside an analytics card — that may use minimal markup
-  per [`AGENTS.md` §3](../../AGENTS.md).
-
-## 2. Anatomy
-
-```
-┌─ ListPageTemplate ────────────────────────────────────────────────────┐
-│ [view tabs] [Add view +]                       [metrics slot]         │
-│  ├ DataTableToolbar ──────────────────────────────────────────────┐   │
-│  │ [search] [filter chips] [sort] [columns] [⋯ properties]        │   │
-│  ├ DataTable header ──────────────────────────────────────────────┤   │
-│  │  Col A ↕ │ Col B │ Col C │ …                                   │   │
-│  ├ DataTable body  ───────────────────────────────────────────────┤   │
-│  │  …rows from `tableState.rows`…                                 │   │
-│  ├ DataTablePaginated footer (optional) ──────────────────────────┤   │
-│  │  ‹ 1 / N ›                                                     │   │
-│  └────────────────────────────────────────────────────────────────┘   │
-└───────────────────────────────────────────────────────────────────────┘
-```
-
-| Slot | Required? | What it carries |
-|---|---|---|
-| `view tabs` | required when ≥ 1 view type | `table / list / board / dashboard` per `ListPageTemplate` |
-| `toolbar.search` | required | `⌘K` / `Ctrl K` find-in-list |
-| `toolbar.filter` | required when entity has filterable fields | Shared `FilterFieldDef` chips |
-| `toolbar.sort` | optional (column headers also sort) | Multi-column sort summary |
-| `toolbar.columns` | required | Column visibility / order chooser |
-| `toolbar.overflow` | required | `⋯` → `TablePropertiesDrawer` |
-| `header` | required | One row of column heads; sortable cells expose `aria-sort` |
-| `body` | required | Rows from **`tableState.rows`** — no parallel data source |
-| `pagination` | optional | When the result set exceeds the virtualization budget |
-
-## 3. States
-
-| State | Visual / behavior |
-|---|---|
-| Empty result | Inline empty-state row (icon + 1 sentence + clear filters action) |
-| Empty entity | Empty-state card (no rows in entity) |
-| Loading | Skeleton header + 5 skeleton rows; toolbar still interactable |
-| Sorted | Active column shows ↑ / ↓ with `aria-sort`; multi-sort shows index pill |
-| Filtered | Chips in toolbar; "X of Y" indicator |
-| Selected rows | Row check + bulk-action bar above toolbar |
-| Pinned cells | Opaque using `--dt-row-bg` / `--dt-header-bg` (never translucent) |
-| New row (just created) | `--dt-new-row-bg` + `--dt-new-row-border` (fades after N seconds) |
-| RTL | Header sort arrows and column resize handles mirror |
-
-## 4. Tokens consumed
-
-| Token | Used for |
-|---|---|
-| `--dt-row-bg`, `--dt-row-hover`, `--dt-row-selected`, `--dt-row-selected-fg` | Row chrome (must be **opaque** for pinned cells) |
-| `--dt-header-bg`, `--dt-group-bg` | Header + group rows |
-| `--dt-new-row-bg`, `--dt-new-row-border` | "Just created" highlight |
-| `--sticky-edge-fade` | Edge-of-pinned-column gradient |
-| `--border` | Hairlines between rows / columns |
-| `--ring` | Focus ring on cells, sort headers, row actions |
-| `--interactive-hover-row` | Hover-row tint |
-| `--avatar-initials-bg`, `--avatar-initials-fg` | Initials cells |
-| `--font-mono` (via `font-mono tabular-nums` class) | System IDs in cells |
-| `--table-row-height` | Default row height (`48px * --scaling`) |
-
-## 5. Accessibility
-
-| WCAG SC | How this blueprint complies |
-|---|---|
-| 1.3.1 Info & relationships | `<table>` / `<thead>` / `<tbody>` / `<tr>` / `<th scope="col">` semantics preserved through TanStack Table renderers |
-| 1.4.3 Contrast | Row hover + selection tints stay ≥ 4.5:1 against `--foreground` |
-| 1.4.11 UI contrast | Cell borders use `--border`; focus uses `--ring` (≥ 3:1) |
-| 2.1.1 Keyboard | Cells reachable by `Tab`; arrow-key cell nav inside the body; `Esc` clears active filter chip |
-| 2.4.3 Focus order | Header → toolbar → body → pagination; never traps |
-| 2.4.6 Headings & labels | Column heads are `<th>` with visible text labels; icon-only sort affordance carries `aria-label` + `Tooltip` (SC 1.1.1 Case C) |
-| 2.5.8 Target size | Sort handles, sort/filter chips, row checkboxes ≥ 24×24 CSS px |
-| 4.1.2 Name, role, value | Sortable headers expose `aria-sort`; row selection checkboxes expose checked state |
-
-## 6. Variants
-
-| Variant | When to use | Differences |
-|---|---|---|
-| `DataTable` | Default — virtualized, sticky header | All features above |
-| `DataTablePaginated` | Server-paginated result sets where virtualization is wrong | Page footer + page-size selector |
-| `DataTable size="compact"` | Dense data (admin tools, reconciliation views) | Reduced `--table-row-height` |
-
-## 7. Implementation
-
-| Framework | Component(s) | File |
-|---|---|---|
-| **React (this app)** | `DataTable`, `DataTablePaginated`, `useTableState`, `DataTableToolbar`, `TablePropertiesDrawer`, **importable cell renderers** in `components/data-views/table-cells.tsx` (`ProgressCell`, `CurrencyCell`, `RatingCell`, `RowActionsCell<TRow>`, …) | [`packages/ui/src/components/data-table/`](../../../../packages/ui/src/components/data-table/), [`apps/web/components/data-views/table-cells.tsx`](../../components/data-views/table-cells.tsx), [`packages/ui/src/components/table-properties/`](../../../../packages/ui/src/components/table-properties/) |
-| Mobile | — | — |
-| Figma | — | — |
-
-Reference compositions:
-
-- **Placements** — `PlacementsClient` + `PlacementsTable` (most complete reference)
-- **Team** — `TeamClient` + `TeamTable`
-- **Compliance** — `ComplianceClient` + `ComplianceTable`
-- **Library** — `LibraryClient` + `LibraryTable` (adds folder
-  scope from URL)
-
-## 8. Do / Don't
-
-| ✅ Do | ❌ Don't |
-|---|---|
-| Use **one** `useTableState` per logical table; pass `tableState.rows` to every connected view (list/board/dashboard) | Hydrate a board / list view from a parallel mock array — the count will diverge from the table |
-| Wrap the table in `ListPageTemplate` so view tabs exist | Render `DataTable` directly under `PageHeader` for a primary hub |
-| Pass `currentView` + `onViewChange` to `TablePropertiesDrawer` so Properties matches the active tab | Mount `TablePropertiesDrawer` on a multi-view page without `currentView` — it defaults to "Table display" copy on Board |
-| Use `font-mono tabular-nums` on system IDs only | Apply `font-mono` to names, statuses, or dates |
-| Mark sort headers with `aria-sort` and visible direction glyph | Use color alone to communicate sort direction |
-| Search keyboard hint shows `⌘K` (no Alt) | Use `⌘⌥K` for the table search — that chord is Ask Leo |
-
-## 9. References
-
-- [`apps/web/docs/data-views-pattern.md`](../data-views-pattern.md) — architecture narrative
-- [`.cursor/rules/exxat-data-tables.mdc`](../../../.cursor/rules/exxat-data-tables.mdc) — the mandatory stack
-- [`.cursor/rules/exxat-list-page-connected-views.mdc`](../../../.cursor/rules/exxat-list-page-connected-views.mdc) — `tableState.rows` across views
-- [`.cursor/rules/exxat-centralized-list-dataset.mdc`](../../../.cursor/rules/exxat-centralized-list-dataset.mdc) — one dataset rule
-- [`.cursor/rules/exxat-table-properties-drawer.mdc`](../../../.cursor/rules/exxat-table-properties-drawer.mdc) — Properties drawer + active view
-- [`apps/web/AGENTS.md`](../../AGENTS.md) §3, §4, §5

package/template/docs/blueprints/key-metrics.md

@@ -1,128 +0,0 @@
-# Blueprint: Key metrics (KPI strip + dashboard tiles)
-
-> **Status:** Stable. **Owner:** Design system. **Implements:** SC 1.3.1, 1.4.3, 1.4.11, 2.4.6, 4.1.2.
-
-## 1. Intent
-
-A **key-metrics strip** summarizes a hub's headline numbers — count, % share,
-average, freshness — in 1-4 horizontal tiles. Each tile carries a label, a
-formatted value, and an optional **trend chip** (`+12% MoM`, `↓ 0.4 day`,
-`stable`). The strip exists in two variants:
-
-- `variant="flat"` — transparent band glued under `ListPageTemplate` headers
-  (brand glow + cell hairlines, no surface panel).
-- `variant="card"` — solid card with header / actions / chart annotations
-  (dashboard "Key metrics" section).
-
-Both feed from the **same row bag** the hub's `DataTable` shows, so the
-numbers reflect active filters / search.
-
-**Use when:**
-
-- The hub's headline answer can be expressed in **≤ 4 numbers**.
-- The numbers update in response to filters, search, or a date scope.
-- The user benefits from a trend chip (signed delta + period label).
-
-**Do NOT use when:**
-
-- You need 5 + tiles (push secondary stats into a `MetricInsight`, a chart, or
-  another section — never raise `KEY_METRICS_KPI_COUNT_MAX` without DS review).
-- The metric is a long-form chart (use `Chart` family, possibly with a
-  `MetricInsight` mini-callout inside).
-
-## 2. Anatomy
-
-```
-flat:
-─────────────────────────────────────────────────────────────────
-│ Label   Value   [+12% MoM ▲] │ Label   Value   [−0.4d ▼]    │
-─────────────────────────────────────────────────────────────────
-                                ↑ hairline between cells (no panel)
-```
-
-```
-card:
-┌──────────────────────────────────────────────┐
-│ Key metrics                       [Ask Leo]  │  ← header (label + actions)
-│ ──────────────────────────────────────────── │
-│ Label   Value   [trend]   ↪ insight chip     │  ← MetricItem rows
-│ Label   Value   [trend]                      │
-└──────────────────────────────────────────────┘
-```
-
-| Slot | Required? | What it carries |
-|---|---|---|
-| `metrics` | required | `MetricItem[]` (≤ 4) — label, value, optional trend, optional polarity |
-| `variant` | required | `"flat"` (list-hub strip) or `"card"` (dashboard tile) |
-| `insight` | optional | `MetricInsight` — a narrative chip (e.g. "Renewals up 12% MoM") |
-| `headerActions` | optional (card only) | Ask-Leo trigger or drill-down button |
-| `loading` | optional | Skeleton state — same layout, no values |
-
-## 3. States
-
-| State | Visual / behavior |
-|---|---|
-| Default | Tiles render label + value + optional trend |
-| Loading | Skeleton bars in the value + trend positions, label visible |
-| Empty | Value = `0` (or `—` for averages), trend = `neutral` |
-| Trend up + favorable | Up arrow + positive tint |
-| Trend up + unfavorable (`trendPolarity: "lower_is_better"`) | Up arrow + destructive tint |
-| Trend neutral / informational | Muted tint, arrow still shows direction |
-| RTL | Trend chip flips alignment; arrows stay direction-correct (logical, not visual) |
-
-## 4. Tokens consumed
-
-| Token | Used for |
-|---|---|
-| `--exxat-color-surface-muted` / `--muted` | Card variant header band |
-| `--exxat-color-surface-2` / `--card` | Card variant background |
-| `--exxat-color-brand-tint-1` / `--brand-tint` | Flat variant OKLCH brand glow |
-| `--exxat-color-border-1` / `--border` | Cell hairlines (flat variant) |
-| `--exxat-color-ink-1` / `--foreground` | Value text |
-| `--exxat-color-ink-2` / `--muted-foreground` | Label + meta text |
-| Trend chip tokens (positive / destructive / neutral) | Trend tint + foreground |
-
-## 5. Accessibility
-
-| WCAG SC | How this blueprint complies |
-|---|---|
-| 1.3.1 Info & relationships | The strip is `role="group"` + `aria-label="Key metrics"`; each tile is a `<dl>`-style label / value pair |
-| 1.4.3 Contrast | Trend chip text + tile value ≥ 4.5:1; trend icon ≥ 3:1 |
-| 1.4.11 Non-text contrast | Trend chip border / glyph ≥ 3:1 against tile background |
-| 2.4.6 Headings / labels | Each tile's label is the accessible name; value is `aria-describedby` |
-| 4.1.2 Name / role / value | Trend chip has `aria-label` like "Trending up 12% month over month" (via `metricTrendAriaQualifier`) |
-
-## 6. Variants
-
-| Variant | When to use | Differences from default |
-|---|---|---|
-| `flat` | List-page hub headers — transparent band under `ListPageTemplate` | No surface panel; OKLCH brand glow; hairlines only |
-| `card` | Dashboards (Data tab, embed widgets) | Solid card chrome + header + optional Ask Leo trigger |
-| `compact` | Embedded in another card (chart annotation) | 1-2 tiles inline with the chart legend |
-| `mini` | Inside a chart card | Single tile rendered next to the chart title |
-
-## 7. Implementation
-
-| Framework | Component(s) | File |
-|---|---|---|
-| **React (this app)** | `KeyMetrics` + `MetricItem` + `MetricInsight` + `metricTrendTone` + `metricTrendAriaQualifier` | `@exxatdesignux/ui/components/key-metrics` |
-| Service injection (Ask Leo) | `KeyMetricsProvider` (in `apps/web/components/key-metrics-ask-leo-bridge.tsx`) | Wires `useAskLeo` → DS context |
-| Mobile | — | — |
-| Figma | "Key metrics – flat" and "Key metrics – card" frames | — |
-
-## 8. Do / Don't
-
-| ✅ Do | ❌ Don't |
-|---|---|
-| Cap visible tiles at 4 (`KEY_METRICS_KPI_COUNT_MAX`) | Add a fifth tile by raising the constant without DS review |
-| Set `trendPolarity: "lower_is_better"` for metrics where up = bad (defects, overdue, low-quality flags) | Always paint "up" as the favorable tint |
-| Feed KPI builders with `tableState.rows` so numbers honor filters | Pass raw mock arrays — the numbers will lie when filters change |
-| Use `variant="flat"` on hub headers and `variant="card"` in dashboards | Build a bespoke 3-column tile grid duplicating `KeyMetrics` |
-| Pair trend with a `MetricInsight` for narrative context | Show a bare delta with no period header or qualifier |
-
-## 9. References
-
-- `apps/web/docs/kpi-flat-band-pattern.md`, `kpi-strip-max-four-pattern.md`, `kpi-trend-pattern.md`
-- `.cursor/rules/exxat-kpi-flat-band.mdc`, `exxat-kpi-max-four.mdc`, `exxat-kpi-trends.mdc`
-- `apps/web/AGENTS.md` §4.1 (template metrics slot), §4.3 (charts + mini-metrics)
-- `apps/web/lib/dashboard-layout-merge.ts` — `KEY_METRICS_KPI_COUNT_MAX`, `clampKeyMetricsKpiCount`

package/template/docs/blueprints/list-page-template.md

@@ -1,123 +0,0 @@
-# Blueprint: List page template
-
-> **Status:** Stable. **Owner:** Design system. **Implements:** SC 1.3.1, 2.1.1, 2.4.3, 2.4.6, 4.1.2.
-
-## 1. Intent
-
-A **list page** is the canonical hub surface for browsing a homogeneous
-collection of records (Placements, Team, Compliance, Library items, …).
-It pairs a single `DataTable` with view-tab variants (table · list · board ·
-dashboard · folder · panel · tree), one shared filter / sort / column model,
-and a metric strip that consumes the same filtered row bag.
-
-**Use when:**
-
-- The route is the **primary** destination for an entity (a hub, not a detail).
-- Users compare records and filter / sort across them.
-- The same dataset can be productively shown as a table **and** as one or more
-  alternate views (board, dashboard, etc.).
-
-**Do NOT use when:**
-
-- The page is a **detail** view of a single record (use a record-home page).
-- The dataset is < ~10 items and never needs filters (use a card grid).
-- The flow is a multi-step **wizard** or **form** (use a primary-page template
-  with a focus mode).
-
-## 2. Anatomy
-
-```
-┌──────────────────────────────────────────────────────────┐
-│  PageHeader  (title · subtitle · primary CTA · ⋯ menu)   │  ← slot: header (required)
-├──────────────────────────────────────────────────────────┤
-│  KeyMetrics flat band  (≤ 4 tiles · trend chips · …)     │  ← slot: metrics (optional)
-├──────────────────────────────────────────────────────────┤
-│  View tabs  [ Table · Board · Dashboard · Folder · … ]   │  ← slot: viewTabs (required, ≥ 1)
-├──────────────────────────────────────────────────────────┤
-│  Toolbar  (search · filter chips · ⋯ properties)         │  ← managed by HubTable
-│  ┌─────────────────────────────────────────────────┐     │
-│  │  Active view body — TABLE / BOARD / …           │     │  ← rendered by HubTable + renderers
-│  └─────────────────────────────────────────────────┘     │
-└──────────────────────────────────────────────────────────┘
-```
-
-| Slot | Required? | What it carries |
-|---|---|---|
-| `header` | required | `PageHeader` (object-home / record-home / collaboration variant) |
-| `metrics` | optional | `KeyMetrics variant="flat"` — ≤ 4 tiles fed by the same `tableState.rows` |
-| `viewTabs` | required (≥ 1) | `ViewTab[]` with `viewType`, `icon`, `label`, optional `filterId` |
-| `renderContent` | required | `(tab, updateTab) => ReactNode` that returns the active view body |
-| `beforeSiteHeader` | optional | Banner / promo strip rendered above the site header |
-| `tablePropertiesRef` | optional | Imperative handle so the ⋯ menu can open the Properties drawer |
-
-`ListPageTemplate` itself owns the **header + metrics + view-tab control**.
-The view body is rendered by `HubTable` (or a custom non-table view) and
-**shares one `useTableState`** instance across every view.
-
-## 3. States
-
-| State | Visual / behavior |
-|---|---|
-| Default | Header + metrics + active view body |
-| No metrics declared | Metrics band is omitted; no empty gap |
-| No rows | Active view shows entity-specific empty state; KPI tiles show zeros + neutral trend |
-| Filters applied | Toolbar chips reflect filters; KPI tiles recalculate against filtered rows |
-| Switching views | `tab.id` is the React key so table state survives (sort, search, columns) |
-| Loading | Render skeleton state in `renderContent`; metric tiles use the `metric-card` skeleton |
-| RTL | All chrome (toolbar, view tabs, properties drawer) flips with `dir="rtl"` |
-
-## 4. Tokens consumed
-
-| Token | Used for |
-|---|---|
-| `--exxat-color-surface-1` / `--background` | Page canvas |
-| `--exxat-color-surface-2` / `--card` | Header + table chrome |
-| `--exxat-color-surface-muted` / `--muted` | View-tab inactive bg, KPI flat band glow |
-| `--exxat-color-brand-1` / `--brand-color` | Active view tab, primary CTA |
-| `--exxat-color-border-1` / `--border` | Hairlines between chrome zones |
-| `--exxat-color-focus-ring` / `--ring` | `:focus-visible` ring on toolbar / tabs |
-| `--exxat-radius-2` / `--radius` | Page chrome radii |
-
-## 5. Accessibility
-
-| WCAG SC | How this blueprint complies |
-|---|---|
-| 1.3.1 Info & relationships | View tabs use `role="tablist"`; toolbar uses `role="toolbar"`; metrics use `role="group"` + name |
-| 2.1.1 Keyboard | Tab through header → tabs → toolbar → grid; arrow keys between tabs and column headers |
-| 2.4.3 Focus order | Tab order matches reading order top-to-bottom |
-| 2.4.6 Headings / labels | Header title is the route `<h1>`; each view tab announces its label |
-| 4.1.2 Name / role / value | View tabs expose `aria-selected`; properties drawer toggle has `aria-haspopup="dialog"` |
-
-## 6. Variants
-
-| Variant | When to use | Differences from default |
-|---|---|---|
-| `base` | Most hubs | Header + metrics + tabs + view body |
-| `no-metrics` | Hubs where KPI summary adds noise (e.g. Library: too many heterogeneous folders) | Omit `metrics` prop |
-| `with-banner` | Pages that need a promo or alert above the header | Use `beforeSiteHeader` slot |
-| `secondary-panel-hub` | Hubs scoped by a sidebar panel (Library) | Wrap in `SecondaryPanelHubTemplate`; same `useTableState` |
-
-## 7. Implementation
-
-| Framework | Component(s) | File |
-|---|---|---|
-| **React (this app)** | `ListPageTemplate` + `HubTable` + `useTableState` + `TablePropertiesDrawer` | `@exxatdesignux/ui/components/templates/list-page`, `@exxatdesignux/ui/components/data-views`, `@exxatdesignux/ui/components/data-table` |
-| Mobile | — | — |
-| Figma | Pattern: "List page – hub" frame in the DS library | — |
-
-## 8. Do / Don't
-
-| ✅ Do | ❌ Don't |
-|---|---|
-| One `useTableState` per hub; every view reads `tableState.rows` | Mount a second mock array for "board only" or "tree only" |
-| Pass `currentView` + `onViewChange` into `TablePropertiesDrawer` | Leave `currentView` unset on a multi-view hub (Properties drawer assumes table) |
-| Use `key={tab.id}` in `renderContent` so table state survives | Use `key={tab.viewType}` (resets state when switching views) |
-| Pull metrics from `tableState.rows` so they react to filters / search | Pass raw mock arrays to KPI builders (numbers will lie when filters change) |
-| Cap the metrics strip at 4 KPI tiles | Add a fifth tile by raising `KEY_METRICS_KPI_COUNT_MAX` without DS review |
-
-## 9. References
-
-- `apps/web/docs/data-views-pattern.md` — connected views narrative
-- `apps/web/docs/kpi-flat-band-pattern.md`, `kpi-strip-max-four-pattern.md`, `kpi-trend-pattern.md`
-- `.cursor/rules/exxat-list-page-connected-views.mdc`, `exxat-centralized-list-dataset.mdc`, `exxat-table-properties-drawer.mdc`, `exxat-list-page-view-shells.mdc`
-- `apps/web/AGENTS.md` §4.1 (template), §4.2 (Properties drawer), §4.5 (view shells)