@pond-ts/charts 0.59.0 → 0.60.0

package/dist/area.d.ts

@@ -1,6 +1,7 @@
 import { type CurveFactory } from 'd3-shape';
 import type { ChartSeries } from './data.js';
 import { type Scale, type TraceState } from './line.js';
+import type { BandLadder } from './bars.js';
 import type { AreaStyle } from './theme.js';
 import type { LayerDrawStats } from './context.js';
 import { type GapMode } from './gaps.js';
@@ -69,7 +70,48 @@ export declare function areaExtent(cs: ChartSeries, baseline: number | undefined
  * bracketed by `save`/`restore` so they don't leak into later layers. Gap edges
  * are collected by one O(N) walk ({@link collectGapEdges}).
  */
-export declare function drawArea(ctx: CanvasRenderingContext2D, cs: ChartSeries, xScale: Scale, yScale: Scale, style: AreaStyle, baselineValue: number, curve?: CurveFactory, gaps?: GapMode, gapConnectorOpacity?: number, decimate?: DecimateOption): LayerDrawStats;
+export declare function drawArea(ctx: CanvasRenderingContext2D, cs: ChartSeries, xScale: Scale, yScale: Scale, style: AreaStyle, baselineValue: number, curve?: CurveFactory, gaps?: GapMode, gapConnectorOpacity?: number, decimate?: DecimateOption, banding?: BandLadder): LayerDrawStats;
+/**
+ * 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 declare function buildBandGradient(ctx: CanvasRenderingContext2D, yScale: Scale, plotHeight: number, banding: BandLadder): CanvasGradient | string;
 /**
  * **Is the pointer inside this area?** The filled-region counterpart of
  * `traceHitIndex` ([PND-TRACESEL]) — returns the nearest sample's index as

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/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

@@ -64,6 +64,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

package/dist/useChartFrame.d.ts

@@ -0,0 +1,122 @@
+import { type ChartXScale, type YScale } from './context.js';
+/**
+ * One ordinal slot on a category axis — its pixel span within the plot, its
+ * centre (where a mark is drawn and a tick is labelled), and its name.
+ *
+ * `x0`/`x1`/`center` are **plot-relative** (`0 … plot.width`); add
+ * {@link ChartFrame.plot}`.x` for container-relative DOM placement.
+ */
+export interface ChartBand {
+    /** The slot's left edge in px. */
+    readonly x0: number;
+    /** The slot's right edge in px. `x1 - x0` is {@link ChartBands.pitch}. */
+    readonly x1: number;
+    /** The slot's centre in px — where a bar centres and a tick labels. */
+    readonly center: number;
+    /** The category name at this slot. */
+    readonly label: string;
+}
+/**
+ * The ordinal slot geometry of a `'category'` x axis — `null` on a `'time'`
+ * or `'value'` axis, which has no slots.
+ *
+ * **The pitch is not `plot.width / count`.** `<ChartContainer maxBandWidth>`
+ * caps it and `bandAlign` places the resulting narrower block within the
+ * plot, so the packed band run can be inset from both plot edges. Reading
+ * `pitch` and `at(i)` rather than recomputing is the difference between
+ * chrome that tracks that packing and chrome that ignores it.
+ */
+export interface ChartBands {
+    /** Number of slots — the category count. */
+    readonly count: number;
+    /** One slot's width in px (the pitch; slots are contiguous and equal). */
+    readonly pitch: number;
+    /** The ordered category names, index-aligned with the slots. */
+    readonly labels: readonly string[];
+    /** The slot at `index`, or `null` when `index` is not a real slot. */
+    at(index: number): ChartBand | null;
+}
+/**
+ * The **row-scoped** half of the frame: y geometry and the row's value
+ * scales. `null` on {@link ChartFrame.row} when the hook is called outside a
+ * `<ChartRow>`.
+ */
+export interface ChartFrameRow {
+    /**
+     * The plot's top inset within the row's box in px — the band reserved by a
+     * `labelPlacement="top"` axis title, `0` when no axis draws one. An overlay
+     * that ignores it sits under the title.
+     */
+    readonly topInset: number;
+    /**
+     * The plot's drawable height in px, below {@link topInset}. The row's own
+     * `height` prop is `topInset + height`, and the y-scales' pixel range is
+     * `[topInset + height, topInset]` (inverted — pixels grow downward).
+     */
+    readonly height: number;
+    /**
+     * One value→pixel scale per `<YAxis id>`, each mapping into
+     * `[topInset + height, topInset]`. A row with no explicit `<YAxis>` has one
+     * entry under the implicit default id.
+     */
+    readonly yScales: ReadonlyMap<string, YScale>;
+    /** Which gutter each axis id sits in — so chrome hugs the right edge. */
+    readonly axisSides: ReadonlyMap<string, 'left' | 'right'>;
+}
+/** The resolved geometry of a chart, as published by {@link useChartFrame}. */
+export interface ChartFrame {
+    /**
+     * The plot's **x** geometry in px, relative to the container's own box:
+     * `x` is the left gutter (where the plot starts) and `width` is the plot's
+     * width after both gutters. Shared by every row.
+     */
+    readonly plot: {
+        readonly x: number;
+        readonly width: number;
+    };
+    /**
+     * The reserved axis gutters in px — how far the plot is inset on each side.
+     * `left` equals {@link plot}`.x`; both are published because chrome above
+     * the plot pads by `left` while chrome sized to the container subtracts
+     * both.
+     */
+    readonly gutters: {
+        readonly left: number;
+        readonly right: number;
+    };
+    /**
+     * The shared x→pixel scale, mapping into `[0, plot.width]`. Callable
+     * (`value → px`) with `invert` / `ticks` / `tickFormat`, whichever kind the
+     * container resolved (see {@link ChartXScale}).
+     *
+     * **Not the same thing as `<ChartContainer xScale>`**, which is a string
+     * naming how a *value* axis spaces itself (`'linear' | 'log' | 'symlog'`).
+     * This is the built scale object that choice — along with the data's kind,
+     * `origin`, `discontinuities` and `categories` — resolves to.
+     */
+    readonly xScale: ChartXScale;
+    /**
+     * Which **kind** of x axis resolved: `'time'`, `'value'` or `'category'`.
+     * `'category'` is exactly when {@link bands} is non-null.
+     *
+     * Distinct from `<ChartContainer xScale>` again: that picks the spacing
+     * *within* a value axis, this says whether the axis is a value axis at all.
+     */
+    readonly xKind: 'time' | 'value' | 'category';
+    /** Ordinal slot geometry on a `'category'` axis; `null` otherwise. */
+    readonly bands: ChartBands | null;
+    /** Row-scoped y geometry — `null` outside a `<ChartRow>`. */
+    readonly row: ChartFrameRow | null;
+}
+/**
+ * Read the container's resolved plot geometry — the plot rect, the axis
+ * gutters, the shared x scale, the row's y scales, and (on a category axis)
+ * the ordinal slot edges. See the module docblock for the x/y split, the
+ * placement-scoped `row` half, and which box each pixel value is relative to.
+ *
+ * Must be called under a `<ChartContainer>`; throws otherwise. To render the
+ * markup *outside* the chart's box, portal it out (`createPortal`) — context
+ * flows through portals.
+ */
+export declare function useChartFrame(): ChartFrame;
+//# sourceMappingURL=useChartFrame.d.ts.map