hazo_ui 2.11.0 → 2.17.0

package/README.md

@@ -202,8 +202,12 @@ 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.
 
+- **[Chart Primitives](#chart-primitives-v2170)** (v2.17.0) - Pure-SVG chart components for KPI cards and trend dashboards: `Sparkline`, `InverseSparkline`, `LineChart`, `MultiLineChart`, `StackedBars`, and `DateRangeSelector`. Zero third-party chart deps. Gap-aware paths, hover tooltips, and per-series endpoint markers built in.
+
 ### State Primitives (v2.10.0)
 
 Lightweight, opinionated components for the four ubiquitous async states: **loading**, **empty**, **error**, and **success**.
@@ -3317,6 +3321,493 @@ 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.
+
+---
+
+## Chart Primitives (v2.17.0)
+
+A set of dependency-free, pure-SVG chart components for KPI cards,
+trend visualisations, and time-series dashboards. No `recharts`,
+no `chart.js`, no canvas — every chart is a flat `<svg>` whose math
+is computed in React. Hover tooltips and gap-aware paths are built in.
+
+```tsx
+import {
+  Sparkline,
+  InverseSparkline,
+  LineChart,
+  MultiLineChart,
+  StackedBars,
+  DateRangeSelector,
+  format_num,
+  pick_x_label_indices,
+  type ChartDataSeries,
+  type MultiSeries,
+  type StackedBar,
+  type DateRangeOption,
+} from 'hazo_ui';
+```
+
+### Sparkline
+
+Axisless single-series trend line for KPI cards. Stretches edge-to-edge
+across the parent (`width: 100%`), 12% area fill, 2px endpoint dot at the
+latest non-null value. By design no hover — the numeric value belongs
+above the sparkline in the KPI card itself.
+
+```tsx
+<Sparkline data={[2, 3, 5, 4, 7, 9, 12]} color="#10b981" height={40} />
+```
+
+Props:
+
+| Prop        | Type                | Default | Description                                |
+|-------------|---------------------|---------|--------------------------------------------|
+| `data`      | `(number \| null)[]`| —       | Series. `null` entries are skipped.        |
+| `color`     | `string`            | —       | Stroke, dot, and area-fill color.          |
+| `height`    | `number`            | `40`    | Pixel height. Width is always 100%.        |
+| `className` | `string`            | —       | Container className passthrough.           |
+
+### InverseSparkline
+
+Same shape as `Sparkline`, but the Y-axis is **inverted** — lower values
+plot higher on the screen. Built for GSC average-position trends (rank 1
+= best). Fixed 62×18 default to fit inline in scrollable query lists.
+No area fill, no dot — the line direction is the only signal.
+
+```tsx
+<InverseSparkline data={[12, 10, 8, 5, 3]} color="#3b82f6" />
+```
+
+Props:
+
+| Prop        | Type                | Default | Description                                |
+|-------------|---------------------|---------|--------------------------------------------|
+| `data`      | `(number \| null)[]`| —       | Series. `null` entries are skipped.        |
+| `color`     | `string`            | —       | Stroke color.                              |
+| `width`     | `number`            | `62`    | Pixel width.                               |
+| `height`    | `number`            | `18`    | Pixel height.                              |
+| `className` | `string`            | —       | Container className passthrough.           |
+
+### LineChart
+
+Full-anatomy single-series chart: three dashed gridlines at 0/50/100% of
+plot height, Y-axis ticks (max/mid/min) at the left, three X-axis labels
+(start/mid/end) below, marker dot at the last data point with a dashed
+guide-line back to the Y-axis and a value label rendered above-left.
+
+Hover the plot area to surface a vertical cursor line and a value bubble
+at the nearest data index. Pass `showTooltip={false}` for static use
+(print export, embeds).
+
+```tsx
+<LineChart
+  data={[12, 14, 18, 20, 25, 30, 36, 42]}
+  dates={['May 1', 'May 2', 'May 3', 'May 4', 'May 5', 'May 6', 'May 7', 'May 8']}
+  color="#10b981"
+  unit="%"
+/>
+```
+
+Props:
+
+| Prop          | Type                | Default | Description                                              |
+|---------------|---------------------|---------|----------------------------------------------------------|
+| `data`        | `(number \| null)[]`| —       | Series. `null` entries are gaps in the line.             |
+| `dates`       | `string[]`          | —       | X-axis label per data point (length should match `data`).|
+| `color`       | `string`            | —       | Stroke / area / marker color.                            |
+| `width`       | `number`            | `360`   | viewBox width.                                           |
+| `height`      | `number`            | `130`   | viewBox height.                                          |
+| `unit`        | `string`            | —       | Suffix on the current-value label (e.g. `"%"`).          |
+| `showTooltip` | `boolean`           | `true`  | Disable hover tooltip when `false`.                      |
+| `className`   | `string`            | —       | Container className passthrough.                         |
+
+### MultiLineChart
+
+Multiple lines sharing a Y-axis. **No area fill** — multi-series uses
+lines only so colors don't muddy each other. Per-series endpoint marker +
+value label keeps the latest reading visible without hovering. Hover
+surfaces one cursor with a stacked bubble showing every series value at
+that index. Optional legend below the SVG.
+
+```tsx
+<MultiLineChart
+  series={[
+    { label: 'Indexed', color: '#10b981', data: [1, 2, 5, 12, 26, 48, 62] },
+    { label: 'Crawled', color: '#f59e0b', data: [3, 4, 8, 15, 22, 28, 30] },
+  ]}
+  dates={['May 1', 'May 2', 'May 3', 'May 4', 'May 5', 'May 6', 'May 7']}
+/>
+```
+
+Props:
+
+| Prop          | Type            | Default | Description                                     |
+|---------------|-----------------|---------|-------------------------------------------------|
+| `series`      | `MultiSeries[]` | —       | One entry per line (`label`, `color`, `data`).  |
+| `dates`       | `string[]`      | —       | X-axis labels.                                  |
+| `width`       | `number`        | `360`   | viewBox width.                                  |
+| `height`      | `number`        | `140`   | viewBox height.                                 |
+| `showTooltip` | `boolean`       | `true`  | Disable hover tooltip when `false`.             |
+| `showLegend`  | `boolean`       | `true`  | Render legend below the chart.                  |
+| `className`   | `string`        | —       | Container className passthrough.                |
+
+### StackedBars
+
+Generic stacked-bar over time. One bar per X position; each bar split
+top-to-bottom into colored bands defined by `segments`. Good for
+distribution-over-time visuals (GSC position buckets, traffic-source mix,
+category breakdowns).
+
+```tsx
+<StackedBars
+  bars={[
+    { label: 'May 1', segments: [
+      { value: 4, color: '#10b981' },
+      { value: 6, color: '#3b82f6' },
+      { value: 2, color: '#f59e0b' },
+    ]},
+    // ...one entry per bar
+  ]}
+/>
+```
+
+Props:
+
+| Prop         | Type           | Default | Description                                         |
+|--------------|----------------|---------|-----------------------------------------------------|
+| `bars`       | `StackedBar[]` | —       | One entry per column; `segments` are top-to-bottom. |
+| `width`      | `number`       | `360`   | viewBox width.                                      |
+| `height`     | `number`       | `140`   | viewBox height.                                     |
+| `showYAxis`  | `boolean`      | `true`  | Render Y-axis ticks (max / mid / 0).                |
+| `className`  | `string`       | —       | Container className passthrough.                    |
+
+### DateRangeSelector
+
+Framework-agnostic segmented control (`value` + `onChange`) for picking
+a chart's time window. The active pill is tinted with the
+`--primary` CSS variable; inactive pills use muted foreground colors.
+No router coupling — wire the value into URL state, local state, or any
+store yourself.
+
+```tsx
+const [range, setRange] = React.useState('30d');
+
+<DateRangeSelector
+  value={range}
+  onChange={setRange}
+  options={[
+    { value: '7d',  label: '7d'  },
+    { value: '30d', label: '30d' },
+    { value: '90d', label: '90d' },
+  ]}
+/>
+```
+
+Props:
+
+| Prop        | Type                          | Default        | Description                          |
+|-------------|-------------------------------|----------------|--------------------------------------|
+| `value`     | `string`                      | —              | Currently selected option value.     |
+| `onChange`  | `(value: string) => void`     | —              | Fires when the user picks an option. |
+| `options`   | `DateRangeOption[]`           | —              | `{ value, label }` pairs.            |
+| `ariaLabel` | `string`                      | `"Date range"` | Aria label for the button group.     |
+| `className` | `string`                      | —              | Container className passthrough.     |
+
+### Helpers
+
+Two pure helpers are exported for callers that want to format values or
+pick label positions consistently with the charts:
+
+```tsx
+format_num(1234);     // "1.2k"
+format_num(1_500_000); // "1.5M"
+format_num(5.73);     // "5.7"
+format_num(null);     // ""
+
+pick_x_label_indices(14); // [0, 7, 13]  — start / mid / end
+```
+
+### Types
+
+```ts
+type ChartDataPoint = number | null;
+type ChartDataSeries = ChartDataPoint[];
+
+interface MultiSeries {
+  label: string;
+  color: string;
+  data: ChartDataSeries;
+}
+
+interface StackedBar {
+  label: string;
+  segments: { value: number; color: string }[];
+}
+
+interface DateRangeOption {
+  value: string;
+  label: string;
+}
+```
+
+### Notes
+
+- **Null handling.** A `null` entry in any series is a *gap* — the line
+  breaks rather than connecting around the missing point. The Y range is
+  computed from non-null values only, so one missing day won't deform the
+  chart.
+- **Axis label color is pinned.** Gridlines (`#2a3441`) and axis labels
+  (`#8b949e`) are hardcoded for dark-themed dashboards. Theming via CSS
+  variables is a follow-up if a second consumer needs it.
+- **All charts are Client Components.** The library bundle is
+  `"use client"`-stamped at build time, so charts work in any Next.js app
+  but don't get RSC-rendered.
+- **Hover assumes `width: 100%`.** `LineChart` / `MultiLineChart` map
+  `clientX` to a viewBox X via `getBoundingClientRect()`. CSS transforms
+  on the wrapper (`scale(...)`) will desync the mapping.
+
+---
+
 ## Troubleshooting
 
 ### Styles not applying (Tailwind v4)