@exxatdesignux/ui 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,594 @@
 # Changelog
 
+## 0.4.0
+
+### Minor Changes
+
+- ### Build and distribution overhaul
+
+  The package now ships a real compiled `dist/` (ESM + `.d.ts` + source
+  maps) produced by `tsup`, replacing the previous shadcn-style "ship raw
+  `.tsx` source" approach. Non-Next consumers (Vite, Remix, plain Node
+  tooling) can now install and import without configuring a TS/JSX
+  transform for `node_modules`.
+  - `exports`, `main`, `module`, `types` point at `./dist/*`.
+  - `"use client"` directives are preserved on emit via a post-build pass
+    in `tsup.config.ts`.
+  - `prepack` builds before publish so `dist/` is always current.
+  - Per-component subpath imports
+    (`@exxatdesignux/ui/components/<name>`) continue to work — they now
+    resolve to `dist/components/ui/<name>.js`.
+
+  ### New primitives
+  - **`AlertDialog`** — blocking confirm dialog backed by Radix
+    `AlertDialog`. Ships `AlertDialogAction` + `AlertDialogCancel` that
+    wrap `Button` so consumers can pair destructive verbs without
+    re-styling. Read the new
+    `.cursor/rules/exxat-drawer-vs-dialog.mdc` for when to choose this
+    over the generic `Dialog`.
+  - **`Accordion`** — Radix-backed expandable section list with
+    chevron-flipping triggers. Use for FAQ-style or settings-grouping
+    surfaces where each panel toggles independently (`type="multiple"`)
+    or as a single-open group (`type="single"`).
+  - **`ContextMenu`** — right-click + long-press menu mirroring the
+    `DropdownMenu` surface (same item heights, tints, separators,
+    sub-menu chevron, checkbox / radio item indicators). Pair with a
+    visible `…` overflow `DropdownMenu` so keyboard-only users can reach
+    the same actions.
+  - **`HoverCard`** — richer hover surface for content too large or
+    interactive for a `Tooltip` (avatars, link previews, glossary
+    entries). Comes with the same animation tokens as `Popover`.
+  - **`ScrollArea`** — explicitly-bounded scroll container with
+    always-visible-on-hover scrollbars that respect platform conventions;
+    for sidebar trees, popover lists, long inspector panels.
+  - **`Slider`** — single- and dual-thumb numeric range backed by Radix
+    `Slider`. Thumbs render automatically based on `value` / `defaultValue`
+    cardinality.
+
+  Each primitive is exported from both the umbrella entry
+  (`@exxatdesignux/ui`) and a subpath
+  (`@exxatdesignux/ui/components/<name>`); matching `apps/web`
+  re-export shims live at `apps/web/components/ui/<name>.tsx`.
+
+  ### Promoted patterns (no longer leaf-only)
+
+  The package now ships product patterns alongside primitives — the same
+  shape as SLDS, Adobe Spectrum, Primer, MUI, Chakra.
+  - **`PageHeader`** — full hub header (h1, subtitle, optional
+    collaboration variant with face row + access info). Moved from
+    `apps/web/components/page-header.tsx`. `apps/web` keeps a 1-line
+    re-export shim at the original path; every existing
+    `import … from "@/components/page-header"` site continues to work.
+  - **`ListPageViewFrame`** — shared horizontal gutter + optional
+    centered max-width for non-`DataTable` list-hub view bodies (folder
+    icon grid, finder panel, OS-style explorer). Moved from
+    `apps/web/components/data-views/list-page-view-frame.tsx`.
+  - **`KeyMetrics`** (with `KeyMetricsContent`, `MetricItem`,
+    `MetricInsight`, `metricTrendTone`, `metricTrendAriaQualifier`) —
+    the full ~1.1 k LOC KPI strip moved from
+    `apps/web/components/key-metrics.tsx`. Hard-wired references to the
+    host app's `useAskLeo()` hook and `<AskLeoShortcutKbds />` component
+    are gone; both flow through a new injectable context.
+
+    Consumers wire their assistant by mounting `KeyMetricsProvider`
+    near the root and passing two optional values:
+    - **`defaultInsightAction: () => void`** — fires when the user
+      clicks the default "Ask Leo about these metrics" header CTA.
+      When omitted, the CTA is hidden entirely so the strip stays
+      useful in apps without an AI surface.
+    - **`shortcutHint: React.ReactNode`** — inline kbd chord (or any
+      node) rendered next to the action label inside the tooltip.
+      When omitted, the tooltip shows just the label.
+    - **`defaultActionLabel: string`** — visible + accessible name
+      for the header CTA. Defaults to "Ask Leo".
+
+    This is the same injection shape Adobe Spectrum (`Provider`-based
+    services) and Material UI (`Theme` context) use, so design-system
+    patterns can ship without taking a hard dependency on the host
+    app's AI / shortcut wiring.
+
+    `apps/web` keeps a 1-line `key-metrics.tsx` re-export shim plus a
+    new `key-metrics-ask-leo-bridge.tsx` adapter that's mounted in
+    `(app)/layout.tsx` just inside `AskLeoProvider`. All 20 existing
+    `<KeyMetrics />` consumers continue to work with no source
+    changes.
+
+  ### New shared utilities (`@exxatdesignux/ui/lib/*`)
+
+  Foundation modules promoted from `apps/web` so the upcoming
+  `DataTable`, `useTableState`, and `TablePropertiesDrawer` promotions
+  have a stable shared contract.
+  - **`row-height`** — `RowHeight` type + `ROW_HEIGHT_TILES` density
+    presets (compact / default / comfortable). Shared by the Properties
+    drawer tiles and `useTableState`.
+  - **`raf-throttle`** — coalesces high-frequency event handlers
+    (scroll, resize, ResizeObserver) into one call per animation frame
+    with a `.cancel()` for effect cleanup.
+  - **`editable-target`** — `isEditableTarget()` guard used by global
+    keyboard-shortcut handlers (Export `⌘⇧E`, rename `F2`, …) so
+    hotkeys don't steal keystrokes from text inputs / `contenteditable`
+    surfaces.
+  - **`conditional-rule-match`** — pure matchers
+    (`conditionalRuleMatchesRow`, `getConditionalRowBackground`,
+    `getConditionalCellBackground`) shared by `DataTable` cells,
+    `data-row-list` rows, and board card row tints so all three views
+    paint conditional formatting identically.
+  - **`table-properties-types`** — generic filter / sort /
+    conditional-rule type contracts (`FilterOperator`,
+    `FilterTextMask`, `FilterFieldDef`, `ActiveFilter`, `SortRule`,
+    `ColDef`, `ConditionalRule`) plus the design-system
+    `OPERATOR_LABELS` and `RULE_COLORS` palette. Product-specific seed
+    data (Placements `FILTER_FIELDS` + `COLUMNS` arrays) intentionally
+    stays in `apps/web/components/table-properties/types.ts`, which
+    now re-exports the types from the package.
+
+  `apps/web` keeps 1-line shims at the original `@/lib/*` paths
+  (`row-height.ts`, `raf-throttle.ts`, `editable-target.ts`,
+  `conditional-rule-match.ts`) so every existing import site continues
+  to work with no source change. The 12 files that import from
+  `@/components/table-properties/types` also keep working because the
+  file now re-exports the package types alongside the Placements
+  defaults.
+
+  ### Promoted DataTable (the biggest one)
+
+  The full generic `DataTable<TData>` family moved into the package as
+  `@exxatdesignux/ui/components/data-table` — ~3 k LOC across six files:
+  - **`./components/data-table`** (the umbrella) — `DataTable`,
+    `DataTableExtendedProps`, the column header context menu, resizing,
+    drag-to-reorder, per-column quick search, pinned columns,
+    group-by + collapsible groups, hidden columns, bulk-action bar,
+    conditional cell tints, sticky group headers, the column auto-fit
+    algorithm, and the inline filter popovers. Imports from
+    `next-themes` (light/dark column resizers) and `react-dom`
+    (`createPortal` for the bulk-action bar) are passed through; everything
+    else routes to DS primitives or DS lib utilities.
+  - **`./components/data-table/use-table-state`** — the 758-LOC hook
+    that owns filtering, sorting, search, density, pinning, hidden
+    columns, group-by, and column ordering for any consumer table.
+    No app-specific coupling; takes a generic `TData[]` + column defs.
+  - **`./components/data-table/pagination`** — `PaginationBar`,
+    `DataTablePaginated`, and `CountSyncer`. Wraps the umbrella
+    `DataTable` with a page-size selector + page navigation.
+  - **`./components/data-table/types`** — `ColumnDef`, `CellContext`,
+    `DataTableProps`, `PaginationConfig`, `SortDir`. Re-exports
+    `ConditionalRule` and `FilterTextMask` from the package
+    `table-properties-types` so column-def authors only need one import.
+  - **`./components/data-table/filter-date-calendar`** — single-date
+    YYYY-MM-DD filter calendar shared by the inline filter popover and
+    the Properties drawer date inputs.
+  - **`./components/data-table/filter-text-value-input`** — masked /
+    unmasked text input router for filter values (`phone`, `zip`,
+    `dateMDY`, free text). Falls back to the package `Input` when no
+    mask is requested.
+
+  The promotion required **no decoupling work** — Wave 7's `KeyMetrics`
+  context refactor and Wave 8's lib promotions had already moved every
+  shared dependency into the package. The DataTable suite has no
+  `useAskLeo`-style app-runtime coupling; every `@/` import the original
+  files used now resolves inside `packages/ui`.
+
+  Package `exports` map adds two new entries so the umbrella + subpath
+  imports both work:
+  - `./components/data-table` → `dist/components/data-table/index.js`
+  - `./components/data-table/*` →
+    `dist/components/data-table/*.{js,d.ts}`
+
+  These are declared **before** the generic `./components/*` rule so
+  the literal key and longer pattern win specificity resolution.
+
+  `apps/web/components/data-table/*.{ts,tsx}` (all 6 files) become 1-line
+  re-export shims so every existing
+  `import { DataTable } from "@/components/data-table"` site (~12 hubs
+  plus `useTableState` consumers) continues to work with no source
+  change.
+
+  The package now publishes `dist/components/data-table/{index,
+pagination, use-table-state, filter-date-calendar,
+filter-text-value-input, types}.{js,d.ts,js.map}` with the leading
+  `"use client"` directive preserved on every client module.
+
+  ### Linting
+  - Add `eslint-plugin-react-hooks` to `packages/ui` and register
+    `react-hooks/rules-of-hooks` (error) + `react-hooks/exhaustive-deps`
+    (warn). Required so the promoted `DataTable` and `useTableState`
+    files keep working — both carry targeted `eslint-disable-next-line
+react-hooks/exhaustive-deps` comments that previously errored out
+    with "Definition for rule '…' was not found".
+
+  ### Promoted Table Properties drawer + data-list view registry
+
+  The full Table Properties drawer family moved into the package as
+  `@exxatdesignux/ui/components/table-properties` — ~1.6 k LOC across six
+  files plus the five data-list-view lib modules that the drawer (and
+  `ListPageTemplate` view tabs) read for label / icon / render-kind
+  metadata.
+  - **`./components/table-properties`** (the umbrella):
+    - `drawer.tsx` (~1.1 k LOC) — Properties sheet with View type tiles,
+      Filters / Sort / Group / Columns panels, Conditional formatting
+      rules, and the Display sub-sheet (gridlines, row height,
+      pagination, board swimlane field, line count). Sheet uses `z-[90]`
+      so portaled menus from inside it stack on top of `z-50` dropdowns.
+    - `drawer-button.tsx` (~280 LOC) — Reusable Properties button + drawer
+      combo. Accepts any `useTableState<T>` return value as `state`
+      (structural typing reads only display-agnostic fields, so it works
+      for any row shape). Mutators are read via `stateRef.current.X`
+      inside the Sheet portal, so handler identities stay stable
+      across re-renders.
+    - `filter-card.tsx` (~250 LOC) — One filter row inside the drawer
+      (operator dropdown, value picker, remove button). Used by both
+      filter rules and conditional-formatting rules.
+    - `sort-card.tsx` (~60 LOC) — One sort rule in the Sort panel (label,
+      direction toggle, drag handle, remove).
+    - `column-row.tsx` (~90 LOC) — One row in the Columns panel
+      (visibility toggle, drag handle).
+    - `draggable-list.ts` (~50 LOC) — `useDraggableList` pointer-driven
+      reorder hook shared by sort cards, column rows, and conditional
+      rule lists.
+
+    Both `drawer.tsx` and `drawer-button.tsx` get cleaner contracts as
+    part of the move: **`fieldDefinitions` and `filterFields` are now
+    required props**, replacing the silent fallback to the Placements
+    `COLUMNS` / `FILTER_FIELDS` constants. Every real consumer was
+    already passing both through `drawerToolbarProps` from
+    `HubTable` (built once via `columnsToFieldDefinitions` /
+    `columnsToFilterFields`); the fallback path was unreachable and
+    leaked Placements column shapes into the design-system package.
+    `DrawerSortCard` similarly drops its `COLUMNS.find(…).label`
+    fallback — the drawer always passes a `fieldLabel`
+    (`resolveColumnLabel(rule.fieldKey)`).
+
+  - **`./lib/data-list-view`** — `DataListViewType` vocabulary
+    (`table | list | board | dashboard | calendar | folder | panel |
+tree-panel`), `DATA_LIST_VIEW_TILES`, `dataListViewLabel`,
+    `dataListViewIcon`, `dataListViewAddShortcut`.
+  - **`./lib/data-list-view-registry`** — Registry that maps each view
+    type to its render kind + chrome rules (`hubMetricsStrip`,
+    `dataListViewTilesForHub`, `dataListViewSelectionTilesForHub`,
+    `DATA_LIST_SURFACE_VIEW_TYPES`, `isDataListSurfaceViewType`,
+    `isDataListViewTypeSupported`).
+  - **`./lib/data-list-view-surface`** — `DataListViewRenderKind` enum
+    - `getDataListViewRenderKind`, `usesDataTableComponent`,
+      `usesDashboardSurface`, `usesToolbarWithFilteredRows` predicates so
+      `view === "dashboard"` is never mistaken for `view === "board"` in
+      switch chains.
+  - **`./lib/data-list-display-options`** — `DataListDisplayOptions`
+    (board line count, board swimlane key, show titles / column labels /
+    search) + `DEFAULT_DATA_LIST_DISPLAY_OPTIONS`.
+  - **`./lib/list-page-table-properties`** —
+    `createListPageEditViewHandler` + `OpenTablePropertiesHandle` so
+    `ListPageTemplate`'s "View → Edit" callback opens the drawer (after
+    coercing the tab to `table` when the active view does not host
+    Properties).
+
+  Package `exports` map adds:
+  - `./components/table-properties` →
+    `dist/components/table-properties/index.js` (umbrella)
+  - `./components/table-properties/*` →
+    `dist/components/table-properties/*.{js,d.ts}` (subpath)
+
+  `apps/web` keeps 1-line shims at all the original paths:
+  - 6 drawer-family files at `apps/web/components/table-properties/*`
+    (`drawer`, `drawer-button`, `filter-card`, `sort-card`, `column-row`,
+    `draggable-list`) — all re-export from
+    `@exxatdesignux/ui/components/table-properties/*`.
+  - 5 lib files at `apps/web/lib/*` (`data-list-view`,
+    `data-list-view-registry`, `data-list-view-surface`,
+    `data-list-display-options`, `list-page-table-properties`).
+
+  `apps/web/components/table-properties/types.ts` keeps the
+  Placements-specific `FILTER_FIELDS` + `COLUMNS` seed data (those are
+  **product data**, not design-system primitives) and continues to
+  re-export the generic types from `@exxatdesignux/ui/lib/table-properties-types`,
+  so every existing `import … from "@/components/table-properties"`
+  site keeps working unchanged.
+
+  The package now ships
+  `dist/components/table-properties/{drawer, drawer-button, filter-card,
+sort-card, column-row, draggable-list, index}.{js,d.ts,js.map}` with
+  the leading `"use client"` directive preserved on the 5 client modules
+  (`draggable-list` is a pure hook so the inheriting consumer's `"use
+client"` boundary covers it).
+
+  ### Promoted Data views — list-page binding layer
+
+  The list-page binding layer moved into the package as
+  `@exxatdesignux/ui/components/data-views` — ~1.15 k LOC across 9
+  files. `HubTable<TRow>` is now the canonical composition that ties
+  `DataTable` + `useTableState` + `TablePropertiesDrawerButton` + view
+  tabs into one generic component:
+  - **`./components/data-views/hub-table`** (~497 LOC) — `HubTable<TRow>`
+    - `columnsToFilterFields` + `columnsToFieldDefinitions` helpers +
+      `HubTableProps<TRow>` / `HubTableRendererArgs<TRow>` /
+      `HubDrawerToolbarProps`. Pass columns, rows, supported view types,
+      and a `renderers: { [renderKind]: ReactNode | () => ReactNode }` map.
+      The component owns `useTableState`, builds
+      `filterFields`/`fieldDefinitions` from your columns, mounts the
+      Properties button, and routes the active view tab through
+      `ListPageConnectedViewBody`.
+  - **`./components/data-views/list-page-connected-view-body`** —
+    `ListPageConnectedViewBody` + `ListPageViewNotConfigured` + the
+    `ListPageConnectedViewRenderers` type. Switches view bodies by
+    `DataListViewRenderKind` and shows a clear empty state when a
+    registered view is missing a renderer (never silently falls through
+    to dashboard).
+  - **`./components/data-views/data-row-list`** — virtualized list-view
+    body backed by `@tanstack/react-virtual` (new package dependency,
+    declared in `peerDependencies` shape; tree-shaken when only board
+    consumers import).
+  - **`./components/data-views/list-page-board-template`** — Reusable
+    kanban shell where columns are defined by predicates over each row.
+  - **`./components/data-views/list-page-board-card`** —
+    `ListPageBoardCard` shell with `stack` and `row` layouts, optional
+    `ListPageBoardCardAvatar`, `ListPageBoardCardTitleRow`,
+    `ListPageBoardCardBadgeRow`, `ListPageBoardCardBody`,
+    `ListPageBoardCardSecondary` slots. Matches placement-board card
+    visuals one-to-one.
+  - **`./components/data-views/board-card-primitives`** —
+    `BoardCardTwoLineBlock`, `BoardCardIconRow`,
+    `BoardNewCardPlaceholder` primitives shared between
+    `list-page-board-template` and consumer-built board cards. Reads
+    `BoardLineCount` from `data-list-display-options` to clamp text
+    lines.
+  - **`./components/data-views/list-page-tree-column-header`** /
+    **`list-page-split-details-placeholder`** /
+    **`list-page-split-hub-chrome`** — Pure-CSS shells used by the
+    finder / tree-panel / multi-column explorer views (centered card
+    - fixed viewport height; composes `ListPageViewFrame`).
+
+  Package `exports` map adds:
+  - `./components/data-views` →
+    `dist/components/data-views/index.js` (umbrella)
+  - `./components/data-views/*` →
+    `dist/components/data-views/*.{js,d.ts}` (subpath)
+
+  All 9 modules are exported from the main `@exxatdesignux/ui` barrel
+  and `apps/web/components/data-views/{hub-table, data-row-list,
+list-page-connected-view-body, board-card-primitives,
+list-page-board-card, list-page-board-template,
+list-page-tree-column-header, list-page-split-details-placeholder,
+list-page-split-hub-chrome}.tsx` are all 1-line re-export shims, so
+  every existing consumer (Placements, Team, Compliance, Question Bank,
+  plus every `HubTableRendererArgs<TRow>`-typed table renderer) keeps
+  working with no source change.
+
+  ### Tooling
+  - Add `@tanstack/react-virtual` to `packages/ui` `dependencies` (the
+    virtualized `DataRowList` body needs it). External in `tsup` so the
+    consumer bundle dedupes against any pre-existing `apps/web` copy.
+  - Add `packages/ui/src/globals.d.ts` declaring a minimal
+    `process.env.NODE_ENV` ambient so `HubTable`'s dev-time
+    missing-renderer `console.warn` typechecks without taking on a
+    `@types/node` dependency. Both bundlers and Next.js's RSC compiler
+    statically replace `process.env.NODE_ENV` at build time, so the
+    declaration only affects type-checking.
+  - Clean up `useImperativeHandle` deps in `HubTable` to extract the
+    stable `setSheetOpen` setter from `useTableState` before the hook
+    call, removing the misplaced
+    `eslint-disable-next-line react-hooks/exhaustive-deps` comment.
+
+  ### Promoted ExportDrawer + ListPageTemplate + small templates
+
+  The page-scale list-hub composition moved into the package as
+  `@exxatdesignux/ui/components/templates` so non-Next consumers (Vite,
+  Remix, plain CRA) can mount a complete hub without copying app source.
+  - **`./components/export-drawer`** — `ExportDrawer` (format + date range
+    - columns + active-filter toggle), single-file component composed from
+      in-package primitives only. App-specific `devLog` came along as
+      `./lib/dev-log` (`process.env.NODE_ENV` gated — bundlers strip the
+      call site in production).
+  - **`./components/templates/list-page`** — `ListPageTemplate` +
+    `ViewTab` / `ViewType` / `FilterOption` types + the canonical
+    `VIEW_TYPES` array derived from `DATA_LIST_VIEW_TILES`. The template
+    composes `PageHeader` slots (`header`, `metrics`,
+    `beforeSiteHeader`), the view-segmented control, and the now-promoted
+    `ExportDrawer` directly.
+  - **`./components/templates/nested-secondary-panel-shell`** — Single
+    responsive shell pairing a primary sidebar with a nested secondary
+    panel (used by Question bank).
+  - **`./components/templates/dedicated-search-landing-template`** —
+    Empty-`?q=` landing surface (`DotPattern` + lens + suggestions
+    slot) composed on `ListPageViewFrame`.
+  - **`./components/templates/dedicated-search-results-template`** —
+    `DedicatedSearchResultsHeaderChrome` + the
+    `DEDICATED_SEARCH_RESULTS_OUTER_CONTENT_CLASSNAME` shared classname
+    for the populated `?q=` branch.
+
+  App-side compositions that wrap product-specific shells
+  (`PrimaryPageTemplate`, `SecondaryPanelHubTemplate`,
+  `DiscoveryHubTemplate`, `NewFocusTemplate`) stay in
+  `apps/web/components/templates/` because they pull in `SiteHeader`,
+  `useAskLeo`, or per-route mock data — those will graduate when their
+  respective shells are decoupled.
+
+  Package `exports` map adds:
+  - `./components/templates` → `dist/components/templates/index.js`
+  - `./components/templates/*` →
+    `dist/components/templates/*.{js,d.ts}`
+
+  `apps/web` ships 1-line re-export shims at
+  `apps/web/components/export-drawer.tsx`,
+  `apps/web/lib/dev-log.ts`, and
+  `apps/web/components/templates/{list-page,
+nested-secondary-panel-shell, dedicated-search-landing-template,
+dedicated-search-results-template}.tsx` so every existing consumer
+  keeps working unchanged. All 15 Next.js routes still compile.
+
+  ### Promoted Data view bodies — finder / folder grid / outline tree / tree-panel shell + folder glyph
+
+  Six view-body modules moved into
+  `@exxatdesignux/ui/components/data-views/`, finishing the data-views
+  surface graduation that started with `HubTable`:
+  - **`./components/data-views/list-page-split-hub-tokens`** — Shared
+    layout classnames (`LIST_PAGE_SPLIT_MILLER_COLUMN_PANEL_CLASS`,
+    `LIST_PAGE_SPLIT_MILLER_DETAIL_PANEL_CLASS`,
+    `LIST_PAGE_SPLIT_RESIZABLE_HANDLE_CLASS`) so finder / tree-panel /
+    multi-column hubs stay visually aligned.
+  - **`./components/data-views/outline-tree-menu`** — VS Code–style
+    outline chrome (`OutlineTreeMenu`, `OutlineTreeMenuItem`,
+    `OutlineTreeLeafButton`, `OutlineTreeSub`, `OutlineTreeSubItem`,
+    `OutlineTreeCollapsibleContentRail`) with the guide-spacer + sub-row
+    shift classnames consumers compose for inset rails.
+  - **`./components/data-views/folder-grid-view`** — Generic icon-grid
+    layout with empty state, `aria-label`-named list, `renderTile`
+    render-prop, and optional centered max-width (icon-grid frame).
+  - **`./components/data-views/finder-panel-view`** — Miller-style
+    3-column split for list hubs (`FinderPanelView`) reusing the split
+    hub tokens + `ListPageTreeColumnHeader` +
+    `ListPageSplitDetailsPlaceholder`.
+  - **`./components/data-views/list-page-tree-panel-shell`** — Generic
+    two-pane layout (tree column + details column) with persisted
+    `react-resizable-panels` group id and shared
+    `ListPageSplitHubChrome` chrome.
+  - **`./components/data-views/os-folder-glyph`** — Windows-11-style
+    folder art (Icons8) + FA glyph overlay, with a generic
+    `FolderGlyphColorKey` palette type. Product `QuestionBankFolderColorKey`
+    stays in app mock data (same string union — structurally compatible
+    with `FolderGlyphColorKey`, no source changes required at call sites).
+
+  Package `exports` map continues to route
+  `./components/data-views/*` to the new modules. The package barrel
+  re-exports them all. App-side 1-line shims continue to provide the
+  `@/components/data-views/<file>` import paths.
+
+  `apps/web/components/data-views/question-bank-folder-tree-branch.tsx`
+  stays in the app — it pulls product mock data
+  (`QuestionBankFolder` / `QUESTION_BANK_FOLDER_ICON_COLORS`) and is the
+  right boundary between "design-system primitive" and "product
+  composition".
+
+  ### Tailwind L0 token namespace — verified
+
+  The `--exxat-color-*` / `--exxat-radius-*` / `--exxat-spacing-*` L0
+  canonical namespace (migration `0002-exxat-token-namespace.md`) is live
+  in the package's `src/globals.css` with Tailwind bridges (`bg-surface-1`,
+  `text-ink-1`, `rounded-2`, …) wired through `@theme inline`. The hooks
+  index (`packages/ui/tokens/hooks-index.json`) is regenerated to 197
+  tokens and passes `tokens:check`. `apps/web/app/globals.css` imports
+  the package CSS, so consumers inherit every L0 alias automatically. No
+  existing token was renamed; opportunistic per-file migration to L0
+  forms is non-breaking and continues as devs touch the code.
+
+  ### Documentation — three new blueprints
+
+  Added SLDS-style spec docs for the most-touched compositions, completing
+  the patterns the blueprints README itself flagged as "future":
+  - **`apps/web/docs/blueprints/list-page-template.md`** — view tabs +
+    metrics slot + properties drawer wiring, with WCAG mapping and
+    Do / Don't table.
+  - **`apps/web/docs/blueprints/board-card.md`** — `ListPageBoardCard`
+    shell + status badge + body primitives, including the list-row
+    counterpart (`layout="row"`).
+  - **`apps/web/docs/blueprints/key-metrics.md`** — flat vs card
+    variant, KPI count cap, trend polarity, and the service-injection
+    bridge for app-specific actions like Ask Leo.
+
+  The blueprints README links each new doc to its narrative + cursor
+  rules + React component. (Storybook / Ladle catalog is intentionally
+  not adopted in this pass: the Next.js demo routes plus blueprints
+  already cover the documentation surface, and adopting Storybook would
+  add infra without immediate signal for this DS.)
+
+  ### Hygiene
+  - Add `license: "UNLICENSED"` + `author` fields to `package.json`.
+  - Add `--exxat-color-wordmark-ink-light` / `-dark` tokens (used by the
+    Exxat product logo SVG + HTML wordmark prefix; replaces five `[#273441](https://github.com/ExxatDesign/Exxat-DS-Workspace/issues/273441)`
+    / `#A8B2BA` literals in `apps/web/components/exxat-product-logo.tsx`
+    - `product-wordmark.tsx`).
+  - ESLint config landed alongside source. Runs in PR CI with the
+    workspace `@exxatdesignux/eslint-plugin` rules (no hex literals, no
+    deprecated tokens, no SLDS / Lightning leakage, no Sonner toasts).
+  - `npm publish` runs with Sigstore `--provenance` from the
+    `.github/workflows/publish-ui.yml` workflow + creates an automated
+    GitHub Release.
+  - New PR-time CI workflow gates every PR on install → lint → typecheck
+    → tokens drift check → vitest → build, plus the Changesets release
+    flow on `main`.
+  - Scope the `brace-expansion` security override (GHSA-v6h2-p8h4-qcjw)
+    to per-major lines so `minimatch@3.1.5` keeps its compatible 1.x
+    branch and ESLint config loading no longer crashes with
+    `expand is not a function`.
+  - Prune unused mutator destructures in
+    `apps/web/components/table-properties/drawer-button.tsx` (left behind
+    by the earlier `react-hooks/refs` refactor). Setters are now read
+    exclusively via `stateRef.current.X` so handler identities stay
+    stable while the Sheet is portaled.
+
+- ### Demo / template hub renamed from "Question bank" → "Library"
+
+  The reference hub that ships in `packages/ui/template/**` and the
+  consumer-side mirrors in `packages/ui/consumer-extras/**` were renamed
+  from a domain-specific "Question bank" to a generic, placeholder-labeled
+  **Library** hub. This affects three surfaces consumers see:
+  1. **Template route + components** (used by `exxat-ui scaffold-app`):
+     - `app/(app)/question-bank/**` → `app/(app)/library/**`. The
+       `library/library` sub-route was simultaneously renamed to
+       `library/all` so the canonical "list everything" path reads
+       `/library/all`.
+     - `components/question-bank-*.tsx` (13 files) →
+       `components/library-*.tsx`. `components/new-question-composer.tsx`
+       → `components/new-library-item-form.tsx`.
+     - `components/data-views/question-bank-folder-tree-branch.tsx` →
+       `components/data-views/library-folder-tree-branch.tsx`.
+     - `lib/mock/question-bank{,-folders,-inspector,-kpi,-header-collaborators}.ts`
+       → `lib/mock/library-*.ts`.
+     - `lib/question-bank-{nav,supported-views,authoring,recent-searches,hub-search,dedicated-search}.ts`
+       → `lib/library-*.ts`.
+  2. **TypeScript surface (template only — package itself ships
+     generic shells):** `QuestionBankItem` → `LibraryItem`,
+     `QuestionBankFolder` → `LibraryFolder`, `QuestionBankNavState` →
+     `LibraryNavState`, `QuestionBankTable` → `LibraryTable`, etc. The
+     nested secondary-panel id flipped from `"question-bank"` to
+     `"library"`; consumers wiring `useAutoPanel` or the `secondaryPanel`
+     prop on a nav row must update the literal.
+  3. **Consumer docs + agent rules** (`packages/ui/consumer-extras/`):
+     `cursor-rules/exxat-question-bank-hub-header.mdc` →
+     `cursor-rules/exxat-library-hub-header.mdc`. The skill and
+     handbook entries that cited "Question bank" as the reference
+     implementation now cite the **Library** hub instead.
+
+  Mock content was also abstracted from clinical/medical strings (Bloom
+  taxonomy, NBME, anatomy, clinical decks) to neutral placeholders:
+  `Item 01..12`, `Owner A..E`, `Category 1..4`, `Type 1..3`,
+  `Low / Normal / High`, `Tier 1..6`, `Folder 1..6`, `LIB-2026-###` ids.
+  This makes the template usable as a starter for any domain — clinical,
+  education, retail, ops, etc. — without rewriting demo data first.
+
+  ### Migration for consumer apps
+
+  Run `pnpm exxat-ui sync-extras` (or whatever wrapper your repo uses)
+  to refresh `cursor-rules/`, `cursor-skills/`, `patterns/`, and
+  `handbook/` from the new mirror. The two breaking edges to check
+  manually inside your own app code:
+  - Any nav row that pinned `secondaryPanel: "question-bank"` →
+    `secondaryPanel: "library"`.
+  - Any direct import from
+    `@/components/question-bank-*` / `@/lib/question-bank-*` /
+    `@/lib/mock/question-bank-*` (likely only if you forked the demo
+    hub) → rename to the matching `library-*` path.
+
+  The `DataTable`, `useTableState`, `HubTable`, `ListPageTemplate`,
+  `TablePropertiesDrawer`, `KeyMetrics`, and `PageHeader` APIs are
+  unchanged — only the demo hub naming flipped.
+
+  ### Pagination chrome regression fixed
+
+  Independent of the rename, `HubTable.defaultTableRenderer` and the
+  `list-with-toolbar` default block now embed `<PaginationBar>` inside
+  the table card with `sticky bottom-0` instead of floating it below the
+  border. The new layout passes `hasFooter` through to `<DataTable>` so
+  the table's top corners stay `rounded-t-lg` and the bottom corners go
+  square, then anchors the pagination slab to the page scroll container
+  (`PrimaryPageTemplate.bodyClassName`). The shipped `PaginationBar`
+  component itself is unchanged.
+
+  ### Docs
+  - `apps/web/docs/large-dataset-strategy.md` — new doc covering today's
+    client-mode behavior, when to enable pagination, the server-mode
+    upgrade path via `paginationOverride`, and the row-virtualization
+    follow-up. Cross-linked from `apps/web/AGENTS.md` and
+    `apps/web/docs/data-views-pattern.md`.
+
 All notable changes to `@exxatdesignux/ui` are documented here. The file ships in the npm tarball at `node_modules/@exxatdesignux/ui/CHANGELOG.md`.
 
 ## For AI assistants (upgrade handoff)
