@pond-ts/charts 0.58.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/bars.d.ts

@@ -55,7 +55,7 @@ export declare function resolveBarBaseline(yScale: Scale): number;
  * hit region are deliberately *not* the same geometry: the `gapPx` inset
  * separates columns visually without carving a dead channel out of the target.
  */
-export declare function barRect(cs: BarSeries, i: number, xScale: Scale, yScale: Scale, baseline: number, gapPx: number, minWidthPx: number): [x0: number, x1: number, yTop: number, yBottom: number] | null;
+export declare function barRect(cs: BarSeries, i: number, xScale: Scale, yScale: Scale, baseline: number, gapPx: number, minWidthPx: number, maxWidthPx?: number): [x0: number, x1: number, yTop: number, yBottom: number] | null;
 /**
  * The value-space span `[lo, hi]` of **threshold band `k`** along a bar running
  * from `base` to `v`, or `null` when the bar doesn't reach that band.
@@ -306,6 +306,9 @@ export interface StackStyle {
     readonly fills: readonly string[];
     readonly opacity: number;
     readonly outlineWidth: number;
+    /** Cap on a segment's ink span in px, centred in the slot — the stacked
+     *  counterpart of `BarStyle.maxWidth` ([PND-BARWIDTH]). Omitted ⇒ uncapped. */
+    readonly maxWidth?: number;
     /**
      * Optional **per-bin** fill override, aligned index-for-index to the bins
      * (bin `b` uses `binFills[b]`), taking precedence over the per-group
@@ -457,7 +460,7 @@ export declare function stackBase(orientation: Orientation, xScale: Scale, yScal
  * is unfloored. Shared by {@link drawStacks} and {@link stackAt} so the drawn rect
  * and the hit rect are identical.
  */
-export declare function segmentRect(ss: StackedBarSeries, b: number, g: number, orientation: Orientation, xScale: Scale, yScale: Scale, cumBefore: number, gapPx: number, minSpanPx: number): [x0: number, x1: number, yTop: number, yBottom: number] | null;
+export declare function segmentRect(ss: StackedBarSeries, b: number, g: number, orientation: Orientation, xScale: Scale, yScale: Scale, cumBefore: number, gapPx: number, minSpanPx: number, maxSpanPx?: number): [x0: number, x1: number, yTop: number, yBottom: number] | null;
 /**
  * Fill every segment of every bin in `ss`, stacking each bin's groups from the
  * value baseline outward (bottom → top vertical, left → right horizontal). A gap
@@ -484,5 +487,9 @@ export declare function drawStacks(ctx: CanvasRenderingContext2D, ss: StackedBar
  * O(N·G) over bins × groups (no spatial index — histogram bin/group counts are
  * small; click / hover are cheap events).
  */
-export declare function stackAt(ss: StackedBarSeries, px: number, py: number, orientation: Orientation, xScale: Scale, yScale: Scale, gapPx: number, minSpanPx: number): [bin: number, group: number, begin: number, name: string, value: number] | null;
+export declare function stackAt(ss: StackedBarSeries, px: number, py: number, orientation: Orientation, xScale: Scale, yScale: Scale, gapPx: number, minSpanPx: number, 
+/** Must match the draw's cap ([PND-BARWIDTH]) — this function's whole
+ *  contract is that its rect is the drawn rect, so a cap applied to one and
+ *  not the other silently drifts the hit target off the ink. */
+maxSpanPx?: number): [bin: number, group: number, begin: number, name: string, value: number] | null;
 //# sourceMappingURL=bars.d.ts.map

package/dist/bars.js

