@pond-ts/charts 0.59.0 → 0.60.0

package/API.md

@@ -249,17 +249,17 @@ Types: `UseSnapshotOptions`, `SnapshotSource` (structural — covers
 
 ### Components — layout & axes
 
-| Component                   | Key props                                                                                                                                                             | Purpose                                                                                                                                     | Source                                                 |
-| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
-| `ChartContainer`            | `width`, `range?`, `theme?`, `cursor?`, `panZoom?`, `bounds?`, `showAxis?`, `calendar?`, `origin?`, `maxBandWidth?`/`bandAlign?`, `onTrackerChanged?`, `onDrawStats?` | Root: shared x-scale, interactions, annotations                                                                                             | `packages/charts/src/ChartContainer.tsx`               |
-| `ChartRow`                  | `height`, `cursor?` (deprecated — mount a cursor in the row)                                                                                                          | One stacked plot band; owns its y-axes                                                                                                      | `packages/charts/src/ChartRow.tsx`                     |
-| `Layers`                    | children                                                                                                                                                              | Mandatory z-stack inside a row (back-to-front)                                                                                              | `packages/charts/src/Layers.tsx`                       |
-| `YAxis`                     | `id` (req), `side?`, `scale?` (`'linear'` \| `'log'` \| `'symlog'`), `linearWindow?`, `min?`/`max?`, `format?`, `width?`, `hide?`                                     | Y-axis gutter; layers bind via their `axis` prop                                                                                            | `packages/charts/src/YAxis.tsx`                        |
-| `XAxis`                     | `side?`, `label?`, `format?`, `ticks?`, `transform?`, `dateStyle?`                                                                                                    | Placeable x-axis strip; kind inferred from data                                                                                             | `packages/charts/src/XAxis.tsx`                        |
-| `TimeAxis` / `CategoryAxis` | (XAxis props)                                                                                                                                                         | Thin `XAxis` presets                                                                                                                        | `packages/charts/src/TimeAxis.tsx`, `CategoryAxis.tsx` |
-| `Canvas`                    | `width`, `height`, `draw`                                                                                                                                             | Low-level DPR-aware canvas primitive                                                                                                        | `packages/charts/src/Canvas.tsx`                       |
-| `Selector`                  | `enabled?` (default `true`), `selected?` (mark \| set), `hovered?`, `onSelect?`, `onHover?`, `children?`                                                              | Wraps its scope; mounting enables click-select and owns the state it drives (RFC A10)                                                       | `packages/charts/src/selectors.tsx`                    |
-| `MultiSelector`             | `enabled?`, `selected?`, `hovered?`, `sequence?`, `onSelect?`, `onHover?`, `children?`                                                                                | Sweep-select superset of `Selector`: drag sweeps marks, release reports `(hits, modifiers, spans)` — plural, one per swept layer (RFC A5.2) | `packages/charts/src/selectors.tsx`                    |
+| Component                   | Key props                                                                                                                                                                        | Purpose                                                                                                                                     | Source                                                 |
+| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
+| `ChartContainer`            | `width`, `range?`, `theme?`, `cursor?`, `panZoom?`, `xScale?`, `bounds?`, `showAxis?`, `calendar?`, `origin?`, `maxBandWidth?`/`bandAlign?`, `onTrackerChanged?`, `onDrawStats?` | Root: shared x-scale, interactions, annotations                                                                                             | `packages/charts/src/ChartContainer.tsx`               |
+| `ChartRow`                  | `height`, `cursor?` (deprecated — mount a cursor in the row)                                                                                                                     | One stacked plot band; owns its y-axes                                                                                                      | `packages/charts/src/ChartRow.tsx`                     |
+| `Layers`                    | children                                                                                                                                                                         | Mandatory z-stack inside a row (back-to-front)                                                                                              | `packages/charts/src/Layers.tsx`                       |
+| `YAxis`                     | `id` (req), `side?`, `scale?` (`'linear'` \| `'log'` \| `'symlog'`), `linearWindow?`, `min?`/`max?`, `format?`, `width?`, `hide?`                                                | Y-axis gutter; layers bind via their `axis` prop                                                                                            | `packages/charts/src/YAxis.tsx`                        |
+| `XAxis`                     | `side?`, `label?`, `format?`, `ticks?`, `transform?`, `dateStyle?`                                                                                                               | Placeable x-axis strip; kind inferred from data                                                                                             | `packages/charts/src/XAxis.tsx`                        |
+| `TimeAxis` / `CategoryAxis` | (XAxis props)                                                                                                                                                                    | Thin `XAxis` presets                                                                                                                        | `packages/charts/src/TimeAxis.tsx`, `CategoryAxis.tsx` |
+| `Canvas`                    | `width`, `height`, `draw`                                                                                                                                                        | Low-level DPR-aware canvas primitive                                                                                                        | `packages/charts/src/Canvas.tsx`                       |
+| `Selector`                  | `enabled?` (default `true`), `selected?` (mark \| set), `hovered?`, `onSelect?`, `onHover?`, `children?`                                                                         | Wraps its scope; mounting enables click-select and owns the state it drives (RFC A10)                                                       | `packages/charts/src/selectors.tsx`                    |
+| `MultiSelector`             | `enabled?`, `selected?`, `hovered?`, `sequence?`, `onSelect?`, `onHover?`, `children?`                                                                                           | Sweep-select superset of `Selector`: drag sweeps marks, release reports `(hits, modifiers, spans)` — plural, one per swept layer (RFC A5.2) | `packages/charts/src/selectors.tsx`                    |
 
 ### Components — draw layers
 
@@ -280,7 +280,7 @@ schema columns). Because the union splits per series _kind_, a value typed as
 | Component      | Data props                                                                                                | Purpose                                             | Source                                 |
 | -------------- | --------------------------------------------------------------------------------------------------------- | --------------------------------------------------- | -------------------------------------- |
 | `LineChart`    | `column`, `gaps?`, `sessionBreaks?`                                                                       | Gap-aware line                                      | `packages/charts/src/LineChart.tsx`    |
