@exxatdesignux/ui 0.5.10 → 0.5.12

package/template-vite/.cursor/skills/exxat-board-cards/SKILL.md

@@ -0,0 +1,68 @@
+---
+name: exxat-board-cards
+description: >-
+  Build and maintain kanban board cards in Exxat DS — ListPageBoardCard shell, title/avatar/badge/body hierarchy, BoardCardTwoLineBlock, list-status-badges, ListPageBoardTemplate. Use when adding board view, Team/Compliance/Placements cards, or status chips on cards.
+user-invocable: true
+---
+
+# Exxat DS — board (kanban) cards
+
+**Canonical MUST/MUST NOT:** **`apps/web/AGENTS.md` §4.4** (or **`./AGENTS.md`** when the workspace is the `apps/web/` app folder only). **Claude:** **`.claude/skills/exxat-board-cards/SKILL.md`** (repo root) — same body as this file. This skill is the **how-to**; the handbook stays the contract.
+
+## When to use this skill
+
+- Adding or changing **`viewType === "board"`** on a **`ListPageTemplate`** hub.
+- Building a new **`EntityBoardView`** or **`renderCard`** for **`ListPageBoardTemplate`**.
+- Aligning **Team** / **Compliance** board cards with **Placements**.
+- Wiring **status** on cards so it matches **table** and **list** views.
+
+## Shell: `ListPageBoardCard`
+
+Import from **`@/components/data-views/list-page-board-card`**:
+
+| Part | Component | Role |
+|------|-----------|------|
+| Outer | **`ListPageBoardCard`** | **`Card` `size="sm"`**; pass **`onClick`**, **`isNew`**, **`style`** (e.g. conditional row bg) like **`BoardPlacementCard`**. |
+| Header wrapper | **`ListPageBoardCardHeader`** | Vertical rhythm inside the card. |
+| Title row | **`ListPageBoardCardTitleRow`** | **`title`** + optional **`trailing`** + **`titleClassName`** (`truncate`, `line-clamp-2`, **`lineClampClass`**). |
+| Avatar | **`ListPageBoardCardAvatar`** | **`initials`** string; **`size-7`**, **`--avatar-initials-bg` / `--avatar-initials-fg`**. |
+| Status / tags | **`ListPageBoardCardBadgeRow`** | **`ListHubStatusBadge`** **`surface="board"`** (+ maps from **`lib/list-status-badges.ts`**) — **not** raw status text or one-off **`Badge`** markup in the body. |
+| Body | **`ListPageBoardCardBody`** | Icon rows and two-line blocks (facts). |
+| Hint | **`ListPageBoardCardSecondary`** | Empty states / helper copy. |
+
+## Primitives: `board-card-primitives.tsx`
+
+- **`BoardCardTwoLineBlock`** — icon + **primary** line (`font-medium text-foreground`) + optional **secondary** (muted). Omit **`line2`** for a single-line fact row.
+- **`BoardCardIconRow`** — when mirroring rich **table cells** (see **`BoardPlacementCard`**).
+- **`lineClampClass`** — pass into title or cell wrappers when density options apply.
+- **`BoardNewCardPlaceholder`** — column chrome for **`ListPageBoardTemplate`**.
+
+Prefer **two-line blocks** for stacked **primary / secondary** facts so cards match Placements’ visual rhythm.
+
+## Status badges (list hubs: Team, Compliance, Library, …)
+
+- **Maps (single source):** **`lib/list-status-badges.ts`** — per-entity `*_STATUS_LABEL`, `*_STATUS_BADGE_CLASS`, `*_STATUS_ICON`, plus semantic **`LIST_HUB_STATUS_TINT_*`** (success / warning / neutral / danger) for new domains.
+- **Component:** **`ListHubStatusBadge`** from **`@/components/list-hub-status-badge`** — **`surface="table"`** for **DataTable** cells and **list** rows; **`surface="board"`** inside **`ListPageBoardCardBadgeRow`**. Do not duplicate the shell classes on each page.
+- Use the **same** maps everywhere for that entity so copy and colors never drift.
+- **Do not** add **`uppercase`** or **`tracking-wide`** — **sentence / title case**, consistent with **`BoardStatusBadge`** on Placements (`placement-board-card.tsx`).
+- **Placements** lifecycle uses **`StatusBadge`** in **`placements-table-cells.tsx`** — thin wrapper over **`ListHubStatusBadge`** + **`PLACEMENT_STATUS_*`** in **`list-status-badges.ts`** (same visuals as Team / Library).
+
+## Avatar when mock has no `initials`
+
+Use **`initialsFromDisplayName`** from **`lib/initials-from-name.ts`** (e.g. compliance **owner** name).
+
+## Column template (simple hubs)
+
+**`ListPageBoardTemplate`** (`list-page-board-template.tsx`) — define **`ListPageBoardColumnDef<T>`** (`id`, `label`, `description`, **`filter`**, **`renderCard`**). Placements uses a **custom** board with richer headers; new hubs usually start here.
+
+## Placements
+
+**`BoardPlacementCard`** (`placement-board-card.tsx`) — domain-specific (lifecycle tabs, **`ColumnDef`**, conditional background). It **still** composes **`ListPageBoardCard`** parts and primitives; copy that structure for new dense entities.
+
+## Checklist
+
+- [ ] **`ListPageBoardCard`** (not one-off button/card markup).
+- [ ] Title row; avatar when product shows a person/owner chip.
+- [ ] Status in **`ListPageBoardCardBadgeRow`** with **`ListHubStatusBadge`** **`surface="board"`** + **`list-status-badges`** (if entity has status).
+- [ ] Body facts via **`BoardCardTwoLineBlock`** / **`BoardCardIconRow`**.
+- [ ] No **`uppercase`** on status **`Badge`** labels.

