@exxatdesignux/ui 0.5.11 → 0.5.13

package/template/docs/jobs/README.md

@@ -1,59 +0,0 @@
-# Exxat DS — Jobs library
-
-> **What:** Canonical reference per **job-to-be-done**, not per component.
-> **Why:** Components answer "how to render". Jobs answer "what to build".
-> **Who:** Humans + AI agents writing design briefs
-> ([`exxat-ux-discovery-protocol.mdc`](../../../.cursor/rules/exxat-ux-discovery-protocol.mdc)).
-
-A **job** is what the user is trying to accomplish — not the screen they end
-up on. Two products with the same component stack can ship different jobs;
-two products with different stacks can ship the same job. **The job is the
-contract.**
-
-## When to use this library
-
-- The user prompt names a screen ("student detail", "settings page", "compose
-  form"). Map it to a **job** first, then pick the reference.
-- Before building, the design brief MUST cite the relevant job doc as a
-  reference.
-- If no job doc matches, **write one** (even short) as part of the work.
-
-## Job → screen mapping
-
-| Job | Doc | Canonical references |
-|-----|-----|----------------------|
-| **Review a record's full state** | [`record-detail.md`](./record-detail.md) | Students / Placements / Library detail |
-| **Triage a list of records** (find at-risk / actionable) | *future* | `PlacementsClient`, `ComplianceClient` |
-| **Compose / create a new record** | *future* | `new-library-item-form.tsx` |
-| **Configure preferences or workspace settings** | *future* | `app/(app)/settings/page.tsx` |
-| **Scan many metrics for anomalies** | *future* | Dashboard route, `DashboardTabs` |
-| **Search / find anything** | *future* | `CommandMenu`, `DedicatedSearch*` |
-| **Onboarding / first-run setup** | *future* | `getting-started.tsx`, `CoachMark` |
-| **Approve / review submitted work** | *future* | (TBD) |
-
-## How a job doc is structured
-
-Every job doc must include:
-
-1. **The job** — one paragraph; user pain, decision, action.
-2. **When this job applies** — triggers, scale, frequency.
-3. **Pattern: route vs sheet vs inline** — with a decision table.
-4. **Information architecture** — ASCII diagram of the IA.
-5. **Layers, in priority order** — identity → status → groups → activity →
-   related.
-6. **When to use tabs / subsections.**
-7. **Navigation — the way back** (P1 enforcement).
-8. **Actions** — primary, overflow, inline.
-9. **States** — loading, empty, error, stale.
-10. **Accessibility** — A11y concerns specific to the job.
-11. **Modern SaaS analogues** — cite by product + Mx codes.
-12. **Anti-patterns** — what NOT to do.
-13. **Quick checklist** for the post-build audit.
-
-## See also
-
-- [`../modern-saas-patterns.md`](../modern-saas-patterns.md) — the canon
-- [`../component-selection-guide.md`](../component-selection-guide.md) —
-  decision tree from job → composition
-- [`../blueprints/`](../blueprints/) — framework-agnostic specs
-- [`../../../.cursor/skills/exxat-senior-ux/SKILL.md`](../../../.cursor/skills/exxat-senior-ux/SKILL.md)

package/template/docs/jobs/record-detail.md

@@ -1,177 +0,0 @@
-# Job: Review a record's full state
-
-> **Surface type:** Standalone route OR side-panel sheet.
-> **Examples in product:** Student profile, Placement record, Library item,
-> Site profile, Team member profile.
-
-## 1. The job
-
-The user lands on a single record and needs to **understand its current
-state** in order to **decide what to do next**. Decisions can include:
-contact someone, edit a field, change status, place / unplace, archive,
-follow up later, or simply confirm correctness before another action.
-
-This job is **not**: edit (separate flow), bulk action (lives on the list),
-configure workspace settings.
-
-## 2. When this job applies
-
-- The record has > ~5 displayable fields.
-- The user reaches it from a list, search, deep link, or notification.
-- The user's next action depends on the record's state (status, ownership,
-  data freshness).
-- The record may have children (placements, attachments, comments) that
-  matter to the decision.
-
-## 3. Pattern: route vs sheet vs inline
-
-| Pattern | When | DS comp |
-|---------|------|---------|
-| **Standalone route** (`/students/[id]`) | Deep link from email / notifications / reports; user may keep tab open; record has > 10 fields | `PrimaryPageTemplate` + `PageHeader` |
-| **Sheet over hub** | User is triaging from a list and may open many records in sequence | `Sheet` over `ListPageTemplate` |
-| **Inline expansion** (`HoverCard`) | Read-only quick preview; < 5 fields | `HoverCard` on row hover |
-
-Pick **route** by default. Pick **sheet** if the user's primary path is
-triaging from a list and they typically open many in a single session.
-
-## 4. Information architecture
-
-```
-┌─ SiteHeader (breadcrumb only) ──────────────────────────────────┐
-│  Dashboard › Students › Jordan Lee                              │  ← ancestors + title (P1, P2)
-└──────────────────────────────────────────────────────────────────┘
-┌─ Identity row ──────────────────────────────────────────────────┐
-│  [Avatar] Jordan Lee                              [Edit] [⋯]    │  ← name, ID, primary action + overflow
-│          STU-2026-1042 · jordan.lee@example.edu                 │
-└──────────────────────────────────────────────────────────────────┘
-┌─ Status row (above the fold, P13) ──────────────────────────────┐
-│  ● Active   ✓ Compliant   ⊕ Placed at Sinai                     │
-└──────────────────────────────────────────────────────────────────┘
-┌─ Field groups (2-col card grid) ────────────────────────────────┐
-│  Program     │  Academic                                         │
-│  Placement   │  Compliance                                       │
-└──────────────────────────────────────────────────────────────────┘
-┌─ Activity timeline (M7, optional) ──────────────────────────────┐
-│  Today · Compliance status updated by Maria                      │
-│  Tue · Placement assigned · Sinai Hospital                       │
-└──────────────────────────────────────────────────────────────────┘
-```
-
-### Layers, in priority order
-
-1. **Identity** — name, system ID (mono), avatar, primary contact link.
-2. **Status** — every status badge that drives a decision; visible without
-   scrolling (P13).
-3. **Field groups** — 2-column card grid by default. Group by **conceptual
-   coherence** (Program / Academic / Placement / Compliance), not by table
-   structure.
-4. **Activity timeline** — if the record changes over time and the history
-   matters (M7).
-5. **Related lists** — placements, comments, attachments — if they exist for
-   this entity.
-
-### When to use section tabs
-
-- **Don't tab** if total field count is ≤ ~20 and groups are ≤ 4. Single
-  scroll is faster.
-- **Do tab** if the record has rich children (placements history,
-  supervisors, contracts, conversation threads) and the user typically
-  deep-dives into one section.
-- Tabs use `Tabs` + `TabsList` `w-fit` `variant="line"` — never full-width
-  (`exxat-tabs-chrome.mdc`).
-
-## 5. Navigation — the way back
-
-**Exactly one path back** (P1).
-
-| Reached from | Way back |
-|--------------|----------|
-| List route | `SiteHeader` breadcrumb (`Students`) |
-| Deep link / email | `SiteHeader` breadcrumb to the canonical parent |
-| Sheet from hub | `Sheet` close (X / Esc) |
-| Notification | Breadcrumb to canonical parent (not "Back to notification") |
-
-**Never** add a body-level "Back to <parent>" button when the breadcrumb is
-present (`exxat-breadcrumbs-no-back.mdc`).
-
-## 6. Actions
-
-| Slot | Component | What goes here |
-|------|-----------|----------------|
-| Primary | `PageHeader.primaryAction` (`Button variant="default" size="lg"`) | The single most common next action — "Edit", "Place", "Approve" |
-| Overflow | `Button variant="outline" size="icon-lg"` → `DropdownMenu` | Export, Archive, Duplicate, Share, dangerous-but-rare actions |
-| Inline | Icon-only buttons with tooltip | Copy email, dial phone, open site |
-| Status flip | `Sheet` or inline `Select` | Status changes that are audited (multi-step) |
-
-Exactly **one** filled CTA per surface (P3).
-
-## 7. States
-
-| State | What to show |
-|-------|--------------|
-| **Loading** | `Skeleton` matching the IA shape (identity → status → cards) — M9 |
-| **Empty / not found** | `EmptyState` + "Return to <list>" outline button |
-| **Error** | `LocalBanner` inside the body; identity row still renders if available |
-| **Stale data** | Subtle "Updated <relative>" in identity meta |
-
-## 8. Accessibility
-
-- One `<h1>` (P2) — typically `PageHeader.title`.
-- Status row is a `role="list"`; each badge is `role="listitem"` (already in
-  `ListHubStatusBadge`).
-- Inline mailto / tel links are real `<a>`s, not buttons.
-- Tab order: breadcrumb → identity → primary action → overflow → status →
-  fields → activity → related.
-- Icon-only actions carry `aria-label` + a tooltip with the same text.
-
-## 9. Modern SaaS analogues
-
-| Product | What to study |
-|---------|---------------|
-| **Linear** issue detail | Identity + status + properties + activity; sheet variant for triage |
-| **Stripe Dashboard** customer / charge | Identity + status badges + grouped data + audit log |
-| **Notion** page-as-database row | Inline editing (M5), property panel |
-| **Plain / Pylon** ticket | Conversation-as-document for support records |
-
-Cite these in the design brief by name + Mx codes:
-`Linear issue detail (M1, M4, M7)`.
-
-## 10. Anti-patterns
-
-| Anti-pattern | Use instead |
-|--------------|-------------|
-| `<h1>` + `PageHeader title` + breadcrumb leaf all repeating the name | One carrier: `PageHeader title` + ancestors-only breadcrumb (P2) |
-| "Back to <parent>" button alongside the breadcrumb | Breadcrumb only (P1) |
-| Two filled CTAs in the header ("Save" + "Submit") | One filled, others outline (P3) |
-| Status only in detail (hidden on list / breadcrumb count) | Status visible everywhere the record appears (M4) |
-| Status communicated by color only | Color + icon + label (`ListHubStatusBadge`) |
-| Full-width section tab bar | `Tabs` `w-fit` (`exxat-tabs-chrome.mdc`) |
-| Centered modal for "Edit name" | Inline edit (M5) or `Sheet` (M3) |
-| Spinner overlay for initial load | `Skeleton` matched to IA (M9) |
-| Activity timeline buried in a tab nobody opens | Show inline below cards, or remove it |
-| New shared "ProfileHero" component invented per entity | Compose: `PageHeader` + identity-row primitives (P8) |
-| `toast()` on save | Inline button label change + `LocalBanner` if persistent |
-
-## 11. Quick checklist (post-build audit)
-
-- [ ] Breadcrumb shows ancestors + title; no duplicate name.
-- [ ] No body "Back to <parent>" button.
-- [ ] One H1.
-- [ ] Status row visible without scrolling.
-- [ ] One filled primary action; overflow has the rest.
-- [ ] 2-col card grid for fields (or tabs if ≥ 4 sections / 20+ fields).
-- [ ] `Skeleton` matches the IA on load; empty state designed for "not found".
-- [ ] Tab order: breadcrumb → identity → primary → overflow → fields.
-- [ ] All status chips use `ListHubStatusBadge` + `lib/list-status-badges.ts`.
-- [ ] No `toast()`, no Vaul, no pixel-copy of legacy.
-
-## 12. Reference
-
-- [`../../../.cursor/skills/exxat-senior-ux/SKILL.md`](../../../.cursor/skills/exxat-senior-ux/SKILL.md)
-- [`../../../.cursor/rules/exxat-ux-discovery-protocol.mdc`](../../../.cursor/rules/exxat-ux-discovery-protocol.mdc)
-- [`../../../.cursor/rules/exxat-ux-principles.mdc`](../../../.cursor/rules/exxat-ux-principles.mdc)
-- [`../../../.cursor/rules/exxat-breadcrumbs-no-back.mdc`](../../../.cursor/rules/exxat-breadcrumbs-no-back.mdc)
-- [`../../../.cursor/rules/exxat-tabs-chrome.mdc`](../../../.cursor/rules/exxat-tabs-chrome.mdc)
-- [`../modern-saas-patterns.md`](../modern-saas-patterns.md)
-- [`../blueprints/page-header.md`](../blueprints/page-header.md)
-- [`../component-selection-guide.md`](../component-selection-guide.md) §1

package/template/docs/kpi-flat-band-pattern.md

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

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

@@ -1,30 +0,0 @@
-# KPI strip — maximum four tiles
-
-> **Code:** `lib/dashboard-layout-merge.ts` — **`KEY_METRICS_KPI_COUNT_MIN`**, **`KEY_METRICS_KPI_COUNT_MAX`** (4), **`clampKeyMetricsKpiCount`**. **Component:** `KeyMetrics` in `components/key-metrics.tsx`.
-
-## Rule
-
-On **primary list hubs** (`ListPageTemplate` metrics slot) and on **dashboard “key metrics” cards** (Data tab chart bundles), **show at most four** `MetricItem` tiles at once.
-
-## Why four
-
-- **Scanning** — More than four headline numbers compete; users miss deltas and period context.
-- **Layout** — `KeyMetrics` wraps to multiple rows; four keeps one or two clean rows on common breakpoints (including **`metricsHalfWidthLayout`** on span-1 cards).
-- **Persistence** — Dashboard layout already stores **`keyMetricsKpiCount`** in **`1…4`**; list-page KPI helpers should **not** return a fifth tile expecting it to display.
-
-## Implementation
-
-1. **KPI builders** (`lib/mock/*-kpi.ts`) — Return **≤ 4** items, or **`.slice(0, 4)`** after prioritizing (hero total + top three drivers). Merge extras into **`MetricInsight`** copy instead of a fifth tile when possible.
-2. **Dashboard canvas** — Never raise **`KEY_METRICS_KPI_COUNT_MAX`**; use **`clampKeyMetricsKpiCount`** when reading saved JSON.
-3. **Full-page dashboards** — If more summaries are needed, add **sections** (charts, tables, secondary cards), not a fifth KPI in the same strip.
-
-## MUST NOT
-
-- Ship **five+** `MetricItem` entries in a single **`KeyMetrics`** band meant as the **primary** KPI row for a hub or the **key-metrics** dashboard card.
-- Duplicate the same metric as two tiles to pad count — prefer **insight rail** or **`MetricInsight`**.
-
-## See also
-
-- **`docs/kpi-trend-pattern.md`** — deltas, arrows, **`trendPolarity`**.
-- **`docs/kpi-flat-band-pattern.md`** — **`variant="flat"`** presentation (orthogonal to tile count).
-- **`.cursor/rules/exxat-kpi-max-four.mdc`**, **`.cursor/skills/exxat-kpi-max-four/SKILL.md`**

package/template/docs/kpi-trend-pattern.md

@@ -1,58 +0,0 @@
-# KPI trend arrows and deltas (`KeyMetrics`)
-
-> **Handbook:** [`AGENTS.md`](../AGENTS.md) (mock KPI helpers, `KeyMetrics`). **Component:** [`components/key-metrics.tsx`](../components/key-metrics.tsx). **Cursor:** [`.cursor/rules/exxat-kpi-trends.mdc`](../../.cursor/rules/exxat-kpi-trends.mdc). **Skill:** [`.cursor/skills/exxat-kpi-trends/SKILL.md`](../../.cursor/skills/exxat-kpi-trends/SKILL.md).
-
-## Goals
-
-1. **Contextual** — The **label**, **value format** (count, %, currency, days), and **comparison period** (e.g. “vs last week”) must read as one story. Do not paste a generic “+12%” without tying it to what moved.
-2. **Honest direction** — **`trend`** (`up` | `down` | `neutral`) always matches the **signed change** in the underlying metric so the **arrow** reflects reality.
-3. **Correct sentiment** — **`trendPolarity`** decides whether “up” is **good news** (tint + assistive copy), **bad news**, or **informational** (muted — direction only).
-
-## `MetricItem` fields
-
-| Field | Role |
-| --- | --- |
-| `value` | Current bucket total or rate (formatted string or number). |
-| `delta` | **Count change for the trend chip**, e.g. `+5`, `-3`, `+12%`. Pass `""` (or `0`) when there is no comparison this period — the chip is then **hidden**, not rendered as `—`. **Never** put captions or labels like `"left + right"` here. |
-| `description` | Optional **caption** rendered **below** the value + trend row (muted, small). Use for *what* moved or *how* the value breaks down — `"left + right"`, `"vs last week"`, `"across 4 sites"`, `"scheduled for removal"`. |
-| `trend` | **Visual direction** of the delta: more → `up`, less → `down`, flat / N/A → `neutral`. Combined with an empty `delta`, `neutral` collapses the chip. |
-| `trendPolarity` | Optional. **`higher_is_better`** (default) \| **`lower_is_better`** \| **`informational`**. |
-
-### Layout
-
-```
-┌─────────────────────────────────────────────┐
-│ Pinned columns                              │  ← label
-│ 2  ↑ +1                                     │  ← value + (delta in chip)
-│ left + right                                │  ← description (caption)
-└─────────────────────────────────────────────┘
-```
-
-The **only** thing next to the arrow is the **count**. Prose lives **below** the value as a description. When there is no direction *and* no count, the chip is **suppressed** entirely (no `—` placeholder).
-
-## Polarity cheat sheet
-
-| `trendPolarity` | Use when | Up arrow tint | Down arrow tint |
-| --- | --- | --- | --- |
-| **`higher_is_better`** (default) | Revenue, pass rate, completions, enrolled count, positive CSAT | Favorable (brand / chart positive token) | Unfavorable (destructive) |
-| **`lower_is_better`** | Error rate, overdue tasks, **low PBI / item quality flags**, time-on-task when minimizing, spend when cutting cost | Unfavorable | Favorable |
-| **`informational`** | Library size, mix %, neutral volume | Muted | Muted |
-
-**Psychometrics example:** Point-biserial (PBI) **dropping** usually helps discrimination — often good (`lower_is_better` on a *“low quality” count* is clearer: **count of items below a review threshold** rising → `trend: "up"` + `trendPolarity: "lower_is_better"` → arrow up with **unfavorable** tint).
-
-## Accessibility
-
-- **Never colour alone:** `KeyMetrics` keeps **icon + numeric delta**; `aria-label` on the chip uses **`metricTrendAriaQualifier`** (e.g. “increased, unfavorable +1”).
-- **Decorative icons** stay `aria-hidden`; meaning lives in the chip’s **`aria-label`** and visible delta text.
-
-## Anti-patterns
-
-- Forcing **`trend: "up"`** green because “up feels good” when the metric is **defects** or **flags** — set **`lower_is_better`** instead.
-- Hiding a worsening metric by flipping the arrow without changing **`trend`** — arrows must match the data.
-- Using **`informational`** for KPIs that **do** have an agreed quality bar — pick a polarity instead.
-- Rendering an **empty `—`** chip just for layout symmetry. The component already hides the chip when there is no direction *and* no count; leave `delta: ""` + `trend: "neutral"` and use `description` for the supporting caption.
-- Putting captions like **`"left + right"`**, **`"hidden"`**, **`"shown"`**, **`"vs last week"`** in **`delta`**. Those are not deltas. Use **`description`**.
-
-## Related surfaces
-
-- **`ChartCard`** `miniMetrics` / `kpi-chart` variant — optional **`trendPolarity`** on each mini metric; uses the same **`metricTrendTone`** helper from `key-metrics.tsx`.

package/template/docs/large-dataset-strategy.md

@@ -1,155 +0,0 @@
----
-title: Large dataset strategy
----
-
-# Large dataset strategy
-
-How the Exxat DS table stack scales as record counts grow — what works today, when to
-turn pagination on, and what to add when the dataset outgrows the browser. Cross-linked
-from [`apps/web/AGENTS.md`](../AGENTS.md) and [`data-views-pattern.md`](./data-views-pattern.md).
-
-## TL;DR
-
-| Row count | What to do |
-|---|---|
-| **≤ 200** | Default `HubTable` setup. No pagination. Filter / sort all in memory. |
-| **200 – 5K** | Turn pagination on (`pagination={true}` on `HubTable`). Default page size 10–25. List + board views auto-virtualize at 100 rows via `DataRowList`. |
-| **5K – 50K** | Stay client-side with pagination, but consider adding `@tanstack/react-virtual` to the `DataTable` `<tbody>` (follow-up; see below). Filtering all rows in memory still works — `useTableState` is sub-100ms at 50K on a typical laptop. |
-| **> 50K** | Switch to **server mode**: lift filters / sort / page out of `useTableState` via `paginationOverride` and fetch one page at a time. The hub composition (`ListPageTemplate` + `HubTable` + Properties drawer) does not change. |
-
-## Today (client mode, in-memory)
-
-The default `HubTable` rendering path is fully client-side:
-
-```mermaid
-flowchart LR
-  Mock["lib/mock/* (or API on first paint)"] --> Rows["rows: TRow[] (full dataset)"]
-  Rows --> UTS["useTableState(rows, columns, sort, paginationOverride?)"]
-  UTS --> FRows["state.rows (filtered + sorted)"]
-  UTS --> PRows["state.pagedRows (sliced when pagination is on)"]
-  FRows --> DT["DataTable body (renders every row in pagedRows)"]
-  FRows --> DRL["DataRowList (auto-virtualizes at 100 rows)"]
-  FRows --> Board["ListPageBoardTemplate (virtualizes per-column)"]
-  FRows --> Dash["Dashboard charts"]
-```
-
-Key properties:
-
-1. **One row bag, every view.** Table / list / board / dashboard / folder / panel all read
-   `tableState.rows` (already filtered + sorted). No parallel arrays — see
-   [`.cursor/rules/exxat-centralized-list-dataset.mdc`](../../.cursor/rules/exxat-centralized-list-dataset.mdc).
-2. **`useTableState` is the only filter pass.** Every keystroke in the toolbar search or any
-   filter-chip change re-runs the predicate set across the full input array. This is
-   in-memory `Array.filter` / `Array.sort` — fast enough to be invisible up to ~50K rows on
-   typical hardware.
-3. **Table grid does NOT virtualize today.** When pagination is off, `DataTable` renders
-   every row in `state.rows` as a `<tr>`. With pagination on, it only renders the current
-   page — typically 10–25 rows — so DOM cost is constant regardless of the dataset size.
-4. **List + board views DO virtualize.** `DataRowList` uses `@tanstack/react-virtual` with
-   a `virtualizeThreshold` (default 100) so 5K rows in the **list** tab paint instantly
-   even without pagination. `ListPageBoardTemplate` slices per column with the same
-   threshold.
-
-## When to turn on pagination
-
-`HubTable` accepts a `pagination={true}` prop that wires:
-
-- The Properties drawer's **Show pagination** toggle.
-- `CountSyncer` so filter changes reset to page 1.
-- `PaginationBar` glued to the bottom of the table card (sticky at viewport bottom on
-  overflow).
-
-```tsx
-<HubTable
-  rows={items}
-  columns={columns}
-  pagination
-  paginationInitialPageSize={25}
-  paginationPageSizeOptions={[10, 25, 50, 100]}
-  // …
-/>
-```
-
-Rule of thumb: **once the table no longer fits on one screen, enable pagination.** That's
-typically around 100 rows for product grids with avatars / two-line cells. Below that,
-scroll-everything feels lighter than chrome.
-
-## Beyond 50K — server mode
-
-`useTableState` accepts a `paginationOverride: { page, pageSize }` so the hub owner can
-lift page state out of the table. Pair that with a `fetcher(page, pageSize, filters,
-sort) => Promise<{ rows, total }>` and you have classic server-side pagination without
-touching any DS primitive.
-
-Skeleton (planned, not implemented today):
-
-```tsx
-function MyHubClient() {
-  const [page, setPage]         = useState(1)
-  const [pageSize, setPageSize] = useState(25)
-  const [filters, setFilters]   = useState<FilterStateShape>(EMPTY_FILTERS)
-  const [sort, setSort]         = useState<SortState>(DEFAULT_SORT)
-
-  // Server fetches one page at a time, returns 25 rows + total count
-  const { data, isLoading } = useQuery({
-    queryKey: ["my-hub", page, pageSize, filters, sort],
-    queryFn:  () => fetchMyHubPage({ page, pageSize, filters, sort }),
-  })
-
-  return (
-    <HubTable
-      rows={data?.rows ?? []}
-      paginationOverride={{ page, pageSize }}
-      // …filters / sort wired the same way
-    />
-  )
-}
-```
-
-What stays the same:
-
-- `HubTable` composition (toolbar + filter chips + Properties + view tabs).
-- `ColumnDef` shape, including `filter:` blocks.
-- The Properties drawer Display / Filter / Sort / Columns / Conditional rules panels.
-
-What changes:
-
-- The filter / sort / page state is **lifted** out of `useTableState`'s internal reducer
-  and into the hub client (so it can be threaded into the fetcher).
-- A loading row state in `DataTable` (already supported via `emptyState`; we'd add a
-  skeleton variant when the data array is empty but a fetch is in-flight).
-
-## Follow-up: row virtualization for `DataTable`
-
-For "infinite scroll" dense grids (Notion / Airtable feel) without pagination, add
-`@tanstack/react-virtual` to `DataTable`'s `<tbody>`:
-
-- The package is already a dependency (used by `DataRowList`).
-- The mechanics are very similar to `DataRowList` — measure visible viewport height,
-  render only the `<tr>` rows in the visible window, padding the head/tail with empty
-  rows of the right pixel height.
-- Caveats: row pinning (left / right sticky columns) needs care; row-detail "expanded"
-  rows complicate height estimation; `groupable` rows would need flat indexing.
-
-This is documented as a follow-up. Not on the critical path because pagination handles
-the same scaling concern with simpler ergonomics.
-
-## What we do NOT do
-
-- **No infinite-scroll-by-default on the table grid.** Pagination is explicit, keyboard
-  reachable, and links well. Infinite scroll on a primary product grid hurts deep-link
-  reachability and keyboard navigation.
-- **No per-cell async hydration.** Every cell render reads from the row prop synchronously.
-  Async cell content (e.g. user avatar from a separate endpoint) is a column-level
-  concern — the column's `cell:` renderer can `useQuery` for that data, but it should not
-  block the row from painting.
-- **No client-side fetch waterfalls.** When the dataset moves to server mode, fetch the
-  page once with the filter / sort / page key. Don't fan out per-row fetches.
-
-## See also
-
-- [`exxat-data-tables.mdc`](../../.cursor/rules/exxat-data-tables.mdc) — `HubTable` is the
-  only product-data-list stack.
-- [`exxat-centralized-list-dataset.mdc`](../../.cursor/rules/exxat-centralized-list-dataset.mdc)
-  — one `useTableState` row bag, every view.
-- [`data-views-pattern.md`](./data-views-pattern.md) — connected-view architecture.

package/template/docs/library-hub-header-pattern.md

@@ -1,25 +0,0 @@
-# Library hub header — folder scope + Customize folder
-
-**Audience:** Engineers extending the library library hub (`LibraryClient`, `LibraryPageHeader`, URL scope).
-
-## Problem
-
-The library uses **`ListPageTemplate`** with multiple **view tabs** (table, panel, tree, …). **`LibraryNewFolderSheet`** (customize mode) is also used inside **`LibraryTable`** for some views (e.g. panel columns). If **Customize folder** exists only there, users on **table** or other tabs **cannot** open the sheet from a consistent chrome entry point when the URL is scoped to a folder (`?scope=folder&folderId=…`).
-
-## Pattern
-
-1. **`LibraryPageHeader`** exposes optional **`onCustomizeFolder?: () => void`**. When **`navState.scope === "folder"`** and **`navState.folderId`** is set, the hub client passes a callback that opens customize mode for the matching **`LibraryFolder`**.
-2. **`LibraryClient`** (or equivalent hub client) mounts **`LibraryNewFolderSheet`** **once** beside **`SecondaryPanelHubTemplate` / `ListPageTemplate`**, with local state for **`open`** and **`customizingFolder`**. Saving updates **`folders`** the same way as table-embedded customize flows.
-3. The header **⋯ More** menu order stays aligned with **§4.7**: **Invite people** (when collaboration variant) → **Customize folder** (when folder-scoped) → **Export** → **Show / hide metric section** (when applicable).
-
-## References
-
-| Piece | Location |
-|-------|-----------|
-| Header prop + menu item | `components/library-page-header.tsx` |
-| Client wiring + sheet | `components/library-client.tsx` |
-| URL scope | `lib/library-nav.ts` (`parseLibraryNav`, `LibraryNavState`) |
-| Sheet UI | `components/library-new-folder-sheet.tsx` |
-
-**Cursor rule:** `.cursor/rules/exxat-library-hub-header.mdc`  
-**Handbook:** `AGENTS.md` §4.6 (folder-scoped hub chrome).