@pond-ts/charts 0.59.0 → 0.61.0

package/dist/area.js

@@ -1,5 +1,5 @@
 import { area as d3area, curveLinear } from 'd3-shape';
-import { baselinePxFromScale, strokeAffinePolyline, TRACE_HIT_PX, } from './line.js';
+import { baselinePxFromScale, plotExtentOf, strokeAffinePolyline, TRACE_HIT_PX, } from './line.js';
 import { bridgeGaps, collectGapEdges, drawGapBridges, drawGapFades, drawGapSteps, gapUnscalable, withAlpha, DEFAULT_GAP_MODE, DEFAULT_GAP_CONNECTOR_OPACITY, } from './gaps.js';
 import { cullChartSeries } from './culling.js';
 import { decimateM4Cached } from './decimate.js';
@@ -155,7 +155,7 @@ export function areaExtent(cs, baseline) {
  * bracketed by `save`/`restore` so they don't leak into later layers. Gap edges
  * are collected by one O(N) walk ({@link collectGapEdges}).
  */
-export function drawArea(ctx, cs, xScale, yScale, style, baselineValue, curve = curveLinear, gaps = DEFAULT_GAP_MODE, gapConnectorOpacity = DEFAULT_GAP_CONNECTOR_OPACITY, decimate = true) {
+export function drawArea(ctx, cs, xScale, yScale, style, baselineValue, curve = curveLinear, gaps = DEFAULT_GAP_MODE, gapConnectorOpacity = DEFAULT_GAP_CONNECTOR_OPACITY, decimate = true, banding) {
     const sourceCount = cs.length; // pre-cull, pre-decimation (for draw stats)
     const baselinePx = yScale(baselineValue);
     // The fill gradient's vertical extent is computed from the **full** series (a
@@ -168,7 +168,13 @@ export function drawArea(ctx, cs, xScale, yScale, style, baselineValue, curve =
     // instead of re-walking O(N) — the mountain@1M ceiling the bench profile
     // flagged. A `'none'` bridge only fills interior gaps with interpolated values
     // that stay within the finite extent, so the plain extent is exact for it too.
-    const fill = buildGradient(ctx, columnFiniteExtent(cs.y, cs.length), yScale, baselinePx, style);
+    //
+    // **Banded** ([PND-BANDAREA]): one hard-stop pixel-space gradient carries the
+    // whole ladder for the fill AND the outline — see {@link buildBandGradient}
+    // for why a gradient rather than one clipped redraw per band.
+    const fill = banding !== undefined
+        ? buildBandGradient(ctx, yScale, plotExtentOf(ctx, xScale, yScale).height, banding)
+        : buildGradient(ctx, columnFiniteExtent(cs.y, cs.length), yScale, baselinePx, style);
     // Clip `cs` to what draws. **Decimated** (linear curve, `decimate !== false`):
     // cull to the visible slice, then the same {@link decimateM4} pre-pass shrinks
     // the fill + outline + gap-bridge work to O(plot width) once dense (the §2.2
@@ -237,14 +243,17 @@ export function drawArea(ctx, cs, xScale, yScale, style, baselineValue, curve =
     ctx.fill();
     ctx.restore();
     // The outline on top: the area's top edge as a line (breaks at the same gaps
-    // as the fill), at full opacity over the graded fill.
+    // as the fill), at full opacity over the graded fill. Banded, it strokes with
+    // the same hard-stop gradient the fill used, so the line switches hue exactly
+    // where it crosses a threshold — the whole point of the ladder is that the
+    // reader sees *where* the value sits, and the edge is the value.
     ctx.save();
     ctx.beginPath();
     if (outline !== null)
         outline(ys);
     else
         strokeAffinePolyline(ctx, cs.x, ys, ax, ay);
-    ctx.strokeStyle = style.color;
+    ctx.strokeStyle = banding !== undefined ? fill : style.color;
     ctx.lineWidth = style.width;
     ctx.stroke();
     ctx.restore();
@@ -345,6 +354,114 @@ function buildGradient(ctx, valueExtent, yScale, baselinePx, style) {
     }
     return grad;
 }
+/**
+ * The banded fill + stroke for `<AreaChart thresholds>` ([PND-BANDAREA]): one
+ * vertical **hard-stop gradient in pixel space**, a colour switch at every
+ * threshold crossing — `colors[0]` between `-t0` and `+t0`, `colors[k]` over
+ * magnitudes `[t(k-1), tk)` on both sides of zero. `thresholds`/`colors` arrive
+ * as a resolved {@link BandLadder} (ascending, positive, `n + 1` colours), the
+ * same currency `drawBars` takes.
+ *
+ * A gradient rather than one clipped redraw per band, and that is the
+ * load-bearing choice: K + 1 clipped passes walk the path K + 1 times and meet
+ * themselves at every boundary with an antialiased seam, where a gradient
+ * draws the identical single path once and costs O(K) colour stops. It also
+ * bands the **outline for free** — `strokeStyle` takes the same gradient, so
+ * the value line switches hue exactly at a crossing, which no per-band clip
+ * can do without shearing the stroke.
+ *
+ * The ladder is walked on the **magnitude** and mirrored below zero, exactly
+ * as `bandSpan` does for a bar: the boundary at `±tk` separates band `k` (the
+ * zero side) from band `k + 1` (the away side). Whether "away from zero" is up
+ * or down the canvas is probed from the scale itself (`t0` vs `t0 + 1`, both
+ * positive and finite by construction), so a flipped axis bands correctly. A
+ * boundary with **no position** on the scale contributes no crossing — on a
+ * log axis the negative mirrors (and zero) simply don't exist, which is the
+ * right reading. A crossing **off the plot** clamps to the gradient's ends
+ * (a real canvas throws on stops outside `[0, 1]`), which is also what makes a
+ * zoomed-in view honest: with every visible pixel inside one band, the clamp
+ * degenerates the other stops and the whole plot paints that band's colour.
+ *
+ * Falls back to the top band's flat colour when there is nothing to anchor on
+ * (no plot height, or no boundary with a position at all) — reachable only
+ * with a degenerate scale stub, since every real axis positions a positive
+ * finite value; any flat colour is equally (in)correct there, and the top
+ * band's is at least stable.
+ *
+ * Like the bar ladder, breakpoints are **absolute data values**, so the
+ * baseline plays no part here: an area resting on a non-zero floor still bands
+ * at the same heights as its neighbours — measuring from the resolved baseline
+ * instead would silently shift every breakpoint by the floor, the quiet
+ * wrongness [PND-BANDBAR2] exists to remove.
+ */
+export function buildBandGradient(ctx, yScale, plotHeight, banding) {
+    const { thresholds, colors } = banding;
+    const fallback = colors[colors.length - 1];
+    // Guards NaN too — `!(x > 0)`, not `x <= 0`.
+    if (!(plotHeight > 0))
+        return fallback;
+    // Axis direction: does value increase toward smaller pixels (the canvas
+    // norm)? Probed on the ladder's own first breakpoint — positive and finite
+    // by construction, so it has a position on every axis kind (linear, log,
+    // symlog). Non-finite or equal probes default to the norm.
+    const pA = yScale(thresholds[0]);
+    const pB = yScale(thresholds[0] + 1);
+    const higherValueAtSmallerPx = !(Number.isFinite(pA) &&
+        Number.isFinite(pB) &&
+        pB > pA);
+    const crossings = [];
+    for (let k = 0; k < thresholds.length; k += 1) {
+        const zeroSide = colors[k];
+        const awaySide = colors[k + 1];
+        for (const sign of [1, -1]) {
+            const v = sign * thresholds[k];
+            const px = yScale(v);
+            if (!Number.isFinite(px))
+                continue; // no position — no crossing
+            const awayAbove = sign > 0 === higherValueAtSmallerPx;
+            crossings.push(awayAbove
+                ? { px, above: awaySide, below: zeroSide, k, sign }
+                : { px, above: zeroSide, below: awaySide, k, sign });
+        }
+    }
+    if (crossings.length === 0)
+        return fallback;
+    // Sort by pixel; same-pixel same-sign crossings (a duplicate breakpoint's
+    // empty band, or distinct breakpoints collapsed by an extreme zoom) order
+    // **away-band-outermost**: the away side's colour first coming from the
+    // away direction, the zero side's first coming from zero. That makes the
+    // walk below telescope — the seed reads the true outermost band and the
+    // last stop at the pixel is the true inner colour, with the skipped bands
+    // as zero-width ghosts in between — instead of seeding one band short and
+    // blending across the region below. Bars skip an empty band the same way
+    // (`bandSpanInto` clips it to nothing); a same-pixel *opposite-sign* pair
+    // (a folded scale) has no defined order and keeps insertion order.
+    crossings.sort((a, b) => {
+        if (a.px !== b.px)
+            return a.px - b.px;
+        if (a.sign !== b.sign)
+            return 0;
+        const awayFirst = a.sign > 0 === higherValueAtSmallerPx;
+        return awayFirst ? b.k - a.k : a.k - b.k;
+    });
+    const grad = ctx.createLinearGradient(0, 0, 0, plotHeight);
+    const offsetOf = (px) => {
+        const o = px / plotHeight;
+        return o < 0 ? 0 : o > 1 ? 1 : o;
+    };
+    // Each crossing is a hard stop: two stops at one offset, old colour then
+    // new. The region above the first crossing seeds the walk; clamped
+    // off-plot crossings collapse to zero-height regions at the ends, leaving
+    // the visible span in the band it actually occupies.
+    grad.addColorStop(0, crossings[0].above);
+    for (const c of crossings) {
+        const off = offsetOf(c.px);
+        grad.addColorStop(off, c.above);
+        grad.addColorStop(off, c.below);
+    }
+    grad.addColorStop(1, crossings[crossings.length - 1].below);
+    return grad;
+}
 /**
  * **Is the pointer inside this area?** The filled-region counterpart of
  * `traceHitIndex` ([PND-TRACESEL]) — returns the nearest sample's index as

package/dist/axis-events.d.ts

@@ -0,0 +1,106 @@
+import type { MouseEvent as ReactMouseEvent } from 'react';
+/**
+ * What an axis hands its {@link AxisMouseHandler} — the raw mouse event, plus
+ * the **axis coordinate under the pointer**, which is the part a consumer
+ * cannot compute for itself (the scale lives inside the container).
+ */
+export interface AxisMouseEvent {
+    /**
+     * The React mouse event, verbatim — `type` says which one fired
+     * (`'click'`, `'mousemove'`, `'contextmenu'`, …), and the modifier keys,
+     * `button`, `preventDefault()` and `stopPropagation()` are all the ordinary
+     * ones. **A single handler receives every mouse event on the strip**, so
+     * switch on `event.type` (or ignore the ones you don't want).
+     */
+    event: ReactMouseEvent<HTMLDivElement>;
+    /** Which axis fired — so one handler can serve both. */
+    axis: 'x' | 'y';
+    /**
+     * The axis's `id`, when it has one. A `<YAxis>` always does (it's required —
+     * charts link to it); an `<XAxis>` has none, so this is `undefined` there.
+     * To tell two stacked x-axes apart, close over the distinction at the call
+     * site (`onMouseEvent={(e) => onAxis('delta', e)}`).
+     */
+    id?: string | undefined;
+    /**
+     * The axis value under the pointer, **in the axis's own data units** — epoch
+     * ms on a time axis, the number on a value axis, the slot value on a
+     * categorical one. Read {@link label} for what the axis would *print* there.
+     *
+     * Not clamped to a tick — it is the continuous inverse of the pixel, so it
+     * lands between ticks. The one exception is a **categorical x-axis**, whose
+     * scale inverts to the nearest band **centre** (`i + 0.5`); a categorical
+     * *row* (horizontal bars on the y-axis) is a plain linear slot scale and does
+     * not snap, so `Math.floor(value)` is its slot index.
+     *
+     * On a `transform`ed x-axis this is the **underlying** value, not the derived
+     * unit — apply the same `transform.to` you passed the axis to get the unit
+     * its ticks read in.
+     */
+    value: number;
+    /**
+     * {@link value} formatted the way this axis reads it — the category name on a
+     * categorical axis, the axis's `format` (or the container's shared formatter)
+     * elsewhere.
+     *
+     * Precisely: it is the axis's **readout** channel, the one the cursor pill
+     * uses — so it always agrees with the pill at that pixel, and a container
+     * `cursorFormat` shapes it exactly as it shapes the pill. That is the
+     * documented precedence (`cursorFormat` → axis `format` → container), and it
+     * is the one case where `label` can read differently from the tick text: a
+     * chart with a precise `cursorFormat` over terse ticks gets the precise form
+     * here, which is the readout it asked for.
+     */
+    label: string;
+}
+/**
+ * A single handler for every mouse event on an axis strip — see
+ * {@link AxisMouseEvent}. Passed as `onMouseEvent` to `<XAxis>` / `<YAxis>`.
+ */
+export type AxisMouseHandler = (info: AxisMouseEvent) => void;
+/** The mouse props an axis strip spreads onto its root element. */
+type AxisMouseProps = {
+    onClick?: (e: ReactMouseEvent<HTMLDivElement>) => void;
+    onDoubleClick?: (e: ReactMouseEvent<HTMLDivElement>) => void;
+    onContextMenu?: (e: ReactMouseEvent<HTMLDivElement>) => void;
+    onMouseDown?: (e: ReactMouseEvent<HTMLDivElement>) => void;
+    onMouseUp?: (e: ReactMouseEvent<HTMLDivElement>) => void;
+    onMouseMove?: (e: ReactMouseEvent<HTMLDivElement>) => void;
+    onMouseEnter?: (e: ReactMouseEvent<HTMLDivElement>) => void;
+    onMouseLeave?: (e: ReactMouseEvent<HTMLDivElement>) => void;
+};
+/**
+ * Build the mouse props for an axis strip: every mouse event routed to the one
+ * `onMouseEvent` handler, each carrying the axis coordinate `at` resolves from
+ * the pointer.
+ *
+ * With no handler this returns `{}` — **nothing is attached**, so an axis that
+ * doesn't opt in keeps costing nothing (no per-move callback, no listeners).
+ *
+ * `at` returns `null` when the pointer maps to no value — the transient render
+ * before a `<YAxis>` has a resolved scale — and the event is then dropped
+ * rather than reported at a made-up coordinate.
+ */
+export declare function axisMouseProps(onMouseEvent: AxisMouseHandler | undefined, axis: 'x' | 'y', id: string | undefined, at: (event: ReactMouseEvent<HTMLDivElement>) => {
+    value: number;
+    label: string;
+} | null): AxisMouseProps;
+/**
+ * The pointer's position along an axis strip, in **strip-local pixels** — the
+ * coordinate the scale inverts. Read from the strip's own client rect
+ * (`currentTarget`, so it is the strip whichever tick label was hit), which is
+ * laid out flush with the plot on that dimension: the x strip carries the left
+ * gutter as a margin and is exactly `plotWidth` wide, and the y gutter is
+ * exactly the row's height.
+ *
+ * Clamped to **the scale's range, not the strip's box** — the two are not
+ * always the same. A row carrying a `labelPlacement="top"` axis reserves a
+ * header, so its y scales run `[height, topHeader]` while the gutter box still
+ * starts at 0; clamping to the box would invert the header band to values
+ * *above* the domain and report a coordinate the axis never draws. Passing the
+ * range means a `mouseleave` off the edge — or a press in that header — still
+ * reports a value the scale actually holds.
+ */
+export declare function axisPointerPx(event: ReactMouseEvent<HTMLDivElement>, axis: 'x' | 'y', range: readonly [number, number]): number;
+export {};
+//# sourceMappingURL=axis-events.d.ts.map

package/dist/axis-events.js

@@ -0,0 +1,56 @@
+/**
+ * Build the mouse props for an axis strip: every mouse event routed to the one
+ * `onMouseEvent` handler, each carrying the axis coordinate `at` resolves from
+ * the pointer.
+ *
+ * With no handler this returns `{}` — **nothing is attached**, so an axis that
+ * doesn't opt in keeps costing nothing (no per-move callback, no listeners).
+ *
+ * `at` returns `null` when the pointer maps to no value — the transient render
+ * before a `<YAxis>` has a resolved scale — and the event is then dropped
+ * rather than reported at a made-up coordinate.
+ */
+export function axisMouseProps(onMouseEvent, axis, id, at) {
+    if (onMouseEvent === undefined)
+        return {};
+    const fire = (event) => {
+        const hit = at(event);
+        if (hit === null)
+            return;
+        onMouseEvent({ event, axis, id, value: hit.value, label: hit.label });
+    };
+    return {
+        onClick: fire,
+        onDoubleClick: fire,
+        onContextMenu: fire,
+        onMouseDown: fire,
+        onMouseUp: fire,
+        onMouseMove: fire,
+        onMouseEnter: fire,
+        onMouseLeave: fire,
+    };
+}
+/**
+ * The pointer's position along an axis strip, in **strip-local pixels** — the
+ * coordinate the scale inverts. Read from the strip's own client rect
+ * (`currentTarget`, so it is the strip whichever tick label was hit), which is
+ * laid out flush with the plot on that dimension: the x strip carries the left
+ * gutter as a margin and is exactly `plotWidth` wide, and the y gutter is
+ * exactly the row's height.
+ *
+ * Clamped to **the scale's range, not the strip's box** — the two are not
+ * always the same. A row carrying a `labelPlacement="top"` axis reserves a
+ * header, so its y scales run `[height, topHeader]` while the gutter box still
+ * starts at 0; clamping to the box would invert the header band to values
+ * *above* the domain and report a coordinate the axis never draws. Passing the
+ * range means a `mouseleave` off the edge — or a press in that header — still
+ * reports a value the scale actually holds.
+ */
+export function axisPointerPx(event, axis, range) {
+    const rect = event.currentTarget.getBoundingClientRect();
+    const px = axis === 'x' ? event.clientX - rect.left : event.clientY - rect.top;
+    const lo = Math.min(range[0], range[1]);
+    const hi = Math.max(range[0], range[1]);
+    return Math.max(lo, Math.min(hi, px));
+}
+//# sourceMappingURL=axis-events.js.map

package/dist/context.d.ts

@@ -1,5 +1,5 @@
 import { type ReactNode } from 'react';
-import type { ScaleContinuousNumeric, ScaleLinear, ScaleTime } from 'd3-scale';
+import type { ScaleContinuousNumeric, ScaleLinear, ScaleLogarithmic, ScaleSymLog, ScaleTime } from 'd3-scale';
 import type { ChartTheme } from './theme.js';
 import type { AxisFormat, CursorFormat } from './format.js';
 import type { LegendItemSpec } from './swatch.js';
@@ -25,6 +25,19 @@ export interface LabelPlacement {
     readonly lane: number;
     readonly label: string | null;
 }
+/**
+ * The container's shared x→pixel scale, in every kind it can resolve to. All
+ * five are callable (`value → px`) and expose `invert` / `ticks` /
+ * `tickFormat`, which is the whole surface the library — and a consumer
+ * reading the frame ({@link ChartFrame.xScale}) — uses; that shared shape is
+ * what lets a trading-time or ordinal axis drop in where a linear one went.
+ *
+ * Named (rather than written inline on {@link ContainerFrame.xScale}) because
+ * {@link useChartFrame} publishes it: a consumer positioning DOM chrome over
+ * the plot needs to be able to *write down the type* of the scale it maps
+ * through.
+ */
+export type ChartXScale = ScaleTime<number, number> | ScaleLinear<number, number> | ScaleLogarithmic<number, number> | ScaleSymLog<number, number> | TradingTimeScale | ScaleBand | ElapsedScale;
 export interface ContainerFrame {
     readonly timeRange: readonly [number, number];
     readonly width: number;
@@ -355,7 +368,16 @@ export interface ContainerFrame {
      * (axis labels, gridlines, cursor pill) reads durations without any consumer
      * knowing about the mode.
      */
-    readonly xScale: ScaleTime<number, number> | ScaleLinear<number, number> | TradingTimeScale | ScaleBand | ElapsedScale;
+    readonly xScale: ChartXScale;
+    /**
+     * Is the x scale **logarithmic** (`log` or `symlog`)?
+     *
+     * Detected structurally rather than threaded from the prop: `base()` exists
+     * on d3's log scales and on no other continuous scale, which is the same test
+     * `yticks.ts` already uses on the y side. Read by the viewport gestures,
+     * which must do their arithmetic in log space (see `ViewportOptions`).
+     */
+    readonly xIsLog: boolean;
     /**
      * The discontinuity provider backing a **trading-time** x axis, if one was
      * supplied to the container — closed-market time (weekends, holidays,
@@ -1655,6 +1677,17 @@ export interface AxisSpec {
  */
 export interface RowFrame {
     readonly height: number;
+    /**
+     * The plot's **top inset** within the row's box, in px — the header band
+     * reserved when any axis in the row draws a `labelPlacement="top"` title,
+     * and `0` when none does. The y-scales' range is `[height, topInset]`, so
+     * the drawable plot is `topInset … height`.
+     *
+     * Carried on the frame (rather than staying a local in `ChartRow`) because
+     * {@link useChartFrame} publishes it — without it a consumer placing an
+     * overlay inside the plot would silently sit under a top axis title.
+     */
+    readonly topInset: number;
     readonly yScales: ReadonlyMap<string, YScale>;
     /** Value formatter per axis id (resolved from the axis's {@link AxisSpec.format}
      *  against its scale) — used by both the tick labels and the cursor readout, so

package/dist/format.d.ts

@@ -77,7 +77,7 @@ interface Tickable {
  * render blank for almost every real number. A linear scale's `tickFormat`
  * applies the specifier to whatever it is handed, which is what every consumer
  * of this function actually wants; the axis's own tick *thinning* is handled by
- * `yTickValues`, not here.
+ * `tickValues`, not here.
  *
  * **A symlog scale's precision comes from its knee, not its span** ([PND-SYMLOG]).
  * `scaleSymlog.tickFormat` is `linearish`, so it derives precision from the

package/dist/format.js

@@ -24,7 +24,7 @@ import { scaleLinear } from 'd3-scale';
  * render blank for almost every real number. A linear scale's `tickFormat`
  * applies the specifier to whatever it is handed, which is what every consumer
  * of this function actually wants; the axis's own tick *thinning* is handled by
- * `yTickValues`, not here.
+ * `tickValues`, not here.
  *
  * **A symlog scale's precision comes from its knee, not its span** ([PND-SYMLOG]).
  * `scaleSymlog.tickFormat` is `linearish`, so it derives precision from the

package/dist/index.d.ts

@@ -31,6 +31,7 @@ export type { YAxisProps } from './YAxis.js';
 export { XAxis } from './XAxis.js';
 export type { XAxisProps } from './XAxis.js';
 export type { AxisTransform } from './derivedTicks.js';
+export type { AxisMouseEvent, AxisMouseHandler } from './axis-events.js';
 export { TimeAxis } from './TimeAxis.js';
 export { CategoryAxis } from './CategoryAxis.js';
 export { HeatMap } from './HeatMap.js';
@@ -64,6 +65,9 @@ export type { LegendProps, LegendPlacement } from './Legend.js';
 export type { SwatchSpec, LegendItemInput } from './swatch.js';
 export { useChartLegend } from './useChartLegend.js';
 export type { ChartLegend, LegendRow, LegendItem } from './useChartLegend.js';
+export { useChartFrame } from './useChartFrame.js';
+export type { ChartFrame, ChartFrameRow, ChartBands, ChartBand, } from './useChartFrame.js';
+export type { ChartXScale } from './context.js';
 export { scaleTradingTime } from './tradingTimeScale.js';
 export type { TradingTimeScale, DiscontinuityProvider, TimeGrain, } from './tradingTimeScale.js';
 export { scaleBand } from './bandScale.js';

package/dist/index.js

@@ -52,6 +52,12 @@ export { Legend } from './Legend.js';
 // consumers who design their own key (horizontal strips, ticker-compare,
 // values-in-the-legend).
 export { useChartLegend } from './useChartLegend.js';
+// The resolved plot geometry — the plot rect, the axis gutters, the shared x
+// scale, a row's y scales, and (on a category axis) the ordinal slot edges.
+// What a consumer aligning DOM chrome to the plot would otherwise re-derive
+// by mirroring the library's own gutter arithmetic — a duplicate that drifts
+// silently the moment the library changes how a gutter is sized.
+export { useChartFrame } from './useChartFrame.js';
 export { scaleTradingTime } from './tradingTimeScale.js';
 // The ordinal category (band) scale — the transpose view's "columns on x" axis.
 export { scaleBand } from './bandScale.js';

package/dist/theme.d.ts

@@ -720,6 +720,28 @@ export interface AreaStyle {
     /** Ink for a swept window's emphasised portion (edge + fill).
      *  **Omitted ⇒ the area keeps its own colours and only strengthens.** */
     readonly spanColor?: string;
+    /**
+     * The **threshold-band ladder** — ordered fills for an area coloured *along
+     * its height* against `<AreaChart thresholds>`: `bands[0]` up to the first
+     * threshold, `bands[1]` between the first and second, and so on. A ladder of
+     * `n` thresholds reads `n + 1` entries. The fill **and** the outline take
+     * the band hues (one hard-stop gradient in pixel space), and the grade to
+     * transparent is dropped: the fade encoded distance-from-the-baseline, which
+     * is exactly what the ladder now states discretely — two encodings of one
+     * thing would fight.
+     *
+     * Lives on `AreaStyle` for {@link BarStyle.bands}' reason: `theme.area` is a
+     * semantic **map**, so a top-level key would collide with a role of that
+     * name — and per-role is the more useful shape (`area.default.bands` and a
+     * capacity role's ladder can differ).
+     *
+     * **Overridden by `<AreaChart bandColors>`** at the call site. If neither
+     * resolves enough entries for the ladder, the shortfall falls back to the
+     * flat {@link fill} and (in dev) warns — the same contract as the bar
+     * ladder, because a silently-unbanded chart is the failure mode the feature
+     * exists to remove.
+     */
+    readonly bands?: readonly string[];
 }
 /**
  * A resolved bar style: the flat `fill` (scaled by `opacity`, 0–1) plus the

package/dist/theme.js

@@ -78,6 +78,9 @@ export const defaultTheme = {
             selectedFillOpacity: 0.55,
             dimmedOpacity: 0.32,
             spanColor: '#3F5BE0',
+            // The same ok → warning → alarm ladder `bar.default.bands` carries, so a
+            // banded area and a banded bar over one dataset read as one system.
+            bands: ['#2A9D8F', '#e8a13c', '#d64545'],
         },
         in: { color: '#0284c7', width: 1.5, fill: '#0284c7', fillOpacity: 0.3 },
         out: { color: '#e8836b', width: 1.5, fill: '#e8836b', fillOpacity: 0.3 },

package/dist/use-band-ladder.d.ts

@@ -0,0 +1,30 @@
+import { type BandLadder } from './bars.js';
+/**
+ * Resolve a component's `thresholds` / `bandColors` props against its theme
+ * role's band ramp into a {@link BandLadder} — or `undefined` when there is no
+ * usable ladder, so the caller keeps its flat path.
+ *
+ * Extracted from `<BarChart>`'s [PND-BANDBAR2] block verbatim when
+ * `<AreaChart thresholds>` arrived ([PND-BANDAREA]): the resolution rules and
+ * every dev warning are one contract across banded marks, differing only in
+ * the component named by the warning text.
+ *
+ * Resolved once here rather than per mark per frame: normalize the breakpoints
+ * (sort, drop non-finite / non-positive), then pair them with `bandColors` →
+ * the role's `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 mark was the workaround's failure mode.
+ *
+ * The two array props are **value-compared** rather than identity-compared:
+ * `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 caller's layer entry, 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>` applies.
+ *
+ * A short colour supply pads with `styleFill` (the role's flat fill) so the
+ * draw path can index freely; `undefined` comes back only when there are no
+ * usable breakpoints or no colours at all.
+ */
+export declare function useBandLadder(component: 'BarChart' | 'AreaChart', thresholds: readonly number[] | undefined, bandColors: readonly string[] | undefined, styleBands: readonly string[] | undefined, styleFill: string): BandLadder | undefined;
+//# sourceMappingURL=use-band-ladder.d.ts.map

package/dist/use-band-ladder.js

@@ -0,0 +1,81 @@
+import { useMemo } from 'react';
+import { normalizeThresholds } from './bars.js';
+import { isDev } from './dev.js';
+/**
+ * Resolve a component's `thresholds` / `bandColors` props against its theme
+ * role's band ramp into a {@link BandLadder} — or `undefined` when there is no
+ * usable ladder, so the caller keeps its flat path.
+ *
+ * Extracted from `<BarChart>`'s [PND-BANDBAR2] block verbatim when
+ * `<AreaChart thresholds>` arrived ([PND-BANDAREA]): the resolution rules and
+ * every dev warning are one contract across banded marks, differing only in
+ * the component named by the warning text.
+ *
+ * Resolved once here rather than per mark per frame: normalize the breakpoints
+ * (sort, drop non-finite / non-positive), then pair them with `bandColors` →
+ * the role's `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 mark was the workaround's failure mode.
+ *
+ * The two array props are **value-compared** rather than identity-compared:
+ * `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 caller's layer entry, 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>` applies.
+ *
+ * A short colour supply pads with `styleFill` (the role's flat fill) so the
+ * draw path can index freely; `undefined` comes back only when there are no
+ * usable breakpoints or no colours at all.
+ */
+export function useBandLadder(component, thresholds, bandColors, styleBands, styleFill) {
+    const thresholdKey = thresholds === undefined ? '' : thresholds.join(',');
+    const bandColorKey = bandColors === undefined ? '' : bandColors.join(',');
+    return useMemo(() => {
+        const steps = normalizeThresholds(thresholds);
+        if (steps === null) {
+            if (isDev && thresholds !== undefined && thresholds.length > 0) {
+                console.warn(`<${component} thresholds>: no usable breakpoints, so no banding ` +
+                    'was applied — each must be finite and greater than zero. The ' +
+                    'chart draws 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(`<${component} 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 the value is on, so a negative breakpoint has no meaning; ` +
+                `banding on [${steps.join(', ')}].`);
+        }
+        const want = steps.length + 1;
+        const supplied = bandColors ?? styleBands;
+        if (supplied === undefined || supplied.length === 0) {
+            if (isDev) {
+                console.warn(`<${component} thresholds>: ${steps.length} breakpoint(s) need ` +
+                    `${want} band colours, but neither \`bandColors\` nor the theme ` +
+                    `role’s \`bands\` supplies any. The chart draws in the flat fill.`);
+            }
+            return undefined;
+        }
+        if (supplied.length < want && isDev) {
+            console.warn(`<${component} 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 }, () => styleFill),
+            ];
+        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.
+    }, [component, thresholdKey, bandColorKey, styleBands, styleFill]);
+}
+//# sourceMappingURL=use-band-ladder.js.map