package/template-vite/.cursor/skills/exxat-card-vs-list-rows/SKILL.md

@@ -0,0 +1,20 @@
+# Exxat DS — cards vs rows vs lists
+
+Use when choosing **card grids**, **`DataTable`**, or **simple list rows** for a surface.
+
+## Read first
+
+- **`docs/card-vs-rows-pattern.md`**
+- **`.cursor/rules/exxat-card-vs-list-rows.mdc`**, **`exxat-data-tables.mdc`**, **`exxat-board-cards.mdc`**
+- **`exxat-centralized-list-dataset.mdc`** — one `tableState.rows` for table + board + cards
+
+## Checklist
+
+1. **10+ homogeneous records + compare/sort/filter?** → **`DataTable`** + hub template.
+2. **Kanban / visual tiles / folders?** → **`ListPageBoardCard`** or **`ListPageViewFrame`** + card primitives.
+3. **Medium vertical list without full table chrome?** → List row pattern; **promote** to `DataTable` when density and parity demand it.
+
+## MUST NOT
+
+- Card wall for the **primary** sortable hub that other hubs implement as **`DataTable`** without product reason.
+- Second mock row source for cards vs table.

package/template-vite/.cursor/skills/exxat-centralized-list-dataset/SKILL.md

@@ -0,0 +1,99 @@
+---
+name: exxat-centralized-list-dataset
+description: Single canonical dataset and derived row bag for Exxat list hubs — useTableState.rows across table/list/board/dashboard/folder/panel/tree, TablePropertiesDrawer wired to the same table state, shared maps for status/KPIs/inspector. Use when adding a hub view, detail panel, mock data, or fixing inconsistent counts between views.
+user-invocable: true
+---
+
+# Exxat DS — centralized dataset for list hubs
+
+Goal: **one row model**, **one filtered bag** (`tableState.rows`), **one place for badge/KPI maps**, so **every** view tab and inspector matches after search/filters.
+
+**Canon:** `apps/web/AGENTS.md` §4.1–§4.2, `docs/data-views-pattern.md`, `.cursor/rules/exxat-centralized-list-dataset.mdc`.
+
+---
+
+## 1. Canonical row module
+
+- **`lib/mock/<entity>.ts`** — exported typed **`interface`** / type alias + **`ENTITY_ROWS`** (or equivalent) for mocks.
+- Future API: replace **mock export** with **`fetch` + same TS shape**; views stay unchanged.
+- **Extend fields once** (e.g. inspector-only columns): add optional props on the **shared** interface — avoid a parallel **`EntityInspectorRow`** that duplicates IDs.
+
+---
+
+## 2. Single table state → all views
+
+| Surface | Data source |
+|---------|-------------|
+| Table | `useTableState` columns + rows |
+| List / Board / Dashboard | **`tableState.rows`** |
+| Folder grid | **`tableState.rows`** (+ folder metadata from **`lib/mock/<entity>-folders.ts`** keyed by **`folderId`**, not a second question list) |
+| Panel / Finder | **`tableState.rows`** + grouping helpers |
+| Tree + detail | **`tableState.rows`** for leaf items; folders from **folder mock**; selected question resolves **by id** from **`tableState.rows`** |
+
+**Anti-pattern:** `import { ENTITY_ROWS } from "..."` inside a view component while the table uses **`useTableState`** — filters won’t match.
+
+**Fix:** Pass **`tableState.rows`** (or setter/updater from parent) into child views; only use raw **`ENTITY_ROWS`** for **initial seed** into **`useTableState`**.
+
+---
+
+## 3. Table properties = same row shape
+
+- **`buildXColumns(rows)`** — column defs use **`accessorKey`** / **`cell`** consistent with the entity interface.
+- **`TablePropertiesDrawer`** — **`columns`**, **`columnVisibility`**, density — all tied to the **`DataTable`** instance that shares **`useTableState`**.
+- **`currentView`** + **`onViewChange`** — from **`ListPageTemplate`** **`renderContent`** (**§4.2**).
+
+---
+
+## 4. KPIs, dashboards, command palette
+
+- **`entityKpiMetrics(rows)`** / **`entityTopicInsight(rows)`** — take **`tableState.rows`** (filtered).
+- Dashboard charts on the hub — same **`rows`** prop as **`KeyMetrics`**.
+- ⌘K row search — index **`tableState.rows`** or shared mock through **`lib/command-menu-search-data.ts`** patterns — not a divergent copy (**`docs/command-menu-pattern.md`**).
+
+---
+
+## 5. Status, labels, icons
+
+- **`DATA_LIST_VIEW_TILES`** / **`dataListViewLabel`** — single registry for tab labels/icons.
+- Entity status — **`lib/list-status-badges.ts`** (**`ListHubStatusBadge`**) or one **`ENTITY_STATUS_*`** map next to mock data.
+- **MUST NOT** hardcode **"Published"** / tint classes in three components when a map already exists.
+
+---
+
+## 6. Implementation checklist (new hub or new view)
+
+- [ ] Exactly **one** primary row array shape in **`lib/mock/<entity>.ts`** (or API).
+- [ ] **`useTableState`** seeded from that array; **child views** receive **`tableState.rows`** (or equivalent), **not** a fresh import of the mock list.
+- [ ] Board / list / dashboard / folder / panel / tree **all** branch from the same client with shared **`rows`**.
+- [ ] Inspector/detail resolves **`selectedId`** with **`rows.find(r => r.id === selectedId)`** (or passes the row object from selection).
+- [ ] **`TablePropertiesDrawer`** receives **`currentView`** / **`onViewChange`** + column model from the **same** table.
+- [ ] KPI/chart helpers invoked with **`tableState.rows`**.
+- [ ] No second mock array unless **derived** (`useMemo(() => rows.filter(...), [rows])`).
+
+---
+
+## 7. Reference implementations
+
+- **`components/placements-client.tsx`** + **`placements-table.tsx`** — Placements pattern.
+- **`components/team-client.tsx`** + **`team-table.tsx`**.
+- **`components/library-table.tsx`** — multiple **`DataListViewType`** branches sharing **`tableState`** / **`folders`** / **`items`**.
+
+---
+
+## 8. Centralized presentation (with the same dataset)
+
+**Layout:** Non-table view branches wrap in **`ListPageViewFrame`** (constants in **`list-page-view-frame.tsx`**) — see **`.cursor/rules/exxat-list-page-view-shells.mdc`**.
+
+**Components:** Prefer **`components/data-views/*`** primitives (**`FolderGridView`**, **`FinderPanelView`**, board template, etc.) with **`rows`** from **`tableState.rows`**, not a second import of **`ENTITY_ROWS`**.
+
+**Rule:** **`.cursor/rules/exxat-centralized-list-dataset.mdc`** (presentation bullets §8–10).
+
+---
+
+## See also
+
+- `.cursor/rules/exxat-centralized-list-dataset.mdc`
+- `.cursor/rules/exxat-list-page-connected-views.mdc`
+- `.cursor/rules/exxat-list-page-view-shells.mdc`
+- `.cursor/rules/exxat-table-properties-drawer.mdc`
+- `.cursor/rules/exxat-data-tables.mdc`

