@pond-ts/charts 0.55.0 → 0.57.0

package/CHANGELOG.md

@@ -8,7 +8,11 @@ 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.55.0...HEAD
+[Unreleased]: https://github.com/pond-ts/pond/compare/v0.57.0...HEAD
+[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
+[0.56.1]: https://github.com/pond-ts/pond/compare/v0.56.0...v0.56.1
+[0.56.0]: https://github.com/pond-ts/pond/compare/v0.55.0...v0.56.0
 [0.55.0]: https://github.com/pond-ts/pond/compare/v0.54.0...v0.55.0
 [0.54.0]: https://github.com/pond-ts/pond/compare/v0.53.1...v0.54.0
 [0.53.1]: https://github.com/pond-ts/pond/compare/v0.53.0...v0.53.1
@@ -56,6 +60,289 @@ include new features and type-level changes; patch bumps are strictly additive.
 
 ## [Unreleased]
 
+## [0.57.0] — 2026-08-07
+
+### Added
+
+- **charts: `<Zone>` — a shaded y-span annotation.** The fourth annotation
+  mark, and the value-axis counterpart of `<Region>`: a band between two y
+  values, spanning the full plot width. The mark for a **classification of the
+  value axis** — US EPA AQI categories, heart-rate / power zones, SLO bands,
+  control-chart spec limits — where a reading only means something read against
+  a scale.
+
+  ```tsx
+  {
+    AQI_CATEGORIES.map((c) => (
+      <Zone key={c.role} from={c.from} to={c.to} axis="aqi" role={c.role} />
+    ));
+  }
+  ```
+
+  Colour comes from `theme.annotation.roles[role]`, so a zone _set_ styles as
+  one palette in the theme rather than N colours at the call site. Bounds are
+  order-free, clamped to the plot (a band past the axis domain is cut, one
+  fully outside culls), and accept `±Infinity` for genuinely open-ended bands
+  (`to={Infinity}` — AQI's "Hazardous", a `ZoneTime.openEnded` zone), so a
+  whole category table can be rendered and the axis decides what shows.
+
+  Three defaults deliberately **invert** the rest of the annotation family,
+  because a zone spans the full width and a set tiles the row:
+  `selectable={false}` (else every mousemove lights a band and its hit area
+  eats the plot's clicks), `edges={false}` (contiguous sets share every
+  interior boundary — edges-on draws each twice), and no auto-label (the bounds
+  are already legible on the y axis; the useful label is a name). `<Zone>` has
+  no `onChange` — drag-to-edit zones await a consumer.
+
+  Guide: [From a CSV to a banded chart](https://pond-ts.org/docs/how-to-guides/air-quality-bands).
+
+- **charts: `annotation.dash` — an optional dash pattern for the annotation
+  register**, per-register or per-role (`{ color, fillOpacity?, dash? }`), same
+  shape as `LineStyle.dash`. Applies to marker / baseline lines and region /
+  zone boundaries; fills are never dashed. A dashed reference line reads as
+  _placed_ rather than _measured_ — the job the annotation register exists to
+  do, and one colour alone can't always carry.
+
+- **charts: threshold-banded bars** — `<BarChart thresholds={[1, 2]}>` colours
+  one bar **along its length** against a ladder (neutral → warning → alarm), so
+  a long bar shows how far through the ladder it travelled rather than only
+  which band it ended in. Band fills come from the new
+  **`BarStyle.bands`** on the resolved theme role, overridable per chart with
+  **`<BarChart bandColors>`** — breakpoints are data, colour stays in the theme,
+  the same split `colors` already applies to a stack's group fills.
+
+  The shape was previously expressible as N `<BarChart>` layers drawn
+  outermost-first, each clipped to a band, compositing the gradient by
+  overpainting. That produces the same pixels and loses what matters: N layers
+  means N hit targets, N `SelectInfo.mark` identities and N legend rows for
+  something the reader sees as one bar. Banding is **draw-only** — the hit rect
+  is untouched, so a banded bar stays one bar. It also measures **27–49%
+  cheaper** than the layered workaround at 8–400 categories
+  (`scripts/perf-bandbar.mjs`, which interleaves the arms and prints the
+  ratios), and costs nothing when unused.
+
+  Applies to any single-value bar — `series`, `bins`, `categories`, both
+  orientations. Negatives band symmetrically on the magnitude, so a ± diverging
+  scale needs no negative breakpoints. Ignored (with a dev warning) on a
+  multi-group stack, and yields to `binColors` when both are set. Suppresses
+  envelope decimation for the same reason `binColors` does.
+
+- **charts: `<YAxis hide>`** — keep the scale, draw no gutter, reserve no
+  width. A `<YAxis>` does two jobs — it _holds the scale_ (`min`/`max`/`scale`/
+  `pad`) and it _renders a gutter_ — and there was no way to ask for the first
+  without the second. A caller could express "auto domain, no gutter" (omit the
+  axis) or "explicit domain, with a gutter", but not the pairing a fixed-domain
+  chart needs. Omitting the axis is not equivalent: the row supplies an implicit
+  auto-domain axis, which is exactly what must not be given up. `width={0}`
+  isn't either — the labels still draw, over the plot.
+
+  Gridlines are unaffected: they belong to the plot, not the gutter, and
+  `<ChartContainer grid>` already governs them.
+
+- **charts: `<ChartContainer maxBandWidth>` + `bandAlign`** — cap the **slot
+  pitch** on a category x axis and place the resulting block
+  (`'start'` (default) / `'center'` / `'end'`). A band scale otherwise spreads
+  its categories across the full plot width, so three categories in a 900px
+  panel become three 300px bars and thirty become thirty 30px ones — the same
+  chart in the same panel reading as two different charts depending on how many
+  categories the data returned. Fine for a fixed domain; wrong for a **live**
+  one, where bar width becomes a variable that moves on its own and a reader
+  can't compare the chart to itself a minute ago.
+
+  `maxBandWidth` caps the **slot**; `<BarChart gap>` still insets the bar
+  within it — one knob for pitch, one for ink. Omitting `maxBandWidth` is the
+  previous fill behaviour exactly, and a cap too loose to bind degrades back to
+  it rather than clipping. There is deliberately no `bandAlign: 'fill'`: "fill"
+  is what omitting the cap means, and a `fill` alongside a pitch cap would be a
+  contradiction rather than a choice.
+
+  **Vertical / x-axis categories only** — a `orientation="horizontal"`
+  categorical chart puts its categories on the y axis as unit slots, a
+  different mechanism this does not cap.
+
+- **charts: themed emphasis on the category path** — `BarStyle.hover` /
+  `.highlight` now apply to `categories` and horizontal bars, which routed
+  through the transposed stacked draw path and read neither. New
+  `BarStyle.selectedOutline` (the selected bar's stroke, where the default is
+  its own fill) and `BarStyle.emphasisOpacity` (the alpha a live bar pops to,
+  previously hard-coded `1`) make the emphasis tunable rather than fixed.
+
+  The _behaviour_ was defensible; the problem was that the theme accepted
+  values it would not use. `bar.hover` / `.highlight` were typed, settable and
+  documented as the emphasis channel, and silently did nothing on the most
+  common categorical chart, so a theme author set them, saw no change, and
+  could not tell whether they were wrong about the colour or the mechanism.
+  The one genuine exclusion stays and is now the only one: a `binColors` bar
+  keeps its own colour under hover/selection, because swapping a
+  zone-coloured or direction-coloured bar to a single highlight hue erases
+  what the colour encodes.
+
+### Fixed
+
+- **charts: a negative segment in a multi-group stack is no longer silently
+  dropped** ([PND-SIGNSTACK]). Positives stack **up** from the baseline and
+  negatives stack **down** from it — two running totals per bin — so the
+  **signed stacked histogram** (net flow by category, inflow/outflow, buy/sell
+  pressure by venue) renders correctly. `stackValueExtent` grew the matching
+  negative half; both had to move together, since an extent stopping at `0`
+  would clip the segments the draw path now emits.
+
+  **This is a visible behaviour change** for any existing chart feeding
+  negative values into a multi-group stack — but such a chart was previously
+  rendering _wrongly_: the dropped segments did not clamp, warn or throw, every
+  remaining segment stacked up as though they had never been in the data, and a
+  mixed-sign series came out as a confident, wrong, all-positive chart. An
+  all-positive stack is bit-identical to before. Splitting into two layers was
+  not a workaround either — the negative layer was still `G > 1`, so it was
+  dropped too.
+
+### Changed
+
+- **charts (docs): `<BarChart bins>` now states that it selects a _value_
+  axis** ([PND-TICKUNIT]), so a time-bucketed histogram fed through `bins` gets
+  the decimal 1-2-5 tick ladder rather than the duration ladder a clock
+  subdivides by — labelling e.g. 11:40 and 13:20 at a ~100-minute step. The
+  natural reading ("I have pre-binned buckets, so I'll pass `bins`") is exactly
+  what forecloses the time axis, and nothing at the call site said so. The prop
+  docs now point a time-keyed caller at `<BarChart series columns>`, where the
+  clock ticks are native. No behaviour change.
+
+## [0.56.2] — 2026-08-05
+
+### Fixed
+
+- **charts (tests only, no shipped change):** the log-axis rendered-label test
+  is no longer an exact-set assertion over every digit-bearing node in the
+  render tree. It passed on Node 22 and failed on CI's Node 18 with one extra
+  element, blocking the publish twice. The discrepancy is **unreproduced and
+  still open** — recorded as `[PND-LOGTICK-N18]` in `PND_CHARTS_PLAN.md` with
+  everything measured about it. The assertion now checks that every chosen tick
+  renders in order, which is the wiring this test exists to cover; the tick
+  _selection_ it was really about is pinned deterministically by the
+  `yTickValues` unit tests.
+
+## [0.56.1] — 2026-08-05
+
+### Fixed
+
+- **charts (tests only, no shipped change):** a log-axis test asserted on
+  rendered label _text_, parsing numbers back out of the DOM to infer scale
+  behaviour. It passed locally and failed in CI on a value it could not have
+  produced there, which blocked the v0.56.0 publish. The root cause was never
+  reproduced; rather than guess at it, the assertion now compares the rendered
+  labels against the ticks the axis is specified to draw, formatted through the
+  same formatter — deterministic regardless of locale, formatting or DOM
+  differences, and the numeric guarantee itself was already pinned directly by
+  the `yTickValues` unit tests. The published artifact is identical to what
+  v0.56.0 would have been.
+
+## [0.56.0] — 2026-08-05
+
+### Added
+
+- **charts:** **`<YAxis scale="log">` — a base-10 logarithmic y axis.** Every y
+  scale was `scaleLinear`, so data spanning orders of magnitude was
+  undrawable: on a linear axis everything below the top decade collapses onto
+  the baseline. Set `scale="log"` and the axis maps by ratio, ticking the
+  decades. `format` still formats the **value**, so a readout says `1.2 PB`
+  rather than its logarithm — the transform is in the scale, not in the data,
+  which is what keeps it transparent to every draw layer, annotation and
+  cursor readout.
+
+  A log domain cannot contain zero, and d3 maps a non-positive value to
+  **`NaN`** — a coordinate the canvas silently _drops_, which is why every
+  consequence below is about something failing invisibly rather than throwing.
+  So the axis is deliberate about it:
+  - **Domain policy matches the linear axis exactly.** Auto-fit takes the
+    smallest **positive** extent (one zero sample can't collapse the axis, and
+    a `BarChart` — whose extent always widens to include zero — can still share
+    it); a positive explicit `min`/`max` is honoured verbatim and never
+    discarded, with the _auto-fit_ side moving if the domain would otherwise
+    invert; a fully auto-fit domain is `.nice()`d out to whole powers of ten, so
+    the extremes get headroom instead of sitting clipped on the plot edge. A
+    non-positive bound has no position and is refused in favour of the data.
+    `pad` is applied multiplicatively, adding the same fraction of a decade at
+    both ends.
+  - **A value with no position on the axis renders as a gap.** Previously the
+    gap test was `Number.isFinite(value)`, and `0` is finite — so the coordinate
+    became `NaN`, the canvas dropped the path op without breaking the path, and
+    the two neighbours were joined by a straight line _over_ the missing data.
+    Lines, area fills and outlines, and band envelopes now all break there.
+  - **Layers that reach for a baseline rest on the axis floor.** `AreaChart`
+    resolves an out-of-domain `baseline` there (writing `baseline={0}` is
+    natural and correct on a linear axis), and a **stacked** bar layer starts
+    its first segment there — starting at zero made the bottom segment of every
+    stack both invisible and unhittable. Unchanged on a linear axis, where zero
+    clamped into the domain _is_ zero.
+  - **The dev-mode warning names only unambiguous mistakes**: a refused
+    `min`/`max`, negative data, or an axis with no positive data at all. It
+    deliberately says nothing about an extent of exactly `[0, hi]`, which a
+    line touching zero and a bar layer on strictly positive data both report
+    identically — warning there fired on _every_ bar chart on a log axis. It
+    warns once per distinct complaint rather than on every repaint.
+
+- **charts:** **pan and zoom now yield whole-millisecond view ranges.** A
+  wheel-zoom derives its range from pixel positions through `xScale.invert()`,
+  so the result was fractional by construction — an ordinary scroll produced
+  `1.7e12 + 0.37`. The epoch millisecond is this model's atomic unit and
+  consumers are entitled to assume it; one did, and a calendar `cursorSequence`
+  threw on a plain scroll. `zoomRange` / `panRange` round both ends, and never
+  collapse a positive span to zero width in doing so. (Core's fractional-instant
+  fix covers the same crash from the other side; this closes the class.)
+
+- **charts:** **`AreaStyle.flatFill` — stacked areas that read as slabs.** An
+  area's fill has always graded to transparent at the baseline, which is right
+  for the elevation form and wrong for a stack: every band showed the one
+  beneath it through the fade, so a stacked area was not really drawable. Set
+  `flatFill` and the fill is flat; omitted, the gradient is unchanged, so no
+  existing theme shifts. The docs theme's `seq1…seq8` area roles set it, since
+  stacking is what they exist for.
+
+- **docs theme:** **a sequential ramp — `seq1…seq8` — for charts with more
+  series than the categorical set has hues.** `--pond-viz-1…5` were, and
+  remain, the categorical set; a chart needing more slots (an eight-source
+  stack, a wall of climate stripes) now steps **tonally** through the brand
+  teal instead of introducing competing hues. Eight steps, evenly spaced
+  (~ΔL\* 9 in CIELAB), defined for light and dark, each mode's ramp containing
+  that mode's `--pond-viz-1` exactly. Exposed as `line` / `area` / `bar` theme
+  roles on `docsTheme` (Storybook) and the docs site's `useSiteChartTheme`,
+  and as an array from the site's `useSequentialRamp()`. Dev-only: the ramp
+  lives in the `docs-theme.fixture.ts` Storybook fixture and the website's
+  CSS, both excluded from the published `@pond-ts/charts` build — the library
+  still ships no palette.
+
+### Fixed
+
+- **core:** **a fractional epoch millisecond no longer crashes calendar
+  math.** `Temporal.Instant` refuses a non-integer epoch ms outright
+  (`epoch milliseconds must be an integer`), and `toPlainDateStart` passed
+  whatever it was given straight through — so realizing a `Sequence.calendar`
+  over a fractional range threw, and in a React app the exception unmounted the
+  page. A fraction is not a caller error: a chart's wheel-zoom derives its view
+  range from pixel positions via `xScale.invert()`, so an ordinary scroll
+  produces `1.7e12 + 0.37`. The instant is now floored to the millisecond
+  containing it — the epoch millisecond is this model's atomic unit and
+  calendar boundaries are themselves whole milliseconds, so the bucket
+  containing `t` and the one containing `t + 0.37` are necessarily the same,
+  and integer inputs are untouched. (`Math.floor`, not `Math.trunc`: pre-1970
+  they disagree, and `-5.5` lies inside the millisecond spanning `[-6, -5)`.)
+
+- **charts:** toggling **`<ChartContainer grid>`** now repaints immediately.
+  `Layers`' draw callback read `container.grid` but didn't depend on it, so
+  switching gridlines off changed nothing until an unrelated dependency moved —
+  in practice you had to pan or zoom a little to force the update. The same
+  omission covered `sessionDividers` and `xKind`.
+
+- **charts:** the log axis's dev-mode warning no longer requires **node's
+  ambient types**. It was guarded by a bare `process.env.NODE_ENV`, which
+  typechecks only when a tool happens to resolve `@types/node` from a parent
+  `node_modules` — so `tsc` inside the package passed while running the _same_
+  tsconfig from a consumer's directory failed with `TS2591: Cannot find name
+'process'`. That took out the docs site's TypeDoc step, and would equally hit
+  any consumer typechecking the package's sources. The guard now lives in
+  `src/dev.ts` behind a local declaration and a `typeof` check, so a browser
+  bundle with no `process` global doesn't throw at import either.
+
 ## [0.55.0] — 2026-08-04
 
 ### Added

package/dist/AreaChart.d.ts

@@ -102,6 +102,24 @@ type AreaChartSource<S extends SeriesSchema = SeriesSchema, VS extends ValueSeri
 };
 /** `<AreaChart>`'s props: the shared knobs plus one series-kind source shape. */
 export type AreaChartProps<S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema> = AreaChartCommon<S, VS> & AreaChartSource<S, VS>;
+/** 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
+ *  it to the call signature, so this reads the bound through a localized,
+ *  documented shape rather than widening `drawArea`'s contract to d3-scale. */
+/**
+ * The area's baseline in **data** units: the caller's `baseline` when it has a
+ * finite position on this axis, else the axis floor.
+ *
+ * The fallback is not defensive padding — it's the log case. `baseline={0}` is
+ * the natural thing to write and is correct on a linear axis; on a log axis
+ * zero has no position at all — `scaleLog()(0)` is **`NaN`** (the `-Infinity`
+ * the log *transform* produces is then interpolated into the range, and
+ * `∞ − ∞` is what comes out) — and a single non-finite coordinate turns the
+ * whole filled path into nothing drawn at all. Resolving to the floor keeps the
+ * layer's meaning ("fill from the bottom") on both scale kinds.
+ */
+export declare function resolveAreaBaseline(baseline: number | undefined, yScale: (value: number) => number): number;
 /**
  * An area draw layer: fills between a value `column` and a `baseline`, with a
  * graded (gradient) shade — opaque at the line, transparent at the baseline —

package/dist/AreaChart.js

@@ -12,6 +12,24 @@ import { useSlotKey } from './use-slot-key.js';
  *  d3 `ScaleLinear` (it carries `.domain()`); the {@link RowLayer} type narrows
  *  it to the call signature, so this reads the bound through a localized,
  *  documented shape rather than widening `drawArea`'s contract to d3-scale. */
+/**
+ * The area's baseline in **data** units: the caller's `baseline` when it has a
+ * finite position on this axis, else the axis floor.
+ *
+ * The fallback is not defensive padding — it's the log case. `baseline={0}` is
+ * the natural thing to write and is correct on a linear axis; on a log axis
+ * zero has no position at all — `scaleLog()(0)` is **`NaN`** (the `-Infinity`
+ * the log *transform* produces is then interpolated into the range, and
+ * `∞ − ∞` is what comes out) — and a single non-finite coordinate turns the
+ * whole filled path into nothing drawn at all. Resolving to the floor keeps the
+ * layer's meaning ("fill from the bottom") on both scale kinds.
+ */
+export function resolveAreaBaseline(baseline, yScale) {
+    const floor = domainFloor(yScale);
+    if (baseline === undefined)
+        return floor;
+    return Number.isFinite(yScale(baseline)) ? baseline : floor;
+}
 function domainFloor(yScale) {
     const d = yScale.domain?.();
     return d && d.length > 0 ? d[0] : 0;
@@ -137,7 +155,12 @@ export function AreaChart({ series, column, readout, as: semantic, axis, baselin
             // Omitted baseline rests on the axis floor (resolved late from the
             // scale, so it tracks the auto-fit domain); a fixed baseline is used
             // verbatim.
-            baseline ?? domainFloor(yScale), curveFactory, gaps, gapConnectorOpacity, decimate),
+            // A log axis has no position for zero — or anything at or below
+            // it — so an explicit out-of-domain `baseline` would scale to
+            // `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),
         },
         axisId: axis,
         index,

package/dist/BarChart.d.ts

@@ -26,6 +26,22 @@ import type { DecimateOption } from './decimate.js';
  *   (`Array<{ start, end, …aggregates }>`); the names are **aggregate
  *   fields** of the record, not schema columns, so they stay `string`. Pair
  *   with `ordinal` for a band axis.
+ *
+ *   **`bins` selects a *value* axis, so a time-bucketed histogram fed this way
+ *   gets decimal ticks** ([PND-TICKUNIT]). A `TimeSeries`/`Map` bins on time; a
+ *   `ValueSeries`/`bins`-array bins on a value axis — which means the tick
+ *   ladder is the plain 1-2-5 walk, not the **duration** ladder a clock
+ *   subdivides by (15s and 30s are round durations where 20s and 50s are not).
+ *   A minute-of-day histogram passed as `bins` therefore labels something like
+ *   11:40 and 13:20 — real times at a ~100-minute step — and nothing at the
+ *   call site says why.
+ *
+ *   The natural reading ("I have pre-binned buckets, so I'll pass `bins`") is
+ *   exactly what forecloses the time axis. For a **time-keyed** histogram use
+ *   the series door instead — `<BarChart series columns>` on a time-keyed wide
+ *   series — and the clock ticks are native with no workaround.
+ *   `<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
@@ -116,6 +132,58 @@ export interface BarChartCommon<S extends SeriesSchema = SeriesSchema, VS extend
      * carry many bars' colours, so every visible bar draws.
      */
     binColors?: readonly (string | undefined)[];
+    /**
+     * **Threshold breakpoints** — colour each bar *along its length* against a
+     * ladder, so a long bar shows how far through the ladder it travelled rather
+     * than only which band it ended in. Breakpoints are **absolute data values**
+     * in the axis's own units — `[1, 2]` means "warning above 1, alarm above 2",
+     * not offsets from wherever the bar happens to rest — 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
+     * <BarChart categories={cats} thresholds={[1, 2]} />
+     * ```
+     *
+     * Band fills come from {@link BarStyle.bands} on the resolved role
+     * (`theme.bar[as] ?? theme.bar.default`), overridden by {@link bandColors}.
+     * Breakpoints are data and live here; colour stays in the theme — the same
+     * split as `colors` over the stack's group fills.
+     *
+     * **A banded bar is still one bar.** It keeps one hit region, one stable
+     * `SelectInfo.mark` and one legend row — which is the whole difference from
+     * the N-overlaid-layers recipe this replaces, where each band was separately
+     * hittable and separately listed. Selection and hover pop the opacity and
+     * keep the band colours (as `binColors` does), outlining in the colour of the
+     * band the value actually reached.
+     *
+     * **Negatives band symmetrically**: the ladder is walked on the magnitude and
+     * re-signed, so a bar hanging below the baseline reads the same ±ladder
+     * without negative breakpoints. Out-of-order entries are sorted (the bands
+     * are defined by their boundaries, so there is no second reading) and
+     * non-finite ones dropped.
+     *
+     * Applies to any **single-value** bar — a `series`/`bins` chart, `categories`,
+     * and both orientations. On a genuine **multi-group stack** it is ignored
+     * with a dev warning: a segment that is already one slice of a total has no
+     * defined banding. Set with `binColors` it also yields (per-bar colour is the
+     * more specific answer) and warns. **Disables envelope decimation** for the
+     * same reason `binColors` does.
+     */
+    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 BarStyle.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 bar.
+     */
+    bandColors?: readonly string[];
     /**
      * Bar growth direction (the histogram orientation). **Default `'vertical'`.**
      *
@@ -220,14 +288,21 @@ export type BarChartProps<S extends SeriesSchema = SeriesSchema, VS extends Valu
  * domain spans zero, or on the axis floor when an explicit `<YAxis min>` sits
  * above zero (see {@link resolveBarBaseline}).
  *
- * **Baseline (stacked).** A stack is **cumulative from value 0** — the segments
- * sum upward from the zero line, so its value axis **must include 0**. The
- * auto-fit guarantees this: {@link stackValueExtent} always returns `[0, maxTotal]`.
- * An explicit `<YAxis min>` **above** 0 is therefore unsupported for a stack — it
- * would hide the bottom of the cumulative column; only the portion above the floor
- * draws (clipped cleanly at the plot floor, as any bar below an explicit floor is).
- * Segment values are assumed **non-negative** (a negative or zero segment is
- * skipped — diverging stacks are out of scope).
+ * **Baseline (stacked).** A stack is **cumulative from value 0** — so its value
+ * axis **must include 0**. The auto-fit guarantees this:
+ * {@link stackValueExtent} returns `[minNegativeTotal, maxPositiveTotal]`, both
+ * seeded at `0`. An explicit `<YAxis min>` **above** 0 is therefore unsupported
+ * for a stack — it would hide the bottom of the cumulative column; only the
+ * portion above the floor draws (clipped cleanly at the plot floor, as any bar
+ * below an explicit floor is).
+ *
+ * **Signed stacks are supported** ([PND-SIGNSTACK]): each bin keeps two running
+ * totals, so positive segments stack **up** from the zero line and negative
+ * ones stack **down** from it — the signed histogram (net flow by category,
+ * inflow/outflow, buy/sell pressure by venue). A **zero** segment is still
+ * skipped, having no extent to draw or hit-test. This changed in the
+ * threshold-banding wave: negative segments were previously dropped outright
+ * and silently, so a mixed-sign series rendered as an all-positive chart.
  *
  * **Interaction (opt-in via `id`).** Hover lights the bar / segment under the
  * cursor (hit-tested by pixel rect, so it works in both orientations); click
@@ -244,6 +319,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, 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, decimate, legend, index, }: BarChartProps<S, VS>): null;
 export {};
 //# sourceMappingURL=BarChart.d.ts.map