-| `AreaChart`    | `column`, `baseline?`, `gaps?`                                                                            | Filled area                                         | `packages/charts/src/AreaChart.tsx`    |
+| `AreaChart`    | `column`, `baseline?`, `gaps?`, `thresholds?`/`bandColors?`                                               | Filled area                                         | `packages/charts/src/AreaChart.tsx`    |
 | `BandChart`    | `lower`, `upper`                                                                                          | Variance-band envelope                              | `packages/charts/src/BandChart.tsx`    |
 | `ScatterChart` | `column`, `id?` (selection), radius/color encodings                                                       | Points; data-driven size/colour                     | `packages/charts/src/ScatterChart.tsx` |
 | `BarChart`     | `column` \| `columns` \| `bins` \| `categories`, `orientation?`, `thresholds?`/`bandColors?`              | Bars, stacked bars, histograms, categorical         | `packages/charts/src/BarChart.tsx`     |
@@ -328,10 +328,10 @@ label + data cells, `sortBy`/`sort`, optional per-row expander. The in-plot
 histogram stays `<BarChart orientation="horizontal">` — these are the table
 shape (react-timeseries-charts' `HorizontalBarChart`).
 
-| Component | Data props                                                                           | Purpose                                                             | Source                            |
-| --------- | ------------------------------------------------------------------------------------ | ------------------------------------------------------------------- | --------------------------------- |
-| `BarList` | `rows`, `columns` (`values` names), `sortBy?`, `before?`/`after?`, `renderExpanded?` | Ranked bar list — one proportional bar line per column per row      | `packages/charts/src/BarList.tsx` |
-| `BoxList` | `rows`, `columns` (five-number names + `value?` tick), same table props              | Distribution list — range band / q1→q3 body / median / current tick | `packages/charts/src/BoxList.tsx` |
+| Component | Data props                                                                                         | Purpose                                                             | Source                            |
+| --------- | -------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- | --------------------------------- |
+| `BarList` | `rows`, `columns` (`values` names), `barColors?`, `sortBy?`, `before?`/`after?`, `renderExpanded?` | Ranked bar list — one proportional bar line per column per row      | `packages/charts/src/BarList.tsx` |
+| `BoxList` | `rows`, `columns` (five-number names + `value?` tick), same table props                            | Distribution list — range band / q1→q3 body / median / current tick | `packages/charts/src/BoxList.tsx` |
 
 Row/option types + readers (`packages/charts/src/list.ts`): `ListRow`,
 `ListValue`, `ListCellSpec`, `ListMarker` (reference rule through every row,
@@ -411,6 +411,10 @@ Series shapes (same file): `ChartSeries`, `BandSeries`, `BoxSeries`,
 | `SwatchSpec` / `LegendItemInput`           | Legend swatch vocabulary + explicit-rows input (`<Legend items>`)                                     | `packages/charts/src/swatch.ts`           |
 | `useChartLegend`                           | Headless legend hook: rows (items grouped by chart row) + `hover`/`select` verbs                      | `packages/charts/src/useChartLegend.ts`   |
 | `ChartLegend` / `LegendRow` / `LegendItem` | The hook's return shape (`rows` group `items`; items carry `selected`/`hovered`)                      | `packages/charts/src/useChartLegend.ts`   |
+| `useChartFrame`                            | Resolved plot geometry: plot rect, gutters, x scale, a row's y scales, band slot edges                | `packages/charts/src/useChartFrame.ts`    |
+| `ChartFrame` / `ChartFrameRow`             | The hook's return shape — container x half, plus a row y half that is `null` outside a `<ChartRow>`   | `packages/charts/src/useChartFrame.ts`    |
+| `ChartBands` / `ChartBand`                 | Ordinal slot geometry on a category axis (`count`/`pitch`/`labels`/`at(i)`); `null` on time/value     | `packages/charts/src/useChartFrame.ts`    |
+| `ChartXScale`                              | The union the container's shared x scale resolves to (time / linear / trading / band / elapsed)       | `packages/charts/src/context.ts`          |
 | `LegendPlacement`                          | `'top-left' \| 'top-right' \| 'bottom-left' \| 'bottom-right'`                                        | `packages/charts/src/Legend.tsx`          |
 | `Curve`                                    | Path interpolation: `'linear' \| 'monotone' \| 'natural' \| 'basis' \| 'step'`                        | `packages/charts/src/curve.ts`            |
 | `RadiusEncoding` / `ColorEncoding`         | Data-driven scatter size/colour                                                                       | `packages/charts/src/encoding.ts`         |

package/CHANGELOG.md

@@ -8,7 +8,8 @@ The `@pond-ts` packages — `pond-ts`, `@pond-ts/react`, `@pond-ts/charts`,
 under a single `v*` tag, so this file covers them all. Pre-1.0: minor bumps may
 include new features and type-level changes; patch bumps are strictly additive.
 
-[Unreleased]: https://github.com/pond-ts/pond/compare/v0.59.0...HEAD
+[Unreleased]: https://github.com/pond-ts/pond/compare/v0.60.0...HEAD
+[0.60.0]: https://github.com/pond-ts/pond/compare/v0.59.0...v0.60.0
 [0.59.0]: https://github.com/pond-ts/pond/compare/v0.58.0...v0.59.0
 [0.58.0]: https://github.com/pond-ts/pond/compare/v0.57.0...v0.58.0
 [0.57.0]: https://github.com/pond-ts/pond/compare/v0.56.2...v0.57.0
@@ -62,6 +63,200 @@ include new features and type-level changes; patch bumps are strictly additive.
 
 ## [Unreleased]
 
+## [0.60.0] — 2026-08-13
+
+### Added
+
+- `@pond-ts/charts`: `<AreaChart thresholds>` + `bandColors` — threshold
+  banding along the area's height ([PND-BANDAREA]), the area counterpart of
+  `<BarChart thresholds>`. `n` breakpoints (absolute data values, magnitude-
+  mirrored below zero) make `n + 1` bands; fills resolve `bandColors` → the
+  new `AreaStyle.bands` theme token (the default theme ships the same
+  teal/amber/red ladder as the bar role). One hard-stop pixel-space gradient
+  carries the ladder for the fill **and** the outline, so the value line
+  switches hue exactly at each crossing and the banded area keeps one hit
+  region, one legend row and one readout identity. Composes with `curve`,
+  `gaps` and M4 decimation unchanged; a swept window keeps the band colours
+  (no `spanColor` swap). Ladder resolution + dev warnings shared with
+  `<BarChart>` via one internal hook.
+- **charts: `<ChartContainer xScale="log" | "symlog">` — a logarithmic value x
+  axis** ([#649]). The x counterpart of `<YAxis scale>`, for a quantity spanning
+  orders of magnitude — a power–duration curve is watts against 1s · 5s · 1m ·
+  20m · 3h, which is unreadable on a linear x.
+
+  ```tsx
+  <ChartContainer range={[1, 10800]} xScale="log">
+  ```
+
+  **Why the container and not `<XAxis scale>`**, where the `<YAxis>` mirror would
+  put it: there is one x scale shared by every row and the container builds it,
+  while every `<XAxis>` prop is presentational (`format`, `label`, `side`,
+  `ticks`, `align`, …). `<YAxis>` is the opposite — one scale per axis per row,
+  declared by the axis, which is why `min`/`max`/`pad`/`scale` live there. It
+  sits beside `origin`, `spacing` and `calendar`, which shape the same scale.
+
+  Ignored on a time or category axis. A `'log'` domain reaching zero **falls back
+  to linear and warns** rather than silently clamping — `log(0)` is undefined;
+  use `'symlog'` for data that crosses zero.
+
+  Nothing downstream branches: d3's log scales share the continuous-scale
+  surface, so draw layers are untouched. The tick ladder is the one the y axis
+  already built (`tickValues`, renamed from `yTickValues` now that both axes use
+  it) — d3's raw `scaleLog.ticks()` is nearly a step function.
+
+  [#649]: https://github.com/pond-ts/pond/issues/649
+
+- **charts: `<BarList barColors>` — per-row bar colour** ([#650]). The list's
+  counterpart to `<BarChart binColors>`: `barColors[i]` aligned to the rows you
+  passed, an `undefined` or short entry falling back to the column's `as` /
+  theme fill.
+
+  ```tsx
+  <BarList rows={zones} columns={[{ column: 'frac' }]} barColors={ZONE_RAMP} />
+  ```
+
+  For the case `binColors` was built for and a list could not do — a zone table
+  where each row's bar carries its own step of a ramp. A `BarListColumn`'s
+  single `as` paints every row the same colour, so the ramp had to move onto the
+  row label, putting it on the wrong element: the bar is the natural carrier of
+  a magnitude.
+
+  **Colours key on the row, not its render position**, so they follow the data
+  through a `sortBy` rather than repainting the ramp onto whichever rows now sit
+  in those slots.
+
+  **A per-row colour makes the fill load-bearing, so its state treatment stands
+  down** — a coloured bar keeps its own colour while selected, and shows the
+  state in opacity instead. That is the rule a multi-metric row already
+  followed, and the one `binColors` follows on the canvas: recolouring a bar
+  that means something trades a distinction the reader needs for one the band
+  and rail already give them.
+
+  [#650]: https://github.com/pond-ts/pond/issues/650
+
+- **charts: `<ChartContainer categories>` — the ordinal axis as a
+  container-level choice** ([PND-IGNITECAT]). Declare the slot names on the
+  container and **any value-keyed layer can live on them** — a target line, a
+  point mark or a filled envelope over categorical bars, which was previously
+  not expressible at all.
+
+  The band scale used to be reachable only _through a layer_: `<BarChart
+categories>` and a **horizontal** heat map reported `xKind: 'category'`, every other layer
+  reported `'time'` or `'value'`, and a container throws on a mixed kind. The
+  workaround — key every layer to a synthetic integer index and hand-supply the
+  tick labels — forfeits two features the ordinal axis already implements, and
+  both came back as their own friction entries: `<XAxis>` label thinning (gated
+  on a category axis with no custom ticks) and the `maxBandWidth` / `bandAlign`
+  slot packing. Declaring the categories on the container keeps both.
+
+  The change is small because the scale was already built for it: `scaleBand`'s
+  domain is **numeric** (`[0, n]`, slot `i` at `[i, i+1]`) with a linear pixel
+  mapping, so a `ValueSeries` keyed on slot coordinates already lands where the
+  bars do. **Slot `i`'s centre is `i + 0.5`** — the same number
+  `ScaleBand.ticks()` returns and where `<XAxis>` puts the tick.
+
+  Two things error, deliberately: a **time-keyed layer** (a timestamp has no
+  slot), and a **category layer that disagrees** with the prop in content or
+  order — the prop is authoritative, and a silent mismatch would draw bars
+  under the wrong labels. The pre-existing mixed-kind error now names the prop
+  as the fix.
+
+  Declaring it has two costs, both already true of an inferred category axis
+  and now reachable from a previously-continuous container: **x pan and zoom
+  stop** (`panZoom` keeps working on y), and **`range` stops applying to x**
+  (the domain is `[0, n]` from the slot count, so an x range is a no-op).
+
+  One hazard is documented rather than enforced: **a value-keyed layer is taken
+  at its word**, so a layer whose x means something other than a slot
+  coordinate — a horizontal categorical `<BarChart>`, whose x is bar _length_ —
+  will draw in the wrong place. A guard for that case was written and removed
+  after review: it tested `binCategories`, which is the generic "my _y_ is
+  ordinal" channel that a **vertical heat map** sets for its rows, so it
+  rejected a slot-keyed grid with named columns on x — a wanted layout, since
+  ordinal rows plus ordinal columns is just a 2-D grid. Nothing distinguishes
+  "my x is a coordinate" from "my x is a magnitude", so there is no
+  contradiction to detect.
+
+  `categories={[]}` is an ordinal axis with **no slots yet**, not a fallback to
+  time — so the kind doesn't flip and rebuild every scale when data arrives.
+
+  Omitting `categories` leaves the inferred behaviour exactly as it was.
+
+- **charts: `useChartFrame()` — the resolved plot geometry, published**
+  ([PND-IGNITEFRAME]). A hook returning what the container already worked out:
+  the plot rect (`plot.x` / `plot.width`), the reserved axis `gutters`, the
+  shared `xScale` and its `xKind`, a row's `yScales` and top inset, and — on a
+  category axis — the ordinal slot edges (`bands.at(i)`, `pitch`, `labels`).
+
+  Consumers aligning DOM chrome to the plot (per-slot header tables, column
+  summary strips, cards pinned over a band, a colour ramp keyed to the plot's
+  own scale) previously had to re-derive all of it: pin every axis gutter to a
+  fixed width so it stops depending on label content, measure the outer box,
+  subtract, and re-implement the band packing. **That duplicate is not merely
+  verbose — it is wrong over time.** It holds only until the library changes
+  how a gutter is sized or how bands are packed, at which point the chrome
+  slides out of alignment with the plot it labels, with no type error and no
+  failing test.
+
+  Two shape notes. **The x/y split is the library's own** — the container owns
+  one shared x scale, rows own their y scales — so `plot` carries x and `row`
+  carries y, and `row` is `null` when the hook is called outside a
+  `<ChartRow>`. That `null` is deliberate: the common case (a header strip
+  beside the rows) genuinely has no y geometry, and reporting `height: 0`
+  instead would be the same silent misalignment the hook exists to remove.
+  **Scope follows placement**, exactly as `useChartLegend` already does.
+
+  `useChartLegend`'s `gutters` is unchanged and still the right call for a
+  legend; it now documents `useChartFrame()` as the fuller surface. It was the
+  only geometry the library published, for one consumer, on a hook named for
+  something else — which is why this exists.
+
+- **charts: `<ChartContainer width="auto">` — fill the available width**
+  ([PND-WIDTH]). `width` now accepts `'auto'`, and an omitted `width` means the
+  same; a number still skips the measure pass and paints on the first render.
+  The container renders a plain full-width box, measures it with a
+  `ResizeObserver`, and mounts the chart at that pixel width — the canvas
+  renderer needs real pixels to lay out ticks and slots, so this is measurement
+  moved inside the library rather than a percentage handed to a canvas. Nothing
+  paints until a real width exists.
+
+  This is the shipped
+  [responsive-width recipe](https://pond-ts.github.io/pond/docs/recipes/responsive-width)
+  become the implementation, and it closes that recipe's sharpest edge by
+  construction: the measured box is one the library owns, so it can never be
+  the caller's padded or bordered box (whose border-box width overflowed the
+  chart by exactly the padding, silently clipped when the box also hid
+  overflow). Style your own wrapper freely.
+
+  Two behaviours worth knowing. A container **hidden** by an ancestor's
+  `display: none` keeps the last width it measured and stays mounted, so a tab
+  switch does not discard pan/zoom position, selection or hover — writing the
+  zero measurement through would unmount and rebuild all of it. And `'auto'`
+  needs a parent with a **definite** width: a parent sized by its own content
+  (a float, an `inline-block`, a grid `auto` track, a flex child without
+  `min-width: 0`) measures 0, and the chart is the content that would have
+  given it a width, so the chart stays blank with no error.
+
+  Three independent consumers reported the explicit-pixel requirement; the
+  third was multiplying the same ~25-line measure-and-gate hook across seven
+  panes.
+
+### Changed
+
+- **charts: `ChartContainerProps.width` is now `number | 'auto'` and optional**
+  (was a required `number`). Strictly additive for callers passing a number.
+
+### Fixed
+
+- **charts: value-axis pan and zoom no longer snap to whole integers**
+  (shipped inside [#653]). `panRange`/`zoomRange` were written for a
+  millisecond axis and silently assumed every axis was one, so a value domain
+  of `[0.5, 10800]` snapped its floor to `0` and `[0.001, 1]` collapsed to
+  `[0, 1]` — fatal under a log axis, where `log(0)` is undefined. Gestures now
+  snap only on a **time** axis (`ViewportOptions.snap`), and a log x axis pans
+  by ratio and zooms in log space, keeping the value under the cursor fixed.
+  Time-axis behaviour is unchanged.
+
 ## [0.59.0] — 2026-08-11
 
 ### Added

package/dist/AreaChart.d.ts

@@ -75,6 +75,58 @@ export interface AreaChartCommon<S extends SeriesSchema = SeriesSchema, VS exten
      * `DecimateOption`.
      */
     decimate?: DecimateOption;
+    /**
+     * **Threshold breakpoints** ([PND-BANDAREA]) — colour the area *along its
+     * height* against a ladder, so the fill (and the value line on its top edge)
+     * shows which zone each stretch of the series sits in: low / medium / high
+     * as bands that switch exactly at the breakpoints. Breakpoints are
+     * **absolute data values** in the axis's own units — `[1, 2]` means
+     * "warning above 1, alarm above 2", not offsets from the baseline — and `n`
+     * of them make `n + 1` bands. Each must be finite and greater than zero;
+     * anything else is dropped with a dev warning (the ladder is walked on the
+     * magnitude, so a negative breakpoint is not expressible).
+     *
+     * ```tsx
+     * // neutral to 1, warning 1–2, alarm above 2
+     * <AreaChart series={s} column="value" thresholds={[1, 2]} />
+     * ```
+     *
+     * Band fills come from {@link AreaStyle.bands} on the resolved role
+     * (`theme.area[as] ?? theme.area.default`), overridden by {@link bandColors}.
+     * Breakpoints are data and live here; colour stays in the theme — the same
+     * split `<BarChart thresholds>` uses ([PND-BANDBAR2]), and the same
+     * magnitude-mirrored reading: values below zero (an above/below-axis area
+     * with `baseline={0}`) walk the same ±ladder without negative breakpoints.
+     *
+     * **A banded area is still one area.** One hit region, one legend row, one
+     * readout identity; hover / selection strengthen the fill and keep the band
+     * colours, and a swept window's `spanColor` single-hue swap is skipped for
+     * the same reason the banded bar keeps its own colours — one hue would
+     * erase the very thing the bands encode. The banded fill is **flat** (the
+     * grade to transparent at the baseline is dropped): the fade encoded
+     * distance-from-baseline, which the ladder now states discretely. The
+     * outline strokes in the band hues too, switching exactly at each crossing.
+     *
+     * Composes with `curve`, `gaps` and `decimate` unchanged — banding rides
+     * the paint, not the geometry, so M4 decimation stays on (unlike the bar
+     * envelope, which collapses many bars into one rect and so cannot carry
+     * per-band colour). The inferred gap connectors (`'dashed'` / `'step'` /
+     * `'fade'`) keep the role's line colour: they are guesses about absent
+     * data, and a zone colour would over-claim exactly where nothing was
+     * measured.
+     */
+    thresholds?: readonly number[];
+    /**
+     * Call-site override for the {@link thresholds} band fills — `bandColors[k]`
+     * paints the band above `thresholds[k - 1]`, so a ladder of `n` thresholds
+     * reads `n + 1` entries. Omitted ⇒ {@link AreaStyle.bands} from the theme.
+     *
+     * Prefer the theme for anything a design system owns; this is the escape
+     * hatch for a one-off ladder that shouldn't mint a theme role. If neither
+     * source supplies enough entries, the shortfall falls back to the flat fill
+     * and dev-warns rather than silently drawing an unbanded area.
+     */
+    bandColors?: readonly string[];
     /**
      * This layer's `<Legend>` row: `false` ⇒ no row (opt out), a string ⇒ the
      * row's display name. **Omitted ⇒ a row named by the layer's readout
@@ -151,6 +203,6 @@ export declare function resolveAreaBaseline(baseline: number | undefined, yScale
  * </Layers>
  * ```
  */
-export declare function AreaChart<S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema>({ series, column, readout, as: semantic, axis, id, baseline, curve, gaps, decimate, legend, index, }: AreaChartProps<S, VS>): null;
+export declare function AreaChart<S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema>({ series, column, readout, as: semantic, axis, id, baseline, curve, gaps, decimate, thresholds, bandColors, legend, index, }: AreaChartProps<S, VS>): null;
 export {};
 //# sourceMappingURL=AreaChart.d.ts.map

package/dist/AreaChart.js

@@ -9,6 +9,7 @@ import { DEFAULT_GAP_MODE, DEFAULT_GAP_CONNECTOR_OPACITY, } from './gaps.js';
 import { ContainerContext, LayersContext, } from './context.js';
 import { legendLabelFor, useLegendItems, } from './swatch.js';
 import { useSlotKey } from './use-slot-key.js';
+import { useBandLadder } from './use-band-ladder.js';
 /** Read a d3 linear scale's domain lower bound (the axis floor) from the plain
  *  `(value) => pixel` function the row hands to `draw`. The runtime object is a
  *  d3 `ScaleLinear` (it carries `.domain()`); the {@link RowLayer} type narrows
@@ -56,7 +57,7 @@ function domainFloor(yScale) {
  * </Layers>
  * ```
  */
-export function AreaChart({ series, column, readout, as: semantic, axis, id, baseline, curve, gaps = DEFAULT_GAP_MODE, decimate = true, legend, index = 0, }) {
+export function AreaChart({ series, column, readout, as: semantic, axis, id, baseline, curve, gaps = DEFAULT_GAP_MODE, decimate = true, thresholds, bandColors, legend, index = 0, }) {
     const container = useContext(ContainerContext);
     if (container === null) {
         throw new Error('<AreaChart> must be rendered inside a <ChartContainer>');
@@ -87,6 +88,11 @@ export function AreaChart({ series, column, readout, as: semantic, axis, id, bas
     // Styling: semantic identifier → theme area style. The single styling channel.
     const { area } = container.theme;
     const style = (semantic !== undefined ? area[semantic] : undefined) ?? area.default;
+    // ── Threshold ladder ([PND-BANDAREA]) — breakpoints normalized + paired
+    // with `bandColors` → the role's `AreaStyle.bands` in the shared
+    // {@link useBandLadder} (one contract with `<BarChart thresholds>`,
+    // including every dev warning).
+    const bandLadder = useBandLadder('AreaChart', thresholds, bandColors, style.bands, style.fill);
     // Series identity for the readout (the `as` role, else the column name).
     const label = semantic ?? column;
     const curveFactory = resolveCurve(curve);
@@ -249,7 +255,13 @@ export function AreaChart({ series, column, readout, as: semantic, axis, id, bas
                     strokeSpanEdges(ctx, [xScale(spanX[0]), xScale(spanX[1])], ctx.canvas.height, container.theme.annotation?.spanEdge ?? '#f0b26b');
                 const [outStyle, outAlpha] = areaStateStyle(style, 'dimmed');
                 const [inStyle] = areaStateStyle(style, 'selected');
-                return drawPartitioned(ctx, [xScale(spanX[0]), xScale(spanX[1])], plotExtentOf(ctx, xScale, yScale).height, fill(outStyle, outAlpha), fill(style.spanColor === undefined || !soleSpannedTrace
+                return drawPartitioned(ctx, [xScale(spanX[0]), xScale(spanX[1])], plotExtentOf(ctx, xScale, yScale).height, fill(outStyle, outAlpha), fill(
+                // A banded area skips the window's single-hue swap: one hue
+                // would erase the very thing the bands encode (the banded bar's
+                // rule), so the window strengthens and keeps the ladder.
+                style.spanColor === undefined ||
+                    !soleSpannedTrace ||
+                    bandLadder !== undefined
                     ? inStyle
                     : { ...inStyle, color: style.spanColor, fill: style.spanColor }, 1), true, 0, plotExtentOf(ctx, xScale, yScale).width);
                 function drawAreaWith(st) {
@@ -262,7 +274,7 @@ export function AreaChart({ series, column, readout, as: semantic, axis, id, bas
                     // `NaN` and poison every coordinate in the fill path. Fall back
                     // to the axis floor, which is exactly what an omitted baseline
                     // already resolves to.
-                    resolveAreaBaseline(baseline, yScale), curveFactory, gaps, gapConnectorOpacity, decimate);
+                    resolveAreaBaseline(baseline, yScale), curveFactory, gaps, gapConnectorOpacity, decimate, bandLadder);
                 }
             },
         },
@@ -281,6 +293,7 @@ export function AreaChart({ series, column, readout, as: semantic, axis, id, bas
         gaps,
         gapConnectorOpacity,
         decimate,
+        bandLadder,
         axis,
         id,
         traceState,

package/dist/BarChart.js

@@ -1,8 +1,9 @@
 import { useContext, useEffect, useMemo } from 'react';
 import { Interval, ValueSeries } from 'pond-ts';
 import { barsFromTimeSeries, barsFromBins, barsFromValueSeries, categoryStack, categoryStacks, stacksFromBins, stacksFromColumns, stacksFromGroups, } from './data.js';
-import { barAt, barExtent, barIndexAtTime, drawBars, drawStacks, normalizeThresholds, resolveBarBaseline, stackAt, stackBinExtent, stackValueExtent, } from './bars.js';
+import { barAt, barExtent, barIndexAtTime, drawBars, drawStacks, resolveBarBaseline, stackAt, stackBinExtent, stackValueExtent, } from './bars.js';
 import { spansForLayer } from './span.js';
+import { useBandLadder } from './use-band-ladder.js';
 import { isDev } from './dev.js';
 import { ContainerContext, LayersContext, } from './context.js';
 import { sweep1D } from './sweep.js';
@@ -278,66 +279,10 @@ export function BarChart({ series, bins, categories, column, columns, as: semant
         ? { ...singleStyle, maxWidth: maxBarWidth }
         : singleStyle, [singleStyle, maxBarWidth]);
     // ── Threshold ladder ([PND-BANDBAR2]) ────────────────────────────────────
-    // Resolved once here rather than per bar per frame: normalize the breakpoints
-    // (sort, drop non-finite), then pair them with `bandColors` → the role's
-    // `BarStyle.bands`. Everything that can go wrong with the pairing is a
-    // *silent* wrong-looking chart, so each case dev-warns — this feature exists
-    // because a quietly-unbanded bar was the workaround's failure mode.
-    // Value-compare the two array props rather than relying on their identity.
-    // `thresholds={[1, 2]}` inline is the documented usage and the shape every
-    // story and doc example uses — and a fresh array each render would rebuild
-    // the ladder, hence the layer `entry` below, hence a `registerLayer` call
-    // **every render**. That is a repaint treadmill, not just a noisy warning.
-    // The same value-compare-on-registration reasoning `<YAxis ticks>` already
-    // applies.
-    const thresholdKey = thresholds === undefined ? '' : thresholds.join(',');
-    const bandColorKey = bandColors === undefined ? '' : bandColors.join(',');
-    const bandLadder = useMemo(() => {
-        const steps = normalizeThresholds(thresholds);
-        if (steps === null) {
-            if (isDev && thresholds !== undefined && thresholds.length > 0) {
-                console.warn('<BarChart thresholds>: no usable breakpoints, so no banding was ' +
-                    'applied — each must be finite and greater than zero. Bars draw ' +
-                    'in the flat fill.');
-            }
-            return undefined;
-        }
-        // Some, but not all, entries dropped. Silently banding on a subset of what
-        // the caller wrote is exactly the class of quiet wrongness this feature is
-        // meant to remove, so say so.
-        if (isDev && thresholds !== undefined && steps.length < thresholds.length) {
-            console.warn(`<BarChart thresholds>: dropped ${thresholds.length - steps.length} ` +
-                'breakpoint(s) that were not finite and greater than zero. The ' +
-                'ladder is walked on the magnitude and mirrored onto whichever side ' +
-                'of zero a bar is on, so a negative breakpoint has no meaning; ' +
-                `banding on [${steps.join(', ')}].`);
-        }
-        const want = steps.length + 1;
-        const supplied = bandColors ?? singleStyle.bands;
-        if (supplied === undefined || supplied.length === 0) {
-            if (isDev) {
-                console.warn(`<BarChart thresholds>: ${steps.length} breakpoint(s) need ${want} ` +
-                    'band colours, but neither `bandColors` nor the theme role’s ' +
-                    '`BarStyle.bands` supplies any. Bars draw in the flat fill.');
-            }
-            return undefined;
-        }
-        if (supplied.length < want && isDev) {
-            console.warn(`<BarChart thresholds>: ${steps.length} breakpoint(s) need ${want} ` +
-                `band colours but only ${supplied.length} were supplied; bands ` +
-                'above the last colour fall back to the flat fill.');
-        }
-        // Pad a short ladder with the flat fill so the draw path can index freely.
-        const resolved = supplied.length >= want
-            ? supplied.slice(0, want)
-            : [
-                ...supplied,
-                ...Array.from({ length: want - supplied.length }, () => singleStyle.fill),
-            ];
-        return { thresholds: steps, colors: resolved };
-        // eslint-disable-next-line react-hooks/exhaustive-deps -- `thresholdKey` /
-        // `bandColorKey` are the value-compared stand-ins for the array props.
-    }, [thresholdKey, bandColorKey, singleStyle]);
+    // Breakpoints normalized + paired with `bandColors` → the role's
+    // `BarStyle.bands` in the shared {@link useBandLadder} (one contract with
+    // `<AreaChart thresholds>`, including every dev warning).
+    const bandLadder = useBandLadder('BarChart', thresholds, bandColors, singleStyle.bands, singleStyle.fill);
     // Conflicts between the ladder and the shapes it can't apply to. In an effect
     // so a re-render doesn't re-log; each fires once per genuinely new pairing.
     const multiGroup = shape.kind === 'stacked' && shape.ss.groups.length > 1;

package/dist/BarList.d.ts

@@ -69,6 +69,28 @@ export interface BarListCommon<R extends ListRow = ListRow> {
     selected?: string | readonly string[] | null;
     /** Row click (rows show the pointer affordance only when provided). */
     onRowClick?: (row: R) => void;
+    /**
+     * Per-**row** bar colour, `barColors[i]` aligned to the rows in order — the
+     * list's `<BarChart binColors>` ([#650]). An `undefined` or short entry falls
+     * back to the column's `as` / theme fill, so a partial list is legal.
+     *
+     * For the case `binColors` was built for and a list could not do: a zone
+     * table where each row's bar carries its own step of a ramp (Z1 deep → Z7
+     * pale). Without it a `BarListColumn`'s single `as` paints every row the same
+     * colour, and the ramp has to move onto the label — putting it on the wrong
+     * element, since the bar is the natural carrier of a magnitude.
+     *
+     * **The fill becomes load-bearing, so its state treatment stands down.** A
+     * per-row-coloured bar keeps its own colour while selected or hovered, and
+     * the live state is carried by the band and rail that already say it. This is
+     * the same rule the multi-metric case follows for the same reason — see the
+     * comment beside the fill resolution — and the same one `binColors` follows
+     * on the canvas: recolouring a bar that means something would trade a
+     * distinction the reader needs for one they already have.
+     *
+     * [#650]: https://github.com/pond-ts/pond/issues/650
+     */
+    barColors?: readonly (string | undefined)[];
     /**
      * **Plural select** — the list's answer to `<MultiSelector>`, and how a user
      * produces a multi-row {@link selected}.

package/dist/BarList.js

@@ -36,7 +36,7 @@ export function BarList(props) {
     // One normalized view of the union — `isSeriesSource` is the runtime
     // narrowing; the doors are mutually exclusive by construction now.
     const source = props;
-    const { rows, series, label, columns, domain, sortBy, sortDirection = 'desc', sort, before, after, renderExpanded, defaultExpanded, onExpandToggle, selected, onRowClick, onRowSelect, hovered, onHover, markers, barHeight = 8, divided, baseline, theme = defaultTheme, } = source;
+    const { rows, series, label, columns, domain, sortBy, sortDirection = 'desc', sort, before, after, renderExpanded, defaultExpanded, onExpandToggle, selected, onRowClick, onRowSelect, barColors, hovered, onHover, markers, barHeight = 8, divided, baseline, theme = defaultTheme, } = source;
     // A runtime guard for JS consumers and `any`-typed call sites — the
     // props union makes both branches unreachable from typed TS, but a
     // silently-ignored source prop is a worse failure than a throw.
@@ -49,6 +49,21 @@ export function BarList(props) {
         (series instanceof ValueSeries
             ? listRowsFromValueSeries(series, label !== undefined ? { label } : {})
             : listRowsFromTimeSeries(series, label !== undefined ? { label } : {})), [rows, series, label]);
+    // Keyed by row, not indexed by render position. `barColors` aligns to the
+    // rows the caller passed — but the table renders `sorted`, so an index would
+    // silently repaint the ramp onto the wrong rows the moment `sortBy` is set.
+    // The key survives any reordering.
+    const barColorOf = useMemo(() => {
+        if (barColors === undefined)
+            return null;
+        const m = new Map();
+        allRows.forEach((r, i) => {
+            const c = barColors[i];
+            if (c !== undefined)
+                m.set(r.key, c);
+        });
+        return m;
+    }, [barColors, allRows]);
     const sorted = useMemo(() => sortListRows(allRows, sortBy, sortDirection, sort), [allRows, sortBy, sortDirection, sort]);
     const scale = useMemo(() => resolveListDomain(allRows, columns.map((c) => c.column), domain, markers?.map((m) => m.value)), [allRows, columns, domain, markers]);
     const resolvedMarkers = useMemo(() => markers?.map((m) => ({
@@ -68,17 +83,35 @@ export function BarList(props) {
                 // Which is also why nothing below may be the *only* signal: strip
                 // this block and a selected row still reads as selected.
                 const soleMetric = columns.length === 1;
-                const fill = state.selected && soleMetric
-                    ? style.highlight
-                    : state.dimmed
-                        ? (style.dimmed ?? style.fill)
-                        : style.fill;
+                // A per-row colour makes the fill mean something, which puts it in
+                // exactly the position a multi-metric row's fill is already in: the
+                // state treatment stands down rather than trading a distinction the
+                // reader needs for one the band and rail already give them. Same
+                // rule `binColors` follows on the canvas.
+                const own = barColorOf?.get(row.key);
+                const fill = own !== undefined
+                    ? own
+                    : state.selected && soleMetric
+                        ? style.highlight
+                        : state.dimmed
+                            ? (style.dimmed ?? style.fill)
+                            : style.fill;
                 // A `dimmed` token carries its own alpha (`rgba(…,0.32)`), so
                 // multiplying `opacity` on top of it would dim twice. Fall back to
                 // the raw 0.32 only when the theme names no dimmed colour.
-                const fillOpacity = state.dimmed && style.dimmed === undefined
-                    ? style.opacity * 0.32
-                    : style.opacity;
+                // Opacity is where a coloured bar shows its state, since its hue
+                // is spoken for. A `dimmed` THEME token carries its own alpha so
+                // multiplying on top would dim twice — but that token is not in
+                // play for a per-row colour, so the raw 0.32 applies there too.
+                const fillOpacity = own !== undefined
+                    ? state.dimmed
+                        ? style.opacity * 0.32
+                        : state.selected
+                            ? 1
+                            : style.opacity
+                    : state.dimmed && style.dimmed === undefined
+                        ? style.opacity * 0.32
+                        : style.opacity;
                 return (_jsxs("div", { "data-list-track": col.column, style: {
                         position: 'relative',
                         height: barHeight,