@pond-ts/charts 0.58.0 → 0.60.0

package/CHANGELOG.md

@@ -8,7 +8,9 @@ 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.58.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
 [0.56.2]: https://github.com/pond-ts/pond/compare/v0.56.1...v0.56.2
@@ -61,6 +63,342 @@ 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
+
+- **charts: `<YAxis scale="symlog">` — linear through zero, logarithmic beyond**
+  ([PND-SYMLOG]). The third `scale` kind, for a **diverging** measure spanning
+  orders of magnitude on both sides of zero. `scale="log"` cannot express that
+  domain at all (no zero, no negatives) and `scale="linear"` flattens everything
+  outside the top decade onto the axis line — so the small and mid-range values,
+  usually the finding, become unreadable.
+
+  The knee is set by the new **`linearWindow`** prop as a _fraction of the
+  domain's largest magnitude_ (default `0.02`): on a ±1M domain the axis is
+  linear through ±20k and logarithmic beyond. Relative rather than absolute so
+  it survives a domain change with no arithmetic at the call site. Values are
+  strictly monotonic across the knee, and zero has a real position. A fraction
+  outside `(0, 1]` is unusable as a knee, so the axis draws with the default and
+  dev-warns which window is in force.
+
+  **The tick ladder is pond's, not d3's.** `scaleSymlog` supplies the transform
+  but ticks it _linearly_, which puts every label in the top decade and none in
+  the linear window the scale exists to open up. `<YAxis scale="symlog">` grids
+  zero, ±the knee, and mirrored decades beyond it, thinned to the tick budget
+  the same way the log path thins its decades, clipped to the domain. When
+  `linearWindow` swallows the domain there is nothing left to grid
+  logarithmically, and the axis defers to the linear ticks — which is correct,
+  not a fallback: inside the knee, symlog _is_ linear.
+
+  It removes a workaround whose cost was **silence**: pre-transforming values
+  into a ±1 plot space with a linear axis pinned to `[-1, 1]` leaves tick
+  positions in plot space while their labels must read in real units, so
+  computing the two by different routes yields a chart that confidently labels
+  positions it does not occupy — no exception, no visual artifact.
+
+  **If you are replacing a hand-rolled curve, the shape will shift.** `symlog` is
+  the single smooth `sign(x) · log1p(|x / knee|)`, not two joined segments; a
+  hand-rolled curve that is exactly linear below the knee and `log10` above is the
+  same family with a different shape. Migrating one, a consumer measured small
+  values at **roughly half** their former height (on a ±9M domain, 283k moved from
+  0.44 to 0.24 of the half-plot above the zero line) with order, tail dominance and
+  the several-fold lift over a linear axis all preserved. No `linearWindow` recovers the piecewise shape — the
+  difference is the curve, not the knee.
+
+- **charts: `<BarChart maxBarWidth>` — cap a bar's ink independently of its slot**
+  ([PND-BARWIDTH]). Applied after the `gap` inset and centred in the slot, with
+  `theme.bar[as].maxWidth` as the fallback (the same relationship `gap` has) and
+  uncapped when neither is set.
+
+  It is the **absolute** half of the width vocabulary. `gap` is _relative_, so
+  with it alone bar width is always `slot - gap` and fattens as the plot widens
+  — and a fixed ink width is what makes a measure comparable **between** panes,
+  since bars that widen with their pane read as different weights of the same
+  thing. Neither existing spelling expresses "spread the slots, pin the bar":
+  `maxBandWidth = barWidth + gap` pins the bar but stops the slots spreading,
+  and `maxBandWidth = slotCap` spreads them but lets the bar grow. The
+  workaround was to compute `gap` from the band width you predicted the library
+  would pick — a re-derivation of pond's layout arithmetic in consumer code,
+  which goes silently wrong the moment that rule changes on either side.
+
+  Pairs with `<ChartContainer maxBandWidth>` (which caps the **slot**) and
+  `minWidth` still wins if the two bounds would invert. **A single-series bar's
+  hit target stays its whole slot**, so narrow ink costs nothing in clickability;
+  on a **stacked** chart the cap does narrow the target, because a stack must
+  hit-test its drawn segment rect to resolve which segment.
+
+- **charts: `<BarChart categories columns>` — a first-class stacked category
+  chart** ([PND-CATSTACK]). Each datum is `{ label, values }` and `columns`
+  names the groups to stack bottom → top, the same relationship
+  `series` + `columns` already has. New `categoryStacks` reader and
+  `CategoryStackDatum` type; geometry, `marks` and the categorical axis are
+  unchanged from the single-value case, so this reaches the shipped
+  `drawStacks` path with no new draw code. A missing or non-finite group reads
+  as a **gap**, not a zero.
+
+  **It removes a workaround with three costs**, the third only visible since
+  0.58.0: composing the picture from one `categories` layer per _cumulative
+  total_ (drawn outermost-first so each overpaints the one beneath) meant a
+  hand-assembled legend, label thinning blind to the sibling layers, and — because
+  a selection entry keys on `(layer id, mark)` — a controlled set replicated
+  across every segment layer, where missing one made a selected bar recede
+  **from the waist up**. Because `marks` is indexed by **bin**, one entry naming
+  `(id, mark)` now matches every segment of a bar, so that failure is not
+  expressible rather than merely fixed.
+
+### Fixed
+
+- **charts: a selected segment of a stack with `colors` no longer collapses to
+  the flat `highlight`.** `StackStyle.groupColored` — the "a selected segment
+  keeps its own fill" exclusion — was gated on the _theme ramp_ having painted
+  the stack, so a call site passing `colors` lost it and both segments of a
+  selected bar went one `highlight` blue, losing the segment distinction exactly
+  where the reader is looking. The gate's stated reason ("a ramp entry the call
+  site overrode is no longer the ramp's colour, so its receded counterpart would
+  be wrong") applies to the _derived_ companions `dimmedFills` / `hoverFills`,
+  which must invent a per-group colour; `groupColored` derives nothing. It now
+  gates on **whether the resolved fills actually differ**, so a `colors` map keeps
+  its colours under selection, while a multi-group stack under a theme that gives
+  its groups no distinct colours at all (no ramp, no roles, no `colors` — e.g.
+  `estelaTheme`) still takes the themed `highlight`, because there is no
+  meaning-carrying colour there to preserve and suppressing the highlight would
+  leave selection invisible. Found building [PND-CATSTACK], where the old gate made
+  the first-class stack render _worse_ under selection than the workaround it
+  replaces; the second half was found in review, since every story and test renders
+  `defaultTheme`, whose ramp hides the difference.
+
+- **all packages: `API.md` now ships inside the npm tarball.** The agent-facing
+  map of every public export across the six packages — one line per export with
+  its purpose and source path — was repo-only, so an agent working in a
+  _consuming_ repo had to crawl `node_modules/*/dist/*.d.ts` or go to the
+  network to learn the surface. It is now copied in by each package's existing
+  `prepack` (the same mechanism that already ships `README`, `LICENSE` and
+  `CHANGELOG`) and listed in `files`. ~69kB per tarball.
+
+  Every package carries the same **monorepo-wide** copy rather than a
+  per-package slice, deliberately: the packages compose, and knowing what is
+  next door is most of the value. The header now names its audience and
+  resolves repo-relative source paths against GitHub, since inside
+  `node_modules` a bare `packages/core/src/…` points nowhere.
+
+- **charts: `BarStyle.dimmed`'s precedence over per-bar and per-band colour is
+  documented, and pinned.** A consumer migrating onto 0.58.0 read
+  `BarStyle.hover`'s documented `binColors` exclusion ("pops each bar's _own_
+  fill"), reasonably generalized it to `dimmed`, concluded their `binColors` and
+  `thresholds` charts would get no de-emphasis, and was about to hand-dim inside
+  their own colour arrays. The opposite is true: **an unselected bar takes
+  `dimmed`, discarding its per-bar colour, and a banded bar draws flat rather
+  than dimming each band.** The asymmetry is deliberate — emphasis preserves a
+  per-bar colour because that colour is what the value means, while a receded
+  bar's job is to stop competing over meaning — but only `hover` said anything,
+  so generalizing was the natural read. `dimmed` now spells out all three paths
+  (`binColors`/`binFills`, bands/thresholds, and the per-group stack fallback
+  through `StackStyle.dimmedFills`), `hover` scopes its exclusion to the live
+  states, and three tests pin the behaviour.
+
+- **charts: the `theme.list` register no longer reads as if it carries
+  `dimmed`.** Its doc mentioned `highlight`/`dimmed` while explaining that a
+  list resolves glyph state through the bar tokens — accurate, but sitting in a
+  sentence about per-metric resolution it read as a field list, and cost the
+  same consumer a couple of passes to rule out a missing `list.dimmed`. Now
+  states explicitly that those are `BarStyle` tokens resolved via
+  `theme.bar[as]`, and that this register carries exactly its five values.
+
 ## [0.58.0] — 2026-08-10
 
 ### 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.d.ts

