hazo_ui 2.11.0 → 2.16.0

package/CHANGE_LOG.md

@@ -5,6 +5,187 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [2.16.0] - 2026-05-17
+
+### Changed
+- **Restyled `HazoUiMultiSortDialog` and `HazoUiMultiFilterDialog`** for a
+  modern, Linear/Notion-style appearance:
+  - Tighter dialog chrome: bordered header, padded body, bordered footer
+    bar with subtle muted background — replaces the flat, dated look.
+  - **Sort dialog**: each row now shows a numbered priority badge, a
+    segmented Asc/Desc pill (replaces the ambiguous switch), and a muted
+    delete affordance that reddens on hover.
+  - **Filter dialog**: rows have compact mathematical operator symbols
+    (`=`, `≠`, `>`, `<`, `≥`, `≤`) in a narrow select; inputs are 32px
+    tall for a denser layout; rows match the sort dialog visually.
+  - **Footer hierarchy fixed**: `Clear all` is a low-emphasis ghost
+    button on the left; `Cancel` (outline) and `Apply` (primary) are
+    grouped on the right — `Apply` is the rightmost / final action.
+  - Trigger buttons now show an active-count badge next to the icon.
+  - Empty state uses a dashed-border placeholder card; the "Add field"
+    affordance matches and disables itself when all fields are added.
+- **Dialog animation**: removed `slide-in-from-left-1/2` /
+  `slide-out-to-left-1/2` classes from `DialogContent`. Modals now
+  fade + zoom in place from center — no more horizontal "drift" that
+  caught the dialog mid-animation looking off-screen.
+
+### API
+- All component props (including the color-override props on both
+  dialogs) are unchanged; this is a visual refresh, not a contract
+  change. Existing consumers do not need to update call sites.
+
+## [2.15.1] - 2026-05-17
+
+### Fixed
+- **SSR/CSR hydration mismatch in HazoUiTable number/currency/percent
+  formatters.** `Intl.NumberFormat(undefined, …)` resolved to the
+  runtime's host locale, which differs between Node (server) and the
+  browser (client) — e.g. server `$4,812,500.00` vs. client
+  `US$4,812,500.00` when the browser default is `en-GB`. The library
+  now pins to `"en-US"` so both environments produce the same string.
+
+### Added
+- New `locale?: string` on `TableColumn` (BCP-47 tag, e.g. `"de-DE"`,
+  `"ja-JP"`) — opt-out for the new pinned default. Applies to `number`,
+  `currency`, and `percent` formatters. Date formatting was unaffected
+  and is unchanged (it uses `date-fns`, not `Intl`).
+
+## [2.15.0] - 2026-05-17
+
+### Added
+- **Shift-click multi-sort on `HazoUiTable` headers.** Plain header
+  click still cycles asc → desc → none (single column). Shift-click
+  a header to append it as a secondary sort, cycling that column
+  asc → desc → removed without collapsing prior columns. Discoverable
+  via a `title=` tooltip on the sort button. `useTableState.cycleHeaderSort`
+  gains an `append?: boolean` parameter; new `cycleAppendColumn` helper
+  alongside the existing `cycleSingleColumn`.
+- **Column-level `currency` override on `TableColumn`.** When `formatter`
+  is `"currency"`, the formatter reads `column.currency` (any ISO-4217
+  code, e.g. `"EUR"`, `"GBP"`) instead of the previously hard-coded
+  `"USD"`. Defaults to `"USD"` when omitted — fully backwards-compatible.
+- **Structured `onLoad` error UX.** `HazoUiTableProps` gains
+  `error?: React.ReactNode | ((err: unknown) => React.ReactNode)`.
+  `useTableState` exposes `serverError` (always `null` outside server
+  mode). On `onLoad` rejection, the table renders the consumer's
+  `error` prop in place of rows; if none is provided, a default
+  `EmptyState` shows the thrown message. `console.warn` continues to
+  log every rejection. Branch added to both the desktop `TableBody`
+  and the mobile card view.
+- Dev-app `/table` §9 demos the error state with a rejecting loader.
+  §2 copy mentions the new shift-click gesture.
+
+### Internal
+- Renamed `use_table_state` → `useTableState` (function only — the
+  filename stays `use_table_state.ts`). Aligns with the package's
+  other hooks (`useMediaQuery`, `useLoadingState`, `useErrorDisplay`)
+  and unblocks the `react-hooks/rules-of-hooks` lint rule.
+- New ESLint v9 flat config (`eslint.config.js`) so `npm run lint`
+  works again. Scoped to `src/**/*.{ts,tsx}` with
+  `@typescript-eslint` and `react-hooks` rules.
+
+### Notes
+- The 200 ms search debounce default is unchanged — the spec §10
+  follow-up about tuning needs empirical data from the sister app.
+  Consumers can already override per-table via `searchDebounceMs`.
+
+## [2.14.0] - 2026-05-17
+
+### Added
+- **`Table` shadcn primitive family.** Eight components (`Table`,
+  `TableHeader`, `TableBody`, `TableFooter`, `TableRow`, `TableHead`,
+  `TableCell`, `TableCaption`) re-exported under bare shadcn names.
+  Matches the canonical shadcn shape — drop-in for consumers that want
+  raw markup.
+- **`HazoUiTable` composite.** Column-config-driven data table that
+  composes the primitive with an in-memory filter/sort/paginate
+  pipeline:
+  - `TableColumn` is the single source of truth for display, sort,
+    filter, and search metadata.
+  - Sortable headers cycle asc → desc → none and replace any
+    multi-column sort with single-column on click. Multi-column sort
+    via the optional `HazoUiMultiSortDialog` integration; indicators
+    show order numbers.
+  - Optional toolbar with debounced free-text search (200 ms),
+    `HazoUiMultiFilterDialog`, and `HazoUiMultiSortDialog`. Available
+    fields are derived from columns — declared once.
+  - Loading state via `SkeletonBar`; empty / no-results via
+    `EmptyState`.
+  - Optional pagination footer with "Showing X–Y of Z" + Prev/Next.
+  - Optional row click with full mouse + keyboard support (Enter,
+    Space) when `onRowClick` is set.
+  - Mobile card-per-row fallback below a configurable breakpoint
+    (default 768 px). Opt out with `mobileCardFallback={false}`.
+  - Optional `onLoad({ page, sort, filter })` for server-side data;
+    latest-request-wins.
+- Dev-app `/table` route with eight demo sections covering every
+  acceptance scenario.
+
+### Dependencies
+- No new dependencies. Composes existing `Skeleton`, `EmptyState`,
+  `Card`, `Input`, `Button`, `HazoUiMultiSortDialog`,
+  `HazoUiMultiFilterDialog`, `useMediaQuery` from this package, plus
+  `date-fns` and `lucide-react` (already deps).
+
+## [2.13.1] - 2026-05-16
+
+### Changed
+- **`KanbanEditor` is now built on `HazoUiDialog`** (was raw shadcn `Dialog` primitives). Picks up the standardized header (with `title` + `description` so Radix's missing-`Description` warning is gone naturally), the standardized Save/Cancel footer with built-in `actionButtonLoading` spinner + `actionButtonDisabled`, and a priority-tinted full-width header bar via `headerBar` + `headerBarColor` — reads `hsl(var(--hazo-kanban-priority-{p0..p3}))` for visual continuity with the card left borders. The Save button gets a `Check` icon for clarity.
+- Auto-detect default editor now appends a **Status** select at the end (sourced from the kanban's `columns`), so users can move the card between columns from the editor out of the box without configuring `editorFields`.
+- Field labels rendered slightly smaller and muted (`text-xs font-medium text-muted-foreground`) for a more compact SaaS density.
+
+### Added
+- New `'status'` value on `KanbanEditorFieldType`. Renders a `Select` pre-populated from the kanban's `columns` prop (label = `column.title`, value = `column.key`). Bound to `columnKey` by convention; saving with a different status moves the card to a new column through the consumer's `onCardSave` handler — same code path as `onMove`.
+- Dev-app §7 editor declares `{ key: 'columnKey', type: 'status', label: 'Status' }` so the demo exercises the new field type.
+
+### Removed
+- The explicit `aria-describedby={undefined}` workaround on `DialogContent` from v2.13.0 — `HazoUiDialog` exposes a proper `description` prop that satisfies Radix without the escape hatch.
+
+## [2.13.0] - 2026-05-16
+
+### Changed (breaking, but pre-publish)
+- **Renamed `HazoUiBoard` family to `HazoUiKanban`.** v2.12.0 was committed to git but never `npm publish`'d, so this is a hard rename with no deprecation shim. Affected exports: `HazoUiBoard` → `HazoUiKanban`, `HazoUiBoardFilter` → `HazoUiKanbanFilter`, `applyBoardFilter` → `applyKanbanFilter`, plus the corresponding type aliases (`BoardItem` → `KanbanItem`, etc.). CSS class prefixes `cls_hazo_board_*` → `cls_hazo_kanban_*`; CSS variables `--hazo-board-*` → `--hazo-kanban-*`. Dev-app route `/board` → `/kanban`.
+
+### Added
+- **Out-of-the-box card editor.** Each card now carries a pencil icon (top-right, opacity-0 idle, opacity-100 on hover/focus). Clicking opens a `HazoUiDialog`-shell editor. Three rendering modes:
+  1. `renderCardEditor` render-prop — full control over the body.
+  2. `editorFields` declarative config — library renders one row per field declaration. Six built-in types: `text`, `textarea`, `select`, `number`, `checkbox`, `priority`. Required-field gating disables Save when text/textarea/number fields are empty.
+  3. Neither — library auto-detects string-typed fields on the item (skipping `id`, `columnKey`, `priority`).
+- **Async save lifecycle.** `onCardSave` returns `void | Promise<void>`. A returned Promise gates dialog close and shows a "Saving…" spinner; a rejected Promise keeps the dialog open with `ctx.error` populated. Consumer is responsible for updating `items` on success (symmetric with `onMove`).
+- Seven new props on `HazoUiKanbanProps<T>`: `editorFields`, `editorPriorities`, `editorTitle`, `renderCardEditor`, `hideEditorFooter`, `onCardSave`, `disableEdit`.
+- Four new public types: `KanbanEditorField`, `KanbanEditorFieldType`, `KanbanEditorCtx<T>`, `KanbanSaveEvent<T>`.
+- Dev-app demo at `/kanban` extended with three new sections (§6 default editor, §7 declarative editor, §8 renderCardEditor override).
+
+### Fixed
+- Suppressed Radix `DialogContent` missing-`Description` warning in `KanbanEditor` by setting `aria-describedby={undefined}` explicitly. Caught during the v2.13.0 smoke test — every editor open emitted a console warning under React strict mode.
+
+### Notes
+- No new CSS variables — the editor uses existing shadcn Dialog tokens and input/select/checkbox/textarea/button variables.
+- The pencil icon is hidden when `disableEdit={true}` OR `onCardSave` is not provided (no point letting the user edit if nothing happens on save).
+- The pencil's `pointerdown`/`mousedown`/`keydown` events stop propagation so dnd-kit's PointerSensor doesn't interpret the click as the start of a drag.
+- One shared `<KanbanEditor>` instance mounts at the orchestrator level, not one Dialog per card.
+- No `SETUP_CHECKLIST.md` changes (no new setup steps for consumers).
+
+## [2.12.0] - 2026-05-16
+
+### Added
+- **`HazoUiBoard`** — drag-drop kanban board primitive with mobile tab-strip / desktop column-grid layout switch via pure CSS. Wraps `@dnd-kit/*` internally; consumers see only the `HazoUi*` API. Optimistic-overlay state model: `items` is consumer-controlled; failed moves snap back via `handle.revert()` carried on the `BoardMoveEvent`.
+- **`HazoUiBoardFilter`** — controlled-or-uncontrolled filter bar with free-text search, multi-select category chips (`ToggleGroup type="multiple"`), and single-select priority chips. Decoupled from `HazoUiBoard` — consumer applies the filter to `items` before passing in.
+- **`applyBoardFilter`** — pure helper that filters `items` by search / categories / priority. Convenience export; consumers can swap in their own filter function.
+- Keyboard navigation per `@dnd-kit/accessibility` patterns (Tab focus → Space pick up → Arrow keys → Space drop → Esc cancel).
+- Custom screen-reader announcements that name the action and column; override-able via the `announcements` prop.
+- New CSS custom properties in both `src/styles/globals.css` (dev-app input) and `src/styles/hazo-ui.css` (shipped to `dist/styles.css`): `--hazo-board-priority-p0..p3` (HSL channels), `--hazo-board-card-bg`, `--hazo-board-card-border`, `--hazo-board-column-gap`. Apps can re-theme by overriding any variable in their cascade.
+- Dev-app demo at `dev-app/app/board/page.tsx` (route `/board`) with 5 sections: default kanban, controlled filter, uncontrolled filter, keyboard-only walkthrough, and optimistic-update + revert.
+
+### Fixed (during the v2.12.0 cycle)
+- **dev-app `next build` failure on pre-existing UI components.** `dev-app/package.json` pinned `@types/react` to `18.3.28` (workspace-root version) so type-check no longer fails in `src/components/ui/button-group.tsx` and `toggle-group.tsx` with "Type 'bigint' is not assignable to type 'ReactNode'". Pre-existing infrastructure issue surfaced during board demo wiring.
+
+### Notes
+- Sub-components `BoardColumn` and `BoardCard` are intentionally internal — the data-driven `HazoUiBoard` API (`columns`, `items`, `renderCard`) is the only entry point.
+- `HazoUiBoard` passes a `React.useId()`-derived value as `DndContext`'s `id` prop so multiple boards on one page produce stable, SSR-deterministic `aria-describedby` IDs (no hydration warnings).
+- No new dependencies (`@dnd-kit/*` was already in `dependencies` from prior versions).
+- No `SETUP_CHECKLIST.md` changes (no new setup steps for consumers).
+
 ## [2.11.0] - 2026-05-16
 
 ### Fixed

package/README.md

@@ -202,6 +202,8 @@ The following components support both global config and prop-level color overrid
 
 - **[HazoUiConfirmDialog](#hazouiconfirmdialog)** - A compact, opinionated confirmation dialog with accent top border, variant system (destructive, warning, info, success), async loading support, and configurable buttons. Perfect for delete confirmations, unsaved changes warnings, and simple acknowledgments.
 
+- **[HazoUiTable](#hazouitable--column-config-driven-data-table-v2140)** - A column-config-driven data table built on a shadcn `Table` primitive family. Sortable headers, debounced search, multi-column filter / sort dialogs, pagination, row click (mouse + keyboard), loading / empty / no-results states, and a card-per-row mobile fallback. Optional server-side `onLoad`.
+
 - **[Drawer](#drawer)** - A `vaul`-backed bottom sheet primitive for mobile UIs. Pair with `useMediaQuery` to swap between `Dialog` and `Drawer` based on viewport width.
 
 ### State Primitives (v2.10.0)
@@ -3317,6 +3319,248 @@ Returns `{ error: string | null; setError: (v: unknown) => void; clearError: ()
 
 ---
 
+## HazoUiKanban — Drag-Drop Kanban (v2.13.0+)
+
+Drag-drop board with mobile tab-strip / desktop column-grid layouts,
+optimistic updates with revert, theme-able priority borders, and
+keyboard-driven DnD. Wraps `@dnd-kit` internally.
+
+### Minimal usage
+
+```tsx
+import {
+  HazoUiKanban,
+  HazoUiKanbanFilter,
+  applyKanbanFilter,
+  type KanbanColumn,
+  type KanbanFilterValue,
+} from 'hazo_ui';
+
+const COLUMNS: KanbanColumn[] = [
+  { key: 'todo',        title: 'To Do' },
+  { key: 'in_progress', title: 'In Progress' },
+  { key: 'blocked',     title: 'Blocked' },
+  { key: 'done',        title: 'Done' },
+];
+
+function Actions({ initial }) {
+  const [items, setItems] = useState(initial);
+  const [filter, setFilter] = useState<KanbanFilterValue>({
+    search: '', categories: [], priority: null,
+  });
+  const visible = useMemo(() => applyKanbanFilter(items, filter), [items, filter]);
+
+  return (
+    <>
+      <HazoUiKanbanFilter
+        categories={['On-page SEO', 'Technical SEO', 'Content']}
+        priorities={['P0', 'P1', 'P2', 'P3']}
+        value={filter}
+        onChange={setFilter}
+      />
+      <HazoUiKanban
+        columns={COLUMNS}
+        items={visible}
+        renderCard={(action) => <ActionCard action={action} />}
+        itemLabel={(action) => `action ${action.id}`}
+        onMove={async (event) => {
+          try {
+            const res = await fetch(`/api/v1/actions/${event.itemId}`, {
+              method: 'PATCH',
+              body: JSON.stringify({ status: event.toColumn }),
+            });
+            if (!res.ok) throw new Error('PATCH failed');
+            setItems(prev => prev.map(it =>
+              it.id === event.itemId ? { ...it, columnKey: event.toColumn } : it,
+            ));
+          } catch {
+            event.revert();
+          }
+        }}
+      />
+    </>
+  );
+}
+```
+
+### Optimistic update + revert
+
+`onMove` fires after the library has already moved the card visually. The
+event carries `revert()` — call it when your API request fails and the
+overlay snaps back to whatever `items` says.
+
+### Theming (CSS custom properties)
+
+| Variable | Default | Purpose |
+|---|---|---|
+| `--hazo-kanban-priority-p0` | `0 84% 60%` (red) | Left border for `P0` cards |
+| `--hazo-kanban-priority-p1` | `45 93% 55%` (yellow) | Left border for `P1` cards |
+| `--hazo-kanban-priority-p2` | `217 91% 60%` (blue) | Left border for `P2` cards |
+| `--hazo-kanban-priority-p3` | `220 9% 64%` (grey) | Left border for `P3` cards |
+| `--hazo-kanban-card-bg` | `var(--card)` | Card background |
+| `--hazo-kanban-card-border` | `var(--border)` | Card border |
+| `--hazo-kanban-column-gap` | `0.75rem` | Gap between columns |
+
+Values are HSL channels (no `hsl()` wrapper) to match the shadcn theme
+convention. Custom priorities like `'critical'` work — define
+`--hazo-kanban-priority-critical` and pass `priority: 'critical'`.
+
+### Visual reference
+
+Run `npm run dev:test-app` and visit `/board` for five demo scenarios
+(default kanban, controlled / uncontrolled filter, keyboard-only flow,
+and optimistic + revert).
+
+### Out-of-the-box card editor
+
+Each card carries a pencil icon (top-right, opacity-0 idle, opacity-100
+on hover/focus). Clicking it opens a `HazoUiDialog` editor:
+
+```tsx
+<HazoUiKanban
+  columns={COLUMNS}
+  items={items}
+  renderCard={(action) => <ActionCard action={action} />}
+  // Declarative field config — library renders one row per declaration.
+  editorFields={[
+    { key: 'title',    type: 'textarea', required: true },
+    { key: 'category', type: 'select',   options: CATEGORIES },
+    { key: 'priority', type: 'priority' },
+  ]}
+  onCardSave={async (event) => {
+    const res = await fetch(`/api/v1/actions/${event.itemId}`, {
+      method: 'PATCH',
+      body: JSON.stringify(event.next),
+    });
+    if (!res.ok) throw new Error('PATCH failed');
+    setItems(prev => prev.map(it =>
+      it.id === event.itemId ? event.next : it,
+    ));
+  }}
+/>
+```
+
+Field types: `text`, `textarea`, `select`, `number`, `checkbox`,
+`priority` (a select pre-populated with `editorPriorities` —
+defaults to `["P0","P1","P2","P3"]`).
+
+If you don't pass `editorFields`, the library auto-detects all
+string-valued fields on the item (except `id`, `columnKey`, `priority`)
+and renders each as a text input with a humanized label.
+
+#### Custom form via renderCardEditor
+
+When the declarative config isn't enough, replace the dialog body
+with your own form:
+
+```tsx
+<HazoUiKanban
+  // ...
+  renderCardEditor={(item, ctx) => (
+    <MyComplexForm
+      value={ctx.draft}
+      onChange={(next) => ctx.setDraft(next)}
+      saving={ctx.saving}
+      error={ctx.error}
+    />
+  )}
+  onCardSave={async (event) => { /* ... */ }}
+/>
+```
+
+`ctx` provides `draft`, `setDraft`, `save()`, `close()`, `saving`, `error`,
+and `isDirty`. The library still renders the dialog shell, title, and
+the default Save/Cancel footer. To render your own buttons too, pass
+`hideEditorFooter={true}` and call `ctx.save()`/`ctx.close()` from
+within your form.
+
+#### Save lifecycle
+
+`onCardSave` returns `void | Promise<void>`. A returned Promise gates
+the dialog close and shows a `Saving…` spinner; a rejected Promise
+keeps the dialog open with `ctx.error` populated. Consumer is
+responsible for updating `items` on success — symmetric with `onMove`.
+
+If `onCardSave` is not provided, the pencil is hidden entirely
+(read-only kanban). To explicitly hide editing without removing
+`onCardSave`, pass `disableEdit={true}`.
+
+---
+
+## HazoUiTable — Column-config-driven Data Table (v2.14.0+, v2.15 additions)
+
+A higher-level data table that composes the shadcn `Table` primitive
+family with the existing `HazoUiMultiSortDialog` /
+`HazoUiMultiFilterDialog` and an in-memory filter / sort / paginate
+pipeline.
+
+```tsx
+import { HazoUiTable, type TableColumn } from 'hazo_ui';
+
+interface Run {
+  id: string;
+  date: Date;
+  status: 'ok' | 'fail';
+  count: number;
+}
+
+const columns: TableColumn<Run>[] = [
+  { key: 'date',   label: 'Date',   sortable: true, formatter: 'date', filterType: 'date' },
+  {
+    key: 'status',
+    label: 'Status',
+    sortable: true,
+    filterType: 'combobox',
+    filterConfig: {
+      comboboxOptions: [
+        { label: 'OK',   value: 'ok'   },
+        { label: 'Fail', value: 'fail' },
+      ],
+    },
+  },
+  { key: 'count', label: 'Count', sortable: true, formatter: 'number', align: 'right' },
+  // v2.15+ — column-level currency override (defaults to USD)
+  { key: 'revenue', label: 'Revenue', sortable: true, formatter: 'currency', currency: 'EUR', align: 'right' },
+];
+
+<HazoUiTable<Run>
+  columns={columns}
+  rows={runs}
+  getRowKey={(r) => r.id}
+  enableSearch
+  enableSortDialog
+  enableFilterDialog
+  pagination={{ pageSize: 25 }}
+  onRowClick={(r) => router.push(`/runs/${r.id}`)}
+/>
+```
+
+Features:
+
+- Header click cycles asc → desc → none. **Shift-click** a second
+  header to append it as a secondary sort (v2.15). Multi-column sort
+  also available via the optional sort dialog.
+- Free-text search across string-typed columns (debounced 200 ms).
+- Per-column filters via the filter dialog — declarable per column.
+- Loading state via `SkeletonBar`, empty / no-results via `EmptyState`.
+- Pagination footer with Prev / Next.
+- Row click with mouse and keyboard (Enter / Space) when `onRowClick`
+  is set.
+- Mobile card-per-row fallback below `mobileBreakpoint` (default
+  768 px). Opt out with `mobileCardFallback={false}`.
+- Optional `onLoad({ page, sort, filter })` for server-driven
+  pagination — latest-request-wins.
+- Structured error UX (v2.15): pass `error={node | (err) => node}`
+  to render a custom failure state when `onLoad` rejects; otherwise
+  the table falls back to an `EmptyState` showing the thrown message.
+- Per-column `currency` (v2.15) for ISO-4217 codes other than USD.
+
+The package also re-exports the bare shadcn primitives — `Table`,
+`TableHeader`, `TableBody`, `TableFooter`, `TableHead`, `TableRow`,
+`TableCell`, `TableCaption` — for consumers that prefer raw markup.
+
+---
+
 ## Troubleshooting
 
 ### Styles not applying (Tailwind v4)