@@ -17,12 +606,25 @@ After the user bumps `@exxatdesignux/ui`, do this in order:
 
 ## [Unreleased]
 
+## [0.3.1] – 2026-05-21
+
+### Fixed
+
+- **Customer demo `template/` was stale.** Re-ran `sync-template-from-web` and confirmed the npm `template/` payload now matches what the monorepo runs (`/columns`, `/tokens-themes`, `/question-bank`, `/dashboard`, settings) byte-for-byte. Previously the published `template/` still carried deleted entity-domain files (`placements-*`, `sites-*`, `team-*`, `compliance-*`, `rotation-*`) — they're gone now.
+
+### Changed
+
+- **`prepack` now auto-syncs template + consumer-extras before `tsup`.** New chain: `sync-template-from-web && vendor-consumer-extras && tsup`. Every `npm publish` (and every `npm pack`) guarantees the shipped `template/` mirrors `apps/web` and the AI bundle under `consumer-extras/` mirrors the latest skills + patterns. No more "I bumped the version but the template is stale" mode — drift is now impossible at publish time.
+- **Handbook + skills refreshed for the post-cleanup canonical refs.** `apps/web/AGENTS.md`, `apps/web/docs/HANDBOOK.md`, `apps/web/docs/data-views-pattern.md`, `apps/web/docs/glossary.md`, `apps/web/docs/reference-implementations.md`, `apps/web/docs/blueprints/{data-table,page-header}.md`, `apps/web/docs/kpi-flat-band-pattern.md`, and `apps/web/docs/component-selection-guide.md` (and the matching `.cursor/skills/exxat-ds-skill/SKILL.md`) all stop citing the deleted Placements / Sites / Team / Compliance components. New canonical references: `columns-showcase.tsx` (smallest single-view hub), `tokens-themes-client.tsx` (smallest secondary-panel + URL-driven scope hub with built-in pagination chrome), `question-bank-table.tsx` + `question-bank-hub-client.tsx` (full multi-view hub: table, board, dashboard).
+
 ## [0.3.0] – 2026-05-21
 
 ### Added
 
