@exxatdesignux/ui 0.3.0 → 0.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@exxatdesignux/ui",
-  "version": "0.3.0",
+  "version": "0.4.1",
   "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.",
   "license": "UNLICENSED",
   "author": "Exxat Design",
@@ -98,7 +98,8 @@
     "src",
     "bin",
     "template",
-    "consumer-extras"
+    "consumer-extras",
+    "tokens"
   ],
   "dependencies": {
     "@hookform/resolvers": "^5.2.2",

package/src/components/data-table/index.tsx

@@ -1100,8 +1100,8 @@ function DataTableInner<TData extends Record<string, unknown>>({
           setHeaderScrollLeft((e.currentTarget as HTMLDivElement).scrollLeft)
         }}
         className={cn(
-          "mx-4 lg:mx-6 overflow-x-auto border border-border",
-          hasFooter ? "rounded-t-lg" : "rounded-lg",
+          "mx-4 lg:mx-6 overflow-x-auto border-t border-x border-border",
+          hasFooter ? "rounded-t-lg" : "border-b rounded-lg",
         )}
       >
         <table

package/src/components/data-table/pagination.tsx

@@ -215,7 +215,11 @@ export function DataTablePaginated<TData extends Record<string, unknown>>({
         paginationOverride={{ page: safePage, pageSize }}
         hasFooter
       />
-      <div className="mx-4 lg:mx-6 border-x border-b border-border rounded-b-lg overflow-hidden">
+      {/* z-40 sits above pinned cells (z-20), group headers (z-25), and pinned headers
+          (z-40) so the pagination chrome stays opaque over any table content that
+          scrolls behind it. Pinned-left cells ship with their own `bg-dt-row-bg`,
+          which would otherwise paint over a lower-z footer. */}
+      <div className="sticky bottom-0 z-40 mx-4 lg:mx-6 border-x border-b border-border rounded-b-lg overflow-hidden bg-background">
         <PaginationBar
           page={safePage}
           pageSize={pageSize}

package/src/components/data-table/use-table-state.ts

@@ -93,7 +93,7 @@ export function useTableState<TData extends Record<string, unknown>>(
   paginationOverride?: { page: number; pageSize: number },
   /**
    * When defined (including `""`), toolbar search is synced from the URL (`?q=`).
-   * Use `searchParams.get("q") ?? ""` on question bank list routes; omit for other hubs.
+   * Use `searchParams.get("q") ?? ""` on library list routes; omit for other hubs.
    */
   syncedSearchFromUrl?: string,
 ) {

package/src/components/data-views/data-row-list.tsx

@@ -2,7 +2,7 @@
 
 /**
  * DataRowList — generic vertical-stack list view used by every hub's "list"
- * tab (placements, team, compliance, sites, question-bank, …). Replaces the
+ * tab (placements, team, compliance, sites, library, …). Replaces the
  * hand-rolled `<ul …flex-col gap-2 px-4 pb-8 pt-2 lg:px-6> {rows.map(<li>…)}`
  * shell that was duplicated across `*-list-view.tsx` files.
  *

package/src/components/data-views/finder-panel-view.tsx

@@ -3,7 +3,7 @@
 /**
  * FinderPanelView — Miller-style 3-column split for list-page hubs.
  *
- * Visual shell matches Question bank panel (`ListPageTreeColumnHeader`, `LIST_PAGE_SPLIT_MILLER_COLUMN_PANEL_CLASS`,
+ * Visual shell matches Library panel (`ListPageTreeColumnHeader`, `LIST_PAGE_SPLIT_MILLER_COLUMN_PANEL_CLASS`,
  * shared resizable handles) — see `list-page-split-hub-tokens.ts`.
  */
 
@@ -50,7 +50,7 @@ export interface FinderPanelViewProps<T> {
    * `ListPageSplitHubChrome` (shared split surface across hubs).
    */
   embedded?: boolean
-  /** Left column title (Question bank: “Categories”). */
+  /** Left column title (Library: “Categories”). */
   groupsColumnTitle?: string
   /** Middle column title; defaults from the active group label. */
   getListColumnTitle?: (activeGroup: FinderGroup | undefined) => string

package/src/components/data-views/hub-table.tsx

@@ -4,7 +4,7 @@
  * `<HubTable<TRow>>` — single centralized table surface used by every list-page hub.
  *
  * Owns all the per-hub scaffolding that was previously duplicated in `placements-table.tsx`,
- * `team-table.tsx`, `compliance-table.tsx`, `question-bank-table.tsx`, and `sites-table.tsx`:
+ * `team-table.tsx`, `compliance-table.tsx`, `library-table.tsx`, and `sites-table.tsx`:
  *
  *  • `useTableState` setup tied to the centralized row dataset
  *  • `displayOptions` state + `patchDisplay`
@@ -27,7 +27,9 @@
  */
 
 import * as React from "react"
+import { cn } from "../../lib/utils"
 import { DataTable, DataTableToolbar } from "../data-table"
+import { CountSyncer, PaginationBar } from "../data-table/pagination"
 import type { ColumnDef } from "../data-table/types"
 import { useTableState } from "../data-table/use-table-state"
 import type { DataListViewType } from "../../lib/data-list-view"
@@ -204,11 +206,17 @@ export interface HubTableProps<TRow extends Record<string, unknown>> {
   tableRenderer?: (args: HubTableRendererArgs<TRow>) => React.ReactNode
   /**
    * Forwarded to `useTableState` so the hub can switch on server-style pagination
-   * (e.g. Placements toggles between paged and unpaged tables).
+   * with externally-controlled page/pageSize (advanced; most hubs should leave
+   * this undefined and let `HubTable` own the internal page state — see
+   * `pagination` + `paginationPageSizeOptions`).
    */
   paginationOverride?: { page: number; pageSize: number }
+  /** Page size options shown in the toolbar `<PaginationBar>`. Default `[10, 25, 50, 100]`. */
+  paginationPageSizeOptions?: number[]
+  /** Initial page size when `HubTable` owns pagination internally. Default `10`. */
+  paginationInitialPageSize?: number
   /**
-   * Forwarded to `useTableState` to sync toolbar search from `?q=` (Question bank search routes).
+   * Forwarded to `useTableState` to sync toolbar search from `?q=` (Library search routes).
    * Defining as `""` enables sync without an initial query.
    */
   syncedSearchFromUrl?: string
@@ -273,6 +281,8 @@ export function HubTable<TRow extends Record<string, unknown>>({
   handleRef,
   tableRenderer,
   paginationOverride,
+  paginationPageSizeOptions = [10, 25, 50, 100],
+  paginationInitialPageSize = 10,
   syncedSearchFromUrl,
   renderListRow,
   listAriaLabel,
@@ -324,14 +334,33 @@ export function HubTable<TRow extends Record<string, unknown>>({
     [],
   )
 
+  // ─── Pagination chrome (centralized) ─────────────────────────────────────
+  // When `pagination === true` and the parent did NOT supply `paginationOverride`,
+  // `HubTable` owns the page/pageSize internally and wraps the default table +
+  // list renderers with `<CountSyncer>` + `<PaginationBar>`. Hubs that need full
+  // control (e.g. server-side pagination) keep using `paginationOverride`.
+  const [internalPage, setInternalPage] = React.useState(1)
+  const [internalPageSize, setInternalPageSize] = React.useState(paginationInitialPageSize)
+  const chromeOwnedPagination = pagination === true && paginationOverride === undefined
+  const effectivePaginationOverride =
+    paginationOverride ??
+    (chromeOwnedPagination ? { page: internalPage, pageSize: internalPageSize } : undefined)
+
   const tableState = useTableState<TRow>(
     rows,
     columns,
     defaultSort,
-    paginationOverride,
+    effectivePaginationOverride,
     syncedSearchFromUrl,
   )
 
+  const handlePageChange = React.useCallback((p: number) => setInternalPage(p), [])
+  const handlePageSizeChange = React.useCallback((n: number) => {
+    setInternalPageSize(n)
+    setInternalPage(1)
+  }, [])
+  const resetPage = React.useCallback(() => setInternalPage(1), [])
+
   // Extract the stable setter from `useTableState` first so the
   // `useImperativeHandle` deps array sees the exact value the hook reads.
   // `setSheetOpen` is referentially stable, so the handle is created once.
@@ -395,31 +424,70 @@ export function HubTable<TRow extends Record<string, unknown>>({
     ],
   )
 
-  // Default `data-table` renderer — full DataTable with toolbar + bulk actions. Hubs can
-  // override via `tableRenderer` for pagination chrome (CountSyncer + PaginationBar) or
-  // any other table-view-specific wrapping.
-  const defaultTableRenderer = (args: HubTableRendererArgs<TRow>) => (
-    <div className="pb-6">
-      <DataTable<TRow>
-        data={rows}
-        columns={columns}
-        getRowId={getRowId}
-        getRowSelectionLabel={getRowSelectionLabel}
-        selectable={selectable}
-        searchable={displayOptions.showToolbarSearch}
-        showColumnHeaders={displayOptions.showColumnLabels}
-        groupable={groupable}
-        defaultSort={defaultSort}
-        emptyState={emptyState ?? <p className="text-sm text-muted-foreground">No records match your filters.</p>}
-        conditionalRules={conditionalRules}
-        state={args.state}
-        renderFilterOptionValue={renderFilterOptionValue}
-        toolbarSlot={s => <TablePropertiesDrawerButton {...drawerToolbarProps} state={s} />}
-        bulkActionsSlot={bulkActionsSlot}
-        onRowClick={onRowClick}
-      />
-    </div>
-  )
+  // Default `data-table` renderer — full DataTable with toolbar + bulk actions. When
+  // `pagination === true` and the parent did not provide `paginationOverride`, the chrome
+  // (CountSyncer + PaginationBar) is wrapped automatically so the drawer toggle "Show
+  // pagination" works out of the box. Hubs that need finer control (custom chrome,
+  // server-side paging) can still override via `tableRenderer`.
+  const defaultTableRenderer = (args: HubTableRendererArgs<TRow>) => {
+    const filteredCount = (args.state.rows as TRow[]).length
+    const totalPages = Math.max(1, Math.ceil(filteredCount / Math.max(1, internalPageSize)))
+    const safePage = Math.min(internalPage, totalPages)
+    return (
+      <div className="pb-6">
+        {chromeOwnedPagination ? (
+          <CountSyncer
+            count={filteredCount}
+            onSync={(n) => {
+              const next = Math.max(1, Math.ceil(n / Math.max(1, internalPageSize)))
+              if (safePage > next) setInternalPage(next)
+            }}
+            onReset={resetPage}
+          />
+        ) : null}
+        <DataTable<TRow>
+          data={rows}
+          columns={columns}
+          getRowId={getRowId}
+          getRowSelectionLabel={getRowSelectionLabel}
+          selectable={selectable}
+          searchable={displayOptions.showToolbarSearch}
+          showColumnHeaders={displayOptions.showColumnLabels}
+          groupable={groupable}
+          defaultSort={defaultSort}
+          emptyState={emptyState ?? <p className="text-sm text-muted-foreground">No records match your filters.</p>}
+          conditionalRules={conditionalRules}
+          state={args.state}
+          renderFilterOptionValue={renderFilterOptionValue}
+          toolbarSlot={s => <TablePropertiesDrawerButton {...drawerToolbarProps} state={s} />}
+          bulkActionsSlot={bulkActionsSlot}
+          onRowClick={onRowClick}
+          hasFooter={chromeOwnedPagination}
+        />
+        {chromeOwnedPagination ? (
+          <div
+            className={cn(
+              "mx-4 lg:mx-6 border-x border-b border-border rounded-b-lg overflow-hidden bg-background",
+              // z-40 sits above pinned cells (z-20), group headers (z-25), and column headers
+              // (z-30 / z-40) so the sticky footer paints over any table content that scrolls
+              // behind it. Pinned-left cells ship with their own `bg-dt-row-bg`, which
+              // otherwise wins because of z-20 > z-10.
+              "sticky bottom-0 z-40",
+            )}
+          >
+            <PaginationBar
+              page={safePage}
+              pageSize={internalPageSize}
+              total={filteredCount}
+              pageSizeOptions={paginationPageSizeOptions}
+              onPageChange={handlePageChange}
+              onPageSizeChange={handlePageSizeChange}
+            />
+          </div>
+        ) : null}
+      </div>
+    )
+  }
 
   const args: HubTableRendererArgs<TRow> = {
     state: tableState,
@@ -455,20 +523,60 @@ export function HubTable<TRow extends Record<string, unknown>>({
   }
 
   // Default centralized list renderer: same DataRowList shell every hub used to roll
-  // by hand. Hub provides only the per-row body via `renderListRow`.
+  // by hand. Hub provides only the per-row body via `renderListRow`. When `pagination`
+  // is on (and `paginationOverride` is not externally supplied), the list view reads
+  // `state.pagedRows` and adds the same `CountSyncer` + `PaginationBar` chrome as the
+  // table view.
   if (renderers["list-with-toolbar"] == null && renderListRow != null) {
-    composed["list-with-toolbar"] = () =>
-      args.toolbarShell(
-        <DataRowList<TRow>
-          rows={args.state.rows as TRow[]}
-          getRowId={row => getRowId(row)}
-          ariaLabel={listAriaLabel ?? hubLabel}
-          emptyState={listEmptyState ?? "No records match your filters."}
-          {...(listVirtualizeThreshold !== undefined ? { virtualizeThreshold: listVirtualizeThreshold } : {})}
-          {...(listEstimatedRowHeight !== undefined ? { estimatedRowHeight: listEstimatedRowHeight } : {})}
-          renderRow={renderListRow}
-        />,
+    composed["list-with-toolbar"] = () => {
+      const fullRows = args.state.rows as TRow[]
+      const pagedRows = chromeOwnedPagination ? (args.state.pagedRows as TRow[]) : fullRows
+      const filteredCount = fullRows.length
+      const totalPages = Math.max(1, Math.ceil(filteredCount / Math.max(1, internalPageSize)))
+      const safePage = Math.min(internalPage, totalPages)
+      return args.toolbarShell(
+        <>
+          {chromeOwnedPagination ? (
+            <CountSyncer
+              count={filteredCount}
+              onSync={(n) => {
+                const next = Math.max(1, Math.ceil(n / Math.max(1, internalPageSize)))
+                if (safePage > next) setInternalPage(next)
+              }}
+              onReset={resetPage}
+            />
+          ) : null}
+          <DataRowList<TRow>
+            rows={pagedRows}
+            getRowId={row => getRowId(row)}
+            ariaLabel={listAriaLabel ?? hubLabel}
+            emptyState={listEmptyState ?? "No records match your filters."}
+            {...(listVirtualizeThreshold !== undefined ? { virtualizeThreshold: listVirtualizeThreshold } : {})}
+            {...(listEstimatedRowHeight !== undefined ? { estimatedRowHeight: listEstimatedRowHeight } : {})}
+            renderRow={renderListRow}
+          />
+          {chromeOwnedPagination ? (
+            <div
+              className={cn(
+                "mx-4 lg:mx-6 border-x border-b border-border rounded-b-lg overflow-hidden bg-background",
+                // Match the table-view footer — above pinned cells (z-20) and column
+                // headers (z-30 / z-40) so the sticky chrome paints over scrolling rows.
+                "sticky bottom-0 z-40",
+              )}
+            >
+              <PaginationBar
+                page={safePage}
+                pageSize={internalPageSize}
+                total={filteredCount}
+                pageSizeOptions={paginationPageSizeOptions}
+                onPageChange={handlePageChange}
+                onPageSizeChange={handlePageSizeChange}
+              />
+            </div>
+          ) : null}
+        </>,
       )
+    }
   }
 
   // Default centralized board renderer: same ListPageBoardTemplate every hub used to wrap.

package/src/components/data-views/list-page-split-hub-tokens.ts

@@ -1,9 +1,9 @@
 /**
  * Shared layout tokens for list-hub split surfaces (Miller columns, tree + details).
- * Keeps Question bank panel / tree and generic `FinderPanelView` visually aligned.
+ * Keeps Library panel / tree and generic `FinderPanelView` visually aligned.
  */
 
-/** `ResizableHandle` between miller / tree columns — matches Question bank panel. */
+/** `ResizableHandle` between miller / tree columns — matches Library panel. */
 export const LIST_PAGE_SPLIT_RESIZABLE_HANDLE_CLASS =
   "w-1 bg-border/40 hover:bg-brand/20 transition-colors"
 

package/src/components/data-views/list-page-tree-column-header.tsx

@@ -11,7 +11,7 @@ export interface ListPageTreeColumnHeaderProps {
 }
 
 /**
- * Shared left-column header for tree / outline surfaces — matches Question bank “Questions” bar.
+ * Shared left-column header for tree / outline surfaces — matches Library “Questions” bar.
  */
 export function ListPageTreeColumnHeader({
   title,

package/src/components/data-views/os-folder-glyph.tsx

@@ -10,7 +10,7 @@ import { cn } from "../../lib/utils"
 
 /**
  * Color palette tones shared across folder hubs. Domain-specific palette
- * names (e.g. `QuestionBankFolderColorKey`) are structurally identical to
+ * names (e.g. `LibraryFolderColorKey`) are structurally identical to
  * this union and pass through without conversion.
  */
 export type FolderGlyphColorKey =

package/src/components/ui/key-metrics.tsx

@@ -301,7 +301,7 @@ function metricsRowColumnsClass(rowLength: number, metricsHalfWidthLayout: boole
       // Step 1 → 2 (2×2 grid) → 4. Skip 3 — that's the awkward 3+1 layout.
       // Aggressive 4-col thresholds so the strip fits all four tiles even
       // when the primary sidebar + secondary panel + insight rail are all
-      // expanded (typical question-bank layout puts the KPI grid at ~27rem).
+      // expanded (typical library layout puts the KPI grid at ~27rem).
       return half
         ? "grid-cols-1 @[14rem]:grid-cols-2 @[26rem]:grid-cols-4"
         : "grid-cols-1 @[18rem]:grid-cols-2 @[30rem]:grid-cols-4"

package/template/.claude/skills/exxat-ds-skill/SKILL.md

@@ -112,17 +112,18 @@ ListPageTemplate
 ```
 
 **Reference implementations:**
-- `components/team-client.tsx` + `components/team-table.tsx` — canonical pattern
-- `components/data-list-client.tsx` + `components/data-list-table.tsx` — Placements (most complete)
+- `components/columns-showcase.tsx` + `components/columns-client.tsx` — smallest single-view hub (start here)
+- `components/tokens-themes-client.tsx` + `components/tokens-secondary-nav.tsx` — hub with secondary panel + URL-driven scope + built-in pagination chrome
+- `components/library-table.tsx` + `components/library-hub-client.tsx` — full multi-view hub (table, board, dashboard)
 
 **Files to create for a new hub page `Foo`:**
 | File | Purpose |
 |------|---------|
 | `lib/mock/foo.ts` | Mock data + TypeScript interface (12+ rows) |
-| `lib/mock/foo-kpi.ts` | `fooKpiMetrics()` + `fooKpiInsight()` |
+| `lib/mock/foo-kpi.ts` | `fooKpiMetrics()` (≤ 4 `MetricItem`s, each with `onClick` or `href`) + `fooKpiInsight()` returning a single `MetricInsight` |
 | `components/foo-page-header.tsx` | `PageHeader` + primary CTA + ⋯ menu |
-| `components/foo-table.tsx` | `DataTable` + `useTableState` + `TablePropertiesDrawer` |
-| `components/foo-client.tsx` | `ListPageTemplate` orchestrator |
+| `components/foo-showcase.tsx` *or* `components/foo-table.tsx` | `HubTable` (NOT raw `DataTable`) — pass `pagination` / `onPaginationChange` if the hub needs pagination chrome |
+| `components/foo-client.tsx` | `ListPageTemplate` orchestrator, mounts `KeyMetrics` with `items` + `insight` |
 | `app/(app)/foo/page.tsx` | Thin server component |
 
 **Do not** ship a **nav-linked hub** as an **empty page** or a single “replace this later” paragraph. If the route appears in **`lib/mock/navigation.tsx`**, implement the full hub (mock rows, **`ListPageTemplate`**, connected views per **`exxat-ds/AGENTS.md` §4.1**) unless the product explicitly defines a non-data shell.
@@ -148,7 +149,7 @@ Align with **`exxat-ds/AGENTS.md` §6.4**, **`docs/data-views-pattern.md`**, **`
 | `ColumnDef` from `@/components/data-table/types` | Column type |
 | `FilterFieldDef`, `FilterOperator`, `ConditionalRule` from `@/components/table-properties/types` | Filter types |
 
-**Board (kanban) cards:** Use **`ListPageBoardCard`** and related parts from **`components/data-views/list-page-board-card.tsx`**; **`BoardCardTwoLineBlock`** / **`BoardCardIconRow`** from **`board-card-primitives.tsx`**. **List hub** status (Team, Compliance, Question bank, …): maps in **`lib/list-status-badges.ts`**; render with **`ListHubStatusBadge`** (**`surface="table"`** in table/list, **`surface="board"`** on cards); semantic tints **`LIST_HUB_STATUS_TINT_*`** for new domains; no **`uppercase`**. **Placements** uses **`StatusBadge`** in **`data-list-table-cells.tsx`** (wrapper over **`ListHubStatusBadge`** + **`PLACEMENT_STATUS_*`**). **Full rules:** **`exxat-ds/AGENTS.md` §4.4**, **`.cursor/rules/exxat-board-cards.mdc`**, **`.cursor/skills/exxat-board-cards/SKILL.md`**.
+**Board (kanban) cards:** Use **`ListPageBoardCard`** and related parts from **`components/data-views/list-page-board-card.tsx`**; **`BoardCardTwoLineBlock`** / **`BoardCardIconRow`** from **`board-card-primitives.tsx`**. **List hub** status (Team, Compliance, Library, …): maps in **`lib/list-status-badges.ts`**; render with **`ListHubStatusBadge`** (**`surface="table"`** in table/list, **`surface="board"`** on cards); semantic tints **`LIST_HUB_STATUS_TINT_*`** for new domains; no **`uppercase`**. **Placements** uses **`StatusBadge`** in **`data-list-table-cells.tsx`** (wrapper over **`ListHubStatusBadge`** + **`PLACEMENT_STATUS_*`**). **Full rules:** **`exxat-ds/AGENTS.md` §4.4**, **`.cursor/rules/exxat-board-cards.mdc`**, **`.cursor/skills/exxat-board-cards/SKILL.md`**.
 
 **Minimum required features on any data list page:**
 - Search (wire `searchable={displayOptions.showToolbarSearch}`)
@@ -245,7 +246,7 @@ Use `PageHeader` from `@/components/page-header` for the content-area header (be
 
 When a hub is **shared**, use **`PageHeader` `variant="collaboration"`**: **empty roster** → outline **Add collaborator**; **non-empty** → face rail (faces / **`+N`** open the invite sheet). **Invite people** also lives under the entity header **⋯ More** and opens **`InviteCollaboratorsDrawer`** via **`CollaborationAccessFlow`** when possible. Library access (Owner / Editor / Commenter / Viewer) comes from **`lib/collaborator-access.ts`**; directory tags (Faculty, Program coordinator, Director) use **`PageHeaderCollaborator.roles`**.
 
-**Handbook:** `apps/web/AGENTS.md` §4.7 · **Doc:** `docs/collaboration-access-pattern.md` · **Skill:** `.cursor/skills/exxat-collaboration-access/SKILL.md` · **Reference:** Question bank header + client.
+**Handbook:** `apps/web/AGENTS.md` §4.7 · **Doc:** `docs/collaboration-access-pattern.md` · **Skill:** `.cursor/skills/exxat-collaboration-access/SKILL.md` · **Reference:** Library header + client.
 
 ---
 

package/template/.cursor/rules/exxat-accessibility.mdc

@@ -26,7 +26,7 @@ alwaysApply: true
    - **C. Interactive icon-only button/link** (close `×`, chevron, overflow `⋯`, sort, filter-dismiss, copy, Ask Leo toggle, row actions) → MUST pair **`aria-label`** on the `<button>` with a wrapping **`Tooltip`**. `aria-label` alone is not enough — sighted users rely on the tooltip too.
 
    In all cases the inner `<i>` / `<svg>` is `aria-hidden`; tooltip text matches the accessible name. Narrow exception: chevron inside a labelled composite (`Select`, `Combobox`). See **`AGENTS.md` §8.6 (Case A/B/C)**.
-10. **Keyboard shortcut hints inside buttons** MUST use **`<Kbd variant="bare">`** (no background/border, inherits `currentColor` at 70%). The default `tile` variant is for **tooltips** and **menu `shortcut=` slots** only. Glue multi-key chords into one bare kbd (e.g. `<Kbd variant="bare">⌘⌥K</Kbd>`). Reference: Next/Back in `new-placement-form.tsx`; see **`.cursor/rules/exxat-kbd-shortcuts.mdc`**.
+10. **Keyboard shortcut hints inside buttons** MUST use **`<Kbd variant="bare">`** (no background/border, inherits `currentColor` at 70%). The default `tile` variant is for **tooltips** and **menu `shortcut=` slots** only. Glue multi-key chords into one bare kbd (e.g. `<Kbd variant="bare">⌘⌥K</Kbd>`). Reference: Next/Back in `new-library-item-form.tsx`; see **`.cursor/rules/exxat-kbd-shortcuts.mdc`**.
 
 Re-run **axe** on **Placements** (or affected page) after changing **views toolbar** or **tabs**.
 

package/template/.cursor/rules/exxat-command-menu.mdc

@@ -7,7 +7,7 @@ alwaysApply: true
 
 ## Intent
 
-- **`CommandMenu`** (**⌘K** / **Ctrl+K**) is **global search** (routes, library, patterns, AI starters, optional row data such as placements / student names)—see **`AGENTS.md` §7.1** and **`docs/command-menu-pattern.md`**.
+- **`CommandMenu`** (**⌘K** / **Ctrl+K**) is **global search** (routes, library, patterns, AI starters, optional row data such as student names / question stems) — see **`AGENTS.md` §7.1** and **`docs/command-menu-pattern.md`**.
 - **Quick / lookup / short AI:** Prefer **results inside the palette** when the product can return compact answers or lightweight “research” without leaving the flow.
 - **Long or complex answers:** **Ask Leo** side panel (**⌘⌥K** / **Ctrl+Alt+K**)—not forced into the palette.
 

package/template/.cursor/rules/exxat-dashboard-view-charts.mdc

@@ -12,7 +12,7 @@ alwaysApply: true
 | Surface | Entry | Shared building blocks |
 |--------|--------|-------------------------|
 | **Full-page dashboard** | `app/(app)/dashboard/page.tsx` | `DashboardTabs`, `ChartsOverview` / gallery demos in `charts-overview.tsx` |
-| **Data tab** on Placements / Team / Compliance | `PlacementsTable`, `TeamTable`, `ComplianceTable` → `*DashboardChartsSection` | `ChartFigure`, `ChartCard`, `useChartVariant()`, `data-view-dashboard-charts*.tsx` |
+| **Data tab** on a hub | `library-table.tsx` → `LibraryDashboardChartsSection` (reference) | `ChartFigure`, `ChartCard`, `useChartVariant()`, the hub's own `*-dashboard-charts.tsx` module |
 
 **MUST NOT** duplicate “another” chart system for Data view — extend **`charts-overview`** patterns and **`lib/chart-keyboard-selection`**.
 
@@ -36,8 +36,8 @@ alwaysApply: true
 
 ## MUST — persistence (centralized)
 
-- **One bundle:** **`lib/data-view-dashboard-storage.ts`** — key **`exxat-ds:data-view-dashboards:v1`**, scopes **`placements` | `team` | `compliance`**.
-- Placements helpers: **`loadDashboardLayout`** / **`saveDashboardLayout`** in **`data-view-dashboard-charts.tsx`** (wrap storage API).
+- **One bundle:** **`lib/data-view-dashboard-storage.ts`** — key **`exxat-ds:data-view-dashboards:v1`**. Each hub registers under a scope string (e.g. **`library`**); add new scopes there, never invent a sibling `localStorage` key.
+- Hub-side: pair **`loadDataViewLayout`** + **`saveDataViewLayout`** with **`mergeDashboardLayoutGeneric`** (`lib/dashboard-layout-merge.ts`) for default-layout safety. Reference: the Library dashboard wiring inside **`library-table.tsx`** + **`library-dashboard-charts.tsx`**.
 - **MUST NOT** introduce parallel **`localStorage`** keys for the same **`DashboardLayout`** shape without updating the storage module.
 
 ## SHOULD — coach marks
@@ -47,7 +47,7 @@ alwaysApply: true
 
 ## Reference files
 
-- `components/data-view-dashboard-charts.tsx` (Placements)
-- `components/data-view-dashboard-charts-team.tsx`, `data-view-dashboard-charts-compliance.tsx`
-- `components/placements-table.tsx` — dashboard tab body wires `PlacementsDashboardChartsSection` + layout-edit toolbar inline (no separate `DashboardShell` component)
+- `components/library-dashboard-charts.tsx` — canonical Data-tab dashboard section (`LibraryDashboardChartsSection`) — chart cards, `MetricsCard`, layout-edit toolbar.
+- `components/library-table.tsx` — dashboard tab body wires `LibraryDashboardChartsSection` + layout-edit toolbar inline (no separate `DashboardShell` component).
+- `components/charts-overview.tsx` — full-page dashboard chart gallery referenced from `app/(app)/dashboard/page.tsx`.
 - `lib/chart-keyboard-selection.ts`, `lib/data-view-dashboard-storage.ts`, `lib/dashboard-customize-coach-mark.ts`

package/template/.cursor/rules/exxat-data-tables.mdc

@@ -7,16 +7,16 @@ alwaysApply: true
 
 ## Use one stack for product data lists
 
-For **any app screen that shows a browsable, filterable grid of records** (lists, directories, placements, etc.):
+For **any app screen that shows a browsable, filterable grid of records** (directories, tokens, columns showcase, question banks, etc.):
 
 1. **Base table:** `DataTable` from `@/components/data-table` (optionally wrapped with `DataTablePaginated` when pagination is required).
 2. **Search:** Wire the table’s search/query UX (toolbar search or equivalent) — do not ship a “bare” table without find-in-list behavior when the page is a data list.
 3. **Filters:** Use the shared filter model (filter chips / `FilterFieldDef` and operators) consistent with existing list pages — not one-off filter UIs that bypass the table stack.
-4. **Table properties:** Include **Table properties** via `TablePropertiesDrawer` from `@/components/table-properties/drawer` (or the same toolbar + drawer pattern used on reference pages such as placements / data list). Users must be able to adjust columns, density, and related table settings from one place.
+4. **Table properties:** Include **Table properties** via `TablePropertiesDrawer` from `@/components/table-properties/drawer` (or the same toolbar + drawer pattern used on the reference pages — `library-table.tsx`, `columns-showcase.tsx`, `tokens-themes-client.tsx`). Users must be able to adjust columns, density, and related table settings from one place.
 5. **Active view:** On **`ListPageTemplate`** pages with **table / list / board / dashboard** tabs, **`TablePropertiesDrawer`** **MUST** receive **`currentView`** and **`onViewChange`** (see **`./AGENTS.md` §4.2** and **`.cursor/rules/exxat-table-properties-drawer.mdc`**) so Properties matches the selected view (not table-only copy on Board).
 6. **Dropdown menus:** **`DropdownMenuContent`** uses the shared **`@exxatdesignux/ui`** default (**intrinsic `w-max`**, **`min-w-52`**, capped **`max-w`**) for view settings, row ⋯, column menus, and filter pickers — **pure CSS**, no **`ResizeObserver`**. Override only for deliberate narrow/wide rails (e.g. pagination **`w-20`**, account trigger-width, school switcher **`!w-max min-w-72 …`**). See **`docs/data-views-pattern.md`** (“Dropdown menus”).
 
-**Reference implementation:** `components/placements-table.tsx` (placements) shows how `DataTable`, filters, and `TablePropertiesDrawer` compose together.
+**Reference implementations:** `components/library-table.tsx` (full hub: table / board / dashboard, conditional rules, bulk actions), `components/columns-showcase.tsx` (catalog hub composing every `table-cells.tsx` primitive — built-in pagination via `HubTable`), and `components/tokens-themes-client.tsx` (table + secondary-panel category rail). Each shows how `HubTable`, filters, and `TablePropertiesDrawer` compose together.
 
 ## Do not
 

package/template/.cursor/rules/exxat-kbd-shortcuts.mdc

@@ -24,7 +24,7 @@ Use `@/components/ui/kbd` (`Kbd` + `KbdGroup`) anywhere users discover actions b
    | Inside a `DropdownMenuItem` via `shortcut=` | menu handles it — pass the chord string |
    | Standalone helper text on a surface | **default `tile`** |
 
-   Glue multi-key chords into **one** bare kbd (`<Kbd variant="bare">⌘⌥K</Kbd>`), not one tile per key. See `new-placement-form.tsx` (Next = `{mod}⏎`, Back = `{mod}{alt}←`) and the primary "Ask Leo" button inside chart insight popovers.
+   Glue multi-key chords into **one** bare kbd (`<Kbd variant="bare">⌘⌥K</Kbd>`), not one tile per key. See `new-library-item-form.tsx` (Next = `{mod}⏎`, Back = `{mod}{alt}←`) and the primary "Ask Leo" button inside chart insight popovers.
 
 1. **Pair hint with behavior** — If `Kbd` shows a chord, implement the same shortcut. **Preferred:** the shared primitives from `@/components/ui/dropdown-menu`:
 
@@ -58,8 +58,8 @@ Use `@/components/ui/kbd` (`Kbd` + `KbdGroup`) anywhere users discover actions b
 | Toggle main sidebar | ⌘/Ctrl + **B** (`components/ui/sidebar.tsx`) |
 | Table search | ⌘/Ctrl + **K** (no Alt — `DataTable`) |
 | Ask Leo | ⌘/Ctrl + **⌥/Alt** + **K** |
-| New placement (Placements header) | ⌘/Ctrl + **⌥/Alt** + **N** |
-| Placements overflow menu | ⌘/Ctrl + **⌥/Alt** + **M** |
+| New record (primary hub header) | ⌘/Ctrl + **⌥/Alt** + **N** |
+| Hub overflow menu (⋯) | ⌘/Ctrl + **⌥/Alt** + **M** |
 | Export | ⌘/Ctrl + **⇧/Shift** + **E** |
 | Hide/Show metric section | ⌘/Ctrl + **⌥/Alt** + **H** |
 | Rename (view, tab) | **F2** |
@@ -79,14 +79,14 @@ Every **workflow surface** (form, dialog, drawer, sheet, multi-step wizard final
 1. **Primary action (submit/commit)** — **Enter** (⏎). Render the `<Kbd>⏎</Kbd>` **inline inside the button** (after the label, inside a `<KbdGroup className="ml-1.5">`) — NOT inside a hover `Tip`. Primary/secondary workflow buttons must expose the shortcut at rest so it is discoverable without hovering. Pair with a `<Shortcut keys="Enter" onInvoke={...}>` mounted while the surface is open. The shared `useShortcut` hook skips events from inputs/textarea/contenteditable, so Enter inside a text field still types normally — it only fires when focus is on the surface chrome.
 2. **Secondary action (Cancel/Dismiss)** — **Esc**. Inline `<Kbd>Esc</Kbd>` inside the Cancel button (same `ml-1.5` pattern). Radix `Dialog` / `Sheet` / `AlertDialog` already bind Esc natively.
 
-> Tip-on-hover Kbd hints remain correct for **page-level** actions (e.g. "New placement", ⋯ overflow triggers) where the button is part of dense page chrome and a persistent Kbd would crowd the layout. Workflow buttons inside a form/drawer/dialog are spacious enough to render the Kbd inline.
+> Tip-on-hover Kbd hints remain correct for **page-level** actions (e.g. primary "New …" CTA, ⋯ overflow triggers) where the button is part of dense page chrome and a persistent Kbd would crowd the layout. Workflow buttons inside a form/drawer/dialog are spacious enough to render the Kbd inline.
 
 **Variant inside a button:** always use `<Kbd variant="bare">` — no background, no border, inherits `currentColor` at 70% opacity. The default tile variant looks like a pasted-on patch on filled primary buttons. Glue multi-key chords into one `<Kbd variant="bare">⌘⌥←</Kbd>` rather than one tile per key.
 3. **Multi-step wizards** — plain **Enter** must NOT submit on intermediate steps (it would auto-close the review/final step when users hit Enter inside an input). Either:
    - Gate `form.onSubmit` on `step === lastStep` (`if (step !== N) { e.preventDefault(); return }`), **or**
    - Remove `type="submit"` on intermediate Next buttons and bind **⌘Enter** to "Next" via `<Shortcut>`.
    On the final step, plain **Enter** submits and the Kbd hint shows **⏎**.
-4. Examples in-app: `new-placement-form.tsx` (Create placement = Enter on step 5, Back = ⌘⌥←), `export-drawer.tsx` (Export = Enter, Cancel = Esc).
+4. Examples in-app: `new-library-item-form.tsx` (Create = Enter on the final step, Back = ⌘⌥←), `export-drawer.tsx` (Export = Enter, Cancel = Esc).
 
 ## Every action menu MUST carry shortcuts
 

package/template/.cursor/rules/exxat-mono-ids.mdc

@@ -16,7 +16,7 @@ Use this when rendering **system identifiers** — values a user copies, searche
 
 ## SHOULD
 
-- Match existing hubs: **`question-bank-table.tsx`**, **`question-bank-list-view.tsx`**, **`new-question-composer.tsx`** (header subtitle), **`sites-table.tsx`** (`row.id`).
+- Match existing hubs: **`library-table.tsx`**, **`columns-showcase.tsx`** (mono record IDs in the showcase row), **`new-library-item-form.tsx`** (header subtitle).
 - Prefer **`truncate`** / **`min-w-0`** on mono IDs in tight layouts so long tokens do not blow out columns.
 
 ## MUST NOT

package/template/.cursor/rules/exxat-page-vs-drawer.mdc

@@ -13,7 +13,7 @@ alwaysApply: true
 ## Product examples (this repo)
 
 - **Drawer-appropriate:** `TablePropertiesDrawer`, `ExportDrawer`, lightweight panels that supplement a hub.
-- **Page-appropriate:** Full placement or settings flows that are the main task, multi-screen wizards.
+- **Page-appropriate:** Full settings flows, multi-step record-creation wizards (e.g. `new-library-item-form.tsx`), or any task that is itself the user's primary intent.
 
 ## Authoritative detail
 

package/template/.cursor/rules/exxat-table-properties-drawer.mdc

@@ -28,7 +28,7 @@ When **`ListPageTemplate`** drives **`tab.viewType`** and the page renders **`Ta
 
 3. Thread **`view`** and **`onViewChange`** through: **client → table component → drawer toolbar → `TablePropertiesDrawer`**.
 
-**Reference implementations:** `components/placements-table.tsx` (`PlacementsTable`), `components/team-client.tsx` + `team-table.tsx`, `components/compliance-client.tsx` + `compliance-table.tsx`.
+**Reference implementations:** `components/library-hub-client.tsx` + `library-table.tsx` (full hub: table / board / dashboard, conditional rules, bulk actions), `components/columns-showcase.tsx` (single-table catalog + built-in pagination via `HubTable`), `components/tokens-themes-client.tsx` (table + `SecondaryPanel` category rail).
 
 ## MUST NOT