@exxatdesignux/ui 0.5.10 → 0.5.12

package/template/docs/card-vs-rows-pattern.md

@@ -1,36 +0,0 @@
-# Cards vs table rows vs list rows
-
-> **Related:** **`AGENTS.md` §4–§5**, **`.cursor/rules/exxat-data-tables.mdc`**, **`.cursor/rules/exxat-board-cards.mdc`**, **`docs/data-views-pattern.md`**.
-
-## When to use **rows** (table or dense list)
-
-- **Many similar records** (roughly **10+**) where users **scan**, **sort**, **filter**, and **compare columns**.
-- **Same fields** across entities — columns align; export and **TablePropertiesDrawer** apply.
-- **Primary hub** pattern — **`DataTable`** + **`ListPageTemplate`** per **`exxat-data-tables`**.
-
-**Use:** `DataTable`, shared toolbar, row actions, pinned columns.
-
-## When to use **cards** (tile / board / marketing)
-
-- **Lower cardinality** or **visual-first** browsing — folders, dashboards, “pick a template”, hero metrics beside a chart.
-- **Heterogeneous content** — each card has a different layout (title, badge, avatar, two-line body) where a rigid grid of columns would fight the design.
-- **Kanban** — **`ListPageBoardCard`** + column model; still fed by **`tableState.rows`**.
-
-**Use:** `ListPageBoardCard`, `ChartCard`, icon grids under **`ListPageViewFrame`**, dashboard chart tiles.
-
-## When to use **list rows** (not full DataTable)
-
-- **Medium density** — fewer columns than a grid; reading order is **vertical** (timeline, activity, simple roster without heavy operators).
-- Still wire **search** when the list is the main surface and item count grows.
-
-**Prefer** graduating to **`DataTable`** once the hub needs filters, column hide, density, or export parity with other list hubs.
-
-## Anti-patterns
-
-- **Cards for 50+ homogeneous records** when the product expects sort/filter/compare — that belongs in **`DataTable`**.
-- **A second bespoke “table”** alongside **`DataTable`** for the same dataset — extend the table stack instead (**`exxat-centralized-list-dataset`**).
-- **Raw `<table>`** for product data lists — forbidden (**`exxat-data-tables`**).
-
-## See also
-
-- **`.cursor/rules/exxat-card-vs-list-rows.mdc`**, **`.cursor/skills/exxat-card-vs-list-rows/SKILL.md`**

package/template/docs/collaboration-access-pattern.md

