@exxatdesignux/ui 0.2.19 → 0.3.0

package/consumer-extras/handbook/HANDBOOK.md

@@ -0,0 +1,185 @@
+# Exxat DS — Handbook
+
+> **Start here.** One page. Read in 10 minutes. Links out to everything else.
+>
+> **Audience:** designers, engineers, contributors, AI agents — anyone shipping UI in the Exxat product.
+
+---
+
+## 1. Five principles
+
+Every screen, primitive, and pattern in this design system serves one or more of these. When in doubt, the principle wins over the convenience.
+
+1. **Clarity over decoration.** Users see one product, one shell, one rhythm. Surprise (mystery icons, hidden states, novel layouts) is a tax on attention.
+2. **Progressive disclosure.** Beginners see what they need. Power users reach what they want. Default to the simpler surface; expose density on opt-in (Properties drawer, view tabs, secondary panel).
+3. **Same-shaped tools.** A hub looks like a hub. A drawer looks like a drawer. A KPI looks like a KPI. Pick the canonical primitive (§5 reference pages) before composing your own.
+4. **Accessibility is non-negotiable.** WCAG 2.1 AA is the **floor**, not the goal. Keyboard, screen-reader, contrast, touch-target, format hints — all enforced by rules, lints, and a checklist.
+5. **The data drives the chrome.** KPIs, status, trend polarity, descriptions — they come from the dataset (or the product) and are honest. No spin arrows, no decorative placeholders.
+
+---
+
+## 2. How to build a hub in 6 steps
+
+This is the **happy path** for the most common task: "I have an entity (placements, sites, columns, tokens, …); ship a hub for it." Follow these in order and the page lands at "best UX/UI", not "random design".
+
+| Step | What to do | Where it lives | Rule |
+|---|---|---|---|
+| 1 | Add typed mock rows in `lib/mock/<entity>.ts`. Aim for ~12 realistic records. | `apps/web/lib/mock/` | `.cursor/rules/exxat-centralized-list-dataset.mdc` |
+| 2 | Write **one** KPI helper `lib/mock/<entity>-kpi.ts` returning `MetricItem[]` (≤ 4 tiles). | same | `exxat-kpi-max-four.mdc`, `exxat-kpi-trends.mdc` |
+| 3 | Build the column defs (`ColumnDef[]`). Set `filter:` per column to get filter chips automatically. | `apps/web/components/<entity>-table.tsx` | `exxat-data-tables.mdc` |
+| 4 | Mount **`HubTable`** (NOT raw `<DataTable>`) inside `ListPageTemplate.renderContent`. `HubTable` wires `useTableState`, toolbar (search + filter chips + sort), and the **Properties drawer** in one place. | `apps/web/components/<entity>-table.tsx` | `exxat-data-tables.mdc` |
+| 5 | Compose the page client with `PrimaryPageTemplate` → `ListPageTemplate` (KPIs in `metrics`, view tabs in `defaultTabs`, the `HubTable` in `renderContent`). | `apps/web/components/<entity>-client.tsx` | `exxat-list-page-connected-views.mdc` |
+| 6 | Add to nav (`lib/mock/navigation.tsx`). If the hub needs scoped sub-navigation (e.g. categories), declare `secondaryPanel: "<id>"` and register the panel. | `apps/web/lib/mock/navigation.tsx`, `apps/web/components/sidebar/secondary-panel.tsx` | `exxat-primary-nav-secondary-panel.mdc` |
+
+**Reference page to copy:** `apps/web/components/sites-table.tsx` (the smallest complete hub) or `apps/web/components/columns-showcase.tsx` (single-view hub with a `HubTable`).
+
+> **Stop signs.** If you find yourself building a parallel table stack, a second metrics strip, a custom filter row, or pasting raw `<DataTable>` into `renderContent` — **stop and re-read** `.cursor/rules/exxat-reuse-before-custom.mdc`.
+
+---
+
+## 3. Where everything lives
+
+```
+┌─────────────────────────────────────────────────────────────────────┐
+│ PRINCIPLES + HANDBOOK   →  docs/HANDBOOK.md (this file)             │
+│                                                                     │
+│ FOUNDATIONS                                                         │
+│   tokens                →  docs/token-taxonomy.md                   │
+│   icons (Font Awesome)  →  .cursor/rules/exxat-fontawesome-icons    │
+│   typography            →  docs/token-taxonomy.md (font-* tokens)   │
+│   spacing / radius      →  docs/token-taxonomy.md (--exxat-*)       │
+│   color & themes        →  apps/web/components/tokens-themes-*      │
+│   voice & tone          →  docs/voice-and-tone.md                   │
+│   glossary              →  docs/glossary.md                         │
+│   reference pages       →  docs/reference-implementations.md        │
+│                                                                     │
+│ DECIDING (selection guides)                                         │
+│   which component?      →  docs/component-selection-guide.md        │
+│   page vs drawer vs     →  docs/drawer-vs-dialog-pattern.md         │
+│     dialog vs route        + .cursor/rules/exxat-{drawer-vs-dialog, │
+│                              page-vs-drawer}.mdc                    │
+│   card vs row vs list   →  docs/card-vs-rows-pattern.md             │
+│                                                                     │
+│ BLUEPRINTS  (framework-agnostic specs — one per pattern)            │
+│                         →  docs/blueprints/                         │
+│                            page-header · data-table ·               │
+│                            list-page-template · board-card ·        │
+│                            key-metrics                              │
+│                                                                     │
+│ PATTERNS  (long-form narrative — the "why" + the "how")             │
+│                         →  docs/*.md (data-views-pattern,           │
+│                            kpi-trend-pattern, drawer-vs-dialog-     │
+│                            pattern, dedicated-search,               │
+│                            command-menu, …)                         │
+│                                                                     │
+│ RULES  (binding MUST / MUST NOT — for AI agents + reviewers)        │
+│                         →  .cursor/rules/*.mdc                      │
+│                                                                     │
+│ SKILLS  (workflows + checklists — for AI agents doing a task)       │
+│                         →  .cursor/skills/  +  .claude/skills/      │
+│                                                                     │
+│ MIGRATIONS  (deprecation history, every breaking change)            │
+│                         →  docs/migrations/                         │
+│                                                                     │
+│ AGENT HANDBOOK  (authoritative §-numbered manual)                   │
+│                         →  apps/web/AGENTS.md                       │
+└─────────────────────────────────────────────────────────────────────┘
+```
+
+### Quick "which file should I open?" cheat-sheet
+
+| You want to… | Open this |
+|---|---|
+| Pick the right component for a job | [`docs/component-selection-guide.md`](https://github.com/ExxatDesign/Exxat-DS-Workspace/blob/main/apps/web/docs/component-selection-guide.md) |
+| Know what "hub" / "view tab" / "KPI band" mean | [`docs/glossary.md`](./glossary.md) |
+| Write empty-state / error / button copy | [`docs/voice-and-tone.md`](./voice-and-tone.md) |
+| Find the canonical reference page to copy | [`docs/reference-implementations.md`](./reference-implementations.md) |
+| Know the spec for a pattern | [`docs/blueprints/`](https://github.com/ExxatDesign/Exxat-DS-Workspace/blob/main/apps/web/docs/blueprints/) |
+| Understand the "why" of a pattern | [`docs/<pattern>-pattern.md`](.) |
+| Know the binding MUST / MUST NOT | [`.cursor/rules/`](../../../.cursor/rules/) |
+| Run a recurring agent workflow | [`.cursor/skills/`](../../../.cursor/skills/) or [`.claude/skills/`](../../../.claude/skills/) |
+| Token name & semantics | [`docs/token-taxonomy.md`](https://github.com/ExxatDesign/Exxat-DS-Workspace/blob/main/apps/web/docs/token-taxonomy.md) |
+| Full authoritative handbook | [`apps/web/AGENTS.md`](https://github.com/ExxatDesign/Exxat-DS-Workspace/blob/main/AGENTS.md) |
+
+---
+
+## 4. Rule precedence (when sources conflict)
+
+If two docs say different things, **the higher row wins**:
+
+1. **`.cursor/rules/*.mdc`** — these are MUST / MUST NOT; they bind the AI agent and the reviewer.
+2. **`apps/web/AGENTS.md`** — authoritative §-numbered handbook. The rules above are summaries of this.
+3. **`docs/blueprints/*.md`** — framework-agnostic specs for a single pattern.
+4. **`docs/*-pattern.md`** — long-form narrative for a pattern.
+5. **Reference page in code** (`apps/web/components/<reference>.tsx`) — the working implementation.
+6. **This handbook** — orientation only. If it conflicts with rules or AGENTS, the rules/AGENTS win.
+
+> **Found a conflict?** Open a PR that updates the *binding* layer (rule or AGENTS section) first, then propagate down. Don't fork the truth.
+
+---
+
+## 5. The canonical primitives (memorize these)
+
+These are the ones you'll use on >90% of screens. If a screen needs something else, it almost certainly already exists — search `components/` before building.
+
+| Need | Primitive | Lives in |
+|---|---|---|
+| Page chrome (breadcrumbs, site header, max-width content rail) | `PrimaryPageTemplate` | `apps/web/components/templates/primary-page-template.tsx` |
+| Hub frame (header + metrics + view tabs + content) | `ListPageTemplate` | `packages/ui` |
+| **Hub view body** (table + search + filters + Properties drawer + bulk-actions) | **`HubTable`** | `packages/ui` (re-exported from `@/components/data-views`) |
+| Page header (title + subtitle + actions + collaborators rail) | `PageHeader` | `apps/web/components/page-header.tsx` |
+| KPI strip / band | `KeyMetrics` (`variant="flat"` on hubs) | `packages/ui` |
+| Status chip + icon | `ListHubStatusBadge` + `lib/list-status-badges.ts` | `apps/web/components/` |
+| Board / kanban card | `ListPageBoardCard` + primitives | `packages/ui` |
+| Side overlay | `Sheet` / `Drawer` (NOT toast — `exxat-no-toast.mdc`) | `packages/ui` |
+| Persistent banner | `LocalBanner` / `SystemBanner` | `packages/ui` |
+| Inline status / format hint | `FormDescription`, inline `<small>` | `packages/ui` |
+| Tooltip | `Tip` / `Tooltip` | `packages/ui` |
+| Keyboard shortcut hint | `Kbd` (`variant="bare"` inside buttons) | `packages/ui` |
+| Global search | `CommandMenu` (⌘K) | `apps/web/components/command-menu.tsx` |
+| AI assistant chrome | Ask Leo side panel (⌘⌥K) | `apps/web/components/` |
+
+For a fuller decision tree see [`docs/component-selection-guide.md`](https://github.com/ExxatDesign/Exxat-DS-Workspace/blob/main/apps/web/docs/component-selection-guide.md).
+
+---
+
+## 6. The shortest accessibility checklist
+
+Run this on every PR. If you can't tick every box, the change isn't ready. (Full list: `.cursor/skills/exxat-accessibility/SKILL.md` and [`AGENTS.md` §8](https://github.com/ExxatDesign/Exxat-DS-Workspace/blob/main/AGENTS.md).)
+
+- [ ] **Keyboard.** Every interactive thing reachable via Tab + activatable via Enter / Space. Focus ring visible (≥ 3:1).
+- [ ] **Touch target ≥ 24×24 CSS px** (or 24 px spacing) per WCAG 2.5.8.
+- [ ] **Icons that mean something** have a text alt — either adjacent label (Case A, `aria-hidden`), or `role="img" + aria-label + Tooltip` (Case B), or `aria-label + Tooltip` on the button (Case C). No silent icons.
+- [ ] **Contrast.** Text ≥ 4.5:1; UI components ≥ 3:1. Don't encode state with color alone — pair with icon or label.
+- [ ] **Format hints are persistent**, never placeholder-only. Use `FormDescription`.
+- [ ] **Dialogs / drawers / sheets** have a `Title` (use `sr-only` if visually hidden).
+- [ ] **Tabs** use `role="tablist"` correctly (no mixed children); composite switchers use `role="toolbar"` instead.
+- [ ] **No toast.** Use banners, inline status, or dialogs (`exxat-no-toast.mdc`).
+- [ ] **HC modes.** Forced-colors and `data-contrast="high"` covered for any fill-only state (progress, gauge, pill).
+
+---
+
+## 7. The "you're done" definition
+
+A hub or screen is **done** when:
+
+1. It uses `PrimaryPageTemplate` + `ListPageTemplate` (or another canonical template).
+2. The data surface is `HubTable` (or, for non-hubs, the right primitive from §5).
+3. KPIs use `KeyMetrics` with `delta` for counts, `description` for prose, ≤ 4 tiles, polarity set correctly.
+4. The §6 accessibility checklist is green.
+5. Copy passes [`docs/voice-and-tone.md`](./voice-and-tone.md).
+6. No new shared primitives were added without `.cursor/rules/exxat-reuse-before-custom.mdc` approval.
+7. The §13 PR-review checklist in [`AGENTS.md`](https://github.com/ExxatDesign/Exxat-DS-Workspace/blob/main/AGENTS.md#section-13) is green.
+
+---
+
+## 8. Where to ask for help
+
+- **Code-level questions** — open the file referenced in a rule's "See also" section.
+- **Pattern-level questions** — open the matching `docs/*-pattern.md`.
+- **"Is this the right approach?"** — read [`.cursor/rules/exxat-reuse-before-custom.mdc`](../../../.cursor/rules/exxat-reuse-before-custom.mdc). If still unsure, ask before building.
+- **AGENTS.md is too long** — that's why this handbook exists. Bring the §-number you're stuck on; we'll split it out.
+
+---
+
+*This file is intentionally short. If you want to add something, ask whether it belongs in a rule, a pattern, a blueprint, or the glossary instead.*

package/consumer-extras/handbook/glossary.md

@@ -0,0 +1,57 @@
+# Exxat DS — Glossary
+
+> Shared vocabulary. When a rule or pattern uses a term in **bold**, it's defined here. Add a term when you find yourself explaining the same word twice in PR review.
+
+| Term | Definition | See also |
+|---|---|---|
+| **Active view** | The currently selected view tab on a hub (table, list, board, dashboard, …). Drives which `HubTableRenderers` entry mounts and what the **Properties drawer** shows in its view-type tile grid. | `exxat-table-properties-drawer.mdc` |
+| **Bare Kbd** | The `<Kbd variant="bare">` rendering — no background, no border, inherits `currentColor` at 70 %. Used inline **inside** a button so the chord doesn't look pasted on. The default `tile` variant is reserved for tooltips and menu shortcut slots. | `exxat-kbd-shortcuts.mdc` |
+| **Blueprint** | Framework-agnostic spec for one UI pattern. Says *what* the pattern is and *what* it must do without committing to React. See `docs/blueprints/`. | `docs/blueprints/README.md` |
+| **Board card** | The kanban-style card surface on a board view. Composed of `ListPageBoardCard` (shell), `ListPageBoardCardTitleRow`, optional `ListPageBoardCardAvatar`, optional badge row with `ListHubStatusBadge` (`surface="board"`), and a body using `BoardCardTwoLineBlock` / `BoardCardIconRow`. | `exxat-board-cards.mdc` |
+| **Brand glow** | The OKLCH-mixed brand tint applied as a soft halo behind a surface (KPI flat band, secondary panel). Not a hard background — the tint **adds**, the underlying surface still reads. | `docs/kpi-flat-band-pattern.md`, `docs/shell-surface-elevation-pattern.md` |
+| **Bulk-actions slot** | The floating action bar that appears when one or more rows are selected in a `HubTable`. Wired via `bulkActionsSlot={(selected) => …}`. | `packages/ui/src/components/data-views/hub-table.tsx` |
+| **Cell pattern** | One column's rendering recipe — built by composing existing primitives (`Badge`, `AvatarInitials`, `ListHubStatusBadge`, `ToggleSwitch`, FA glyphs, `Tip`, `Tooltip`, `DropdownMenu`). The canonical catalog of patterns lives in `apps/web/components/columns-showcase.tsx`; the live demo is at `/columns`. | `docs/reference-implementations.md` |
+| **Centralized list dataset** | The rule that **one** `useTableState` row bag drives **every** view (table, list, board, dashboard, panel, tree, …) on a given hub. No parallel mock arrays per view. | `exxat-centralized-list-dataset.mdc` |
+| **Coach mark** | The onboarding overlay that highlights a UI element and explains it. State managed by `useCoachMark`. Dismissals stick per flow id. | `apps/web/lib/coach-mark-registry.ts` |
+| **Collaboration variant** | The `PageHeader` flavor that exposes the face rail + Invite-people overflow item for shared hubs. | `exxat-collaboration-access.mdc` |
+| **Column def (`ColumnDef`)** | The typed column shape consumed by `DataTable` / `HubTable`. Adding `filter:` to a column auto-generates a filter chip and toolbar dropdown entry. | `packages/ui/src/components/data-table/types.ts` |
+| **Conditional rule** | A `ColumnDef`-level rule that applies a background tint to a cell when its value matches an operator + value (e.g. "score < 60 → red"). Authored in the **Properties drawer**. | `packages/ui/src/components/table-properties/` |
+| **Content rail** | The centered, max-width column the `PrimaryPageTemplate` reserves for primary content. Width comes from the template, not the page; don't override per-page. | `apps/web/components/templates/primary-page-template.tsx` |
+| **DataTable** | The low-level table primitive in `packages/ui`. Mount this **only** outside a hub (drawer-body mini-grids, modal sub-tables). Inside `ListPageTemplate`, use `HubTable`. | `exxat-data-tables.mdc` |
+| **`delta`** | The KPI **count** of change (e.g. `"+5"`, `-3`, `"+12 %"`) on a `MetricItem`. Pass `""` or `0` to suppress the trend chip. Never prose. | `exxat-kpi-trends.mdc` |
+| **`description`** | The KPI **caption** beneath the value and trend row on a `MetricItem`. Use this for prose like `"left + right"` or `"vs last week"`. Never a delta count. | `exxat-kpi-trends.mdc` |
+| **Display options** | Per-table preferences (toolbar search visibility, density, gridlines, pagination toggle, …) that flow through `DataListDisplayOptions`. `HubTable` owns the state by default; the hub client can take it over with `displayOptions` + `onDisplayOptionsChange`. | `packages/ui/src/components/table-properties/` |
+| **Empty state** | The text + icon + (optional) action shown when a view body has zero rows after filters. Distinct from "no data ever" (use `EmptyTableState`) vs "no matches" (filter-aware copy). | `docs/voice-and-tone.md` |
+| **Face rail** | The small overlapping-faces row on a `PageHeader` (collaboration variant) showing collaborators. Click to open the invite drawer. | `exxat-collaboration-access.mdc` |
+| **Filter chip** | The dismissible chip rendered above a `HubTable` body for each active filter. Auto-generated from `ColumnDef.filter`. | `exxat-data-tables.mdc` |
+| **Flat band (KPI)** | `KeyMetrics variant="flat"` — transparent cell, brand glow only, hairline cell borders. The shape used on every primary hub metrics strip. | `exxat-kpi-flat-band.mdc` |
+| **Hairline** | A 1 px border at exactly `--border` color used to separate KPI cells, table cells, surface divisions. Never thicker for hierarchy — use spacing or color instead. | `docs/kpi-flat-band-pattern.md` |
+| **HubTable** | The canonical hub view body. Wraps `useTableState`, the toolbar (search + filter chips + filter dropdown + sort), `TablePropertiesDrawerButton`, view-type tiles, bulk-actions, and conditional rules. Always use this inside `ListPageTemplate.renderContent`. | `exxat-data-tables.mdc` |
+| **Hub primitive** | Synonym for `HubTable` — the single primitive that produces a "hub-shaped" view body. | same |
+| **Inspector** | A side-anchored drawer that shows a single record's details without leaving the hub. Resolved against the same `tableState.rows` as the grid. | `exxat-centralized-list-dataset.mdc` |
+| **`KeyMetrics`** | The KPI strip / band component. Accepts `MetricItem[]` (≤ 4) and a single `MetricInsight`. Use `variant="flat"` on hubs; `variant="card"` for embedded analytics cards. | `exxat-kpi-flat-band.mdc`, `exxat-kpi-max-four.mdc` |
+| **KPI strip** | The horizontal KPI row at the top of a hub. ≤ 4 tiles. | `exxat-kpi-max-four.mdc` |
+| **Lifecycle tab label** | The string shown under "Properties" in the drawer header (e.g. "Placements", "Team"). Set on `HubTable.lifecycleTabLabel`. | `packages/ui/src/components/table-properties/drawer-button.tsx` |
+| **List hub status badge** | The shared status chip + icon used everywhere status appears (table rows, board cards, list rows). Colors and icons live in `lib/list-status-badges.ts`. `surface="table"` for grid; `surface="board"` for cards. | `exxat-board-cards.mdc` |
+| **List page template** | The hub frame component. Owns the page header slot, metrics strip slot, view-tabs row, and the `renderContent(tab, updateTab)` body callback. | `packages/ui/src/components/templates/list-page.tsx` |
+| **Mono ID** | A system-generated identifier shown in `font-mono tabular-nums` so digits align and the ID is visibly distinct from prose. Mono **only** the ID token in a mixed line. | `exxat-mono-ids.mdc` |
+| **OKLCH** | The perceptually uniform color space used by the brand-tint mix and the glow tokens. Surfaces stack: page → secondary panel → sidebar. | `docs/shell-surface-elevation-pattern.md` |
+| **Pattern** | Long-form narrative that explains a UI behavior in prose: when to use it, how it composes, anti-patterns, references. Lives in `docs/*-pattern.md`. Complements (but doesn't replace) a blueprint or rule. | `docs/HANDBOOK.md` |
+| **`PrimaryPageTemplate`** | The page chrome: breadcrumbs, site header, content rail with the project's standard max-width. Wrap every primary route in this. | `apps/web/components/templates/primary-page-template.tsx` |
+| **Progressive disclosure** | The principle that complexity is exposed only when the user opts into it. KPIs default visible, filters default folded into the toolbar, conditional rules live in the Properties drawer, etc. | `docs/HANDBOOK.md` §1 |
+| **Properties drawer** | The right-side `Sheet` opened from the table toolbar, hosting view-type tiles, column visibility, density, sort, group-by, filters, conditional rules, and pagination toggle. Mounted automatically by `HubTable`. | `exxat-table-properties-drawer.mdc` |
+| **Reference page** | A canonical full implementation of a hub or pattern in `apps/web/components/<entity>-*.tsx`. Listed in `docs/reference-implementations.md`. Copy from these before inventing. | `docs/reference-implementations.md` |
+| **Rule (binding)** | A `.cursor/rules/*.mdc` doc with MUST / MUST NOT. Binds the AI agent and the human reviewer. Wins over patterns and narratives. | `docs/HANDBOOK.md` §4 |
+| **Secondary panel** | A scoped navigation rail (e.g. "Question bank → All / Mine / Tree", "Tokens & themes → Colors / Radius / Motion / …") that sits between the main sidebar and the page. Opening one collapses the main sidebar; closing one restores the previous sidebar state. | `exxat-primary-nav-secondary-panel.mdc` |
+| **Site header** | The top bar on a primary route (org/product switcher + breadcrumbs + actions). Owned by `PrimaryPageTemplate`. | `apps/web/components/templates/primary-page-template.tsx` |
+| **Skill** | A `.cursor/skills/<name>/SKILL.md` (mirrored in `.claude/skills/`) workflow + checklist for a recurring agent task. Use a skill when the same checklist would be repeated across many sessions. | `apps/web/AGENTS.md` |
+| **`supportedViewTypes`** | The allowlist of `DataListViewType` values a hub implements. Passed to `HubTable.supportedViewTypes` so the Properties drawer never offers a view the hub can't render. | `packages/ui/src/components/data-views/hub-table.tsx` |
+| **Trend polarity** | `MetricItem.trendPolarity` says whether "up" is good (`higher_is_better`, default), bad (`lower_is_better`), or value-neutral (`informational`). The arrow's tint follows the polarity, not the sign. | `exxat-kpi-trends.mdc` |
+| **`useTableState`** | The state hook that owns rows, filters, search, sort, pagination, group-by, and column visibility. Always one instance per hub. | `exxat-centralized-list-dataset.mdc` |
+| **View tab** | A tab on `ListPageTemplate` representing one view of the same dataset (table, list, board, dashboard, folder, panel, tree, …). Each tab carries a `viewType` and the `renderContent` callback receives it. | `exxat-list-page-connected-views.mdc` |
+| **View type (`DataListViewType`)** | The enum of view shapes the design system supports — `"table" \| "list" \| "board" \| "dashboard" \| "folder" \| "panel" \| "tree"`. Each tab declares one. | `apps/web/lib/data-list-view.ts` |
+| **Voice & tone** | The microcopy rules for the product: empty states, errors, banners, buttons, validation. See `docs/voice-and-tone.md`. | `docs/voice-and-tone.md` |
+
+---
+
+*Missing a term? Add it. Glossary entries are short — link to the rule or pattern for depth, don't restate it here.*

package/consumer-extras/handbook/reference-implementations.md

@@ -0,0 +1,126 @@
+# Exxat DS — Reference implementations
+
+> When a rule says "see Placements" or "see Team", **this is the index**. Open the file. Copy. Don't reinvent.
+
+Reference pages are the **canonical working implementations** of a pattern. They're the source of truth that rules + blueprints summarize. If a rule conflicts with a reference page, the bug is in the rule — open a PR.
+
+---
+
+## How to use this page
+
+1. Find the row that matches the pattern you're building.
+2. Open the **Reference page** column — that file is the template.
+3. Read the linked **Blueprint** for the framework-agnostic spec.
+4. Read the linked **Rule** for the binding MUST / MUST NOT.
+5. Read the linked **Pattern** for the long-form "why".
+
+If you find yourself diverging from the reference page, ask **why** before shipping.
+
+---
+
+## Primary hubs
+
+| Pattern | Reference page | Blueprint | Rule(s) | Pattern doc |
+|---|---|---|---|---|
+| Full hub: table + board + dashboard + list + paginated + conditional rules + dashboard customize | `apps/web/components/placements-table.tsx` + `placements-client.tsx` | [`list-page-template`](https://github.com/ExxatDesign/Exxat-DS-Workspace/blob/main/apps/web/docs/blueprints/list-page-template.md), [`data-table`](https://github.com/ExxatDesign/Exxat-DS-Workspace/blob/main/apps/web/docs/blueprints/data-table.md), [`board-card`](https://github.com/ExxatDesign/Exxat-DS-Workspace/blob/main/apps/web/docs/blueprints/board-card.md), [`key-metrics`](https://github.com/ExxatDesign/Exxat-DS-Workspace/blob/main/apps/web/docs/blueprints/key-metrics.md) | [`exxat-data-tables`](../../../.cursor/rules/exxat-data-tables.mdc), [`exxat-list-page-connected-views`](../../../.cursor/rules/exxat-list-page-connected-views.mdc), [`exxat-centralized-list-dataset`](../../../.cursor/rules/exxat-centralized-list-dataset.mdc) | [`data-views-pattern`](../data-views-pattern.md) |
+| Hub with dashboard customize (canvas layout edit) | `apps/web/components/team-table.tsx` + `team-client.tsx` | [`list-page-template`](https://github.com/ExxatDesign/Exxat-DS-Workspace/blob/main/apps/web/docs/blueprints/list-page-template.md), [`key-metrics`](https://github.com/ExxatDesign/Exxat-DS-Workspace/blob/main/apps/web/docs/blueprints/key-metrics.md) | [`exxat-list-page-connected-views`](../../../.cursor/rules/exxat-list-page-connected-views.mdc) | [`data-views-pattern`](../data-views-pattern.md) |
+| Hub with finder / split-panel view | `apps/web/components/sites-table.tsx` + `sites-client.tsx` | [`list-page-template`](https://github.com/ExxatDesign/Exxat-DS-Workspace/blob/main/apps/web/docs/blueprints/list-page-template.md) | [`exxat-list-page-view-shells`](../../../.cursor/rules/exxat-list-page-view-shells.mdc) | [`data-views-pattern`](../data-views-pattern.md) |
+| Hub with secondary panel scope (folder rail) | `apps/web/components/question-bank-table.tsx` + `question-bank-client.tsx` | [`list-page-template`](https://github.com/ExxatDesign/Exxat-DS-Workspace/blob/main/apps/web/docs/blueprints/list-page-template.md) | [`exxat-primary-nav-secondary-panel`](../../../.cursor/rules/exxat-primary-nav-secondary-panel.mdc), [`exxat-question-bank-hub-header`](../../../.cursor/rules/exxat-question-bank-hub-header.mdc) | [`question-bank-hub-header-pattern`](https://github.com/ExxatDesign/Exxat-DS-Workspace/blob/main/apps/web/docs/question-bank-hub-header-pattern.md) |
+| Hub with secondary panel scope (token categories) — **smallest** secondary-panel reference | `apps/web/components/tokens-themes-client.tsx` + `tokens-secondary-nav.tsx` | [`list-page-template`](https://github.com/ExxatDesign/Exxat-DS-Workspace/blob/main/apps/web/docs/blueprints/list-page-template.md) | [`exxat-primary-nav-secondary-panel`](../../../.cursor/rules/exxat-primary-nav-secondary-panel.mdc) | [`shell-surface-elevation-pattern`](../shell-surface-elevation-pattern.md) |
+| Single-view showcase hub (table only) — **18 SaaS cell patterns**: select, primary identity + ID + favorite, avatar + name + email, avatar group with +N, type pill, difficulty signal, status chip, inline toggle, tag list, rating stars, progress bar, currency, plain numeric, attachment count, external link, relative time, absolute date, row actions overflow | `apps/web/components/columns-showcase.tsx` + `columns-client.tsx` | [`list-page-template`](https://github.com/ExxatDesign/Exxat-DS-Workspace/blob/main/apps/web/docs/blueprints/list-page-template.md), [`data-table`](https://github.com/ExxatDesign/Exxat-DS-Workspace/blob/main/apps/web/docs/blueprints/data-table.md) | [`exxat-data-tables`](../../../.cursor/rules/exxat-data-tables.mdc) | — |
+
+> **First-time hub builder:** start with `sites-table.tsx` (smallest complete hub) or `columns-showcase.tsx` (single-view, easiest).
+
+---
+
+## Hub chrome
+
+| Pattern | Reference page | Blueprint | Rule(s) |
+|---|---|---|---|
+| Page header — primary hub | `apps/web/components/placements-page-header.tsx` | [`page-header`](https://github.com/ExxatDesign/Exxat-DS-Workspace/blob/main/apps/web/docs/blueprints/page-header.md) | [`exxat-collaboration-access`](../../../.cursor/rules/exxat-collaboration-access.mdc), [`exxat-mono-ids`](../../../.cursor/rules/exxat-mono-ids.mdc) |
+| Page header — collaboration variant (face rail + invite) | `apps/web/components/question-bank-page-header.tsx` | [`page-header`](https://github.com/ExxatDesign/Exxat-DS-Workspace/blob/main/apps/web/docs/blueprints/page-header.md) | [`exxat-collaboration-access`](../../../.cursor/rules/exxat-collaboration-access.mdc) |
+| Page header — entity / record (no view tabs) | `apps/web/components/page-header.tsx` (variants) | [`page-header`](https://github.com/ExxatDesign/Exxat-DS-Workspace/blob/main/apps/web/docs/blueprints/page-header.md) | — |
+| KPI flat band on a hub | `apps/web/components/placements-client.tsx` | [`key-metrics`](https://github.com/ExxatDesign/Exxat-DS-Workspace/blob/main/apps/web/docs/blueprints/key-metrics.md) | [`exxat-kpi-flat-band`](../../../.cursor/rules/exxat-kpi-flat-band.mdc), [`exxat-kpi-max-four`](../../../.cursor/rules/exxat-kpi-max-four.mdc), [`exxat-kpi-trends`](../../../.cursor/rules/exxat-kpi-trends.mdc) |
+| Properties drawer wiring | `apps/web/components/placements-table.tsx` | — | [`exxat-table-properties-drawer`](../../../.cursor/rules/exxat-table-properties-drawer.mdc) |
+| Export drawer + ⋯ menu | `apps/web/components/placements-page-header.tsx` + `export-drawer.tsx` | — | [`exxat-drawer-vs-dialog`](../../../.cursor/rules/exxat-drawer-vs-dialog.mdc) |
+
+---
+
+## Board, list, dashboard views
+
+| Pattern | Reference page | Blueprint | Rule(s) |
+|---|---|---|---|
+| Board card (kanban) | `apps/web/components/placements-board-view.tsx`, `team-table.tsx` (`renderListRow`) | [`board-card`](https://github.com/ExxatDesign/Exxat-DS-Workspace/blob/main/apps/web/docs/blueprints/board-card.md) | [`exxat-board-cards`](../../../.cursor/rules/exxat-board-cards.mdc), [`exxat-card-vs-list-rows`](../../../.cursor/rules/exxat-card-vs-list-rows.mdc) |
+| List row (single-column) | `apps/web/components/team-table.tsx` `renderListRow` | [`board-card`](https://github.com/ExxatDesign/Exxat-DS-Workspace/blob/main/apps/web/docs/blueprints/board-card.md) (row layout) | [`exxat-card-vs-list-rows`](../../../.cursor/rules/exxat-card-vs-list-rows.mdc) |
+| Dashboard view with charts + KPI band | `apps/web/components/placements-dashboard-charts-section.tsx` | [`key-metrics`](https://github.com/ExxatDesign/Exxat-DS-Workspace/blob/main/apps/web/docs/blueprints/key-metrics.md) | [`exxat-dashboard-view-charts`](../.cursor/rules/exxat-dashboard-view-charts.mdc) |
+| Folder / finder split view | `apps/web/components/data-views/finder-panel-view.tsx` (used in `sites-table.tsx`) | — | [`exxat-list-page-view-shells`](../../../.cursor/rules/exxat-list-page-view-shells.mdc) |
+
+---
+
+## Search
+
+| Pattern | Reference page | Rule(s) | Pattern doc |
+|---|---|---|---|
+| Global command palette (⌘K) | `apps/web/components/command-menu.tsx` + `lib/command-menu-config.ts` | [`exxat-command-menu`](../../../.cursor/rules/exxat-command-menu.mdc) | [`command-menu-pattern`](../command-menu-pattern.md) |
+| Dedicated search (landing + results) | `apps/web/components/dedicated-search-*.tsx` | [`exxat-dedicated-search-surfaces`](../../../.cursor/rules/exxat-dedicated-search-surfaces.mdc) | — |
+| In-table search (toolbar) | wired by `HubTable` automatically | [`exxat-data-tables`](../../../.cursor/rules/exxat-data-tables.mdc) | [`data-views-pattern`](../data-views-pattern.md) |
+
+---
+
+## Collaboration
+
+| Pattern | Reference page | Rule(s) | Pattern doc |
+|---|---|---|---|
+| Face rail + invite drawer | `apps/web/components/collaboration-access-flow.tsx`, `invite-collaborators-drawer.tsx` | [`exxat-collaboration-access`](../../../.cursor/rules/exxat-collaboration-access.mdc) | [`collaboration-access-pattern`](../collaboration-access-pattern.md) |
+
+---
+
+## Overlays and confirmations
+
+| Pattern | Reference page | Rule(s) | Pattern doc |
+|---|---|---|---|
+| Side drawer (long auxiliary flow) | `apps/web/components/export-drawer.tsx`, `invite-collaborators-drawer.tsx`, `apps/web/components/table-properties/drawer.tsx` | [`exxat-drawer-vs-dialog`](../../../.cursor/rules/exxat-drawer-vs-dialog.mdc), [`exxat-page-vs-drawer`](../../../.cursor/rules/exxat-page-vs-drawer.mdc) | [`drawer-vs-dialog-pattern`](https://github.com/ExxatDesign/Exxat-DS-Workspace/blob/main/apps/web/docs/drawer-vs-dialog-pattern.md) |
+| Dialog (blocking short confirm / destructive) | `apps/web/components/ui/alert-dialog.tsx` consumers (search `<AlertDialog`) | [`exxat-drawer-vs-dialog`](../../../.cursor/rules/exxat-drawer-vs-dialog.mdc) | [`drawer-vs-dialog-pattern`](https://github.com/ExxatDesign/Exxat-DS-Workspace/blob/main/apps/web/docs/drawer-vs-dialog-pattern.md) |
+| Coach mark / onboarding | `apps/web/lib/coach-mark-registry.ts` consumers (Placements dashboard customize) | — | — |
+
+---
+
+## Settings, tokens, themes
+
+| Pattern | Reference page | Rule(s) |
+|---|---|---|
+| Settings page (preferences + sections) | `apps/web/app/(app)/settings/page.tsx` | — |
+| Tokens & themes hub (secondary panel + categories + visualizers) | `apps/web/components/tokens-themes-client.tsx`, `tokens-themes-section.tsx`, `tokens-secondary-nav.tsx` | [`exxat-token-discipline`](../../../.cursor/rules/exxat-token-discipline.mdc), [`exxat-primary-nav-secondary-panel`](../../../.cursor/rules/exxat-primary-nav-secondary-panel.mdc) |
+
+---
+
+## Anti-references (what NOT to copy)
+
+These exist but are **not** canonical. They predate a rule, are scoped to a one-off, or use a legacy primitive. **Don't copy from them.**
+
+| Anti-reference | Why not | What to use instead |
+|---|---|---|
+| Raw `<DataTable>` mounted directly in `ListPageTemplate.renderContent` (historical) | Loses filter chips + Properties drawer; users lose discoverability | `HubTable` (see Sites / Placements / Tokens / Columns refs) |
+| Custom search input above a `DataTable` | `HubTable`'s toolbar already does this; duplicating leads to drift | Configure `ColumnDef.filter` + use `HubTable` |
+| `toast()` / Sonner / snackbar | Forbidden — see [`exxat-no-toast.mdc`](../../../.cursor/rules/exxat-no-toast.mdc) | `LocalBanner` / `SystemBanner` or inline status |
+| Negative-margin overlapping avatars | Forbidden — see [`exxat-person-identity-display.mdc`](../../../.cursor/rules/exxat-person-identity-display.mdc) | `AvatarGroup` (gapped by default) |
+
+---
+
+## Adding a new reference page
+
+If you build a pattern that **other hubs will copy**, list it here. A reference page is canonical when:
+
+1. It satisfies the matching blueprint or rule end-to-end.
+2. It passes the §13 PR-review checklist in [`AGENTS.md`](https://github.com/ExxatDesign/Exxat-DS-Workspace/blob/main/AGENTS.md).
+3. The file has a top-level doc comment that names what it's the reference for (e.g. *"Sites hub — thin wrapper around `<HubTable>`. Owns only the column defs, renderers for non-table views, and the mock-data wiring."*).
+4. The matching rule's "Reference implementations" list points back to it.
+
+---
+
+## See also
+
+- [`HANDBOOK.md`](./HANDBOOK.md) — start-here doc map
+- [`blueprints/README.md`](https://github.com/ExxatDesign/Exxat-DS-Workspace/blob/main/apps/web/docs/blueprints/README.md) — what a blueprint is
+- [`component-selection-guide.md`](https://github.com/ExxatDesign/Exxat-DS-Workspace/blob/main/apps/web/docs/component-selection-guide.md) — decision tree across blueprints
+- [`apps/web/AGENTS.md` §13](https://github.com/ExxatDesign/Exxat-DS-Workspace/blob/main/AGENTS.md) — full PR-review checklist