@exxatdesignux/ui 0.1.0 → 0.2.6

package/consumer-extras/cursor-skills/exxat-fontawesome-icons/SKILL.md

@@ -0,0 +1,31 @@
+---
+name: exxat-fontawesome-icons
+description: Font Awesome Pro in Exxat DS — Kit script, fa-light/fa-solid, subset audit (fa:subset-audit), aria-hidden on decorative icons, no parallel icon libraries for product chrome. Use when adding or changing icons, nav glyphs, table toolbar icons, or debugging missing kit glyphs.
+user-invocable: true
+---
+
+# Exxat DS — Font Awesome icons
+
+**Cursor rule:** `.cursor/rules/exxat-fontawesome-icons.mdc`  
+**Handbook:** `apps/web/AGENTS.md` §1 (item 8), §8 accessibility for icon-only / informational cases.
+
+## Stack
+
+- **Kit:** `apps/web/app/layout.tsx` loads the Font Awesome Pro kit (subset via `fontawesome-subset.manifest.json`).
+- **Audit:** `pnpm --filter web fa:subset-audit` — refresh kit icon selection when adding new glyph names.
+
+## MUST
+
+1. **`<i className="fa-light fa-…" aria-hidden="true" />`** when a parent provides the accessible name (`Button` + `aria-label`, `Tip`, adjacent visible text).
+2. **`fa-light`** for default; **`fa-solid`** for active/selected where the app already does (sidebar rows, tabs).
+3. **Static** `className` strings where possible so the audit script can find class names.
+
+## MUST NOT
+
+- Introduce a **second** icon library for the same surfaces (duplicate Lucide/Heroicons for nav, hubs, toolbars).
+- Put the **only** accessible name on `<i>` without parent labelling — see **exxat-accessibility** Case B/C.
+
+## See also
+
+- `.cursor/rules/exxat-accessibility.mdc`
+- `.cursor/skills/exxat-accessibility/SKILL.md`

package/consumer-extras/cursor-skills/exxat-list-page-view-shells/SKILL.md

@@ -0,0 +1,36 @@
+---
+name: exxat-list-page-view-shells
+description: >-
+  Centered, reusable layout for ListPageTemplate view bodies — ListPageViewFrame,
+  data-views/ primitives, and rules to avoid page-tied view markup. Use when adding
+  folder/panel/custom views, fixing wide-viewport layout, or extracting view UI from a single hub.
+---
+
+# List-page view shells (Exxat DS)
+
+## When to use this skill
+
+- Adding or changing **`viewType`** surfaces: **folder**, **panel**, list/board chrome, icon grids, OS-style explorers.
+- User or PR asks for **“centered”**, **“reusable view”**, or **“not tied to one page”** layout.
+- You see **duplicated** `mx-4 lg:mx-6`, `mx-auto max-w-6xl`, or similar wrappers in multiple `*-table.tsx` files.
+
+## Instructions
+
+1. **Gutter + optional max width** — Import **`ListPageViewFrame`** from **`@/components/data-views/list-page-view-frame`** (or **`@/components/data-views`**). Wrap the view body (usually below **`DataTableToolbar`** when the view shares the table toolbar).
+   - Pass **`maxWidthClassName={LIST_PAGE_VIEW_FRAME_MAX_ICON_GRID}`** for dense tile grids.
+   - Pass **`maxWidthClassName={LIST_PAGE_VIEW_FRAME_MAX_WIDE}`** when the view includes toolbar rows + breadcrumbs + grid.
+2. **Do not double-gutter** — If **`DataTable`** already provides horizontal inset for the **table** view, do **not** wrap that branch in **`ListPageViewFrame`**. Use the frame on **sibling** view branches (folder, panel, etc.) only.
+3. **Reuse before inventing** — Prefer **`FolderGridView`**, **`FinderPanelView`**, **`ListPageBoardTemplate`**, **`ListPageViewFrame`**. If a new pattern appears twice, **promote** it to **`components/data-views/`** with domain-agnostic props.
+4. **Entity-specific → generic** — If logic is “any tree + any row type”, build **`components/data-views/<generic-name>.tsx`** and keep **`question-bank-*`** (or similar) as a thin composition + mock types.
+
+## Checklist
+
+- [ ] View body uses **`ListPageViewFrame`** (or a component that uses it internally, e.g. **`FolderGridView`**).
+- [ ] No **extra** horizontal padding around **`DataTable`** vs **`AGENTS.md` §5**.
+- [ ] New grid/shell lives under **`components/data-views/`** when a second hub could reuse it.
+
+## References
+
+- **`apps/web/components/data-views/list-page-view-frame.tsx`** — implementation + exported constants.
+- **`apps/web/AGENTS.md` §4.5** — MUST/MUST NOT.
+- **`.cursor/rules/exxat-list-page-view-shells.mdc`**.