@@ -1,116 +0,0 @@
-# Collaboration & access pattern
-
-Shared UI for **who can access a hub** (face stack in the header) and **inviting people** (floating sheet). **Reference:** Library — `LibraryPageHeader`, `LibraryClient`, `InviteCollaboratorsDrawer`.
-
-**Folder-scoped library:** When the library URL selects a folder (`?scope=folder&folderId=`), the same header **⋯ More** menu also exposes **Customize folder** (name / color / icon) via **`LibraryNewFolderSheet`** mounted on **`LibraryClient`** so it works on every view tab. See **`docs/library-hub-header-pattern.md`** and **`.cursor/rules/exxat-library-hub-header.mdc`**.
-
-## When to use
-
-- A list hub or library is **shared** across people (not a private directory).
-- Users need to see **who has access**, **invite by email**, and assign **library access** (Owner / Editor / Commenter / Viewer).
-- The hub already uses **`ListPageTemplate`** + **`PageHeader`** (or an entity header built on it).
-
-**Do not** use this for org-wide **role** administration (Faculty, Program coordinator, Director) as the only story — those are **directory role tags** on people, not library access.
-
-## Vocabulary
-
-| Concept | Meaning | Source |
-|--------|---------|--------|
-| **Library access** | What someone can do **in this hub** (Owner, Editor, Commenter, Viewer) | `lib/collaborator-access.ts` |
-| **Directory roles** | Org/job tags on a person (Faculty, Program coordinator, Director) | `PageHeaderCollaborator.roles` |
-| **Face rail** | Overlapping avatars in the header when the roster is non-empty | `PageHeader` `variant="collaboration"` |
-| **Empty roster CTA** | Outline **Add collaborator** in the header when `collaborators` is empty | `PageHeader` + `COLLABORATION_HEADER_ADD_LABEL` |
-| **Invite sheet** | Floating right **`Sheet`** for roster + invite form | `InviteCollaboratorsDrawer` |
-| **Hub wiring** | Roster state + invite sheet in one render-prop shell | `CollaborationAccessFlow` |
-
-## Header (`PageHeader`)
-
-- Set **`variant="collaboration"`**.
-- Pass **`collaborators`** (`PageHeaderCollaborator[]`) and optional **`accessInfo`**.
-- **Non-empty roster** — overlapping **face rail** only; each face and **`+N`** open the invite sheet via **`onCollaboratorsOpen`**.
-- **Empty roster** — outline **`Add collaborator`** (`addCollaboratorLabel`, default **`COLLABORATION_HEADER_ADD_LABEL`**) opens the same sheet.
-- **Invite** also lives under **⋯ More** on the entity page header (first item when `variant="collaboration"`).
-
-```tsx
-<CollaborationAccessFlow
-  initialCollaborators={LIBRARY_HEADER_COLLABORATORS}
-  resourceLabel={hubHeader.title}
->
-  {({ collaborators, openInvite }) => (
-    <LibraryPageHeader
-      variant="collaboration"
-      title={hubHeader.title}
-      questionCount={count}
-      collaborators={collaborators}
-      onAddCollaborator={openInvite}
-      onCollaboratorsOpen={openInvite}
-      onExport={() => setExportOpen(true)}
-      showMetrics={showMetrics}
-      onToggleMetrics={() => setShowMetrics(v => !v)}
-    />
-  )}
-</CollaborationAccessFlow>
-```
-
-## Hub client state
-
-- Prefer **`CollaborationAccessFlow`** — owns **`collaborators`**, **`openInvite`**, and **`InviteCollaboratorsDrawer`**; pass **`openInvite`** to **`onAddCollaborator`** / **`onCollaboratorsOpen`**.
-- Without the flow: **`collaborators`** — `useState` seeded from `lib/mock/<entity>-header-collaborators.ts` (or API later); **`inviteOpen`** — boolean; mount **`InviteCollaboratorsDrawer`** beside **`ListPageTemplate`**.
-- On invite success, append to **`collaborators`** so the **face rail** and sheet roster stay aligned.
-- **Change access** — roster menu updates **`collaborators`** via **`onCollaboratorAccessChange`** ( **`CollaborationAccessFlow`** default).
-- **Remove access** — confirm dialog then **`onCollaboratorRemove`**; blocked for the only **Owner**.
-
-## `PageHeaderCollaborator`
-
-| Field | Use |
-|-------|-----|
-| `id`, `name`, `imageUrl`, `initials` | Face rail + roster row |
-| `email` | Roster (below name); invite form |
-| `access` | Library access badge (Owner … Viewer) |
-| `roles` | Optional **outline** chips (Faculty, Program coordinator, Director) |
-
-## Invite sheet (`InviteCollaboratorsDrawer`)
-
-Mirror **`ExportDrawer`** chrome: floating **`Sheet`**, no overlay, **`showCloseButton={false}`**, footer **Cancel** / **Send invite** with inline **`Kbd`** (**Esc** / **⏎**), **`Shortcut`** for Enter on the open surface.
-
-**Invite field:** one bordered row — email input + **access** menu on the right.
-
-- Use **`Select`** with **`SelectGroup`** for access (invite row in **`InputGroupAddon`**, roster row standalone); **`position="popper"`** inside the sheet; **no** toast on success (**§6.5**).
-
-**People with access:** one **`rounded-lg border`** list with **`divide-y`** — **not** one card per person.
-
-Row order:
-
-1. **Name** (`text-sm font-medium`)
-2. **Email** (`text-xs text-muted-foreground`)
-3. **Role tags** (`Badge variant="outline"`) when `roles` is set
-4. Trailing **library access** **`Select`** when the hub wires **`onCollaboratorAccessChange`**; **Remove access** (trash) opens a confirm **`Dialog`** when **`onCollaboratorRemove`** is set. The sole **Owner** cannot be removed or demoted until another owner exists.
-
-## Library access constants
-
-- Types and invite options: **`lib/collaborator-access.ts`**
-- **`INVITE_COLLABORATOR_ACCESS_OPTIONS`** — Editor / Commenter / Viewer (no Owner on invite)
-- Customize option **descriptions** per hub; keep **values** stable for forms/API
-
-## File map
-
-| Piece | Path |
-|-------|------|
-| Access types | `lib/collaborator-access.ts` |
-| Hub flow | `components/collaboration-access-flow.tsx` |
-| Collaborator type | `components/page-header.tsx` (`PageHeaderCollaborator`) |
-| Invite sheet | `components/invite-collaborators-drawer.tsx` |
-| Entity header | `components/library-page-header.tsx` |
-| Hub wiring | `components/library-client.tsx` |
-| Demo roster | `lib/mock/library-header-collaborators.ts` |
-
-## Checklist (new hub)
-
-- [ ] `PageHeader` / entity header uses **`variant="collaboration"`** when the product is shared.
-- [ ] **Empty roster** shows **Add collaborator**; **non-empty** shows face rail; both open the invite sheet.
-- [ ] **Invite people** under **⋯ More**; **`CollaborationAccessFlow`** (or equivalent) owns roster + sheet.
-- [ ] Roster: single bordered list; **name → email → role tags**; access badge on the right.
-- [ ] Invite row: email + access menu; **`FormDescription`** for format; **no** toast.
-- [ ] Labels from **`collaborator-access.ts`**; mock/API rows extend **`PageHeaderCollaborator`** once.
-
-**Handbook:** `AGENTS.md` §4.7 · **Rule:** `.cursor/rules/exxat-collaboration-access.mdc` · **Skill:** `.cursor/skills/exxat-collaboration-access/SKILL.md`

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

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

