hazo_ui 2.9.0 → 2.16.0

package/README.md

@@ -202,6 +202,24 @@ 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)
+
+Lightweight, opinionated components for the four ubiquitous async states: **loading**, **empty**, **error**, and **success**.
+
+- **[Skeleton](#skeleton)** family (`Skeleton`, `SkeletonCircle`, `SkeletonBar`, `SkeletonRect`, `SkeletonGroup`) - Shimmer placeholders. Respects `prefers-reduced-motion`.
+- **[EmptyState](#emptystate)** - Icon + title + description + CTA for empty lists, search misses, no-data screens.
+- **[ErrorBanner](#errorbanner)** - Inline `warning` or `error` strip with optional title, action button, and dismiss.
+- **[ErrorPage](#errorpage)** - Full-page error fallback with title, description, error code tag, correlation id, and CTAs.
+- **[LoadingTimeout](#loadingtimeout)** - Wraps a loading region and escalates messaging at 5s / 15s / 30s thresholds before showing a retry banner.
+- **[ProgressiveImage](#progressiveimage)** - Three-stage image render: grey placeholder → blurred LQIP → sharp final image.
+- **[HazoUiToaster + toast helpers](#toasts-hazouitoaster--successtoast--errortoast)** - `sonner`-backed toaster with `successToast()` and `errorToast()` imperative helpers.
+- **[useLoadingState](#useloadingstate)** hook - `{ isLoading, setLoading, withLoading }` with an async wrapper.
+- **[useErrorDisplay](#useerrordisplay)** hook - Passive `{ error, setError, clearError }` that coerces `Error` instances to strings.
+
 ### shadcn/ui Primitive Re-exports
 
 All shadcn/ui base components are re-exported from hazo_ui, so sibling hazo_* packages (and consumers) can import UI primitives from a single source without installing shadcn/ui separately:
@@ -3022,6 +3040,527 @@ function Example() {
 
 ---
 
+## State Primitives
+
+Components and hooks for the four ubiquitous async states. All are exported flat (unprefixed) from the package root — `import { Skeleton, EmptyState, ErrorBanner, ErrorPage, LoadingTimeout, ProgressiveImage, HazoUiToaster, successToast, errorToast, useLoadingState, useErrorDisplay } from "hazo_ui"`.
+
+### Skeleton
+
+Shimmer placeholders for loading content. The shimmer animation respects `prefers-reduced-motion` (renders as a static grey block instead).
+
+```tsx
+import { Skeleton, SkeletonCircle, SkeletonBar, SkeletonRect, SkeletonGroup } from "hazo_ui";
+
+<SkeletonGroup label="Loading user profile">
+  <div className="flex items-center gap-3">
+    <SkeletonCircle size={40} />
+    <div className="flex-1 space-y-2">
+      <SkeletonBar width="60%" height={14} />
+      <SkeletonBar width="40%" height={10} />
+    </div>
+  </div>
+  <SkeletonRect height={120} radius={8} />
+</SkeletonGroup>
+```
+
+| Variant | Props |
+|---|---|
+| `Skeleton` | All standard `<div>` props. Base shimmer block. |
+| `SkeletonCircle` | `size?: number` (default 40), `className?: string` |
+| `SkeletonBar` | `width?: number \| string` (default "100%"), `height?: number` (default 12), `className?: string` |
+| `SkeletonRect` | `width?`, `height?`, `radius?: number \| string` (default 6), `className?: string` |
+| `SkeletonGroup` | `label?: string` (default "Loading content"), `children: ReactNode` — wraps a region with `role="status"` + `aria-busy` + visually-hidden label. |
+
+### EmptyState
+
+Standardized empty-list / no-data / no-results display.
+
+```tsx
+import { EmptyState, Button } from "hazo_ui";
+import { InboxIcon } from "lucide-react";
+
+<EmptyState
+  icon={<InboxIcon />}
+  title="No messages yet"
+  description="When you receive a message, it'll show up here."
+  action={<Button onClick={onCompose}>Send your first message</Button>}
+  size="md"
+/>
+```
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `title` | `string` | **required** | Main heading |
+| `icon` | `ReactNode` | — | Icon element (recommended 48×48) |
+| `description` | `ReactNode` | — | Secondary description |
+| `action` | `ReactNode` | — | CTA region (typically a `<Button>`) |
+| `size` | `"sm" \| "md" \| "lg"` | `"md"` | Visual size for inline cards (`sm`) vs full pages (`lg`) |
+| `className` | `string` | — | Additional classes |
+
+### ErrorBanner
+
+Inline error or warning strip. `role="alert"`, with `aria-live="assertive"` for errors / `"polite"` for warnings.
+
+```tsx
+import { ErrorBanner, Button } from "hazo_ui";
+
+<ErrorBanner
+  severity="error"
+  title="Couldn't save your changes"
+  message="We hit a network error. Your draft is safe locally."
+  action={<Button size="sm" onClick={onRetry}>Retry</Button>}
+  onDismiss={() => setBannerVisible(false)}
+/>
+
+<ErrorBanner severity="warning" message="Your session expires in 2 minutes." />
+```
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `message` | `ReactNode` | **required** | Body text |
+| `severity` | `"warning" \| "error"` | `"error"` | Drives colour & icon |
+| `title` | `string` | — | Bold heading above the message |
+| `icon` | `ReactNode` | auto | Override the auto-selected `AlertTriangle` / `OctagonAlert` |
+| `action` | `ReactNode` | — | CTA region (typically a `<Button>`) |
+| `onDismiss` | `() => void` | — | When provided, renders a dismiss X button |
+| `className` | `string` | — | Additional classes |
+
+### ErrorPage
+
+Full-page error fallback, ideal for route-level error boundaries.
+
+```tsx
+import { ErrorPage, Button } from "hazo_ui";
+
+<ErrorPage
+  title="Something went wrong"
+  description="We couldn't load this page. The issue has been reported."
+  errorCode="500"
+  correlationId="req_a8f3c12e4d"
+  actions={
+    <>
+      <Button onClick={onRetry}>Try again</Button>
+      <Button variant="outline" onClick={onGoHome}>Go home</Button>
+    </>
+  }
+/>
+```
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `title` | `string` | `"Something went wrong"` | Main heading |
+| `description` | `ReactNode` | — | Explanation paragraph(s) |
+| `errorCode` | `string` | — | Short symbolic code rendered as a tag (`"500"`, `"NOT_FOUND"`) |
+| `correlationId` | `string` | — | Correlation id (typically from `hazo_logs`) — rendered in a copyable mono block |
+| `actions` | `ReactNode` | — | CTA region |
+| `illustration` | `ReactNode` | `<OctagonAlert />` | Override the default icon |
+| `className` | `string` | — | Additional classes |
+
+### LoadingTimeout
+
+Wraps a loading region and escalates messaging if the load takes too long. Four phases:
+
+| Phase | When | What renders |
+|---|---|---|
+| `silent` | 0 – 5s | The provided `skeleton` (no message) |
+| `gentle` | 5s – 15s | Skeleton + "Loading {label}…" |
+| `firm` | 15s – 30s | Skeleton + "Still working on it — almost there." |
+| `expired` | 30s+ | `<ErrorBanner severity="error">` with a "Try again" button |
+
+```tsx
+import { LoadingTimeout, SkeletonGroup, SkeletonBar } from "hazo_ui";
+
+<LoadingTimeout
+  active={isLoading}
+  label="dashboard"
+  onRetry={refetch}
+  skeleton={
+    <SkeletonGroup>
+      <SkeletonBar width="80%" />
+      <SkeletonBar width="60%" />
+    </SkeletonGroup>
+  }
+>
+  <Dashboard data={data} />
+</LoadingTimeout>
+```
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `active` | `boolean` | **required** | When `true`, runs the timeout escalation; when `false`, renders `children` |
+| `children` | `ReactNode` | — | Content shown when `active` is `false` |
+| `skeleton` | `ReactNode` | — | Placeholder rendered during the `silent`/`gentle`/`firm` phases |
+| `onRetry` | `() => void` | — | Called when the user clicks Retry in the `expired` phase |
+| `thresholds` | `{ gentle?, firm?, expired? }` | `{5000, 15000, 30000}` | Override timeout thresholds (ms) |
+| `label` | `string` | `"content"` | Used in gentle/firm/expired messages |
+| `className` | `string` | — | Additional classes |
+
+### ProgressiveImage
+
+Three-stage image render: grey placeholder → blurred low-quality image (`lqip`) → sharp final image. Sets a stable container box so layout doesn't shift.
+
+```tsx
+import { ProgressiveImage } from "hazo_ui";
+
+<ProgressiveImage
+  src="/photos/large.jpg"
+  lqip="data:image/jpeg;base64,/9j/4AAQ…"
+  alt="Sunset over the lake"
+  width={400}
+  height={300}
+  fit="cover"
+  loading="lazy"
+/>
+```
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `src` | `string` | **required** | Final image src |
+| `alt` | `string` | **required** | Alt text (empty string allowed for decorative) |
+| `width` | `number \| string` | **required** | Container width (px or any CSS length) |
+| `height` | `number \| string` | **required** | Container height |
+| `lqip` | `string` | — | Low-quality placeholder (data URL or tiny image URL) |
+| `loading` | `"eager" \| "lazy"` | `"lazy"` | Native loading attribute |
+| `fit` | `"cover" \| "contain" \| "fill" \| "none" \| "scale-down"` | `"cover"` | Object-fit for the final image |
+| `onLoad` | `() => void` | — | Called when the final image loads |
+| `onError` | `() => void` | — | Called if the final image errors |
+| `className` | `string` | — | Additional classes |
+
+### Toasts (HazoUiToaster + successToast / errorToast)
+
+A `sonner`-backed toaster plus two opinionated imperative helpers.
+
+**Mount the toaster once** near the root of your app:
+
+```tsx
+import { HazoUiToaster } from "hazo_ui";
+
+export default function RootLayout({ children }) {
+  return (
+    <>
+      {children}
+      <HazoUiToaster position="bottom-right" />
+    </>
+  );
+}
+```
+
+**Fire toasts imperatively from anywhere:**
+
+```tsx
+import { successToast, errorToast } from "hazo_ui";
+
+await save();
+successToast({ title: "Saved", description: "Your changes have been published." });
+
+try { await sync(); } catch (e) {
+  errorToast({
+    title: "Sync failed",
+    description: "Check your connection and try again.",
+    action: { label: "Retry", onClick: () => sync() },
+  });
+}
+```
+
+`HazoUiToaster` props:
+
+| Prop | Type | Default |
+|---|---|---|
+| `position` | `"top-left" \| "top-right" \| "bottom-left" \| "bottom-right" \| "top-center" \| "bottom-center"` | `"bottom-right"` |
+| `closeButton` | `boolean` | `true` |
+| `visibleToasts` | `number` | `5` |
+
+`ToastOptions` (for `successToast` / `errorToast`):
+
+| Prop | Type | Default |
+|---|---|---|
+| `title` | `string` | **required** |
+| `description` | `string` | — |
+| `duration` | `number` (ms) | `3000` success / `5000` error |
+| `action` | `{ label: string; onClick: () => void }` | — |
+
+Also exports `rawToast` (re-export of sonner's `toast`) for advanced use cases.
+
+### useLoadingState
+
+Hook that returns a controlled loading flag plus an async wrapper.
+
+```tsx
+import { useLoadingState } from "hazo_ui";
+
+const { isLoading, setLoading, withLoading } = useLoadingState(false);
+
+async function onSubmit() {
+  await withLoading(async () => {
+    await api.save(data);
+  });
+}
+
+return <Button disabled={isLoading} onClick={onSubmit}>{isLoading ? "Saving…" : "Save"}</Button>;
+```
+
+Returns `{ isLoading: boolean; setLoading: (v: boolean) => void; withLoading: <T>(fn: () => Promise<T>) => Promise<T> }`. `withLoading` sets the flag to `true` before the call and clears it in a `finally` block — even on errors.
+
+### useErrorDisplay
+
+Passive error state. Coerces `Error` instances to their `.message`, strings pass through, anything else is `String()`-cast.
+
+```tsx
+import { useErrorDisplay, ErrorBanner } from "hazo_ui";
+
+const { error, setError, clearError } = useErrorDisplay();
+
+try { await save(); } catch (e) { setError(e); }
+
+return error ? <ErrorBanner message={error} onDismiss={clearError} /> : null;
+```
+
+Returns `{ error: string | null; setError: (v: unknown) => void; clearError: () => void }`. Pass `null` (or any nullish value) to `setError` to clear.
+
+---
+
+## 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)