package/consumer-extras/cursor-skills/exxat-primary-nav-secondary-panel/SKILL.md

@@ -0,0 +1,27 @@
+---
+name: exxat-primary-nav-secondary-panel
+description: Exxat DS pattern — one primary sidebar row opens a nested SecondaryPanel (Question bank). NavLinkItem.secondaryPanel id, PANELS registry, useAutoPanel on hub, URL scope + same useTableState rows. Use when adding hub scoped nav (All/My/tree) beside content.
+user-invocable: true
+---
+
+# Exxat DS — primary nav → secondary panel
+
+**Cursor rule:** `.cursor/rules/exxat-primary-nav-secondary-panel.mdc`  
+**Handbook:** `apps/web/AGENTS.md` §4.6
+
+## Wiring checklist
+
+1. **`lib/mock/navigation.tsx`** — set **`secondaryPanel: "<id>"`** on the primary **`NavLinkItem`**; **`url`** = hub route.
+2. **`components/secondary-panel.tsx`** — add **`PANELS["<id>"]`** → panel shell (title, optional search) + secondary nav component.
+3. **Hub client** — mount **`*PanelActivator`** with **`useAutoPanel("<id>")`** (same id) for the lifetime of the route (e.g. `QuestionBankPanelActivator`).
+4. **Data** — keep **one** **`useTableState`** / **`tableState.rows`**; drive scope from **URL** + small helpers (see **`lib/question-bank-nav.ts`**).
+
+## MUST NOT
+
+- Set **`secondaryPanel`** without **`PANELS[id]`** + **`useAutoPanel`** — broken empty rail.
+- Use this for full product areas that belong as **primary** or **collapsible child** rows.
+
+## Reference
+
+- `components/app-sidebar.tsx` — `openPanel` on same-route primary click.
+- `components/question-bank-secondary-nav.tsx` + `lib/question-bank-nav.ts`.

package/consumer-extras/patterns/command-menu-pattern.md

@@ -0,0 +1,45 @@
+# 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 **`exxat-ds/AGENTS.md` §7.1** when behavior or copy changes.

package/consumer-extras/patterns/data-views-pattern.md

