hazo_ui 2.16.0 → 3.0.1

package/CHANGE_LOG.md

@@ -5,6 +5,82 @@ 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).
 
+## v3.0.0 — test-harness sub-export
+
+**New sub-export:** `hazo_ui/test-harness`
+
+Ships a complete in-app test runner for consuming packages. Import from the dedicated sub-export — it is never included in the main `hazo_ui` bundle.
+
+- **`SidebarLayout` + `AppSidebar`** — sidebar shell for test-app pages with `NavItem[]` navigation.
+- **`AutoTestProvider` + `useAutoTest`** — React context that tracks run status, per-case results, and timing across all registered scenarios.
+- **`AutoTestRunner`** — renders all registered scenarios with Run / Run All controls and pass/fail/timing output per case.
+- **`CopyAllFailuresButton`** — copies all failed cases as a structured Claude prompt (8-section format: header, what-went-wrong, expected/actual/diff, test code, code under test, error chain, context, ring buffer).
+- **`registerScenario(scenario)`** — registers a scenario at module load time; scenarios are collected into a global registry.
+- **`assertEqual`, `assertThrows`, `assertResolves`, `assertRejects`, `assertMatch`, `assertIncludes`, `HazoAssertionError`** — assertion helpers for use inside `case.run()`.
+- **`formatAsClaudePrompt(failedCases, options?)`** — formats an array of failed cases into a copy-pasteable Claude prompt.
+
+## v2.18.0 — CelebrationModal
+
+**New:** `CelebrationProvider`, `celebrate()`, `CELEBRATION_GRADIENT`
+
+- Imperative confetti + modal overlay triggered by `celebrate({ id, title, ... })`.
+- `<CelebrationProvider />` mounts at app root; `celebrate()` works from anywhere in the tree.
+- **Session gating:** each `id` is shown at most once per browser session (sessionStorage). Cross-session gating is the consumer's responsibility.
+- **FIFO queue:** rapid-fire `celebrate()` calls queue up and show one at a time.
+- **Shareable card** (optional): 1080×1080 node rendered at full size, scaled to 400×400 for preview. Download PNG / Share / Copy image buttons (html-to-image, dynamically imported).
+- **`background?: string`:** CSS background for the card. Default: `CELEBRATION_GRADIENT` export.
+- **`caption?: string`:** falls back to `subtitle` when omitted.
+- **Auto-dismiss:** defaults to `true` (8 s). Configure via `autoDismissDelay`.
+- **Audio:** `audioChime: true` plays the bundled success chime (.mp3 inlined as base64).
+- **Dependencies added:** `canvas-confetti`, `html-to-image`.
+
+## [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,421 @@ 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.
+
+---
+
+## Celebration Modal
+
+Fire a confetti overlay with an optional 1080×1080 shareable card from anywhere in your app.
+
+### Setup
+
+Mount `<CelebrationProvider />` once at your app root:
+
+```tsx
+// app/layout.tsx
+import { CelebrationProvider } from "hazo_ui";
+
+export default function RootLayout({ children }) {
+  return (
+    <html>
+      <body>
+        <CelebrationProvider>
+          {children}
+        </CelebrationProvider>
+      </body>
+    </html>
+  );
+}
+```
+
+### Usage
+
+```tsx
+import { celebrate, CELEBRATION_GRADIENT } from "hazo_ui";
+
+// Basic celebration
+celebrate({
+  id: "first_login",       // sessionStorage dedup key — shown once per session
+  title: "Welcome!",
+  subtitle: "Your account is ready.",
+});
+
+// With shareable card
+celebrate({
+  id: "milestone_100",
+  title: "100 entries!",
+  subtitle: "You just crossed 100 entries.",
+  autoDismissDelay: 10_000,
+  shareableCard: {
+    background: CELEBRATION_GRADIENT,  // or any CSS background value
+    foreground: <YourCardContent />,
+    caption: "100 entries logged",     // optional; defaults to subtitle
+  },
+  audioChime: true,
+});
+```
+
+### Session gating
+
+`celebrate()` is a no-op if `hazo_ui_celebration_<id>` is already set in sessionStorage.
+The key is written when the modal opens. Gating resets when the user opens a new tab or browser session.
+
+**Cross-session dedup is the consumer's responsibility.** Check your server-side milestone state before calling `celebrate()`.
+
+### API
+
+| Prop | Type | Default | Description |
+|---|---|---|---|
+| `id` | `string` | required | Dedup key. Used as `hazo_ui_celebration_<id>` in sessionStorage. |
+| `title` | `string` | required | Modal heading. |
+| `subtitle` | `string` | — | Subheading; also used as card caption fallback. |
+| `shareableCard` | `CelebrationShareableCard` | — | Enables card preview + download/share/copy buttons. |
+| `autoDismiss` | `boolean` | `true` | Auto-close after `autoDismissDelay` ms. |
+| `autoDismissDelay` | `number` | `8000` | Ms until auto-dismiss. |
+| `audioChime` | `boolean` | `false` | Play bundled success chime on open. |
+
+---
+
+## Test Harness (v3.0.0)
+
+`hazo_ui/test-harness` is a dedicated sub-export that ships a complete in-app test runner for consuming packages. It is **never included in the main `hazo_ui` bundle** — only imported by test-app code.
+
+### Setup
+
+```tsx
+// test-app/app/layout.tsx
+import { SidebarLayout, AppSidebar, AutoTestProvider } from 'hazo_ui/test-harness';
+import type { NavItem } from 'hazo_ui/test-harness';
+
+const nav: NavItem[] = [
+  { href: '/', label: 'Overview' },
+  { href: '/my-feature', label: 'My Feature' },
+];
+
+export default function RootLayout({ children }) {
+  return (
+    <html>
+      <body>
+        <AutoTestProvider>
+          <SidebarLayout sidebar={<AppSidebar nav={nav} title="my_pkg" />}>
+            {children}
+          </SidebarLayout>
+        </AutoTestProvider>
+      </body>
+    </html>
+  );
+}
+```
+
+### Registering scenarios
+
+```ts
+// test-app/scenarios/my_feature.ts
+import { registerScenario, assertEqual } from 'hazo_ui/test-harness';
+
+registerScenario({
+  id: 'my_feature',
+  name: 'My Feature',
+  pkg: 'my_pkg',
+  cases: [
+    {
+      name: 'returns correct value',
+      run: async () => {
+        const result = myFunction(1, 2);
+        assertEqual(result, 3, 'should add two numbers');
+      },
+    },
+    {
+      name: 'throws on invalid input',
+      run: async () => {
+        await assertThrows(() => myFunction(null, 2), 'invalid input');
+      },
+    },
+  ],
+});
+```
+
+### Rendering the runner
+
+```tsx
+// test-app/app/my-feature/page.tsx
+import { AutoTestRunner } from 'hazo_ui/test-harness';
+import '../scenarios/my_feature'; // registers the scenario
+
+export default function MyFeaturePage() {
+  return <AutoTestRunner scenarioId="my_feature" />;
+}
+```
+
+### Copying failures as a Claude prompt
+
+`CopyAllFailuresButton` copies all failed cases as a structured prompt with 8 sections (what-went-wrong, expected/actual/diff, test code, code under test, error chain, context, ring buffer). Place it in your sidebar or test page header.
+
+```tsx
+import { CopyAllFailuresButton } from 'hazo_ui/test-harness';
+
+// Inside your layout or sidebar:
+<CopyAllFailuresButton />
+```
+
+### Assertions
+
+| Function | Description |
+|---|---|
+| `assertEqual(actual, expected, msg?)` | Deep-equal assertion |
+| `assertThrows(fn, msgOrPattern?)` | Sync function must throw |
+| `assertResolves(promise)` | Promise must resolve |
+| `assertRejects(promise, msgOrPattern?)` | Promise must reject |
+| `assertMatch(value, pattern)` | String must match regex or substring |
+| `assertIncludes(arr, item)` | Array must include item |
+
+All failures throw `HazoAssertionError` with a structured message.
+
+---
+
 ## Troubleshooting
 
 ### Styles not applying (Tailwind v4)