package/template-vite/.cursor/skills/exxat-collaboration-access/SKILL.md

@@ -0,0 +1,35 @@
+---
+name: exxat-collaboration-access
+description: Shared hub collaboration — PageHeader face rail, InviteCollaboratorsDrawer, library access vs directory role tags. Use when adding invite people, access roster, or collaboration variant headers.
+user-invocable: true
+---
+
+# Exxat DS — collaboration & access
+
+**Handbook:** `apps/web/AGENTS.md` §4.7  
+**Narrative:** `apps/web/docs/collaboration-access-pattern.md`  
+**Cursor rule:** `.cursor/rules/exxat-collaboration-access.mdc`  
+**Related (Library folder scope + ⋯ Customize folder):** `.cursor/rules/exxat-library-hub-header.mdc` · `docs/library-hub-header-pattern.md`
+
+## Wiring checklist
+
+1. **`PageHeaderCollaborator`** — `name`, `email`, `access`, optional `roles[]`, avatar fields (`components/page-header.tsx`).
+2. **Mock/API** — `lib/mock/<entity>-header-collaborators.ts`; one shape for header + invite sheet.
+3. **Entity header** — `variant="collaboration"`; **Invite people** first in **⋯ More**; pass **`onAddCollaborator`** and **`onCollaboratorsOpen`**.
+4. **Hub client** — **`CollaborationAccessFlow`** (preferred) or `collaborators` + `inviteOpen` + **`InviteCollaboratorsDrawer`**; on invite, append to **`collaborators`**.
+5. **Access maps** — `lib/collaborator-access.ts` for Owner / Editor / Commenter / Viewer, invite options, and **`COLLABORATION_HEADER_ADD_LABEL`**.
+6. **Header** — empty roster → outline **Add collaborator**; non-empty → face rail; both open the invite sheet.
+7. **Invite sheet** — `InviteCollaboratorsDrawer`: export-style **`Sheet`**, combined email + access menu, grouped roster (name → email → role tags → access badge).
+8. **Library — folder URL scope** — When **`?scope=folder`**, **`LibraryPageHeader`** **⋯** also lists **Customize folder**; **`LibraryNewFolderSheet`** on **`LibraryClient`** — **`.cursor/rules/exxat-library-hub-header.mdc`**, **`docs/library-hub-header-pattern.md`**.
+
+## MUST NOT
+
+- A second invite control beside a populated face rail.
+- Per-hub access label forks or parallel collaborator types.
+- Toast/snackbar for invite outcomes (**`exxat-no-toast.mdc`**).
+- **`Select`** in **`InputGroupAddon`** for access inside the sheet.
+
+## Reference
+
+- `components/collaboration-access-flow.tsx`, `components/library-page-header.tsx`, `components/library-client.tsx`
+- `components/invite-collaborators-drawer.tsx`, `components/export-drawer.tsx`

