@pond-ts/charts 0.57.0 → 0.59.0

package/dist/XAxis.js

@@ -2,7 +2,8 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
 import { Fragment, useContext } from 'react';
 import { scaleLinear } from 'd3-scale';
 import { derivedTicks } from './derivedTicks.js';
-import { ContainerContext, CursorContext } from './context.js';
+import { ContainerContext, CursorContext, } from './context.js';
+import { xAxisCursorEntries } from './cursors.js';
 import { axisPillStyle } from './chip.js';
 import { resolveAxisFormat, resolveTimeFormat, } from './format.js';
 /** Tick strip height (mark + value label) in CSS px. */
@@ -65,16 +66,19 @@ export function XAxis({ format, label, side = 'bottom', height, ticks: customTic
     // gridlines and `formatTime` use, so labels and grid stay on the same instants
     // (width-derived on a trading-time axis).
     const { xScale, plotWidth, leftGutter, theme, formatTime, xKind, xTickCount, } = container;
-    // The crosshair's x-time pill: when the container cursor is `'crosshair'` and a
-    // cursor is live in-bounds, pin the hovered time to this axis (covering the
-    // tick behind it), matching the on-axis y value pills the rows draw. Gated on
-    // the container default, so a per-row `cursor` override doesn't reach here.
+    // The cursor's x-axis slot: did the mounted cursor in effect register one
+    // (`renderXAxis` — the crosshair's time pill)? While hovering, that is the
+    // **hovered row's** effective cursor — so a per-row override reaches this
+    // axis, which the old `container.cursor === 'crosshair'` string gate never
+    // let it do (a row-level crosshair had no time pill); with no live pointer
+    // (a controlled `trackerPosition`), any scope's effective cursor keeps its
+    // pill. The slot renders below when the cursor is live in-bounds.
     const cursorX = cursor.cursorX;
-    const showCursorTag = container.cursor === 'crosshair' &&
+    const xSlotEntries = xAxisCursorEntries(container.cursors, cursor.cursorRowKey).filter((e) => e.spec.renderXAxis !== undefined);
+    const showCursorTag = xSlotEntries.length > 0 &&
         cursorX !== null &&
         cursorX >= 0 &&
         cursorX <= plotWidth;
-    const cursorColor = theme.cursor ?? theme.axis.label;
     const annotationColor = theme.annotation?.color ?? '#0d9488';
     // Derived-unit (`transform`) layout: nice ticks in the derived unit at
     // mixed step sizes, admitted where they keep pixel room (see derivedTicks).
@@ -417,20 +421,34 @@ export function XAxis({ format, label, side = 'bottom', height, ticks: customTic
                                 [onTop ? 'bottom' : 'top']: `${laneY}px`,
                                 zIndex: 2,
                             }, children: t.text })] }, t.id));
-            }), showCursorTag && (_jsxs(Fragment, { children: [_jsx("div", { style: {
-                            position: 'absolute',
-                            left: `${cursorX}px`,
-                            [onTop ? 'bottom' : 'top']: 0,
-                            width: '1px',
-                            height: `${pillOffset}px`,
-                            background: cursorColor,
-                            zIndex: 3,
-                        } }), _jsx("div", { style: {
-                            ...axisPillStyle(theme, cursorColor),
-                            left: `${cursorX}px`,
-                            transform: 'translateX(-50%)',
-                            [onTop ? 'bottom' : 'top']: `${pillOffset}px`,
-                            zIndex: 3,
-                        }, children: readoutFmt(+xScale.invert(cursorX)) })] }))] }));
+            }), showCursorTag &&
+                (() => {
+                    // The x-axis {@link ResolvedCursorFrame}: no row, no samples — the
+                    // slot draws a pill from the resolved cursor x + the axis's own
+                    // readout-formatted time (this axis's precedence chain, `readoutFmt`),
+                    // placed per the strip's side + tick-label offset.
+                    const f = {
+                        cursorX,
+                        cursorY: null,
+                        rowKey: null,
+                        hoveredRowKey: cursor.cursorRowKey,
+                        samples: [],
+                        flags: [],
+                        pointer: null,
+                        band: null,
+                        bandY: null, // …nor a transposed one: same reason as `rect`
+                        bandLine: false,
+                        bandDragging: false, // no band in the axis strip to edge
+                        rect: null, // …and no 2-D brush: the strip has no y
+                        restingCross: false,
+                        formattedTime: readoutFmt(+xScale.invert(cursorX)),
+                        plotWidth,
+                        rowHeight: 0,
+                        isFirstRow: false,
+                        theme,
+                        xAxis: { onTop, pillOffset },
+                    };
+                    return xSlotEntries.map((e, i) => (_jsx(Fragment, { children: e.spec.renderXAxis(f) }, `cursor-${i}`)));
+                })()] }));
 }
 //# sourceMappingURL=XAxis.js.map