@@ -0,0 +1,167 @@
+# Data views pattern (table, list, board)
+
+> **Canonical rules for agents (MUST/MUST NOT, checklists):** [`AGENTS.md`](../AGENTS.md) in this package (including **§8 Accessibility**). This file is the long-form narrative; keep both aligned when patterns change.
+
+This document describes how list pages combine **views**, **toolbar** behavior, **filters**, **properties**, and **persistence** in this codebase.
+
+## Reuse existing components (required)
+
+**Prefer composing what already exists** over rebuilding one-off tabs, search, filters, or property panels. The **Placements** flow is the reference implementation; new list/table/board pages should wire the same building blocks with new data and column definitions.
+
+| Need | Reuse | Where Placements uses it |
+| --- | --- | --- |
+| **View tabs** (table / list / board, lifecycle filters) | `ListPageTemplate` (`ViewTab`, `renderContent`, optional metrics + export) | `components/data-list-client.tsx` + `components/templates/list-page.tsx` |
+| **Table shell** (search, filter bar, sort, grouping, columns, pagination) | `DataTable`, `DataTableToolbar`, `useTableState` | `components/data-table/`, `components/data-list-table.tsx` |
+| **Properties drawer** (display, columns, filters, sort, view type tiles) | `TablePropertiesDrawer` from `@/components/table-properties` | `DrawerToolbar` / list–board shells in `data-list-table.tsx` |
+| **Board / list** | `PlacementsBoardView`, `PlacementsListView` + same `useTableState` | `DataListTable` |
+| **Page header** (primary CTA + More ⋯ + export) | `PlacementsPageHeader` or `TeamPageHeader` | `components/placements-page-header.tsx`, `components/team-page-header.tsx` |
+| **Team page (primary template)** | `TeamClient` = `ListPageTemplate` + `KeyMetrics` + `TeamPageHeader` + `TeamTable` (same composition as `DataListClient`) | `components/team-client.tsx`, `lib/mock/team-kpi.ts` |
+| **Team roster** | `TeamTable` — `DataTable` + `useTableState` + `TablePropertiesDrawer`; list/board/dashboard read **`tableState.rows`** | `components/team-table.tsx` |
+| **Dashboard view (list tab)** | **`KeyMetrics`** (`variant="flat"` or `"card"`) — same KPI system as the template metrics strip; **do not** add ad-hoc `Card` grids for entity summaries | `TeamTable` dashboard branch, `lib/mock/team-kpi.ts` |
+| **Export** | `ExportDrawer` | `ListPageTemplate` export props; `DataListClient` |
+| **View body layout** (gutter + centered max-width for folder / icon / panel-style content) | **`ListPageViewFrame`** (`components/data-views/list-page-view-frame.tsx`, re-exported from `components/data-views`) | **`FolderGridView`** (uses the frame); **`QuestionBankOsFolderView`** — see **`AGENTS.md` §4.5** |
+
+**Rules:** (1) Import and compose these components; pass **props** and **column defs** for your entity. (2) If something is missing, **extend the shared component** under `components/` (e.g. a new optional slot on `DataTableToolbar`) rather than copying markup into a single page. (3) Card-only or lightweight pages may use a smaller **Properties** sheet only when there is **no** table—otherwise use `TablePropertiesDrawer` with `DataTable` (see Team).
+
+### Table pages must use view tabs
+
+If the page uses a **`DataTable`** (or equivalent data grid) as the main surface, it **must** sit under **`ListPageTemplate`** so users get the **views toolbar** (tabs, add view, per-tab settings). The default `ViewTab` entries should include at least one tab whose `viewType` is **`table`** when the primary experience is tabular data. **Do not** render a `DataTable` alone under only `PageHeader` + body.
+
+- **Reference:** `DataListClient` (Placements) and `TeamClient` (Team).
+- **Rationale:** Consistent navigation, saved views, per-tab view type (table / list / board), and export at the template level.
+
+## View layout frame (centered, reusable)
+
+Non-table view branches (e.g. **folder** icon grid, **panel** finder, OS-style folder explorer) **should** use **`ListPageViewFrame`** for the same horizontal gutter and optional **`max-w-*`** centering as other hubs — **not** hand-copied `mx-4 lg:mx-6` + `mx-auto max-w-6xl` in each `*-table.tsx`. New view types belong in **`components/data-views/`** as **generic** components with render props; hub tables only wire **`tableState.rows`** and callbacks.
+
+**Handbook:** **`AGENTS.md` §4.5**. **Cursor:** **`.cursor/rules/exxat-list-page-view-shells.mdc`**. **Skill:** **`.cursor/skills/exxat-list-page-view-shells/SKILL.md`**. **Do not** wrap **`DataTable`** in the frame if that stacks padding with the table toolbar (**`AGENTS.md` §5**).
+
+## Architecture
+
+- **Page shell** — `ListPageTemplate` owns the views toolbar (tabs), optional metrics, and export drawer. Content for the active tab is rendered via `renderContent`.
+- **Per–lifecycle (or category) data** — `DataListTable` swaps **columns** and **row sets** based on `lifecycleTabId` (e.g. All / Upcoming / Ongoing / Completed). Each lifecycle tab gets its **own** `DataListTable` instance (`key={tab.filterId}`) so `useTableState` resets correctly when columns change.
+- **Shared table state** — `useTableState` holds sort, search, filters, grouping, column order/visibility/pins/widths, row height, gridlines, and pagination flags. **Table**, **list**, **board**, and **dashboard** all read the same state so switching view type keeps behavior aligned.
+
+## Mock data and connected views
+
+1. **Put entity rows in `lib/mock/<entity>.ts`** — Export a typed array (e.g. `TeamMember[]`, `Placement[]`) and reuse it from the page client and from KPI helpers.
+2. **KPI / summary helpers** — Add `lib/mock/<entity>-kpi.ts` (or next to the mock file) with pure functions **`entityKpiMetrics(rows: T[])`** and **`entityKpiInsight(rows: T[])`** returning `MetricItem[]` and `MetricInsight` from `@/components/key-metrics`. Drive **both** the template **`metrics`** slot and the **dashboard view** from the **same helpers**, passing **`tableState.rows`** in the table component so filters/search apply everywhere.
+3. **Single table component** — One component (e.g. `TeamTable`) receives **`members`** (full mock) + **`view`**. It calls **`useTableState(members, columns, …)`** once. Branch on `view`:
+   - **`table`** → `DataTable` with that state.
+   - **`list` / `board`** → `DataTableToolbar` + list/board UI with **`tableState.rows`**.
+   - **`dashboard`** → `DataTableToolbar` + **`KeyMetrics`** (and/or other **existing** dashboard building blocks — `ChartsOverview` only when charts are product-appropriate) fed by **`teamKpiMetrics(tableState.rows)`** / **`teamKpiInsight(tableState.rows)`** — **not** bespoke `Card` grids duplicating KPIs.
+4. **Client wiring** — `renderContent` always renders the table component with **`view={tab.viewType}`** and **`key={tab.id}`** (not `viewType`) so switching views does not remount state. **Do not** show “not wired” placeholders for list/board/dashboard when the table stack supports those views.
+5. **Full-route dashboards** — The **`/dashboard`** page uses **`DashboardTabs`**, **`KeyMetrics`**, and **`ChartsOverview`** with `lib/mock/dashboard.ts`. List-page **dashboard view** is a **narrower** slice: reuse **`KeyMetrics`** (+ entity KPI helpers) first; add charts only when they match the entity and reuse **`ChartsOverview`** patterns from `components/charts-overview.tsx`.
+
+## Table vs list vs board vs dashboard
+
+| Concern | Table | List | Board | Dashboard (view tab) |
+| --- | --- | --- | --- | --- |
+| Primary surface | `DataTable` | `PlacementsListView` / entity list | `PlacementsBoardView` / entity board | **`KeyMetrics`** (+ optional charts via shared dashboard components) |
+| Data source | `useTableState` | **`tableState.rows`** | **`tableState.rows`** | **`tableState.rows`** via KPI helpers |
+| Column headers / labels | `showColumnLabels` | Same source columns, list layout | Phase columns + optional board column menu | N/A (metrics from same columns/filters) |
+| Row click / navigation | From `DataListTable` | From list shell | Card `onOpen` | N/A |
+| Pagination | Optional `PaginationBar` + `CountSyncer` | Same pattern | N/A (board uses phase columns) | N/A |
+
+## Toolbar and properties
+
+- **Search** — Global quick search lives in table state (`search` / `showToolbarSearch` from display options). Board phase columns can add local search in the board column header.
+- **Filters** — Built from `ColumnDef.filter` and `filterFields` passed to `TablePropertiesDrawer`. Connectors between filters (`and` / `or`) are part of table state.
+- **Sort / group** — Sort rules and `groupBy` are in table state; board menu proxies the same actions when `boardColumnMenu` is wired.
+- **Properties drawer** — `TablePropertiesDrawer` is **generic**: supply `filterFields`, `fieldDefinitionsForDrawer`, `resolveColumnLabel`, `activeFilters`, sort/column handlers, `displayOptions`, and optional view-type tiles. Domain-specific defaults (e.g. `FILTER_FIELDS` in `types.ts`) are optional; new pages can pass their own definitions.
+
+**Import:** `@/components/table-properties` re-exports the drawer and types.
+
+## Board UI reuse
+
+**Handbook:** **`AGENTS.md` §4.4** — board card shell, badge row, shared status maps, and MUST/MUST NOT. **Cursor:** **`.cursor/rules/exxat-board-cards.mdc`**, skill **`.cursor/skills/exxat-board-cards/SKILL.md`**.
+
+- **Card shell** — `components/data-views/list-page-board-card.tsx` — **`ListPageBoardCard`**, **`ListPageBoardCardHeader`**, **`ListPageBoardCardTitleRow`**, **`ListPageBoardCardAvatar`**, **`ListPageBoardCardBadgeRow`**, **`ListPageBoardCardBody`**, **`ListPageBoardCardSecondary`**. All product board cards on list hubs **should** use this shell (same **`Card` `size="sm"`** pattern as Placements).
+- **Primitives** — `components/data-views/board-card-primitives.tsx` — `BoardCardIconRow`, `BoardCardTwoLineBlock` (optional `line2`), `BoardNewCardPlaceholder`, `lineClampClass`.
+- **Status (Team & Compliance)** — `lib/list-status-badges.ts` — single source for label strings + badge `className` tails for **table, list, and board**. Do **not** pair with `uppercase` on the Badge (labels are sentence case, aligned with Placements `BoardStatusBadge`).
+- **Owner initials** — `lib/initials-from-name.ts` when mock rows have a display name but no `initials` field.
+- **Shared column shell** — `components/data-views/list-page-board-template.tsx` — `ListPageBoardTemplate` + `ListPageBoardColumnDef<T>`: define columns with `filter` predicates, `renderCard`, `getRowKey`. Used by **Team** and **Compliance** boards; new hubs should start here before custom chrome.
+- **Placement card** — `components/data-views/placement-board-card.tsx` — `BoardPlacementCard` composes **`ListPageBoardCard`** parts with `ColumnDef<Placement>` and lifecycle layout helpers from `lib/placement-board-card-layout.ts`. Placements keeps richer column headers (search, menus); still uses the same primitives.
+- New entities should add their own card component that composes **`ListPageBoardCard`** + primitives rather than duplicating column scroll/layout or ad-hoc card chrome.
+
+## Dashboard view (list pages)
+
+- **Reuse the dashboard chart bundle** — `components/dashboard-report-charts.tsx` — `DashboardReportCharts`: flat `KeyMetrics` + middle chart section + period comparison `KeyMetrics` card. **`ChartsOverview`** (placement-themed demo gallery) is the default middle section for `/dashboard` and **Placements**. **Team** passes **`chartsSection={<TeamDashboardChartsSection members={tableState.rows} />}`** so charts reflect roster data, not placements. List hubs use `ListPageDashboardCharts` (`metricsSingleRow`). Chart **style** can follow `ChartVariantProvider` when using `ChartsOverview`.
+- **Data tab canvas charts** (`data-view-dashboard-charts*.tsx`) share **`ChartFigure`**, **`ChartCard`**, and **`ChartDataTable`** with `charts-overview.tsx`. **Layout** for Placements / Team / Compliance is stored in one place: **`lib/data-view-dashboard-storage.ts`** (see `AGENTS.md` §4.3). **Keyboard-selected bars/slices** must use **`lib/chart-keyboard-selection.ts`** (`activeBar` / `activeShape`) so behavior matches the gallery — not opacity-only `Cell` dimming.
+
+## Persistence
+
+- **Page-level** (`lib/data-list-persistence.ts`, key `exxat-ds:data-list:page:v1`): `displayOptions`, `showMetrics`, `tabs`, `activeTabId`. Loaded in `DataListClient` with `useLayoutEffect`, saved debounced on change. `ListPageTemplate` runs in **controlled** mode when `tabs` / `onTabsChange` / `activeTabId` / `onActiveTabChange` are passed.
+- **Per–lifecycle tab** (key `exxat-ds:data-list:lifecycle:v1:<filterId>`): sort, search, filters, group by, column order/hidden/widths/pins/wrap, column menu search map, row height, gridlines, filter bar visibility, search popover, conditional rules, pagination toggle and page/size. Hydrated in `DataListTable` with `useLayoutEffect`; saved debounced when those fields change.
+
+To add a new page: copy the `DataListClient` pattern (controlled `ListPageTemplate` + storage key namespace) or call `schedulePageSave` / `scheduleLifecycleSave` with your own keys.
+
+## Rules of thumb
+
+1. **One `useTableState` per logical table** — Remount with `key` when the column set or entity context changes.
+2. **Don’t fork filter/sort UX** — Reuse `TablePropertiesDrawer` and `DataTableToolbar` patterns so accessibility and behavior stay consistent.
+3. **Boards derive from the same columns** — `boardColumns` / `hiddenColKeys` should reflect table `displayCols` so “hide column” and “properties” stay in sync.
+4. **Persist stable JSON** — Version objects with `v: 1` and keep keys namespaced to allow migrations later.
+
+---
+
+## Required UX for dense lists (10+ items)
+
+When a page shows a **list**, **table**, or **card grid** with **more than 10 items**, it must expose:
+
+| Capability | Table / list / board | Card-only pages (no `DataTable`) |
+| --- | --- | --- |
+| **Search** | Toolbar search + column quick-search where applicable | At least one search control filtering the visible set |
+| **Filter** | Filter bar + `TablePropertiesDrawer` filters | Filters in toolbar or in Properties, as appropriate to the content |
+| **Sorting** | Column sort / sort rules in drawer | User-visible sort (e.g. name, date, role) |
+| **Properties** | `TablePropertiesDrawer` (columns, display, filters, sort) | A **Properties** entry point (sheet or drawer) for view options — same *role* as table properties, even if the UI is simpler |
+
+Below the threshold, these may be omitted unless the page is a primary data hub (see below).
+
+---
+
+## Data pages: primary CTA + More + Export
+
+If the page **has exportable data** (rows, members, placements, etc.), follow the **Placements** header pattern:
+
+1. **Primary action** — One default (filled) button for the main task (e.g. **New placement**, **Invite member**). Do **not** use `variant="outline"` for that primary action.
+2. **More (⋯)** — An outline **icon** button opening a menu that includes **Export** (and other overflow actions). Wire **Export** to `ExportDrawer` (or equivalent).
+3. **Subtitle** — Prefer a short line with **count + freshness** (e.g. `24 records · Last updated now`), matching `PlacementsPageHeader`.
+
+Reference: `components/placements-page-header.tsx`, `components/team-page-header.tsx`, `components/team-client.tsx`.
+
+---
+
+## Page vs drawer (actions and auxiliary views)
+
+**When to use a drawer or sheet:** The user needs **the surrounding page** (list, hub, or parent task) to stay **visible for context** *and* they need a **quick view**, **quick actions**, or a **short auxiliary step** — e.g. table properties, export, a brief row summary, or “change one setting and dismiss.”
+
+**When to use a new page (route):** The flow is **primary**, **long-form**, **multi-step**, or should have its **own URL** / bookmark / history **without** the parent page behind it — e.g. full create/edit, wizards, or detail that *is* the task.
+
+**Rule of thumb:** **Context + quick** → **drawer**; **otherwise** → **new page**.
+
+Canonical rules: **`AGENTS.md` §6.4**, root **`.cursor/rules/exxat-page-vs-drawer.mdc`**.
+
+---
+
+## Primary pages with large datasets
+
+When a route is a **primary** destination in nav (main hub for an entity) **and** the dataset is **large** or **highly interactive**:
+
+- Use the **primary page template**: `ListPageTemplate` (tabs, metrics strip, export drawer at template level) + data client pattern as in **`DataListClient`** / **`DataListTable`** — not a minimal `PageHeader`-only layout.
+- Smaller satellite pages may use **`PageHeader` + section content**; once the dataset grows past the dense-list threshold, add the toolbar rules above and consider promoting to the full template if the page becomes a main hub.
+
+---
+
+## Summary checklist
+
+- [ ] **Reuse** — Tabs, search, filters, and property UI come from **`ListPageTemplate`**, **`DataTable` / `useTableState`**, **`TablePropertiesDrawer`**, and related Placements modules—not ad-hoc duplicates.
+- [ ] **Table + tabs** — Any **`DataTable`** is wrapped in **`ListPageTemplate`** (view tabs), not only `PageHeader` + body.
+- [ ] **>10 items** → search, filter, sort, properties (per surface type above).
+- [ ] **Has data to export** → **More** menu with **Export** + shared `ExportDrawer` pattern.
+- [ ] **Primary + large / main hub** → `ListPageTemplate`-style shell where applicable.
+- [ ] **Page vs drawer (§6.4)** — Quick actions with parent **context** → drawer/sheet; primary or long flows → **new route**.
+- [ ] **Primary button** → `Button` default variant (`size="lg"` for parity with Placements), not outline.
+- [ ] **Dashboard view tab** → `KeyMetrics` + shared KPI helpers from **`tableState.rows`**; no duplicate one-off metric cards.
+- [ ] **Data view charts** → `ChartFigure` + `chart-keyboard-selection`; layout persistence via **`data-view-dashboard-storage`** (see `AGENTS.md` §4.3).
+- [ ] **Mock + KPIs** → Entity rows in **`lib/mock/`**; **`entityKpiMetrics` / `entityKpiInsight`** consumed by template metrics and dashboard view.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exxatdesignux/ui",
-  "version": "0.1.0",
+  "version": "0.2.6",
   "description": "Exxat shared design system (components, hooks, tokens). Monorepo setup: clone repo then pnpm bootstrap at workspace root — see github.com/ExxatDesign/Exxat-DS-Workspace README.",
   "type": "module",
   "private": false,