@@ -1,6 +1,6 @@
 import { ValueSeries } from 'pond-ts';
 import type { SeriesSchema, TimeSeries, ValueSeriesSchema } from 'pond-ts';
-import { type BinRecord, type CategoryDatum } from './data.js';
+import { type BinRecord, type CategoryDatum, type CategoryStackDatum } from './data.js';
 import { type Orientation } from './bars.js';
 import type { NumericColumn, ValueNumericColumn } from './column-names.js';
 import type { DecimateOption } from './decimate.js';
@@ -43,11 +43,17 @@ import type { DecimateOption } from './decimate.js';
  *   `<ChartContainer origin>` does not rescue it: it relabels a value axis but
  *   does not re-ladder it.
  * - **`categories`** — an ordered `{ label, value }[]`, one bar per category.
- *   Takes **no** `column`/`columns` (each datum carries its own value).
- *   Vertical puts the categories on the ordinal **x** axis (the container's
- *   band scale); `orientation="horizontal"` puts them on **y** as unit slots
- *   and the value on x, and a `<YAxis>` with no explicit `ticks` labels one
- *   per category automatically ([PND-HCAT]).
+ *   Takes no `column`. Vertical puts the categories on the ordinal **x** axis
+ *   (the container's band scale); `orientation="horizontal"` puts them on **y**
+ *   as unit slots and the value on x, and a `<YAxis>` with no explicit `ticks`
+ *   labels one per category automatically ([PND-HCAT]).
+ * - **`categories` + `columns`** — a **stacked** category chart
+ *   ([PND-CATSTACK]): each datum is `{ label, values }` and `columns` names the
+ *   groups to stack, bottom → top. The same relationship `series` + `columns`
+ *   already has, so a category stack is now a first-class shape rather than one
+ *   `categories` layer per cumulative total. One layer means one `mark` per
+ *   bar, so **one selection entry lights the whole bar** and the composed
+ *   workaround's per-layer replication is unnecessary.
  *
  * **Live charts:** `series.byValue(…)` / `.toMap()` mint fresh objects each
  * call, so an inline `series={…}` re-registers this layer every render — on a
@@ -95,6 +101,12 @@ type BarChartSource<S extends SeriesSchema = SeriesSchema, VS extends ValueSerie
     bins?: never;
     column?: never;
     columns?: never;
+} | {
+    categories: readonly CategoryStackDatum[];
+    columns: readonly string[];
+    series?: never;
+    bins?: never;
+    column?: never;
 };
 /** The props every {@link BarChartSource} mode shares. */
 export interface BarChartCommon<S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema> {
@@ -230,6 +242,43 @@ export interface BarChartCommon<S extends SeriesSchema = SeriesSchema, VS extend
      * would invert collapses to the style's `minWidth`.
      */
     gap?: number;
+    /**
+     * Cap on a bar's **ink** width in px — applied after the `gap` inset and
+     * centred in its slot ([PND-BARWIDTH]). **Omitted ⇒ the theme's `bar`
+     * `maxWidth`, and uncapped if that is unset too** (a bar is `slot - gap`
+     * wide, as it always was).
+     *
+     * This is the *absolute* half of the width vocabulary. `gap` is **relative**,
+     * so with it alone bar width is always `slot - gap` and fattens as the plot
+     * widens; a fixed ink width is what makes a measure comparable **between**
+     * panes, since bars that widen with their pane read as different weights of
+     * the same thing.
+     *
+     * Pairs with `<ChartContainer maxBandWidth>`: that caps the **slot** (how far
+     * the bars spread), this caps the **ink** inside whatever slot results. The
+     * two are independent, which is the point — neither spelling alone expresses
+     * "spread the slots, pin the bar":
+     *
+     * - `maxBandWidth = barWidth + gap` pins the bar but stops the slots
+     *   spreading;
+     * - `maxBandWidth = slotCap` spreads them but lets the bar grow.
+     *
+     * `theme.bar[as].minWidth` still wins if the two bounds would invert, so the
+     * rect can never flip.
+     *
+     * **On a stacked chart the cap narrows the hit target too**, because a stack
+     * hit-tests its drawn segment rect (it must, to resolve *which* segment).
+     * A single-series bar is unaffected: it hit-tests its whole slot, so the ink
+     * can be narrow while the target stays full width.
+     *
+     * That holds in **both orientations**, and costs a deliberate guard to keep:
+     * a single-series *horizontal* chart shares the oriented draw/hit path with
+     * stacks, so the cap is withheld from its hit rect explicitly (`groups.length >
+     * 1`). Vertical charts get it for free — `barSlotRect` takes no cap. Don't
+     * "simplify" that guard away: the rule follows from segment disambiguation,
+     * which is a property of a stack, not of an axis.
+     */
+    maxBarWidth?: number;
     /**
      * **M4 column decimation** (charts decimator wave). **Omitted ⇒ `true`**: once
      * the visible bars are denser than ~2 per device pixel (each slot < ~1px), the
@@ -319,6 +368,6 @@ export type BarChartProps<S extends SeriesSchema = SeriesSchema, VS extends Valu
  * </Layers>
  * ```
  */
-export declare function BarChart<S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema>({ series, bins, categories, column, columns, as: semantic, colors, binColors, thresholds, bandColors, orientation, ordinal, id, axis, gap, decimate, legend, index, }: BarChartProps<S, VS>): null;
+export declare function BarChart<S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema>({ series, bins, categories, column, columns, as: semantic, colors, binColors, thresholds, bandColors, orientation, ordinal, id, axis, gap, maxBarWidth, decimate, legend, index, }: BarChartProps<S, VS>): null;
 export {};
 //# sourceMappingURL=BarChart.d.ts.map