+- **`exxat-token-economy` skill** (`.cursor/skills/exxat-token-economy/SKILL.md` + Claude mirror) — the new "read this first" entry for any AI working with the design system. Targets **~50% fewer input tokens per design turn** by giving the assistant: a task → minimum-file-set table (so it doesn't reflexively open `AGENTS.md`), a five-question pre-flight that catches the top rule violations before generation, canonical primitive aliases (no `grep` needed), tiny copy-verbatim scaffolds for hub client / column def / KPI item, a deny-list of expensive files, an ask-vs-assume heuristic, and an output-discipline section that keeps the assistant's own response lean. `HANDBOOK.md` now opens with a callout pointing to it.
+- **Importable cell primitives** — every SaaS-grid cell pattern demoed in `columns-showcase.tsx` (progress, currency, numeric, rating, signal bars, boolean toggle, attachment count, external link, relative time, face rail with `+N`, type pill, tag list with `+N`, generic `RowActionsCell<TRow>`) is now a named export from `@/components/data-views` (`apps/web/components/data-views/table-cells.tsx`). The showcase becomes a thin orchestrator that imports these — proving they're production-ready, not demo-only. The token-economy skill's §3 ("primitive aliases") and §4 ("`ColumnDef` scaffolds") both name the cells so the AI imports them on the first try instead of re-deriving `Intl.NumberFormat`, star loops, or `<a target="_blank">` inline. `.cursor/rules/exxat-data-tables.mdc` adds a MUST-USE clause; `reference-implementations.md` gains a "Cell primitives (importable)" table; `glossary.md` adds a "Cell primitive" entry.
 - **`exxat-ui sync-extras` now installs the full AI bundle in one command.** Previously the CLI shipped only Cursor skills + pattern docs; consumers had to `degit` Cursor rules and handbook tier docs separately. The CLI now writes, in one pass:
-  1. **Skills to both clients** — `.cursor/skills/exxat-*/` **and** `.claude/skills/exxat-*/` (same `SKILL.md` shape, two readers, one source of truth — no more `ln -s` step).
+  1. **Skills to both clients** — `.cursor/skills/exxat-*/` **and** `.claude/skills/exxat-*/` (16 folders including the new **`exxat-token-economy`**; same `SKILL.md` shape, two readers, one source of truth — no more `ln -s` step).
   2. **Cursor rules** — `.cursor/rules/exxat-*.mdc` (29 binding `MUST` / `MUST NOT` files: data-tables, accessibility, kbd shortcuts, KPI trends/flat-band/max-four, board cards, list-page-view-shells, centralized-list-dataset, reuse-before-custom, no-toast, drawer-vs-dialog, page-vs-drawer, no-slds-leakage, token-discipline, mono-ids, fontawesome-icons, dashboard-view-charts, …).
   3. **Handbook tier** — `docs/exxat-ds/handbook/{HANDBOOK,glossary,voice-and-tone,reference-implementations}.md`. These are stage-rewritten copies of `apps/web/docs/*.md` — links to shipped patterns use `../`, links to unshipped neighbours (blueprints, token-taxonomy, root `AGENTS.md`, `lib/*`) are rewritten to absolute GitHub URLs at bundle time so every link in the consumer's repo resolves.
   4. **Patterns + checklist** — unchanged from prior releases (`docs/exxat-ds/*-pattern.md`, `consumer-upgrade-checklist.md`).
@@ -76,11 +678,11 @@ After the user bumps `@exxatdesignux/ui`, do this in order:
 ### Fixed
 
 - **Dark mode surface elevation ladder — popover / card split, secondary panel nestled** (`globals.css`):
-  1. **`--popover` lifted to L=0.275** (was 0.225). Sharing the card's subtle 0.225 value made floating dropdowns blend straight into the canvas (only +0.025 above L=0.20) — the dropdown chrome lost its boundary. Popover now sits +0.075 above canvas with a slightly elevated chroma (built-ins 0.022 / custom `max(0.018, c·0.16)`), giving dropdowns and menus the visible lift they need over content. `--card` stays at 0.225 — it's an *inline* surface, not a floating one, and the earlier "subtle wash" reading was correct for it.
-  2. **`--secondary-panel-bg` rewired** from `var(--brand-tint)` (which resolved to L=0.30) down to **L=0.22**. The old value made the secondary nav panel *brighter* than the surrounding sidebar (L=0.245), so the Library / question-bank rail popped out as a bright tile instead of nesting in. The new value wedges it between sidebar (0.245) and canvas (0.20). Per-theme overrides carry the brand hue + chroma (Exxat One 0.025, Prism 0.030, Assessment 0.025, custom `max(0.020, c·0.20)`).
+  1. **`--popover` lifted to L=0.275** (was 0.225). Sharing the card's subtle 0.225 value made floating dropdowns blend straight into the canvas (only +0.025 above L=0.20) — the dropdown chrome lost its boundary. Popover now sits +0.075 above canvas with a slightly elevated chroma (built-ins 0.022 / custom `max(0.018, c·0.16)`), giving dropdowns and menus the visible lift they need over content. `--card` stays at 0.225 — it's an _inline_ surface, not a floating one, and the earlier "subtle wash" reading was correct for it.
+  2. **`--secondary-panel-bg` rewired** from `var(--brand-tint)` (which resolved to L=0.30) down to **L=0.22**. The old value made the secondary nav panel _brighter_ than the surrounding sidebar (L=0.245), so the Library / question-bank rail popped out as a bright tile instead of nesting in. The new value wedges it between sidebar (0.245) and canvas (0.20). Per-theme overrides carry the brand hue + chroma (Exxat One 0.025, Prism 0.030, Assessment 0.025, custom `max(0.020, c·0.20)`).
   3. **Dark surface ladder is now** `--background` 0.20 → `--secondary-panel-bg` 0.22 → `--card` 0.225 → `--sidebar` / `--input-background` 0.245 → `--popover` 0.275 — clear, monotonic stepping with floating elements lifting further than inline ones.
-- **Dark mode card / popover / input-background — softened to a subtle brand wash, not a tinted panel** (`globals.css`): The previous pass at `L=0.255 C=0.030` made cards read as a *separate tinted surface* floating above canvas. Pulled lightness down to `L=0.225` (only 0.025 above `--background` at L=0.20) and chroma down to `C=0.017` (built-ins) / `max(0.015, calc(c*0.13))` (custom). Cards now read as the same surface family as canvas with a small elevation step and a whisper of brand hue — the saturated brand expression remains on `--brand-tint` and `--sidebar` where it belongs. Input background follows the same shift (L 0.245 / C 0.010). Foreground contrast unchanged (≥ 12:1).
-- **Hydration warnings from the Cursor IDE browser preview** (`app/(app)/layout.tsx`, `components/templates/nested-secondary-panel-shell.tsx`, `components/ask-leo-sidebar.tsx`): The in-IDE browser MCP injects a `data-cursor-ref` attribute on top-level layout chrome *before* React hydrates so it can target those nodes for click automation. React then warned about an attribute it didn't render. Added `suppressHydrationWarning` on just the three SSR-rendered shell roots that the MCP tags. The flag is scoped to *each element's own attributes only* — children still hydrate normally and any real mismatch inside the panel still surfaces. Has zero effect outside the Cursor IDE preview.
+- **Dark mode card / popover / input-background — softened to a subtle brand wash, not a tinted panel** (`globals.css`): The previous pass at `L=0.255 C=0.030` made cards read as a _separate tinted surface_ floating above canvas. Pulled lightness down to `L=0.225` (only 0.025 above `--background` at L=0.20) and chroma down to `C=0.017` (built-ins) / `max(0.015, calc(c*0.13))` (custom). Cards now read as the same surface family as canvas with a small elevation step and a whisper of brand hue — the saturated brand expression remains on `--brand-tint` and `--sidebar` where it belongs. Input background follows the same shift (L 0.245 / C 0.010). Foreground contrast unchanged (≥ 12:1).
+- **Hydration warnings from the Cursor IDE browser preview** (`app/(app)/layout.tsx`, `components/templates/nested-secondary-panel-shell.tsx`, `components/ask-leo-sidebar.tsx`): The in-IDE browser MCP injects a `data-cursor-ref` attribute on top-level layout chrome _before_ React hydrates so it can target those nodes for click automation. React then warned about an attribute it didn't render. Added `suppressHydrationWarning` on just the three SSR-rendered shell roots that the MCP tags. The flag is scoped to _each element's own attributes only_ — children still hydrate normally and any real mismatch inside the panel still surfaces. Has zero effect outside the Cursor IDE preview.
 - **Dark mode brand surfaces — every product chrome surface now reads as the brand per product** (`globals.css`):
   1. **`--brand-tint`** was never overridden in `.dark` or any `.theme-*.dark` block, so it cascaded down from the light-mode pale value (e.g. `oklch(0.97 0.02 343)` for Prism). Because the dark `--secondary-panel-bg` formula derived it as `color-mix(--card 32%, --brand-tint 68%)`, the question-bank Library secondary panel rendered as a pale rose / lavender pastel on dark canvas. Fixed by adding `--brand-tint` / `--brand-tint-light` / `--brand-tint-subtle` overrides at dark-mode lightness inside `.dark`, `.theme-one.dark`, `.theme-prism.dark`, `.theme-assessment.dark`, and `.theme-custom.dark`.
   2. **`--secondary-panel-bg` formula in `.dark`** rewritten from `color-mix(--card 32%, --brand-tint 68%)` to plain `var(--brand-tint)`. The old mix folded in `--card`'s neutral hue 270 — never overridden per theme in dark mode — so every product's secondary panel was pulled toward the same purple-neutral. Now the panel renders as a fully brand-tinted dark surface that varies clearly per product: Exxat One `#2c2a46` (navy-lavender), Prism `#402235` (wine), Assessment `#143525` (forest green).
@@ -113,7 +715,7 @@ After the user bumps `@exxatdesignux/ui`, do this in order:
 
 ### Changed
 
-- **Tokens**: `globals.css` refinements and starter **`template/`** parity with the web app (layout, Question bank hub chrome, navigation). *(Note: `theme.css` was a duplicate of `globals.css` and has been removed — see [`0003-globals-css-canonical.md`](../../apps/web/docs/migrations/0003-globals-css-canonical.md).)*
+- **Tokens**: `globals.css` refinements and starter **`template/`** parity with the web app (layout, Question bank hub chrome, navigation). _(Note: `theme.css` was a duplicate of `globals.css` and has been removed — see [`0003-globals-css-canonical.md`](../../apps/web/docs/migrations/0003-globals-css-canonical.md).)_
 - **Consumer extras**: Cursor skills + pattern docs refreshed for collaboration / Question bank hub header.
 
 ### Chore (monorepo)