package/dist/YAxis.d.ts

@@ -46,8 +46,64 @@ export interface YAxisProps {
      *
      * A dev-mode warning fires for the cases that are unambiguously a mistake: a
      * refused bound, negative data, or an axis with no positive data at all.
+     *
+     * `'symlog'` is **linear through zero, logarithmic beyond** — for data that
+     * spans orders of magnitude *on both sides of zero*, which `'log'` cannot
+     * express at all (it admits no zero and no negatives). The linear window is
+     * {@link linearWindow}. Because it admits zero, it resolves its domain on the
+     * ordinary **linear** path: no positive-only bound refusal, no rounding out to
+     * decades, no gapping of non-positive samples.
+     *
+     * **The axis owns tick placement, and that is the substance of the feature.**
+     * d3's symlog supplies the transform but ticks it *linearly*, which on a ±1M
+     * domain with a 20k knee labels nothing below the knee — the exact region the
+     * scale was chosen to reveal. pond grids it on zero, the knee (±`linearWindow ×
+     * maxAbs`) and mirrored decades beyond, thinned by the same rule the log axis
+     * uses. See `yticks.ts`.
+     *
+     * **The curve is `log1p`, not piecewise — read this before replacing a
+     * hand-rolled one.** "Linear through zero, logarithmic beyond" describes how the
+     * axis *reads*, not two joined segments: `scaleSymlog` is the single smooth
+     * `sign(x) · log1p(|x / knee|)`, so there is no exact boundary at which one law
+     * stops and the other starts. A common hand-rolled curve *is* piecewise —
+     * exactly linear below the knee, `log10` above — and the two are the same family
+     * with materially different shape. Swapping one for the other, a reporting
+     * consumer measured small values landing at **roughly half** their former height
+     * (a ±9M domain: 283k went from 0.44 to 0.24 of the half-plot above the zero
+     * line), while order, the dominance of the tail, and a several-fold lift over a
+     * linear axis all held — the chart still says the same thing, but it does not
+     * say it identically.
+     *
+     * **No `linearWindow` recovers a piecewise shape.** The same consumer tried: a
+     * smaller window fits the large values while overshooting the small ones about
+     * 2×, because the difference is the curve, not the knee. If you need the
+     * piecewise curve exactly, you need your own transform — which is the thing this
+     * scale exists to let you delete, so weigh that before reaching for it.
+     */
+    scale?: 'linear' | 'log' | 'symlog';
+    /**
+     * `scale="symlog"`'s **linear window**, as a fraction of the domain's largest
+     * magnitude. **Default `0.02`** — the knee sits at 2% of `maxAbs`, so a ±1M
+     * domain is linear through ±20k and logarithmic beyond. Ignored on any other
+     * scale.
+     *
+     * **Domain-relative, not absolute** (d3's own `constant` is absolute). A chart
+     * that re-keys to the largest magnitude on every update would otherwise need
+     * the constant recomputed each tick, and would drift silently the moment
+     * someone forgot — the fraction survives a domain change with no call-site
+     * arithmetic at all.
+     *
+     * Precisely: a fraction of the **resolved domain before any pan/zoom** — the
+     * one the axis's `min`/`max`/`pad`/auto-fit produce. A 2-D gesture is carried
+     * as a *pixel* transform and the knee is deliberately **not** recomputed from
+     * the zoomed window, so zooming moves the plot without moving the boundary
+     * between the two régimes underneath it. (Recomputing would make the same
+     * datum linear at one zoom level and logarithmic at the next.)
+     *
+     * A value outside `(0, 1]` cannot be a knee; the axis draws with the default
+     * instead and dev-warns which window is in force.
      */
-    scale?: 'linear' | 'log';
+    linearWindow?: number;
     /** Explicit domain bounds; omit to auto-fit the charts linked to this axis. */
     min?: number;
     max?: number;
@@ -155,5 +211,5 @@ export interface YAxisProps {
  * tick marks + labels from that scale. Charts attach via `<LineChart axis="id">`
  * (default: the first axis).
  */
-export declare function YAxis({ id, side, label, scale, min, max, format, ticks, tickCount, pad, boundaryLabels, width, hide, labelPlacement, color, index, }: YAxisProps): import("react/jsx-runtime").JSX.Element | null;
+export declare function YAxis({ id, side, label, scale, linearWindow, min, max, format, ticks, tickCount, pad, boundaryLabels, width, hide, labelPlacement, color, index, }: YAxisProps): import("react/jsx-runtime").JSX.Element | null;
 //# sourceMappingURL=YAxis.d.ts.map

package/dist/YAxis.js

@@ -17,7 +17,7 @@ const DEFAULT_TICK_COUNT = 5;
  * tick marks + labels from that scale. Charts attach via `<LineChart axis="id">`
  * (default: the first axis).
  */
-export function YAxis({ id, side = 'left', label, scale = 'linear', min, max, format, ticks, tickCount, pad = 0, boundaryLabels = true, width = DEFAULT_WIDTH, hide = false, labelPlacement = 'rotated', color, index = 0, }) {
+export function YAxis({ id, side = 'left', label, scale = 'linear', linearWindow, min, max, format, ticks, tickCount, pad = 0, boundaryLabels = true, width = DEFAULT_WIDTH, hide = false, labelPlacement = 'rotated', color, index = 0, }) {
     const container = useContext(ContainerContext);
     if (container === null) {
         throw new Error('<YAxis> must be rendered inside a <ChartContainer>');
@@ -35,6 +35,7 @@ export function YAxis({ id, side = 'left', label, scale = 'linear', min, max, fo
         // and layers still bind to it, which is the whole point of the prop.
         width: hide ? 0 : width,
         scale,
+        linearWindow,
         min,
         max,
         pad,
@@ -49,6 +50,7 @@ export function YAxis({ id, side = 'left', label, scale = 'linear', min, max, fo
         width,
         hide,
         scale,
+        linearWindow,
         min,
         max,
         pad,

package/dist/area.d.ts

@@ -1,6 +1,6 @@
 import { type CurveFactory } from 'd3-shape';
 import type { ChartSeries } from './data.js';
-import { type Scale } from './line.js';
+import { type Scale, type TraceState } from './line.js';
 import type { AreaStyle } from './theme.js';
 import type { LayerDrawStats } from './context.js';
 import { type GapMode } from './gaps.js';
@@ -70,4 +70,37 @@ export declare function areaExtent(cs: ChartSeries, baseline: number | undefined
  * 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;
+/**
+ * **Is the pointer inside this area?** The filled-region counterpart of
+ * `traceHitIndex` ([PND-TRACESEL]) — returns the nearest sample's index as
+ * click provenance, or `null` when the pointer is outside the fill.
+ *
+ * An area is not a stroke, so the test is not distance-to-path: the pointer is
+ * on the area when it lies **between the trace and the baseline** at that x.
+ * That is the honest reading of "you clicked the area", and it makes the whole
+ * filled shape the target rather than a 1.5px edge — which is the same reason
+ * the list family made the row the target rather than the bar.
+ *
+ * The x cut bisects `xScale(cs.x[i])` for `traceHitIndex`'s reasons (a layer's
+ * `hitTest` gets the forward scale only, and a trading-time scale has no honest
+ * inverse), and the trace's y is **interpolated** between the bracketing
+ * samples so the boundary follows the drawn edge rather than a step. A tolerance
+ * is still added, so the top edge is grabbable from just outside.
+ *
+ * A gap is a hole, not a bridge: either bracketing sample non-finite ⇒ no hit,
+ * matching what `drawArea` actually fills.
+ */
+export declare function areaHitIndex(cs: ChartSeries, baseline: number | undefined, px: number, py: number, xScale: Scale, yScale: Scale, tolerance?: number): number | null;
+/**
+ * The style an area fills with in a given interaction state
+ * ([PND-TRACESEL]) — the {@link AreaStyle} counterpart of `traceStateStyle`.
+ *
+ * The channels differ from a line's because what carries the mark differs: an
+ * area's mark is its **fill**, so state is the fill's strength plus the edge's
+ * weight. A line has only a stroke, so there weight is all there is.
+ *
+ * Alpha comes back separately, as it does for a line, so a muted area keeps its
+ * hue rather than having the fade baked into a colour.
+ */
+export declare function areaStateStyle(style: AreaStyle, state: TraceState): readonly [AreaStyle, number];
 //# sourceMappingURL=area.d.ts.map

package/dist/area.js

@@ -1,5 +1,5 @@
 import { area as d3area, curveLinear } from 'd3-shape';
-import { strokeAffinePolyline } from './line.js';
+import { baselinePxFromScale, 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';
@@ -345,4 +345,91 @@ function buildGradient(ctx, valueExtent, yScale, baselinePx, style) {
     }
     return grad;
 }
+/**
+ * **Is the pointer inside this area?** The filled-region counterpart of
+ * `traceHitIndex` ([PND-TRACESEL]) — returns the nearest sample's index as
+ * click provenance, or `null` when the pointer is outside the fill.
+ *
+ * An area is not a stroke, so the test is not distance-to-path: the pointer is
+ * on the area when it lies **between the trace and the baseline** at that x.
+ * That is the honest reading of "you clicked the area", and it makes the whole
+ * filled shape the target rather than a 1.5px edge — which is the same reason
+ * the list family made the row the target rather than the bar.
+ *
+ * The x cut bisects `xScale(cs.x[i])` for `traceHitIndex`'s reasons (a layer's
+ * `hitTest` gets the forward scale only, and a trading-time scale has no honest
+ * inverse), and the trace's y is **interpolated** between the bracketing
+ * samples so the boundary follows the drawn edge rather than a step. A tolerance
+ * is still added, so the top edge is grabbable from just outside.
+ *
+ * A gap is a hole, not a bridge: either bracketing sample non-finite ⇒ no hit,
+ * matching what `drawArea` actually fills.
+ */
+export function areaHitIndex(cs, baseline, px, py, xScale, yScale, tolerance = TRACE_HIT_PX) {
+    const n = cs.length;
+    if (n === 0)
+        return null;
+    let lo = 0;
+    let hi = n;
+    while (lo < hi) {
+        const mid = (lo + hi) >> 1;
+        if (xScale(cs.x[mid]) < px)
+            lo = mid + 1;
+        else
+            hi = mid;
+    }
+    // The bracketing pair around the pointer. At either end of the series the
+    // pair degenerates to one sample, which is correct — the fill stops there.
+    const i = Math.max(0, Math.min(n - 1, lo));
+    const j = Math.max(0, Math.min(n - 1, lo === 0 ? 0 : lo - 1));
+    const yi = cs.y[i];
+    const yj = cs.y[j];
+    if (!Number.isFinite(yi) || !Number.isFinite(yj))
+        return null;
+    const xi = xScale(cs.x[i]);
+    const xj = xScale(cs.x[j]);
+    // Interpolate the edge at the pointer's x, so the boundary is the drawn
+    // slope and not a staircase. Guard the degenerate same-pixel pair.
+    const t = xi === xj ? 0 : (px - xj) / (xi - xj);
+    const edgePx = yScale(yj + (yi - yj) * Math.max(0, Math.min(1, t)));
+    const basePx = baseline === undefined ? baselinePxFromScale(yScale) : yScale(baseline);
+    const top = Math.min(edgePx, basePx) - tolerance;
+    const bottom = Math.max(edgePx, basePx) + tolerance;
+    if (py < top || py > bottom)
+        return null;
+    // Outside the series' own x span there is no fill to be inside of.
+    if (px < xScale(cs.x[0]) - tolerance)
+        return null;
+    if (px > xScale(cs.x[n - 1]) + tolerance)
+        return null;
+    return Math.abs(px - xi) <= Math.abs(px - xj) ? i : j;
+}
+/**
+ * The style an area fills with in a given interaction state
+ * ([PND-TRACESEL]) — the {@link AreaStyle} counterpart of `traceStateStyle`.
+ *
+ * The channels differ from a line's because what carries the mark differs: an
+ * area's mark is its **fill**, so state is the fill's strength plus the edge's
+ * weight. A line has only a stroke, so there weight is all there is.
+ *
+ * Alpha comes back separately, as it does for a line, so a muted area keeps its
+ * hue rather than having the fade baked into a colour.
+ */
+export function areaStateStyle(style, state) {
+    const emphasised = {
+        ...style,
+        width: style.selectedWidth ?? style.width * 2,
+        fillOpacity: style.selectedFillOpacity ?? Math.min(style.fillOpacity * 2, 1),
+    };
+    switch (state) {
+        case 'selected':
+            return [emphasised, 1];
+        case 'hover':
+            return [emphasised, 1];
+        case 'dimmed':
+            return [style, style.dimmedOpacity ?? 0.32];
+        case 'rest':
+            return [style, 1];
+    }
+}
 //# sourceMappingURL=area.js.map

package/dist/bars.d.ts

@@ -1,7 +1,7 @@
 import type { BarSeries, StackedBarSeries } from './data.js';
 import type { Scale } from './line.js';
 import type { BarStyle } from './theme.js';
-import type { LayerDrawStats } from './context.js';
+import type { LayerDrawStats, SpanSelection } from './context.js';
 import { type DecimateOption } from './decimate.js';
 /**
  * Bar growth direction — the histogram orientation. `'vertical'` bars grow **up**
@@ -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.
@@ -146,6 +146,21 @@ export interface BarMark {
     readonly key: number;
     readonly mark?: string;
 }
+/**
+ * Stroke a selected mark's outline **inside** its ink rect. Canvas strokes
+ * centre on the path, so a plain `strokeRect(x0, yTop, …)` paints
+ * `lineWidth / 2` *outside* the rect — which, with the default
+ * `outlineWidth: 1.5` against the default `gap: 1`, is enough to bridge the
+ * whole inter-bar gap from both sides: a swept run of selected bars fused
+ * into one unreadable block (you could not count them). Insetting the path by
+ * half the line width keeps every stroked pixel within the bar's own ink, so
+ * adjacent selected marks stay separated by exactly the gap the resting bars
+ * show. A mark too thin to contain its outline (either dimension
+ * `<= lineWidth`) skips the stroke — the highlight fill is already the
+ * signal, and an outline wider than the bar would only smear into the
+ * neighbours this exists to keep distinct.
+ */
+export declare function strokeSelectedOutline(ctx: CanvasRenderingContext2D, x0: number, x1: number, yTop: number, yBottom: number, lineWidth: number): void;
 /**
  * Fill one rectangle per bar in `cs`, each spanning its key's `[begin, end]`
  * (inset by `gapPx`) from the resolved `baseline` to the value.
@@ -198,7 +213,7 @@ export interface BarMark {
  * repaint them one flat colour; per-bar-coloured layers draw every visible bar.
  * Returns {@link LayerDrawStats} for `onDrawStats`.
  */
-export declare function drawBars(ctx: CanvasRenderingContext2D, cs: BarSeries, xScale: Scale, yScale: Scale, style: BarStyle, baseline: number, gapPx: number, seriesId: string | undefined, selection: BarMark | null, hovered: BarMark | null, decimate?: DecimateOption, binFills?: readonly (string | undefined)[], banding?: BandLadder): LayerDrawStats;
+export declare function drawBars(ctx: CanvasRenderingContext2D, cs: BarSeries, xScale: Scale, yScale: Scale, style: BarStyle, baseline: number, gapPx: number, seriesId: string | undefined, selection: readonly BarMark[], hovered: readonly BarMark[], decimate?: DecimateOption, binFills?: readonly (string | undefined)[], banding?: BandLadder, spans?: readonly SpanSelection[]): LayerDrawStats;
 /**
  * The index of the bar whose key span `[begin, end]` contains `time` — the bar
  * **under the cursor** — or `-1` if `time` falls in no bar's span. This is the
@@ -291,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
@@ -335,6 +353,45 @@ export interface StackStyle {
      * resting and live, only the floor.
      */
     readonly emphasisOpacity?: number;
+    /**
+     * Fill for a segment **not** in a non-empty selection set — the themed
+     * de-emphasis ([PND-MULTISEL], RFC A2.3). Unset ⇒ nothing dims, so this is
+     * opt-in and back-compatible. Unlike {@link highlight}, this **does** apply
+     * over {@link binFills}: dimming is about recession, not identity, so a
+     * zone-coloured bar can recede without its colour changing meaning — the
+     * dimmed value simply replaces it while it is out of the set.
+     */
+    readonly dimmed?: string;
+    /**
+     * Per-group {@link dimmed}, parallel to {@link fills} — the resolved
+     * `theme.bar.default.groupsDimmed` ramp. Set only for a **group-ramped**
+     * stack; `undefined` falls back to the flat {@link dimmed}.
+     *
+     * A stack dimmed to one colour stops being a stack — the segment boundaries
+     * vanish and the receded bins read as solid blocks, which is exactly the
+     * structure a selection wants to keep visible for comparison.
+     */
+    readonly dimmedFills?: readonly string[];
+    /**
+     * Per-group {@link hover}, parallel to {@link fills} — the resolved
+     * `theme.bar.default.groupsHover` ramp. Set only for a **group-ramped**
+     * stack; `undefined` falls back to the flat {@link hover}.
+     *
+     * A single hover colour repaints the pointed-at segment in a hue belonging
+     * to another group, so hovering erases the ramp exactly where the reader is
+     * looking — and block-scoped hover erases the whole bin.
+     */
+    readonly hoverFills?: readonly string[];
+    /**
+     * Whether {@link fills} carry **group identity** (a resolved group ramp)
+     * rather than being one repeated role colour.
+     *
+     * When they do, a selected segment keeps its own fill and the outline plus
+     * the receded neighbours are the cue — the same exclusion {@link binFills}
+     * already gets, and for the same reason: replacing a meaning-carrying colour
+     * with the flat `highlight` destroys the thing the selection is *about*.
+     */
+    readonly groupColored?: boolean;
 }
 /** The narrowed selection / hover identity a stacked segment matches against:
  *  the series `id`, the bin's `begin` (its `key`), and the group (its `label`).
@@ -403,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
@@ -418,7 +475,7 @@ export declare function segmentRect(ss: StackedBarSeries, b: number, g: number,
  *
  * O(N·G) over bins × groups, one fill (+ optional stroke) per drawn segment.
  */
-export declare function drawStacks(ctx: CanvasRenderingContext2D, ss: StackedBarSeries, orientation: Orientation, xScale: Scale, yScale: Scale, style: StackStyle, gapPx: number, minSpanPx: number, seriesId: string | undefined, selection: StackMark | null, hover: StackMark | null, banding?: BandLadder): void;
+export declare function drawStacks(ctx: CanvasRenderingContext2D, ss: StackedBarSeries, orientation: Orientation, xScale: Scale, yScale: Scale, style: StackStyle, gapPx: number, minSpanPx: number, seriesId: string | undefined, selection: readonly StackMark[], hover: readonly StackMark[], banding?: BandLadder, spans?: readonly SpanSelection[]): void;
 /**
  * Hit-test plot-pixel `(px, py)` against `ss`'s stacked segments — the **first**
  * segment whose rect contains the point, or `null`. The geometry is
@@ -430,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