@@ -73,11 +73,11 @@ export function resolveBarBaseline(yScale) {
  * hit region are deliberately *not* the same geometry: the `gapPx` inset
  * separates columns visually without carving a dead channel out of the target.
  */
-export function barRect(cs, i, xScale, yScale, baseline, gapPx, minWidthPx) {
+export function barRect(cs, i, xScale, yScale, baseline, gapPx, minWidthPx, maxWidthPx) {
     const v = cs.y[i];
     if (!Number.isFinite(v))
         return null;
-    const [x0, x1] = barSpanPx(cs.begin[i], cs.end[i], xScale, gapPx, minWidthPx);
+    const [x0, x1] = barSpanPx(cs.begin[i], cs.end[i], xScale, gapPx, minWidthPx, maxWidthPx);
     const yValue = yScale(v);
     const yBase = yScale(baseline);
     return [x0, x1, Math.min(yValue, yBase), Math.max(yValue, yBase)];
@@ -430,7 +430,7 @@ spans = NO_SPANS) {
         : null;
     let drawn = 0;
     for (let i = vStart; i < vEnd; i += 1) {
-        const rect = barRect(cs, i, xScale, yScale, baseline, gapPx, style.minWidth);
+        const rect = barRect(cs, i, xScale, yScale, baseline, gapPx, style.minWidth, style.maxWidth);
         if (rect === null)
             continue;
         const [x0, x1, yTop, yBottom] = rect;
@@ -779,7 +779,7 @@ export function stackBase(orientation, xScale, yScale) {
  * is unfloored. Shared by {@link drawStacks} and {@link stackAt} so the drawn rect
  * and the hit rect are identical.
  */
-export function segmentRect(ss, b, g, orientation, xScale, yScale, cumBefore, gapPx, minSpanPx) {
+export function segmentRect(ss, b, g, orientation, xScale, yScale, cumBefore, gapPx, minSpanPx, maxSpanPx) {
     const G = ss.groups.length;
     const v = ss.values[b * G + g];
     // Skip non-finite (a gap) or zero (a zero-extent rect that can't draw or be
@@ -801,12 +801,12 @@ export function segmentRect(ss, b, g, orientation, xScale, yScale, cumBefore, ga
     if (!Number.isFinite(v) || v === 0)
         return null;
     if (orientation === 'vertical') {
-        const [x0, x1] = barSpanPx(ss.begin[b], ss.end[b], xScale, gapPx, minSpanPx);
+        const [x0, x1] = barSpanPx(ss.begin[b], ss.end[b], xScale, gapPx, minSpanPx, maxSpanPx);
         const yA = yScale(cumBefore);
         const yB = yScale(cumBefore + v);
         return [x0, x1, Math.min(yA, yB), Math.max(yA, yB)];
     }
-    const [y0, y1] = barSpanPx(ss.begin[b], ss.end[b], yScale, gapPx, minSpanPx);
+    const [y0, y1] = barSpanPx(ss.begin[b], ss.end[b], yScale, gapPx, minSpanPx, maxSpanPx);
     const xA = xScale(cumBefore);
     const xB = xScale(cumBefore + v);
     return [Math.min(xA, xB), Math.max(xA, xB), y0, y1];
@@ -865,7 +865,7 @@ spans = NO_SPANS) {
         let cumNeg = base;
         for (let g = 0; g < G; g += 1) {
             const v = ss.values[b * G + g];
-            const rect = segmentRect(ss, b, g, orientation, xScale, yScale, v < 0 ? cumNeg : cumPos, gapPx, minSpanPx);
+            const rect = segmentRect(ss, b, g, orientation, xScale, yScale, v < 0 ? cumNeg : cumPos, gapPx, minSpanPx, style.maxWidth);
             if (Number.isFinite(v)) {
                 if (v > 0)
                     cumPos += v;
@@ -1011,7 +1011,11 @@ spans = NO_SPANS) {
  * O(N·G) over bins × groups (no spatial index — histogram bin/group counts are
  * small; click / hover are cheap events).
  */
-export function stackAt(ss, px, py, orientation, xScale, yScale, gapPx, minSpanPx) {
+export function stackAt(ss, px, py, orientation, xScale, yScale, gapPx, minSpanPx, 
+/** Must match the draw's cap ([PND-BARWIDTH]) — this function's whole
+ *  contract is that its rect is the drawn rect, so a cap applied to one and
+ *  not the other silently drifts the hit target off the ink. */
+maxSpanPx) {
     const G = ss.groups.length;
     const base = stackBase(orientation, xScale, yScale);
     for (let b = 0; b < ss.length; b += 1) {
@@ -1021,7 +1025,7 @@ export function stackAt(ss, px, py, orientation, xScale, yScale, gapPx, minSpanP
         let cumNeg = base;
         for (let g = 0; g < G; g += 1) {
             const v = ss.values[b * G + g];
-            const rect = segmentRect(ss, b, g, orientation, xScale, yScale, v < 0 ? cumNeg : cumPos, gapPx, minSpanPx);
+            const rect = segmentRect(ss, b, g, orientation, xScale, yScale, v < 0 ? cumNeg : cumPos, gapPx, minSpanPx, maxSpanPx);
             if (Number.isFinite(v)) {
                 if (v > 0)
                     cumPos += v;

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,
@@ -1597,17 +1619,17 @@ export interface LayerEntry {
 }
 /** A y-axis declared in a {@link ChartRow} via `<YAxis>`. */
 /** Which scale a y axis maps its domain through. */
-export type YScaleKind = 'linear' | 'log';
+export type YScaleKind = 'linear' | 'log' | 'symlog';
 /**
- * A row's resolved y scale — d3's `scaleLinear()`, or `scaleLog()` when the
- * axis asks for `scale="log"`.
+ * A row's resolved y scale — d3's `scaleLinear()`, `scaleLog()` when the axis
+ * asks for `scale="log"`, or `scaleSymlog()` for `scale="symlog"`.
  *
  * Deliberately the **continuous-numeric** supertype rather than `ScaleLinear`:
  * every consumer (the axis labels, the row's gridlines, the cursor readout, and
  * every draw layer) only ever calls it, or reads `domain` / `range` / `ticks` /
- * `tickFormat` / `invert` — the surface both scales share. Keeping the shared
- * type here is what lets a log axis be transparent to the draw layers instead
- * of every layer growing a branch.
+ * `tickFormat` / `invert` — the surface all three scales share. Keeping the
+ * shared type here is what lets a log or symlog axis be transparent to the draw
+ * layers instead of every layer growing a branch.
  */
 export type YScale = ScaleContinuousNumeric<number, number>;
 export interface AxisSpec {
@@ -1617,6 +1639,11 @@ export interface AxisSpec {
     readonly width: number;
     /** Which scale the axis maps its domain through ({@link YAxisProps.scale}). */
     readonly scale: YScaleKind;
+    /** `scale="symlog"`'s linear window as a **fraction of the domain's largest
+     *  magnitude** ({@link YAxisProps.linearWindow}) — `undefined` on any other
+     *  scale. Domain-relative rather than absolute so it survives a domain change
+     *  without a recompute ([PND-SYMLOG]). */
+    readonly linearWindow?: number | undefined;
     /** Explicit domain bounds, or `undefined` to auto-fit linked layers. */
     readonly min: number | undefined;
     readonly max: number | undefined;
@@ -1650,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/data.d.ts

@@ -499,6 +499,44 @@ export interface CategoryDatum {
     readonly label: string;
     readonly value: number;
 }
+/**
+ * One category of a **stacked** category chart ([PND-CATSTACK]) — a label plus a
+ * value **per group**, read by name through `<BarChart columns>`.
+ *
+ * The `values` record is the shape the list family already uses
+ * (`ListRow.values`), deliberately: "a row with named values" is one concept in
+ * this library and a category with several groups is exactly that. A missing or
+ * non-finite entry reads as a gap, so a group absent from one category is a hole
+ * rather than a zero — the same rule every other reader applies.
+ */
+export interface CategoryStackDatum {
+    readonly label: string;
+    readonly values: Readonly<Record<string, number | undefined>>;
+}
+/**
+ * Build a {@link StackedBarSeries} from ordered categories carrying a value
+ * **per group** — the stacked counterpart of {@link categoryStack}
+ * ([PND-CATSTACK]).
+ *
+ * Geometry is identical to the single-value case (one unit slot `[i, i+1]` per
+ * category, `marks` carrying the names), so the categorical axis derives its
+ * ordered labels exactly as before and a pinned selection still keys on the
+ * stable name. Only `groups` and the `values` layout differ, and both match
+ * {@link stacksFromColumns} — `values[i * G + g]`, bin-major — so this reaches
+ * the shipped `drawStacks` path with no new draw code.
+ *
+ * **Why this replaces a real workaround.** Composing the same picture from one
+ * `<BarChart categories>` layer per cumulative total (drawn outermost-first so
+ * each overpaints the one beneath) costs three things a first-class stack does
+ * not: hand-assembled legends, label thinning that cannot see the other layers,
+ * and — since selection entries key on `(layer id, mark)` — a controlled set
+ * that must be replicated across every segment layer, where missing one makes a
+ * selected bar recede *from the waist up*. With one layer and one `mark` per
+ * bar, that last failure is not expressible.
+ *
+ * O(n·G) with one `Float64Array` allocation, matching `stacksFromColumns`.
+ */
+export declare function categoryStacks(records: readonly CategoryStackDatum[], columns: readonly string[]): StackedBarSeries;
 /**
  * Build a {@link StackedBarSeries} (single group, `G === 1`) from an ordered list
  * of `{ label, value }` categories — one **unit slot** `[i, i+1]` per category, in

package/dist/data.js

@@ -619,6 +619,49 @@ export function stacksFromBins(bins, columns, options = {}) {
     }
     return { begin, end, groups: columns, values, length: n };
 }
+/**
+ * Build a {@link StackedBarSeries} from ordered categories carrying a value
+ * **per group** — the stacked counterpart of {@link categoryStack}
+ * ([PND-CATSTACK]).
+ *
+ * Geometry is identical to the single-value case (one unit slot `[i, i+1]` per
+ * category, `marks` carrying the names), so the categorical axis derives its
+ * ordered labels exactly as before and a pinned selection still keys on the
+ * stable name. Only `groups` and the `values` layout differ, and both match
+ * {@link stacksFromColumns} — `values[i * G + g]`, bin-major — so this reaches
+ * the shipped `drawStacks` path with no new draw code.
+ *
+ * **Why this replaces a real workaround.** Composing the same picture from one
+ * `<BarChart categories>` layer per cumulative total (drawn outermost-first so
+ * each overpaints the one beneath) costs three things a first-class stack does
+ * not: hand-assembled legends, label thinning that cannot see the other layers,
+ * and — since selection entries key on `(layer id, mark)` — a controlled set
+ * that must be replicated across every segment layer, where missing one makes a
+ * selected bar recede *from the waist up*. With one layer and one `mark` per
+ * bar, that last failure is not expressible.
+ *
+ * O(n·G) with one `Float64Array` allocation, matching `stacksFromColumns`.
+ */
+export function categoryStacks(records, columns) {
+    const n = records.length;
+    const G = columns.length;
+    const begin = new Float64Array(n);
+    const end = new Float64Array(n);
+    const values = new Float64Array(n * G);
+    const marks = new Array(n);
+    for (let i = 0; i < n; i += 1) {
+        begin[i] = i;
+        end[i] = i + 1;
+        marks[i] = records[i].label;
+        const row = records[i].values;
+        for (let g = 0; g < G; g += 1) {
+            const v = row[columns[g]];
+            // A missing key and a non-finite value are the same thing here: no bar.
+            values[i * G + g] = typeof v === 'number' && Number.isFinite(v) ? v : NaN;
+        }
+    }
+    return { begin, end, groups: columns, values, length: n, marks };
+}
 /**
  * Build a {@link StackedBarSeries} (single group, `G === 1`) from an ordered list
  * of `{ label, value }` categories — one **unit slot** `[i, i+1]` per category, in

package/dist/format.d.ts

@@ -47,6 +47,9 @@ interface Tickable {
     tickFormat(count: number, specifier?: string): (value: number) => string;
     /** Present on d3's `scaleLog` and on no other continuous scale. */
     base?: () => number;
+    /** Present on d3's `scaleSymlog` and on no other continuous scale — the linear
+     *  window's half-width in data units. */
+    constant?: () => number;
     domain?: () => number[];
 }
 /**
@@ -74,7 +77,19 @@ 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
+ * domain — and a symlog axis is chosen precisely when the interesting values are
+ * *orders of magnitude smaller* than the domain. On `[-1, 1]` with a `0.02` knee
+ * the ladder emits `-0.02, 0, 0.02` and a span-derived formatter labels all three
+ * **`"0.0"`**: three ticks at three positions asserting the same value, on the
+ * axis whose whole purpose was to separate them. Formatting through a linear
+ * scale over `[-knee, knee]` calibrates to the smallest magnitude the ladder can
+ * emit. It changes nothing when the knee is already coarse (a 20k knee on a ±1M
+ * domain formats identically), and the cursor readout inherits the same extra
+ * precision — which is wanted, since near-zero is where a symlog readout is read.
  */
 export declare function resolveAxisFormat(scale: Tickable, count: number, format: AxisFormat | undefined): (value: number) => string;
 /** The slice of a d3 **time** scale {@link resolveTimeFormat} needs. A d3

package/dist/format.js

@@ -24,14 +24,29 @@ 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
+ * domain — and a symlog axis is chosen precisely when the interesting values are
+ * *orders of magnitude smaller* than the domain. On `[-1, 1]` with a `0.02` knee
+ * the ladder emits `-0.02, 0, 0.02` and a span-derived formatter labels all three
+ * **`"0.0"`**: three ticks at three positions asserting the same value, on the
+ * axis whose whole purpose was to separate them. Formatting through a linear
+ * scale over `[-knee, knee]` calibrates to the smallest magnitude the ladder can
+ * emit. It changes nothing when the knee is already coarse (a 20k knee on a ±1M
+ * domain formats identically), and the cursor readout inherits the same extra
+ * precision — which is wanted, since near-zero is where a symlog readout is read.
  */
 export function resolveAxisFormat(scale, count, format) {
     if (typeof format === 'function')
         return format;
+    const knee = typeof scale.constant === 'function' ? Math.abs(scale.constant()) : 0;
     const source = typeof scale.base === 'function' && typeof scale.domain === 'function'
         ? scaleLinear().domain(scale.domain())
-        : scale;
+        : Number.isFinite(knee) && knee > 0
+            ? scaleLinear().domain([-knee, knee])
+            : scale;
     return format !== undefined
         ? source.tickFormat(count, format)
         : source.tickFormat(count);

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';
@@ -73,8 +76,8 @@ export type { RegionProps, BaselineProps, MarkerProps, ZoneProps, } from './anno
 export type { AnnotationKind, CreateSpec } from './context.js';
 export { YAxisIndicator, createLiveValue } from './indicators.js';
 export type { YAxisIndicatorProps, LiveValue } from './indicators.js';
-export { fromTimeSeries, bandFromTimeSeries, boxFromTimeSeries, barsFromTimeSeries, barsFromBins, ohlcFromTimeSeries, stacksFromGroups, stacksFromColumns, stacksFromBins, categoryStack, transposeRow, } from './data.js';
-export type { ChartSeries, BandSeries, BoxSeries, BoxColumns, BarSeries, OhlcSeries, OhlcColumns, StackedBarSeries, BinRecord, StacksFromBinsOptions, CategoryDatum, RowAt, TransposeRowOptions, } from './data.js';
+export { fromTimeSeries, bandFromTimeSeries, boxFromTimeSeries, barsFromTimeSeries, barsFromBins, ohlcFromTimeSeries, stacksFromGroups, stacksFromColumns, stacksFromBins, categoryStack, categoryStacks, transposeRow, } from './data.js';
+export type { ChartSeries, BandSeries, BoxSeries, BoxColumns, BarSeries, OhlcSeries, OhlcColumns, StackedBarSeries, BinRecord, StacksFromBinsOptions, CategoryDatum, CategoryStackDatum, RowAt, TransposeRowOptions, } from './data.js';
 export type { Orientation } from './bars.js';
 export type { RadiusEncoding, ColorEncoding } from './encoding.js';
 export type { Curve } from './curve.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';
@@ -68,6 +74,11 @@ export { fromTimeSeries, bandFromTimeSeries, boxFromTimeSeries, barsFromTimeSeri
 stacksFromGroups, stacksFromColumns, stacksFromBins, 
 // Categorical row-read: one bar per `{ label, value }` on the category axis.
 categoryStack, 
+// …and its stacked sibling: one bar per `{ label, values }`, segments named by
+// `columns` ([PND-CATSTACK]). Public for the same reason every reader above is
+// — a caller assembling a `StackedBarSeries` by hand needs it — and because
+// API.md already documented it as public while `index.ts` did not export it.
+categoryStacks, 
 // The transpose reader — one row of a wide series read across into categories.
 transposeRow, } from './data.js';
 export { defaultTheme, estelaTheme } from './theme.js';