hazo_ui 2.16.0 → 2.17.0

package/CHANGE_LOG.md

@@ -5,6 +5,53 @@ 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.17.0] - 2026-05-17
+
+### Added
+- **`hazo_ui_charts` — new chart-primitives sub-section.** Six components
+  for the Site Ops Dashboard project, ported from its mockup HTML so the
+  app doesn't need a third-party chart lib:
+  - `Sparkline` — axisless trend line for KPI cards (12% area fill,
+    single endpoint dot, no hover — by design per PRD §6b).
+  - `InverseSparkline` — same shape but Y-axis inverted (lower = better)
+    for GSC position trends. 62×18 default, used inline in scrollable
+    query lists.
+  - `LineChart` — full anatomy (3 dashed gridlines, Y ticks max/mid/min,
+    X labels start/mid/end, marker dot + dashed guide-line to Y-axis +
+    above-left value label). Optional hover tooltip surfaces a cursor +
+    bubble at the nearest data index.
+  - `MultiLineChart` — shared Y-axis, per-series endpoint marker, no
+    area fill (avoids color collisions). Hover bubble shows all series
+    stacked. Optional legend below the SVG.
+  - `StackedBars` — generic stacked-bar over time. One bar per X
+    position; each bar split into top-to-bottom colored bands. Used by
+    the GSC position-bucket distribution view.
+  - `DateRangeSelector` — segmented control (`value` + `onChange`).
+    Framework-agnostic: no `next/navigation` import; consumer wires the
+    state. Active pill tints with `--primary`.
+- Pure helpers: `format_num` (compact `1.2k` / `1.3M`),
+  `pick_x_label_indices`.
+- Shared types: `ChartDataPoint`, `ChartDataSeries`, `MultiSeries`,
+  `StackedBar`, `DateRangeOption`.
+- Dev-app demo at `/charts` with six sections (one per primitive)
+  covering rising / falling / flat / with-nulls / all-zeros /
+  single-point data shapes.
+
+### Notes
+- Hover coordinate mapping uses `getBoundingClientRect()` to translate
+  client X → viewBox X. Assumes the SVG renders at `width: 100%` (the
+  default we ship). Documented in `src/components/hazo_ui_charts/AGENTS.md`.
+- Axis label color and gridline color are pinned hex (`#8b949e`,
+  `#2a3441`) chosen for the Site Ops dark theme. Theming via CSS
+  variables is a follow-up if a second consumer needs it.
+- All chart components ship as Client Components by default — the
+  library bundle is `"use client"`-stamped at build time, same as the
+  rest of hazo_ui. The pure-SVG primitives don't *require* JS to
+  render, but they don't get RSC-rendered either.
+
+### API
+- No changes to existing components; this is purely additive.
+
 ## [2.16.0] - 2026-05-17
 
 ### Changed

package/README.md

@@ -206,6 +206,8 @@ The following components support both global config and prop-level color overrid
 
 - **[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**.
@@ -3561,6 +3563,251 @@ The package also re-exports the bare shadcn primitives — `Table`,
 
 ---
 
+## 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)