package/template-vite/.cursor/skills/exxat-dedicated-search-surfaces/SKILL.md

@@ -0,0 +1,45 @@
+---
+name: exxat-dedicated-search-surfaces
+description: >-
+  Dedicated search landing vs results split, URL composer, recents storage, and templates
+  (generic DedicatedSearch*). Use when adding a route pair like empty ?q= landing + ListPageTemplate results,
+  or wiring localStorage recents without hydration mismatches.
+---
+
+# Dedicated search surfaces (Exxat DS)
+
+## When to use
+
+- A hub exposes **two URL states** on the same feature: **landing** (no primary query / empty `?q=`) vs **results** (non-empty query drives `ListPageTemplate` / `DataTable`).
+- You need an **AI-style composer** that **updates the URL** with `router.replace` and **does not** open Ask Leo.
+- You need **recent searches** persisted in `localStorage` **without** SSR/client markup drift.
+
+## MUST
+
+1. **Hydration-safe recents** — **MUST NOT** read `localStorage` in `useState` initializers. Initial client paint **MUST** match the server (`[]` then `useEffect` sync). See **`DedicatedSearchRecents`**.
+2. **Generic names** — Reusable pieces live under **`DedicatedSearch*`** (`components/dedicated-search-*.tsx`, **`components/templates/dedicated-search-*-template.tsx`**, **`lib/dedicated-search-*.ts`**). Hub code passes **`patchSearchParams`**, **`recents` controller**, copy, and entity table — **MUST NOT** fork parallel “question search landing” components for a second hub.
+3. **Landing shell** — Use **`DedicatedSearchLandingTemplate`** (`ListPageViewFrame` + title + composer slot + optional trailing).
+4. **Results chrome** — Reuse **`DEDICATED_SEARCH_RESULTS_OUTER_CONTENT_CLASSNAME`** on the hub content wrapper and **`DedicatedSearchResultsHeaderChrome`** around page header + composer strip.
+5. **Namespaces recents** — Use **`createDedicatedSearchRecentsController(namespace, legacy?)`** from **`lib/dedicated-search-recents.ts`**. When replacing an existing storage key, pass **`legacy: { storageKey, eventName }`** so users do not lose saved rows.
+
+## MUST NOT
+
+- Gate render on **`typeof window`** for the **first** paint of recents or landing bodies.
+- Duplicate the landing vertical rhythm (`mt-*` between title, composer, recents) outside the template without updating the template for product-wide consistency.
+
+## References (apps/web)
+
+| Piece | Path |
+|-------|------|
+| Landing template | `components/templates/dedicated-search-landing-template.tsx` |
+| Results chrome | `components/templates/dedicated-search-results-template.tsx` |
+| URL composer | `components/dedicated-search-url-composer.tsx` |
+| Recents list | `components/dedicated-search-recents.tsx` |
+| Recents storage factory | `lib/dedicated-search-recents.ts` |
+| Optional default `q` patcher | `lib/dedicated-search-url.ts` |
+| Library adapter (placeholders + patch) | `lib/library-dedicated-search.ts` |
+| Library wiring | `components/library-client.tsx` |
+
+## Cursor rule
+
+- **`.cursor/rules/exxat-dedicated-search-surfaces.mdc`**