package/SETUP_CHECKLIST.md

@@ -135,6 +135,8 @@ npm install @radix-ui/react-dialog @radix-ui/react-popover @radix-ui/react-selec
   - **ProgressiveImage**: No additional dependencies
   - **HazoUiToaster, successToast, errorToast, rawToast**: `sonner`, `lucide-react`
   - **useLoadingState, useErrorDisplay** hooks: No additional dependencies
+- **Celebration (v2.18.0)**:
+  - **CelebrationProvider, celebrate, CELEBRATION_GRADIENT**: No additional peer deps — `canvas-confetti` and `html-to-image` are bundled direct dependencies
 
 ### 4. Configure Tailwind CSS
 
@@ -252,10 +254,18 @@ import {
   HazoUiToaster, successToast, errorToast,
   useLoadingState, useErrorDisplay,
 } from 'hazo_ui';
+
+// Import celebration (v2.18.0)
+import { CelebrationProvider, celebrate, CELEBRATION_GRADIENT } from 'hazo_ui';
+
+// Import test harness (v3.0.0) — test-app only, never in production bundles
+import { AutoTestProvider, AutoTestRunner, SidebarLayout, AppSidebar, registerScenario, assertEqual } from 'hazo_ui/test-harness';
 ```
 
 **Toaster setup**: Mount `<HazoUiToaster />` once at the root of your app (e.g., in `layout.tsx`) so `successToast()` / `errorToast()` calls have somewhere to render.
 
+**Celebration setup**: Mount `<CelebrationProvider />` once at the root of your app (e.g., in `layout.tsx`) so `celebrate({ id, title })` calls have somewhere to render. Session gating (one show per `id` per browser session) runs automatically.
+
 [ ] Use the component in your code (see README.md for detailed usage examples)
 
 ### 6. Verify Installation