package/template/docs/component-selection-guide.md

@@ -1,224 +0,0 @@
-# Exxat DS — Component Selection Guide
-
-**Audience:** humans + AI agents. **Companion to:** [`token-taxonomy.md`](./token-taxonomy.md), [`blueprints/`](./blueprints/).
-
-When you're about to build a UI, **start here**. Follow the decision tree
-to find the right composition before you write any markup. The rule is
-always: **compose existing components first**; only create a new shared
-primitive after asking the user
-([`exxat-reuse-before-custom.mdc`](../../.cursor/rules/exxat-reuse-before-custom.mdc)).
-
----
-
-## 0. Quick chart
-
-```
-                ┌─────────────────────────────────────┐
-                │ What is the surface?               │
-                └──┬──────────────────────────────────┘
-                   │
-       ┌───────────┴────────────────────────────┐
-       │                                        │
-   PRIMARY HUB                               OVERLAY / SECONDARY
-   (route w/ many records,                   (on top of a hub,
-   filters, properties)                      modal task, side panel)
-       │                                        │
-       │                                        ▼
-       │                                  See § 3
-       ▼
-   See § 1
-```
-
----
-
-## 1. Building a primary hub (route with records)
-
-```
-   Q: Is the data > ~10 comparable records?
-   ─────────────────────────────────────────
-   │ yes ──────────────────────────────► DataTable inside ListPageTemplate (§1.1)
-   │ no  ──┬─ all rows shown at once?
-   │       │ yes ── simple `<dl>` / card list (no Properties / Filters needed)
-   │       │ no  ── still use DataTable — future growth is expected
-   └─────►
-```
-
-### 1.1 DataTable hub (canonical)
-
-| Need | Use |
-|---|---|
-| Browsable grid | **`DataTable`** + **`useTableState`** ([blueprint](./blueprints/data-table.md)) |
-| View tabs (table/list/board/dashboard) | **`ListPageTemplate`** + connected views ([`exxat-list-page-connected-views.mdc`](../../.cursor/rules/exxat-list-page-connected-views.mdc)) |
-| Column/density/properties | **`TablePropertiesDrawer`** (pass `currentView` + `onViewChange`) |
-| Filters | Shared `FilterFieldDef` chips |
-| Find-in-list | Toolbar search (`⌘K`) |
-| Metrics strip | **`KeyMetrics`** `variant="flat"` ([`kpi-flat-band-pattern.md`](./kpi-flat-band-pattern.md)) — **max 4 tiles** ([`exxat-kpi-max-four.mdc`](../../.cursor/rules/exxat-kpi-max-four.mdc)) |
-| Export | Filled primary CTA + `⋯` → `ExportDrawer` |
-| Kanban view body | **`ListPageBoardCard`** + `ListPageBoardTemplate` ([`exxat-board-cards.mdc`](../../.cursor/rules/exxat-board-cards.mdc)) |
-| Folder / panel view body | **`FolderGridView`** / **`FinderPanelView`** wrapped in **`ListPageViewFrame`** ([`exxat-list-page-view-shells.mdc`](../../.cursor/rules/exxat-list-page-view-shells.mdc)) |
-| Dashboard view body | **`KeyMetrics variant="card"`** + a hub-specific chart section (reference: `library-dashboard-charts.tsx`) |
-| Nested scope nav (All / Mine / tree) | **`secondaryPanel`** + `PANELS` + `useAutoPanel` ([`exxat-primary-nav-secondary-panel.mdc`](../../.cursor/rules/exxat-primary-nav-secondary-panel.mdc)) |
-| Shared hub w/ invite | **`PageHeader` `variant="collaboration"`** + `InviteCollaboratorsDrawer` |
-| Dedicated search (empty `?q=` vs results) | **`DedicatedSearchLandingTemplate`** + **`DedicatedSearchResultsHeaderChrome`** |
-
-**Reference:** `PlacementsClient` (Placements) is the most complete example.
-
-### 1.2 Visual-browse hub (kanban / gallery)
-
-If the product wants a **kanban-first** experience and the table is the
-fallback rather than primary:
-
-```
-ListPageTemplate
-├── PageHeader
-├── KeyMetrics (optional, ≤4)
-└── viewType="board" → ListPageBoardTemplate + ListPageBoardCard
-```
-
-Even here, **back the board with `useTableState`** so switching to the table
-tab is consistent. Don't fork the data.
-
----
-
-## 2. Naming a card / row / list
-
-| Pattern | What to reach for |
-|---|---|
-| Dense comparable rows | `DataTable` row (don't card-wall it — see [`card-vs-rows-pattern.md`](./card-vs-rows-pattern.md)) |
-| Kanban column card | `ListPageBoardCard` + `BoardCardTwoLineBlock` + `BoardCardIconRow` |
-| OS-folder grid | `FolderGridView` in `ListPageViewFrame` |
-| Finder split (list + preview) | `FinderPanelView` |
-| Sidebar nav row | `SidebarMenuButton` (do not roll your own) |
-| KPI tile | `KeyMetrics` `MetricItem` — never a custom `Card` w/ number |
-| Coach mark tile | `CoachMark` step — never an ad-hoc onboarding popover |
-
----
-
-## 3. Same-route overlay vs new route
-
-Always ask: **does the user need the hub visible behind them?**
-
-```
-                ┌────────────────────────────┐
-                │ Does the user need the hub │
-                │   visible behind them?     │
-                └─────────────┬──────────────┘
-                              │
-              ┌───── YES ─────┴───── NO ─────┐
-              ▼                              ▼
-        Same route                     New route
-       (overlay)                     (own URL)
-              │                              │
-        ┌─────┴──────┐                       │
-        │ Is the task│                       │
-        │   short +  │                       │
-        │  blocking? │                       │
-        └─────┬──────┘                       │
-              │                              │
-        ┌─ YES ┴ NO ──┐                      │
-        ▼              ▼                      ▼
-     Dialog        Sheet panel            Page route
-   (AlertDialog,  (TablePropertiesDrawer,  (full create/edit
-   delete confirm)  ExportDrawer,           wizard, deep detail)
-                   InviteCollaboratorsDrawer)
-```
-
-See [`drawer-vs-dialog-pattern.md`](./drawer-vs-dialog-pattern.md) and
-[`exxat-page-vs-drawer.mdc`](../../.cursor/rules/exxat-page-vs-drawer.mdc).
-
----
-
-## 4. Search / Find / Command
-
-| Need | Use | Shortcut |
-|---|---|---|
-| Find inside a table | `DataTableToolbar` search | `⌘K` / `Ctrl K` (no Alt) |
-| Find inside a hub (across tabs/views) | Same `⌘K` while focus is on the hub | `⌘K` |
-| Global navigation + AI starter | `CommandMenu` ([`command-menu-pattern.md`](./command-menu-pattern.md)) | `⌘K` while no input has focus |
-| Long AI / chat | `AskLeoSidebar` | `⌘⌥K` |
-| Dedicated search page (results view) | `DedicatedSearchLandingTemplate` + `DedicatedSearchResultsHeaderChrome` | — |
-
----
-
-## 5. Feedback / messaging
-
-| Need | Use |
-|---|---|
-| Persistent banner ("system maintenance") | `SystemBanner` |
-| Per-page contextual info | `LocalBanner` |
-| Per-control success/error | Inline text next to the field |
-| Confirm a destructive action | `AlertDialog` |
-| **Never** | `toast()` / Sonner / snackbars ([`exxat-no-toast.mdc`](../../.cursor/rules/exxat-no-toast.mdc)) |
-
----
-
-## 6. Icons
-
-| Use case | Pattern |
-|---|---|
-| Icon next to a label | FA glyph + `aria-hidden` (Case A) |
-| Icon standing alone (meaning-bearing) | `<span role="img" aria-label="…" tabIndex={0}>` + `Tooltip` (Case B) |
-| Icon-only button / link | `<button aria-label="…">` wrapped in `Tooltip` (Case C) |
-| Product mark | `ExxatProductLogo` |
-| School / org mark | `logoDevUrl()` |
-
-Source: `apps/web/AGENTS.md` §8.6.
-
----
-
-## 7. KPIs / metrics
-
-| Need | Use |
-|---|---|
-| Hub metric strip on top of `ListPageTemplate` | `KeyMetrics variant="flat"` |
-| Dashboard view tab key-metrics card | `KeyMetrics variant="card"` (1–4 tiles) |
-| Chart + mini-metric next to it | `ChartCard` + chart's own KPI helpers |
-| Trend arrow on a metric | Set `MetricItem.trend` to match delta sign; set `trendPolarity` when "up" is bad |
-
-Cap visible KPIs at **4** ([`exxat-kpi-max-four.mdc`](../../.cursor/rules/exxat-kpi-max-four.mdc)).
-
----
-
-## 8. Identifiers and typography
-
-| Carries | Use |
-|---|---|
-| System ID (`questionId`, record key) | `font-mono tabular-nums` ([`exxat-mono-ids.mdc`](../../.cursor/rules/exxat-mono-ids.mdc)) |
-| Page title | `<h1>` with `font-heading` (Ivy Presto) inside `PageHeader` |
-| Body | Default Inter, ≥ 11px (`text-xs` minimum) |
-| Status label | `ListHubStatusBadge` from `lib/list-status-badges.ts` — never raw text |
-| Currency / counts | `tabular-nums` (no `font-mono`) |
-
----
-
-## 9. When NOTHING here fits
-
-You are now in the territory covered by
-[`exxat-reuse-before-custom.mdc`](../../.cursor/rules/exxat-reuse-before-custom.mdc):
-
-1. Re-scan `apps/web/components/`, `packages/ui/src/components/`, and `apps/web/components/data-views/`.
-2. Check `AGENTS.md` §9 architecture table.
-3. If still no fit, **ask the user** with a short option list:
-   - extend an existing primitive (preferred),
-   - add a new component under `components/data-views/` or `components/templates/`,
-   - or open a packaged shared primitive in `packages/ui`.
-
----
-
-## 10. Cheat sheet — one-line rules
-
-- **Data list, > 10 rows** → `DataTable` + `ListPageTemplate`.
-- **Visual browse / kanban** → `ListPageBoardCard`.
-- **Folder / panel / OS-folder view** → `data-views/` primitive in `ListPageViewFrame`.
-- **Quick auxiliary task with hub behind** → drawer.
-- **Blocking short confirm** → dialog.
-- **Primary / long / own-URL flow** → new route.
-- **Global ⌘K** → `CommandMenu` (search + quick AI).
-- **Long AI** → Ask Leo (`⌘⌥K`).
-- **Feedback** → banner / inline / dialog — **never** toast.
-- **Icon-only button** → `aria-label` + `Tooltip` (Case C).
-- **System ID** → `font-mono tabular-nums`.
-- **KPI strip** → ≤ 4 tiles, `variant="flat"` on hubs.
-- **Hex color in code** → no. Use a token.
-
-See also: [`AGENTS.md` §13 checklist](../AGENTS.md) — run it before shipping a hub.

package/template/docs/components-audit-2026-05.md

@@ -1,158 +0,0 @@
-# `apps/web/components/` audit — 2026-05
-
-**Author:** Exxat DS hardening sweep · **Scope:** observation only — no code moved.
-
-This audit was triggered by formalizing the design system (token taxonomy +
-blueprints + selection guide + ESLint guardrails) so that any future
-component refactor has a clear target structure. **No file is moved or
-deleted by this audit itself.** Treat each finding as a follow-up PR
-candidate; bundle them as you like.
-
-## 1. Sizes & shape
-
-| Bucket | Count | Notes |
-|---|---|---|
-| Top-level `components/*.tsx` | **99** | Mix of hub clients, hub tables, hub views, page headers, dashboard charts, sidebar bits, leaf primitives |
-| `components/data-table/` | 5 | Correct — base table stack |
-| `components/data-views/` | 14 | Correct — generic view primitives + board card |
-| `components/onboarding/` | 5 (4 demos + index) | Demo variants of `GettingStarted` |
-| `components/table-properties/` | (drawer + parts) | Correct |
-| `components/templates/` | 7 | Correct — page-level templates |
-| `components/ui/` | 40+ | Reserved for shadcn primitives bridged from `packages/ui` |
-
-## 2. Findings
-
-### 2.1 Dead components (zero importers found)
-
-> **Resolved 2026-05-19.** A re-verification scan confirmed that
-> `form-layout-01.tsx` and `section-cards.tsx` are **not present** in either
-> `apps/web/components/` or `packages/ui/template/components/` — the audit's
-> initial finding was based on a stale snapshot. No action needed.
-
-### 2.2 Onboarding components split between two locations
-
-> **Resolved 2026-05-19.** Option A landed:
-> - `getting-started.tsx` moved into `components/onboarding/getting-started.tsx`
->   (both `apps/web/` and `packages/ui/template/`).
-> - Deprecated shims `dashboard-onboarding.tsx` and
->   `dashboard-onboarding-gallery.tsx` deleted in both locations
->   (no consumers outside themselves).
-> - `components/onboarding/index.ts` now re-exports `GettingStarted`,
->   `GettingStartedProgressCard`, `GettingStartedVariantView`,
->   `renderGettingStartedVariant`, `GETTING_STARTED_STORAGE_KEY`, and
->   the `Onboarding01`–`Onboarding04` variant cards.
-> - Dashboard consumers (`dashboard-tabs.tsx`, `dashboard-report-charts.tsx`)
->   import via `@/components/onboarding/getting-started`; intra-folder
->   variants use the relative `./getting-started` path.
-
-### 2.3 Sidebar shell — high top-level density
-
-> **Resolved 2026-05-19.** All 11 sidebar files relocated into
-> `components/sidebar/` (both `apps/web/` and `packages/ui/template/`):
->
-> ```
-> components/sidebar/
-> ├── index.ts            ← barrel re-export
-> ├── app-sidebar.tsx
-> ├── app-sidebar-dynamic.tsx
-> ├── sidebar-shell.tsx
-> ├── sidebar-auto-collapse.tsx
-> ├── sidebar-auto-open.tsx
-> ├── nav-main.tsx
-> ├── nav-secondary.tsx
-> ├── nav-documents.tsx
-> ├── nav-user.tsx
-> ├── secondary-nav.tsx
-> └── secondary-panel.tsx
-> ```
->
-> **External consumers** now import via the barrel:
-> `import { AppSidebar, SidebarShell, useSecondaryPanel } from "@/components/sidebar"`.
-> Per-file paths still resolve (escape hatch), e.g.
-> `@/components/sidebar/secondary-panel`.
->
-> **Intra-folder** imports use relative paths (`./nav-user`, `./secondary-panel`)
-> so internal restructure does not ripple out.
->
-> Dead-import audit at completion: zero references to `@/components/<sidebar-file>"`
-> remain outside the new folder.
->
-> `nav-main`, `nav-secondary`, `nav-documents`, `sidebar-auto-open` are
-> currently zero-import (only mentioned in docs/skills). They were moved for
-> directory consistency; pruning truly dead files is a separate concern.
-
-### 2.4 Dedicated-search files — naming consistent
-
-`dedicated-search-recents.tsx`, `dedicated-search-url-composer.tsx`,
-`components/templates/dedicated-search-{landing,results}-template.tsx` —
-generic family already lives across `templates/` + top-level. **No action.**
-
-### 2.5 Entity-bound views — correctly at top level
-
-`*-list-view.tsx`, `*-board-view.tsx`, `*-page-header.tsx`, `*-client.tsx`,
-`*-table.tsx`, `*-dashboard-charts*.tsx`, `*-os-folder-view.tsx`,
-`*-panel-activator.tsx` — these are entity-specific compositions that
-**must** stay co-located with the hub they serve. **No action.**
-
-### 2.6 Possibly generic — re-evaluate during reuse work
-
-- `tinted-icon-disc.tsx` — used in KPI/empty states. If the API has stabilized,
-  consider moving to `components/data-views/` or `packages/ui/src/components/ui/`.
-- `task-list-panel.tsx`, `task-priority-badge.tsx` — generic-sounding but
-  bound to a Task entity. Confirm scope before any move.
-- `tree-panel-view.tsx`-style: `hub-tree-panel-view.tsx`,
-  `folder-details-shell.tsx` — already generic-sounding. If imported by
-  ≥ 2 hubs, move under `data-views/`.
-
-A quick rule of thumb:
-
-> If a component is imported by **only one** hub, it stays at the top level
-> next to that hub.
-> If it is (or could be) imported by **≥ 2** hubs, promote it into
-> `components/data-views/` (record-bearing) or `components/templates/`
-> (page chrome).
-
-### 2.7 `packages/ui/template/` parity
-
-Most top-level files are mirrored under `packages/ui/template/components/`
-(starter scaffold for `create-exxat-app`). When a file moves in
-`apps/web/components/`, `pnpm --filter @exxatdesignux/ui sync-template`
-will also move it under `template/`. **Always run `sync-template` after any
-refactor under §2.3 / §2.6** so the published starter stays buildable.
-
-## 3. Non-findings — what's already healthy
-
-- **`components/ui/`** is reserved for shadcn-aligned primitives; no
-  duplicates appear at the top level (e.g. no rogue `button.tsx` next to the
-  one in `ui/`).
-- **`components/data-views/`** is the right home for generic record-bearing
-  surfaces (`FolderGridView`, `FinderPanelView`, `ListPageBoardCard`).
-  Entity-specific board cards (`placement-board-card.tsx`) correctly stay
-  at top level.
-- **`components/templates/`** is the right home for page-level wrappers
-  (`ListPageTemplate`, `DedicatedSearch*Template`,
-  `SecondaryPanelHubTemplate`, `DiscoveryHubTemplate`). No drift.
-- **No `components/lightning/`** folder anywhere — `exxat-no-slds-leakage`
-  rule already passes.
-- **No second toast surface** — only `components/ui/sonner.tsx` exists, and
-  it's gated by `exxat-no-toast` + the new `exxat-ds/no-sonner-toast` lint.
-
-## 4. Suggested follow-up PRs
-
-| # | Title | Scope | Risk |
-|---|---|---|---|
-| 1 | Remove dead `form-layout-01.tsx` + `section-cards.tsx` from `apps/web/` and `packages/ui/template/` | Trivial | Low |
-| 2 | Consolidate `getting-started.tsx` + `dashboard-onboarding*.tsx` under `components/onboarding/` | Small | Low (import rename) |
-| 3 | ~~Move sidebar files into `components/sidebar/`~~ — **done 2026-05-19** (§2.3) | Medium | — |
-| 4 | Promote `tinted-icon-disc.tsx`, `hub-tree-panel-view.tsx`, `folder-details-shell.tsx` to `data-views/` if used by ≥ 2 hubs | Small per file | Low |
-| 5 | Run `sync-template` after each of 1–4 to keep `packages/ui/template/` aligned | Single command | Low |
-
-None of these is urgent. They become valuable when the top-level file count
-exceeds ~110 or when a new hub joins the codebase.
-
-## 5. References
-
-- [`apps/web/AGENTS.md`](../AGENTS.md) §9 — architecture pointers
-- [`apps/web/docs/component-selection-guide.md`](./component-selection-guide.md)
-- [`.cursor/rules/exxat-reuse-before-custom.mdc`](../../.cursor/rules/exxat-reuse-before-custom.mdc) — ask before adding new primitives
-- [`.cursor/rules/exxat-list-page-view-shells.mdc`](../../.cursor/rules/exxat-list-page-view-shells.mdc) — when to extract to `data-views/`

package/template/docs/consumer-upgrade-checklist.md

@@ -1,52 +0,0 @@
-# Upgrading `@exxatdesignux/ui` (human + AI checklist)
-
-Use this after **`npm install @exxatdesignux/ui@…`** / **`pnpm add @exxatdesignux/ui@…`**. It is copied into **`docs/exxat-ds/`** when you run **`exxat-ui sync-extras`**, so Cursor and other tools can find it beside other DS pattern docs.
-
-## 1. See what changed
-
-| Source | Purpose |
-|--------|---------|
-| **`node_modules/@exxatdesignux/ui/CHANGELOG.md`** | Release notes for the installed version (and peers). |
-| **`npx --package=@exxatdesignux/ui@latest exxat-ui changelog`** | Print the changelog from the package on disk / npx extract. |
-
-## 2. Refresh AI / pattern docs (optional but recommended)
-
-```bash
-npx --package=@exxatdesignux/ui@latest exxat-ui sync-extras
-```
-
-Overwrites only **`.cursor/skills/exxat-*`** and **`docs/exxat-ds/*.md`** (including this file). Does **not** change your app routes or product code.
-
-## 3. Align app code with the reference template
-
-The npm package includes a full Next.js reference under:
-
-**`node_modules/@exxatdesignux/ui/template/`**
-
-Use it when you need to know **what files exist**, **how shims re-export** `@exxatdesignux/ui`, or **what AGENTS / layout** patterns look like for the current release. Porting is manual: diff template vs your repo and apply intentional changes (imports, new components, CSS entrypoints).
-
-## 4. Dependency and Node
-
-- Keep **`@exxatdesignux/ui`** on the same semver your team tested; prefer explicit **`^x.y.z`** or pinned **`x.y.z`**.
-- Match **`engines.node`** in your app to the value declared in **`node_modules/@exxatdesignux/ui/package.json`** (see CHANGELOG if it changed).
-- **≥ 0.5.3:** Remove **`vaul`** from your app `package.json` and delete any `components/ui/drawer.tsx` shim — side panels use **`Sheet`** only (**`.cursor/rules/exxat-no-vaul.mdc`**).
-
-## 5. Consumer UI audit (after sync-extras)
-
-If the app was built before current agent rules, verify:
-
-| Symptom | Fix |
-|---------|-----|
-| Full-width tab bar on list hub | Use **`ListPageTemplate`** view toolbar — **`exxat-tabs-chrome.mdc`** |
-| Full-width Overview / Academics tabs | **`TabsList`** must stay **`w-fit`** — no `w-full` / `flex-1` stretch |
-| Grey custom header buttons | **`PageHeader`** + **`Button`** variants — **`exxat-page-header-actions.mdc`** |
-| Bespoke student popover in table | **`HoverCard`** + shared cells/badges — **`exxat-table-row-preview.mdc`** |
-| Custom hub table / trimmed Add view | **`HubTable`** + **`FULL_HUB_SUPPORTED_VIEWS`** — **`exxat-hub-supported-views.mdc`** |
-| Agent copied uploaded screenshots pixel-for-pixel | **`exxat-no-image-pixel-copy.mdc`** — images = IA only; map to blueprints + reference hubs |
-
-## 6. Still stuck?
-
-- **`npx --package=@exxatdesignux/ui@latest exxat-ui doctor`** — compares local CLI version vs npm **`latest`**.
-- **`npx --package=@exxatdesignux/ui@latest exxat-ui update`** — install commands and reminders.
-
-Maintainers publish from the design-system monorepo with git tags **`ui-v<version>`**; registry **`latest`** follows those tags.