@@ -30,12 +30,14 @@
   "main": "./src/index.ts",
   "types": "./src/index.ts",
   "bin": {
+    "exxat-ui": "./bin/cli.mjs",
     "create-exxat-app": "./bin/init.mjs"
   },
   "files": [
     "src",
     "bin",
-    "template"
+    "template",
+    "consumer-extras"
   ],
   "dependencies": {
     "@hookform/resolvers": "^5.2.2",
@@ -72,6 +74,7 @@
   },
   "scripts": {
     "typecheck": "tsc --noEmit",
-    "lint": "eslint src/"
+    "lint": "eslint src/",
+    "vendor:consumer-extras": "node ./scripts/vendor-consumer-extras.mjs"
   }
 }

package/src/components/ui/sidebar.tsx

@@ -469,14 +469,19 @@ function SidebarMenuItem({ className, ...props }: React.ComponentProps<"li">) {
     <li
       data-slot="sidebar-menu-item"
       data-sidebar="menu-item"
-      className={cn("group/menu-item relative", className)}
+      className={cn(
+        "group/menu-item relative",
+        /* Icon rail: center the square menu control in the column (footer + primary). */
+        "group-data-[collapsible=icon]:flex group-data-[collapsible=icon]:justify-center",
+        className,
+      )}
       {...props}
     />
   )
 }
 
 const sidebarMenuButtonVariants = cva(
-  "peer/menu-button group/menu-button flex w-full cursor-pointer select-none items-center gap-2 overflow-hidden rounded-md p-2 text-start text-sm ring-sidebar-ring outline-hidden transition-[width,height,padding] group-has-data-[sidebar=menu-action]/menu-item:pe-8 group-data-[collapsible=icon]:size-8! group-data-[collapsible=icon]:p-2! hover:bg-sidebar-accent hover:text-sidebar-accent-foreground focus-visible:ring-2 active:bg-sidebar-accent active:text-sidebar-accent-foreground disabled:pointer-events-none disabled:opacity-50 aria-disabled:pointer-events-none aria-disabled:opacity-50 data-open:hover:bg-sidebar-accent data-open:hover:text-sidebar-accent-foreground data-active:bg-background data-active:font-medium data-active:text-foreground data-active:shadow-sm data-active:ring-1 data-active:ring-sidebar-border data-active:hover:bg-background data-active:hover:text-foreground data-active:hc:border data-active:hc:border-foreground data-active:forced-colors:border data-active:forced-colors:border-[Highlight] [&_svg:not([data-product-logo]):not([data-product-logo-mark])]:size-4 [&_svg]:shrink-0 [&>span:last-child]:truncate",
+  "peer/menu-button group/menu-button flex w-full group-data-[collapsible=icon]:w-8 cursor-pointer select-none items-center gap-2 overflow-hidden rounded-md p-2 text-start text-sm ring-sidebar-ring outline-hidden transition-[width,height,padding] group-has-data-[sidebar=menu-action]/menu-item:pe-8 group-data-[collapsible=icon]:size-8! group-data-[collapsible=icon]:p-2! hover:bg-sidebar-accent hover:text-sidebar-accent-foreground focus-visible:ring-2 active:bg-sidebar-accent active:text-sidebar-accent-foreground disabled:pointer-events-none disabled:opacity-50 aria-disabled:pointer-events-none aria-disabled:opacity-50 data-open:hover:bg-sidebar-accent data-open:hover:text-sidebar-accent-foreground data-active:bg-background data-active:font-medium data-active:text-foreground data-active:shadow-sm data-active:ring-1 data-active:ring-sidebar-border data-active:hover:bg-background data-active:hover:text-foreground data-active:hc:border data-active:hc:border-foreground data-active:forced-colors:border data-active:forced-colors:border-[Highlight] [&_svg:not([data-product-logo]):not([data-product-logo-mark])]:size-4 [&_svg]:shrink-0 [&>span:last-child]:truncate group-data-[collapsible=icon]:justify-center group-data-[collapsible=icon]:gap-0 group-data-[collapsible=icon]:[&>*:not(:first-child)]:hidden",
   {
     variants: {
       variant: {

package/template/components/page-header.tsx

@@ -1,22 +1,60 @@
+"use client"
+
 /**
  * PageHeader — Full-width content area header
  *
  * Sits at the top of a page's main content, BELOW the breadcrumb/topbar.
  * Uses Ivy Presto (Adobe Fonts) for the title via font-heading CSS variable.
  *
+ * **Variant `collaboration`** — optional access line + stacked collaborator faces
+ * and an invite control ahead of the primary `actions` slot (Question bank pattern).
+ *
  * WCAG 2.1 AA:
  *  ✓ <h1> landmark — one per page (WCAG 1.3.1)
  *  ✓ Sufficient colour contrast ≥ 4.5:1 on title + subtitle (SC 1.4.3)
+ *  ✓ Face stack: `role="group"` + aggregate `aria-label`; each face has a `Tooltip` name
  */
 
 import * as React from "react"
 import { cn } from "@/lib/utils"
+import { Avatar, AvatarFallback, AvatarImage } from "@/components/ui/avatar"
+import { Button } from "@/components/ui/button"
+import { Tip } from "@/components/ui/tip"
+import {
+  Tooltip,
+  TooltipContent,
+  TooltipTrigger,
+} from "@/components/ui/tooltip"
+
+export type PageHeaderVariant = "default" | "collaboration"
+
+export interface PageHeaderCollaborator {
+  id: string
+  name: string
+  imageUrl?: string | null
+  initials?: string
+}
 
 export interface PageHeaderProps {
   /** Primary page title — rendered as <h1> in Ivy Presto serif */
   title: string
-  /** Short descriptor or date shown below the title */
+  /** Short descriptor or date shown below the title (and below `accessInfo` when set) */
   subtitle?: string
+  /** Layout preset — `collaboration` enables access line + face stack + invite ahead of `actions`. */
+  variant?: PageHeaderVariant
+  /**
+   * Role / access copy or badges — rendered between the title and subtitle when
+   * `variant="collaboration"` (e.g. lock icon + “Editors can modify”).
+   */
+  accessInfo?: React.ReactNode
+  /** People with access — shown as an overlapping face stack when `variant="collaboration"`. */
+  collaborators?: PageHeaderCollaborator[]
+  /** Max faces before a `+N` chip — default 4 */
+  collaboratorDisplayLimit?: number
+  /** Outline control beside the stack — e.g. open share / invite dialog */
+  onAddCollaborator?: () => void
+  /** Accessible name for the invite control — default “Invite people” */
+  addCollaboratorLabel?: string
   /** Optional slot for right-aligned actions (buttons, selectors, etc.) */
   actions?: React.ReactNode
   /** Extra className for the outer wrapper */
@@ -25,32 +63,136 @@ export interface PageHeaderProps {
   showTitleBlock?: boolean
 }
 
-export function PageHeader({ title, subtitle, actions, className, showTitleBlock = true }: PageHeaderProps) {
+function PageHeaderCollaborationFaces({
+  people,
+  limit,
+  addLabel,
+  onAdd,
+}: {
+  people: PageHeaderCollaborator[]
+  limit: number
+  addLabel: string
+  onAdd?: () => void
+}) {
+  const visible = people.slice(0, limit)
+  const overflow = Math.max(0, people.length - visible.length)
+  const names = people.map(p => p.name).join(", ")
+
+  return (
+    <div
+      role="group"
+      aria-label={names ? `People with access: ${names}` : "People with access"}
+      className="flex shrink-0 items-center gap-2 sm:gap-2.5"
+    >
+      {visible.length > 0 && (
+        <div className="flex -space-x-2 ps-0.5">
+          {visible.map((c, index) => (
+            <Tooltip key={c.id}>
+              <TooltipTrigger asChild>
+                <Avatar
+                  size="sm"
+                  shape="circle"
+                  className="relative ring-2 ring-background"
+                  style={{ zIndex: 10 + index }}
+                >
+                  {c.imageUrl ? (
+                    <AvatarImage src={c.imageUrl} alt="" referrerPolicy="no-referrer" />
+                  ) : null}
+                  <AvatarFallback className="text-xs font-semibold">
+                    {(c.initials ?? c.name.slice(0, 2)).toUpperCase()}
+                  </AvatarFallback>
+                </Avatar>
+              </TooltipTrigger>
+              <TooltipContent side="bottom">{c.name}</TooltipContent>
+            </Tooltip>
+          ))}
+          {overflow > 0 && (
+            <div
+              className="relative z-30 flex size-6 shrink-0 items-center justify-center rounded-full bg-muted text-xs font-medium tabular-nums text-muted-foreground ring-2 ring-background sm:size-7"
+              aria-label={`${overflow} more people with access`}
+            >
+              +{overflow}
+            </div>
+          )}
+        </div>
+      )}
+      {onAdd ? (
+        <Tip side="bottom" label={addLabel}>
+          <Button
+            type="button"
+            variant="outline"
+            size="icon"
+            className="size-8 min-h-8 min-w-8 shrink-0 rounded-full border-dashed"
+            aria-label={addLabel}
+            onClick={onAdd}
+          >
+            <i className="fa-light fa-user-plus text-sm" aria-hidden="true" />
+          </Button>
+        </Tip>
+      ) : null}
+    </div>
+  )
+}
+
+export function PageHeader({
+  title,
+  subtitle,
+  variant = "default",
+  accessInfo,
+  collaborators,
+  collaboratorDisplayLimit = 4,
+  onAddCollaborator,
+  addCollaboratorLabel = "Invite people",
+  actions,
+  className,
+  showTitleBlock = true,
+}: PageHeaderProps) {
+  const isCollaboration = variant === "collaboration"
+  const showAccess = Boolean(isCollaboration && accessInfo)
+  const showFaceRail =
+    isCollaboration &&
+    ((collaborators && collaborators.length > 0) || Boolean(onAddCollaborator))
+  const showActionsColumn = Boolean(actions) || showFaceRail
+
   return (
     <div
       className={cn(
         "flex flex-col gap-1 px-4 pt-2 pb-4 lg:px-6",
         "sm:flex-row sm:items-end sm:gap-4",
         showTitleBlock ? "sm:justify-between" : "sm:justify-end",
-        className
+        className,
       )}
     >
       {/* Title block — hidden visually when showTitleBlock is false; keep h1 for a11y */}
-      <div className={cn("flex flex-col gap-0.5", !showTitleBlock && "sr-only")}>
+      <div className={cn("flex min-w-0 flex-col gap-0.5", !showTitleBlock && "sr-only")}>
         <h1
           className="text-2xl font-semibold tracking-tight leading-tight text-foreground"
           style={{ fontFamily: "var(--font-heading)" }}
         >
           {title}
         </h1>
+        {showAccess && (
+          <div className="flex min-w-0 flex-wrap items-center gap-x-2 gap-y-1 text-xs leading-snug text-muted-foreground">
+            {accessInfo}
+          </div>
+        )}
         {subtitle && (
           <p className="text-sm text-muted-foreground leading-none">{subtitle}</p>
         )}
       </div>
 
-      {/* Right-side actions — e.g. date picker, CTA buttons */}
-      {actions && (
-        <div className="flex items-center gap-2 shrink-0">{actions}</div>
+      {showActionsColumn && (
+        <div className="flex flex-wrap items-center gap-2 sm:gap-3 shrink-0 sm:ms-auto sm:justify-end">
+          {showFaceRail ? (
+            <PageHeaderCollaborationFaces
+              people={collaborators ?? []}
+              limit={collaboratorDisplayLimit}
+              addLabel={addCollaboratorLabel}
+              onAdd={onAddCollaborator}
+            />
+          ) : null}
+          {actions}
+        </div>
       )}
     </div>
   )

package/template/components/question-bank-client.tsx

@@ -43,6 +43,7 @@ export function QuestionBankClient() {
       tablePropertiesRef={tableRef}
       header={(
         <QuestionBankPageHeader
+          variant="collaboration"
           questionCount={count}
           onNewQuestion={() => {}}
           onExport={() => setExportOpen(true)}