basalt-ui 1.14.0 → 1.15.0

package/AGENTS.md

@@ -9,7 +9,7 @@ Toolchain: Bun runtime, oxlint + oxfmt, conventional commits (empty scope), `mas
 | Subpath                     | Layer           | Purpose                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
 | --------------------------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `basalt-ui`                 | mantine-coupled | BasaltProvider, createBasaltTheme, BasaltShell + sidebar/mobile-nav/breadcrumbs, NavCountBadge, ThemeToggle, ThreadWorkspace + thread-chat components, dashboard composites (DeltaBadge, StatCard with threshold tone, EmptyState, SettingsSection/SettingsRow/DangerZone)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
-| `basalt-ui/charts`          | headless        | visx chart primitives, sparklines, hooks, and token re-exports (Mantine-free)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
+| `basalt-ui/charts`          | headless        | CartesianChart + visx chart primitives, kinds, sparklines, hooks, and token re-exports (Mantine-free)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
 | `basalt-ui/tokens`          | headless        | VX token refs, buildPaletteCss, defineSeries, seriesTokens, groupTokens, alpha (Mantine-free)                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
 | `basalt-ui/theme-lab`       | mantine-coupled | ThemeLabControls, applyOverrides, COLOR_GROUPS — a low-level inspector for the non-derived structural tokens; identity/color tuning lives in DeriveControls                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
 | `basalt-ui/vite`            | mantine-coupled | basaltViteConfig(opts) — Vite preset for basalt-ui consumer apps; basaltAppPlugin(opts) — PWA head, manifest, and icon metadata derived from the token palette                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            |

package/CHANGELOG.md

@@ -1,3 +1,11 @@
+# [1.15.0](https://github.com/jkrumm/basalt-ui/compare/v1.14.0...v1.15.0) (2026-08-18)
+
+
+### Features
+
+* add x-range chart bands, a dual-axis margin, and legend notes ([4883c19](https://github.com/jkrumm/basalt-ui/commit/4883c19d06a43d6a908efcf9fe8098610c86627a))
+* make one cartesian primitive the whole chart contract ([4f8a507](https://github.com/jkrumm/basalt-ui/commit/4f8a507b2ca01923c1ee9bdf8a911ac0e5b76710))
+
 # [1.14.0](https://github.com/jkrumm/basalt-ui/compare/v1.13.0...v1.14.0) (2026-08-10)
 
 

package/README.md

@@ -222,7 +222,7 @@ deleted rather than silently surviving into the next real skew.
 | Subpath             | Mantine? | Purpose                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
 | ------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
 | `.`                 | coupled  | `BasaltProvider`, `createBasaltTheme` / `baseTheme` / `cssVariablesResolver`, `BasaltShell` + sidebar / mobile-nav / breadcrumbs / page-header, `NavCountBadge`, `SidebarAccount` + the provider-agnostic account contract (`BasaltAccountProps`/`State`/`Actions`), `ThreadWorkspace` + thread-chat components, shell types — the root entry still re-exports the thread-chat components; `./agent-chat` takes the same components standalone, without `BasaltProvider`, the shell, the dashboard composites, or `./connectivity`                                                                                                                    |
-| `./charts`          | **free** | visx chart primitives, sparklines, hooks, and token re-exports                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
+| `./charts`          | **free** | `CartesianChart` + visx primitives, kinds, sparklines, hooks, token re-exports                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
 | `./tokens`          | **free** | `VX` token refs, `buildPaletteCss`, `defineSeries`, `seriesTokens`, `groupTokens`, `alpha`, `ColorPair` / `SeriesMap` types                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
 | `./theme-lab`       | coupled  | `ThemeLabControls`, `applyOverrides`, `loadOverrides`, `COLOR_GROUPS` for live theme inspection                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
 | `./vite`            | —        | `basaltViteConfig(opts)` — Vite preset for basalt-ui consumer apps; `basaltAppPlugin(opts)` — PWA head, manifest, and icon metadata derived from the token palette                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
@@ -331,10 +331,46 @@ bun add @visx/axis @visx/curve @visx/event @visx/grid @visx/group @visx/responsi
 dependency-free: it needs the nine `@visx/*` packages, all pinned exact at `4.0.0`. They ship as
 optional peers, not bundled dependencies, so a `./tokens`-only consumer never installs them.
 
+`CartesianChart` is the entry point: it owns the measured margins, both y scales and their
+domains, the axes, grid, the page-shared cursor, the crosshair and the derived tooltip, so a chart
+supplies its `series` and draws only marks. Legends toggle series, margins size themselves from
+the tick labels actually painted, and charts share a cursor with no provider.
+
 ```tsx
-import { Bars, VxThemeProvider } from 'basalt-ui/charts'
+import { CartesianChart, LinePath, VX } from 'basalt-ui/charts'
+;<CartesianChart
+  data={rows}
+  chartId="sessions"
+  getX={(d) => d.date}
+  series={[
+    {
+      key: 'sessions',
+      label: 'Sessions',
+      color: VX.accent,
+      mark: 'line',
+      getValue: (d) => d.sessions,
+    },
+  ]}
+  y={{ format: (v) => v.toFixed(0) }}
+  height={260}
+>
+  {({ visible, xScale, yScale }) =>
+    visible.map((s) => (
+      <LinePath
+        key={s.key}
+        data={rows}
+        x={(d) => xScale(d.date) ?? 0}
+        y={(d) => yScale(s.getValue(d) ?? 0)}
+        stroke={s.color}
+      />
+    ))
+  }
+</CartesianChart>
 ```
 
+Shipped kinds (`Bars`, `MultiLine`, `StackedArea`, `ZonedLine`, `Donut`, `DualPanel`, `Heatmap`)
+are that same composition, pre-wired.
+
 ### `./query` — TanStack Query adapter
 
 ```bash

package/agent/rules/basalt-charts.md

@@ -11,8 +11,11 @@ paths:
 
 basalt-ui owns the chart doctrine. Charts are built from low-level [visx](https://airbnb.io/visx)
 primitives so we can build exactly the chart we want; the trade-off is that every chart duplicates
-structure unless we compose shared building blocks. **The primitives + a small kind set are the
-contract, not optional polish.**
+structure unless we compose shared building blocks. **`CartesianChart` plus a small kind set are
+the contract, not optional polish** — composing `CartesianChart` (single-plot) or `ChartFrame`
+directly (multi-pane/radial/matrix) is mandatory for every chart, mechanically enforced by
+`basalt/hand-rolled-plot` (see "Mechanical enforcement" below). `docs/CHARTS-SPEC.md` is the ground
+truth this doc reflects.
 
 ## The boundary (lint-enforced)
 
@@ -25,7 +28,7 @@ downstream apps too:
   `AreaClosed`, `scaleLinear`, `curveMonotoneX`, …) — keep the dependency declared in one place, and
   keep your own bespoke chart file under a `charts/` directory so it stays on the right side of the
   boundary.
-- **`@visx/tooltip` is banned everywhere** (`basalt/visx-tooltip`). Use `ChartTooltip` +
+- **`@visx/tooltip` is banned everywhere** (`basalt/visx-tooltip`). Use `ChartTooltipFloat` +
   `TooltipHeader`/`TooltipRow`/`TooltipBody` from `basalt-ui/charts`.
 
 `basalt-ui/charts` is itself Mantine-free (`basalt/token-layer-boundary`, enforced only inside
@@ -44,62 +47,164 @@ either — both remedies point at a Mantine layout primitive (`Flex`/`Grid`/`Gro
 Mantine-free boundary above already forbids there, so the finding would be unactionable. Reach for
 `ChartCenter` (below, under "Pending state") when a chart file needs to center something.
 
+## The contract is mandatory (lint-enforced)
+
+Composing `CartesianChart` for a single-plot chart, or `ChartFrame` directly for a multi-pane/
+radial/matrix shape, is not optional — two `basalt` oxlint plugin rules
+(`packages/basalt-ui/configs/oxlint-plugin.js`) make it a lint failure to bypass:
+
+- **`basalt/hand-rolled-plot`** — rendering a chart-assembly primitive (`AxisLeftNumeric`,
+  `AxisRightNumeric`, `AxisBottomDate`, `HoverOverlay`, `Crosshair`) in a file that does not
+  compose `CartesianChart` fails the build. Escape: a `theme-allow` comment on the first such
+  site — that is how a genuinely non-single-plot shape (multi-pane, radial, matrix) declares
+  itself; `DualPanel` carries the repo's one such comment. The file that DEFINES `CartesianChart`
+  is exempt definitionally (detected by declaration, not by path), since a rule saying "compose X"
+  cannot fire inside X.
+- **`basalt/chart-legend-literal`** — passing a hand-written array literal to `ChartLegend`'s
+  `items` fails the build; the legend must be derived from the same `series` array the chart draws
+  (`deriveLegend`, or just let `ChartFrame`/`CartesianChart` do it), so it cannot go stale and keep
+  naming a series the plot no longer draws.
+
+Both ship at `warn` in the consumer preset (`configs/oxlint.json`) for one minor and `error`
+repo-local, per the "Shipping a stricter guard — the grace minor" doctrine in
+`packages/basalt-ui/CLAUDE.md`. They promote to `error` in the next minor.
+
+## Maps are not charts
+
+Neither `@visx/geo` nor any map library is among the 9 exact-pinned `@visx/*` peers, and basalt
+ships no map kind.
+
+- **Maps are consumer territory.** A map is a MapLibre/Leaflet/deck.gl component in the consumer's
+  own tree, not a visx chart — build it wherever the rest of that consumer's non-chart UI lives.
+- **The `basalt/visx-boundary` rule doesn't apply.** It constrains `@visx/*` imports only. A map
+  library is not `@visx/*`, so a map component needs no `charts/` path segment and no exemption.
+- **Want `@visx/geo` anyway?** Install it yourself — basalt doesn't pin it — and keep it under a
+  `charts/` segment like every other visx import, same as any bespoke chart.
+- **Style map chrome with `--vx-*` tokens** (`VX.*`/`alpha()`) so it matches the rest of the app.
+- **The guard trap:** `check-theme`'s `inline-spacing` kind is a per-line regex over raw source, not
+  an AST pass — it flags any `padding:`/`gap:`/`margin:` followed by a number in _any_ object
+  literal, in any file. A map's pixel geometry (`fitBounds({ padding: 48 })`, marker offsets) trips
+  it even though it isn't spacing, and hoisting the value to a module-scope const doesn't help — the
+  regex sees the line, not the binding. Use a `theme-allow` line comment; that's the sanctioned
+  answer, not a bug to file.
+
 ## Every chart has
 
-1. **ChartCard** wrapper — gives title + info-tooltip + extra slot, consistent margin.
-2. **ChartLegend** — never hand-rolled legend markup. Supports `line | bar | split | splitLine`
-   shapes and optional highlight state.
-3. **ChartTooltip** + `TooltipHeader` + `TooltipRow` + `TooltipBody` — never `@visx/tooltip` directly.
-   Portals to `document.body` (SSR-guarded: renders nothing when `document` is undefined), so it
-   can be authored anywhere in the tree, including inside an `<svg>`. A plain `<div>` there used to
-   mount in the SVG namespace — accepting every prop, throwing nothing, typechecking, passing lint
-   — and never paint; one consumer shipped eight authored tooltip rows no one had ever seen. The
-   portal also un-breaks `position: fixed` under a transformed ancestor.
-4. **AxisLeftNumeric** / **AxisRightNumeric** + **AxisBottomDate** — never raw `<AxisLeft>`/`<AxisBottom>`/`<AxisRight>`
-   (they miss theme tokens + smart ticks). Enforced by `basalt-ui check-theme` (`raw-visx-axis` guard
-   fails the build on a raw axis in a `/charts/` file; escape via `theme-allow`), not just convention.
-   `AxisBottomDate` takes an optional `tickFormat` (`TickFormatter<string>`, defaults to
-   `fmtAxisDate` — `DD.MM`) — the only supported exit for a sub-day window, where the default
-   collapses every tick to the same label and a raw `<AxisBottom>` isn't an option.
-5. **HoverOverlay** for pointer capture (mouse + touch + pen — `touch-action: pan-y` lets vertical
-   page scroll pass through while a horizontal drag scrubs the chart), **HoverContext** for
-   cross-chart crosshair sync, **useChartTooltip** for tip state, **useHoverSync** for the shared
-   cursor. Wrap a group of date-aligned charts in **ChartHoverSync** (from `basalt-ui/charts`) to
-   activate cross-chart sync — hovering one chart casts a ghost crosshair on all siblings; without
-   it `useHoverSync` runs per-chart only and logs a dev warning:
+1. **`CartesianChart`** — the primitive every single-plot cartesian chart composes, and composes
+   NOTHING else from this list by hand. `ZonedLine`, `Bars`, `StackedArea`, and `MultiLine` all
+   compose it; a bespoke single-plot chart should too. It owns measured margins, both y scales +
+   domains, the x scale + tick thinning, grid, zones, axes, the shared cursor, the crosshair + its
+   per-series dots, the hover/keyboard overlay, and the derived tooltip. The caller supplies
+   `series` (the single source of truth — see #3) and a `children` render prop that draws ONLY
+   marks:
 
    ```tsx
-   <ChartHoverSync>
-     <ChartCard>…</ChartCard>
-     <ChartCard>…</ChartCard>
-   </ChartHoverSync>
+   <CartesianChart
+     data={data} chartId="sessions" getX={(d) => d.date} series={SERIES}
+     y={{ domain: 'auto', format: fmtInt }}
+     height={260}
+   >
+     {({ xScale, yScale, visible }) => visible.map((s) => <LinePath key={s.key} … />)}
+   </CartesianChart>
    ```
 
-   Sync is exact string match on the broadcast key by default, so two charts share a cursor only
-   when they emit identical key strings. A chart that folds/downsamples its domain for a narrow
-   viewport stops owning most of the keys its unfolded siblings broadcast — the shared crosshair
-   then lands on roughly one hover in three, worse than no shared cursor at all. Pass
-   `useHoverSync`'s `resolveKey` to map a foreign key onto whichever of this chart's own points
-   swallowed it; it only affects reading a SIBLING's broadcast key, never this chart's own hover:
+   Reaching past it for an axis, a tooltip, or a margin means the chart has drifted from every
+   other chart. `DualPanel`, `Heatmap`, and `Donut` are the deliberate exception, by shape: they
+   compose `ChartFrame` + `useChartCursor` + `autoMargin` + `ChartTooltipFloat` directly instead —
+   same machinery, different assembly, because their contract isn't a single plot rect with one or
+   two numeric y axes.
+
+2. **ChartCard** wrapper — never a raw `<Card>`. Gives title + info-tooltip + extra slot, consistent
+   margin.
+3. **`series` is the single source of truth.** Legend entries and tooltip rows are DERIVED from it
+   (`deriveLegend` / `deriveTooltipRows`) — a chart cannot show a row or a legend key it doesn't
+   draw. Never hand-author a legend or a tooltip row in parallel. Corollary for mark renderers: draw
+   `ctx.visible` (the `PlotContext` field), never the `series` prop directly — `visible` is `series`
+   minus whatever the legend has toggled off, so drawing `series` would repaint a mark the reader
+   just hid.
+4. **`ChartTooltipFloat`** + `TooltipHeader` + `TooltipRow` + `TooltipBody` — never `@visx/tooltip`
+   directly. `CartesianChart` wires this internally for a single-plot chart; a non-cartesian shape
+   composes it directly (see #1). Portals to `document.body` (SSR-guarded: renders nothing when
+   `document` is undefined), so it can be authored anywhere in the tree, including inside an
+   `<svg>`. A plain `<div>` there mounts in the SVG namespace — accepting every prop,
+   throwing nothing, typechecking, passing lint — and never paint; one consumer shipped eight
+   authored tooltip rows no one had ever seen. The portal also un-breaks `position: fixed` under a
+   transformed ancestor.
+5. **AxisLeftNumeric** / **AxisRightNumeric** + **AxisBottomDate** — never raw
+   `<AxisLeft>`/`<AxisBottom>`/`<AxisRight>` (they miss theme tokens + smart ticks). Enforced by
+   `basalt-ui check-theme` (`raw-visx-axis` guard fails the build on a raw axis in a `/charts/`
+   file; escape via `theme-allow`), not just convention. `AxisBottomDate` takes an optional
+   `tickFormat` (`TickFormatter<string>`, defaults to `fmtAxisDate` — `DD.MM`) — the only supported
+   exit for a sub-day window, where the default collapses every tick to the same label and a raw
+   `<AxisBottom>` isn't an option. `CartesianChart`'s own `formatX` prop is the higher-level way to
+   set this without touching the axis component at all.
+6. **The cursor is shared by default.** No provider needed — `useChartCursor` reads a module-level
+   external store (`useSyncExternalStore`), so every `CartesianChart`/`ChartFrame`-composed chart on
+   the page shares one cursor out of the box. `ChartCursorScope` **isolates** a subtree onto a
+   private store instead: it opts a subtree OUT of sharing, never into it. Reach for it only when a
+   group must not follow the rest of the page.
 
    ```tsx
-   useHoverSync({
-     data: foldedData,
-     chartId: 'load-mobile',
-     getKey: (d) => d.bucketKey,
-     xScale,
-     marginLeft,
-     // ~288 daily buckets folded into ~97 columns at this width — map an unfolded sibling's key
-     // onto the folded bucket that swallowed it.
-     resolveKey: (key) => pointByKey.get(foldKey(key)) ?? null,
-   })
+   <ChartCursorScope>
+     <ChartCard>…</ChartCard>
+     <ChartCard>…</ChartCard>
+   </ChartCursorScope>
    ```
 
-6. **Theme-aware colors** via `VX.*` tokens + `alpha()`. **Never** a raw hex literal in a chart file.
-   **Never** `localStorage.getItem('theme')` — the scheme resolves via CSS vars (see Dark/light below).
-
-**Exemption:** sparklines (`LineSparkline`, `BarSparkline` — tiny inline charts with no legend/tooltip)
-don't have to compose ChartCard/ChartLegend/ChartTooltip — but still use `VX.*` tokens.
+   **Resolution is domain-aware, not string-equal**, which is what makes sharing safe as a default.
+   Exact-string matching would desync any chart that folds or downsamples its own domain: it stops
+   owning most of the keys its siblings broadcast, so the shared crosshair lands on some hovers and
+   not others, with no rule a reader can infer — worse than no shared cursor at all.
+   `useChartCursor` resolves a broadcast key against a chart's own points by, in order: exact
+   match → nearest parsed-numeric/date match within the chart's own step → `null`. A chart that folds its calendar
+   into weekly buckets still tracks a hover from a sibling plotting daily points, with no extra
+   wiring — `resolveKey` no longer exists because there is nothing left for it to patch.
+
+7. **Keyboard-operable by construction.** The hover overlay `CartesianChart` renders is focusable;
+   `←`/`→` scrub the shared cursor one point at a time, `Escape` clears it. The tooltip is
+   `aria-live="polite"`. This comes for free from composing `CartesianChart`/`ChartFrame` — nothing
+   to wire per chart.
+8. **Theme-aware colors** via `VX.*` tokens + `alpha()`. **Never** a raw hex literal in a chart file.
+   **Never** `localStorage.getItem('theme')` — the scheme resolves via CSS vars (see Dark/light
+   below).
+
+**Exemption:** sparklines (`LineSparkline`, `BarSparkline` — tiny inline charts with no
+legend/tooltip) don't have to compose ChartCard/`CartesianChart`'s legend/tooltip — but still use
+`VX.*` tokens.
+
+## Legend interaction
+
+At ≥2 entries, the derived legend is a toggle by default: clicking an entry hides that series from
+the plot, the tooltip, AND the auto y-domain, together — a stacked chart's axis actually shrinks
+when a band is hidden, it doesn't just leave a dead gap. `legend={{ toggle: false }}` opts a chart
+out. A single-entry legend never toggles (hiding the only series a chart draws is never useful).
+This is exactly why marks must draw `ctx.visible` and never `series` (see "Every chart has" #3) —
+`visible` is what actually reflects a hidden key; the raw `series` prop never changes.
+
+## Tooltip config
+
+`CartesianChart`'s `tooltip` prop (`CartesianTooltipConfig<T>`, or `false` to disable the tooltip
+and its crosshair dots entirely):
+
+- `label?: (d: T) => { text; color } | null` — a right-aligned badge in the header (a status label,
+  a zone name).
+- `prependRows?: (d: T) => ReactNode` — rows rendered BEFORE the derived per-series rows (a total, a
+  context line).
+- `extraRows?: (d: T) => ReactNode` — rows appended after the derived rows.
+- `follow?: boolean` — default `true`, the tooltip tracks the pointer. `follow: false` anchors it to
+  the crosshair at the plot's top edge instead, which reads better across a column of charts sharing
+  one cursor (every tooltip lines up on the same x). Anchoring costs one `getBoundingClientRect` per
+  hovered frame, which is why following is the default.
+
+Per-series, `SeriesStyle.tooltip: false` means "draw the mark and legend it, but never give it a
+tooltip row" — it lives on the series, not on the
+kind.
+
+A **stacked** chart needs `cursorValue` too: `CartesianChart`'s crosshair dot defaults to
+`series.getValue(point)`, which is correct for an unstacked line but puts a stacked band's dot at
+its own raw value — somewhere inside the fill, not on the edge the reader is tracking. Pass
+`cursorValue={(point, series, visible) => …}` to place it at the cumulative band top instead;
+`StackedArea` is the reference implementation (`kinds/StackedArea.tsx`).
 
 ## Pending state (`isPending`)
 
@@ -116,15 +221,18 @@ import { Bars } from 'basalt-ui/charts'
   isPending={query.isPending}
   chartId="load"
   getX={(d) => d.date}
-  getY={(d) => d.load}
+  getValue={(d, key) => d[key]}
+  positiveBars={[{ key: 'load', label: 'Load', color: VX.accent }]}
 />
 ```
 
-All seven kinds accept `isPending` and forward it to `ChartFrame` (`Heatmap` handles it locally —
-it composes no `ChartFrame`, taking `width`/`height` directly rather than measuring). `ChartFrame`
-with `isPending` renders `ChartPending` over the plot rect in place of `children`, suppresses the
-legend entirely (a legend naming a series with nothing yet to point at is its own small lie), and
-sets `aria-busy="true"` on the outer container.
+All seven kinds accept `isPending` and forward it to `ChartFrame` — `ZonedLine`/`Bars`/
+`StackedArea`/`MultiLine` forward it through `CartesianChart`, which forwards it on to `ChartFrame`
+in turn; `DualPanel`/`Heatmap`/`Donut` compose `ChartFrame` directly and forward it there. Every
+path lands on the same `ChartFrame`, so there's one pending renderer, not seven. `ChartFrame` with
+`isPending` renders `ChartPending` over the plot rect in place of `children`, suppresses the legend
+entirely (a legend naming a "not measured" series with nothing to point at is its own small lie),
+and sets `aria-busy="true"` on the outer container.
 
 `ChartPending` reserves the plot's exact footprint and draws **nothing** that could be mistaken for
 a measurement — no axes, no gridlines, no hatching, no marks, no animation (the motion doctrine
@@ -138,31 +246,78 @@ directly in a bespoke chart file the same way; it's deliberately minimal (`width
 
 ## Kinds — the recurring shapes
 
-basalt-ui ships these kinds (declarative props, generic over your point type via `getX`/`getY`):
-
-- **`ZonedLine`** — a line with zone bands, thresholds, and reference lines.
-- **`Bars`** — bars with optional overlaid line, zones, ref lines, dual-axis config.
-- **`StackedArea`** — opaque stacked bands.
-- **`Donut`** — proportional donut.
-- **`MultiLine`** — N series on a shared y-axis: legend-hover dimming, per-series synced dots,
-  dashed companion (MA) lines, per-point markers (PR stars / status dots), zones + refLines, fixed
-  or auto domain (covers z-score/σ via a fixed symmetric domain + zero refLine).
+basalt-ui ships these kinds (declarative props, generic over your point type via `getX` and
+per-series `getValue` accessors on `ChartSeries<T>`):
+
+- **`ZonedLine`** — a single-series line with zone bands, thresholds, x-zones, and reference lines.
+  Composes `CartesianChart`.
+- **`Bars`** — 1+ stacked positive/negative bar series, optional line overlays, zones, ref lines,
+  dual-axis config. Composes `CartesianChart`.
+- **`StackedArea`** — opaque stacked bands, auto cumulative-top y-domain. Composes `CartesianChart`.
+- **`MultiLine`** — N series on a shared y-axis (or two, via `y2`): legend-hover dimming, per-series
+  synced dots, dashed companion (MA) lines, per-point markers (PR stars / status dots), zones +
+  refLines, fixed or auto domain (covers z-score/σ via a fixed symmetric domain + zero refLine).
+  Composes `CartesianChart`.
 - **`DualPanel`** — top line-pane + bottom signed-histogram pane sharing one x-scale and one cursor;
-  optional fill-between two top lines, zones, refLines.
+  optional fill-between two top lines, zones, refLines. Composes `ChartFrame` directly (two panes,
+  not one plot rect).
 - **`Heatmap`** — category×category intensity grid (`color-mix` alpha), per-cell tooltip, optional
-  gradient legend strip.
+  gradient legend strip. Composes `ChartFrame` directly; self-measures, no separate responsive
+  wrapper.
+- **`Donut`** — proportional donut with an optional center-content overlay. Composes `ChartFrame`
+  directly (radial, not cartesian).
+
+`ZonedLine` and `MultiLine` also accept `xZones?: XZoneSpec[]` — the vertical counterpart to a
+kind's horizontal zone bands, for marking a time window rather than a value range. Each
+`{ from?, to?, fill }` bound is a `getX` **domain key** (the label string the kind's
+`scalePoint<string>` runs over), not a date or timestamp. An omitted bound is the plot edge; a key
+absent from the scale's domain skips that band entirely rather than clamping to an edge.
 
 How to add a chart:
 
-1. **Fits an existing kind?** Use it. Pass `data`, `width`, `height`, `chartId`, accessors, and the
-   declarative zones/thresholds/refLines arrays.
+1. **Fits an existing kind?** Use it. Pass `data`, `chartId`, `getX`, `series` (or
+   `positiveBars`/`getValue` for `Bars`), an `AxisConfig` per axis (`y`/`y2`), and the declarative
+   zones/thresholds/refLines arrays.
 2. **Second instance of a new recurring shape?** Extract a kind and migrate both call sites
    (Rule of Three: don't extract on the first, don't wait past the third). Bespoke escape hatches
-   (`renderExtraTooltipRows`, etc.) are fine but must not grow into god-object configs.
-3. **Genuinely unique (e.g. a dual-panel MACD)?** Stay bespoke — compose the primitives + the raw
-   visx re-exports directly. Keep it in the page's chart file, not in a shared kind.
+   (`tooltip.extraRows`, etc.) are fine but must not grow into god-object configs.
+3. **Genuinely unique (e.g. a dual-panel MACD, or a dual-axis line pair no kind's config surface
+   covers)?** Stay bespoke — compose `CartesianChart` (single-plot) or `ChartFrame` (multi-pane/
+   non-cartesian) directly, drawing only marks in the `children` render prop. Keep it in the page's
+   chart file, not in a shared kind. See `apps/playground/src/demo/ChartsPage.tsx`'s
+   `SessionsRevenueChart` (a dual-axis line pair via `CartesianChart` + `y`/`y2`) and
+   `ChannelVolumeChart` (a role-grouped, `maxRows`-capped legend with a threshold-as-legend-entry
+   trick) for two real bespoke compositions.
+
+**Anti-pattern:** a single `<Chart type="..." config={...} />` that switches by kind. Prefer N small
+kinds.
 
-**Anti-pattern:** a single `<Chart type="..." config={...} />` that switches by kind. Prefer N small kinds.
+## Axis config (`AxisConfig<T>`)
+
+One object per axis on `CartesianChart` and every kind that composes it — this collapses the
+`yDomain` / `yAutoMaxFloor` / `yAutoMinCeil` / `yAutoPad` / `numTicksY` /
+`formatYTick` prop soup:
+
+```tsx
+y={{
+  domain: 'auto',        // 'auto' (default) | [min, max] | (data, visible) => [min, max]
+  autoMaxFloor: 100,      // when 'auto': upper bound is at least this
+  autoMinCeil: 0,         // when 'auto': lower bound is at most this (Infinity = pad from raw min)
+  autoPad: 1.1,           // when 'auto': padding multiplier away from the data
+  ticks: 5,
+  format: (v) => `${v}%`,
+  grid: true,             // horizontal grid rules; default on for `y`, off for `y2`
+}}
+```
+
+**Passing `y2` is what makes a chart dual-axis** — it draws the right axis and widens the right
+margin by measurement; nothing else flips it on. A series opts into that axis with `axis: 'right'`
+on its `ChartSeries` entry (`SeriesStyle.axis`, default `'left'`).
+
+`domain` as a function is the seam a stacked chart uses: it receives `(data, visible)`, so a
+domain summed from the VISIBLE series shrinks correctly when the legend toggles a band off
+(`StackedArea`'s `yConfig` is the reference — summing `props.series` there instead would leave a
+permanent gap above the stack once a band is hidden).
 
 ## Series color
 
@@ -183,6 +338,10 @@ shifts shade across schemes — that's why each entry is a `{ light, dark }` pai
 **Adding a new color** means adding a pair to your series map and rebuilding the palette CSS — never
 inline a hex in a chart.
 
+A series that's invisible in the plot (flat at the domain floor, filtered to zero) can still carry
+an explanation: `SeriesStyle.note` (and so `LegendEntry.note`, via `deriveLegend`) renders a short
+muted qualifier after the legend label — e.g. _"Low cloud — 0% all night"_. Keep it to a clause.
+
 ## Dark/light mode
 
 Theme reactivity is **pure CSS**: the `--vx-*` variables are redeclared under the light/dark color
@@ -198,51 +357,44 @@ clutter). Keep stacked-area bands opaque — fading them leaks lower bands.
 
 ## Responsive sizing
 
-Use `ResponsiveChart` (render-prop container) or `useChartSize` (hook) from `basalt-ui/charts` —
-both are backed by `@visx/responsive`'s `useParentSize` and keep the `@visx/*` import inside a
-`charts/` directory per `basalt/visx-boundary`. Never reach for `@visx/responsive` directly or
-`useElementSize` from `@mantine/hooks` in a chart file.
+There is exactly one responsive path now — `ChartFrame` (composed either directly, or via
+`CartesianChart`, which composes it internally). `Heatmap` self-measures
+the same way every other kind does, instead of taking `width`/`height` from a separate wrapper.
+Every kind and `CartesianChart` itself resolve their size the same three ways, tried in this order:
 
 ```tsx
-import { ResponsiveChart, Bars } from 'basalt-ui/charts'
-
-// Preferred: render prop, renders nothing until the first measurement
-<ResponsiveChart height={320}>
-  {({ width, height }) => (
-    <Bars width={width} height={height} data={data} chartId="load" getX={…} getY={…} />
-  )}
-</ResponsiveChart>
-
-// aspectRatio variant: height = width / ratio
-<ResponsiveChart aspectRatio={16 / 9}>
-  {({ width, height }) => <MyChart width={width} height={height} />}
-</ResponsiveChart>
+<Bars height={260} … />                 // fixed height (most common)
+<Bars aspectRatio={16 / 9} … />         // height = round(measured width / ratio)
+<Bars fill … />                          // fills the parent flex/grid cell's measured height
 ```
 
-Use `useChartSize` directly when you need the `ref` on a custom container:
+Reach for `useChartSize` directly only when composing `ChartFrame`/`CartesianChart` yourself in a
+bespoke chart and you need the measured `{ width, height }` for something beyond what those
+primitives already do with it — `ChartFrame` already calls it internally for you in the common case.
+`UseChartSizeResult`: `{ ref, width, height }`; attach `ref` to the container you want measured.
 
-```ts
-import { useChartSize } from 'basalt-ui/charts'
-
-const { ref, width, height } = useChartSize()
-// attach ref to your container div; width/height update via ResizeObserver
-```
+## Margin
 
-`ResponsiveChartProps`: `height` (default 240), `aspectRatio`, `debounceMs` (default 0), `children`.
-`UseChartSizeResult`: `{ ref, width, height }`.
+Margins are **measured**, not hand-picked. `CartesianChart` runs every configured axis's tick
+labels through `autoMargin`/`measureText` (`basalt-ui/charts`) before laying out the plot, so
+`VX.margin` is a **floor**, not the value — a wide tick label (a long right-axis dollar format, a
+rotated x label) widens its own gutter automatically instead of clipping or needing a hand-tuned
+margin. Passing `y2` to get a dual-axis chart no longer needs a manual margin nudge at all:
 
-## Migrating from pre-1.0 (`@argo/charts` era)
+```tsx
+// now: nothing — passing y2 is what widens the right margin, measured from what's actually painted
+<CartesianChart data={data} chartId="x" getX={…} series={SERIES} y={{…}} y2={{…}} />
+```
 
-Three silent renames/behavior changes trip up a consumer migrating off the pre-1.0 in-house charts
-package — all typecheck-clean only in a strict setup, so they're easy to miss in a quick port:
+The escape hatch is `margin={{ left: n }}` (`Partial<ChartMargin>`) on `CartesianChart` — a per-side
+override applied LAST, after measurement, so it always wins.
 
-- **`HoverCtx.date` → `HoverCtx.key`.** The hover context's cross-chart cursor field is generic
-  now (not date-only) — rename the field, not just the type.
-- **`useHoverSync({ getX })` → `useHoverSync({ getKey })`.** Same generalization — pass an accessor
-  returning the series key, not an x/date value.
-- **`legend.maxRows` renders a `+N more` chip** instead of silently truncating. A consumer that
-  previously hand-rolled `.slice(0, N)` on its legend items gets a visible UX diff (a real overflow
-  indicator) — drop the manual slice and let `maxRows` own it.
+`chartMargin(opts?)` (`basalt-ui/tokens`, also re-exported from `basalt-ui/charts`) still exists,
+but only matters for a bespoke chart that composes `ChartFrame` directly (not `CartesianChart`) and
+needs a right-axis-sized margin without running its own measurement pass — `DualPanel` and `Heatmap`
+don't use it today (neither renders a measured dual numeric axis), so treat it as a fallback, not the
+default path. It returns `VX.margin` widened for `{ rightAxis: true }`, or any side overridden
+directly; returns a new object per call, so memoize it at the call site if you do reach for it.
 
 ## Rule of thumb
 

package/agent/rules/basalt-mantine.md

@@ -114,8 +114,10 @@ Route components import chart primitives directly from `basalt-ui/charts` — ne
   as dead code against the floor.
 - **DatePickerInput**: from `@mantine/dates` (if you separately install it). In v9 it uses string
   values (`YYYY-MM-DD`) for `value`/`onChange` — no `Date` conversion.
-- **Responsive chart sizing**: use `ResponsiveChart` or `useChartSize` from `basalt-ui/charts`
-  (see basalt-charts.md). Never `useElementSize` from `@mantine/hooks` in a chart file (Mantine is
+- **Responsive chart sizing**: charts measure themselves — `CartesianChart`/`ChartFrame` do it,
+  including reserving the legend band, so pass `height` / `aspectRatio` / `fill` and nothing else
+  (see basalt-charts.md). `useChartSize` from `basalt-ui/charts` is for a non-chart box that needs
+  measuring. Never `useElementSize` from `@mantine/hooks` in a chart file (Mantine is
   banned inside `charts/**`), and never raw `@visx/responsive` outside `charts/**`.
 
 ## Strict surfaces & layout primitives