package/template-vite/.cursor/skills/exxat-drawer-vs-dialog/SKILL.md

@@ -0,0 +1,20 @@
+# Exxat DS — drawer vs dialog
+
+Use when choosing **Radix `Dialog` / `AlertDialog`** vs **floating `Sheet` panels** vs **route** for a flow.
+
+## Read first
+
+- **`docs/drawer-vs-dialog-pattern.md`**
+- **`AGENTS.md` §6.4** + **`docs/data-views-pattern.md`** (page vs drawer)
+- **`.cursor/rules/exxat-drawer-vs-dialog.mdc`**, **`exxat-page-vs-drawer.mdc`**
+
+## Checklist
+
+1. **Must the user see the hub while acting?** Yes → **`Sheet`** panel (properties, export, invite). No and short → **dialog**. Long / own URL → **route**.
+2. **Destructive confirm?** Prefer **dialog** (`AlertDialog`) unless the product explicitly keeps context in a sheet with the same safeguards.
+3. **Title + focus** — Dialog and sheet both need an accessible **title**; restore focus to trigger on close.
+
+## Repo references
+
+- `TablePropertiesDrawer`, `ExportDrawer`, `InviteCollaboratorsDrawer` — floating **`Sheet`** (names end in “Drawer” but implementation is `Sheet` only).
+- Delete / irreversible — dialog pattern, not toast (**`exxat-no-toast.mdc`**).