@pond-ts/charts 0.31.0

package/dist/area.js

@@ -0,0 +1,186 @@
+import { area as d3area, curveLinear } from 'd3-shape';
+import { bridgeGaps, collectGapEdges, drawGapBridges, drawGapFades, drawGapSteps, withAlpha, DEFAULT_GAP_MODE, DEFAULT_GAP_CONNECTOR_OPACITY, } from './gaps.js';
+/**
+ * The `[min, max]` vertical extent an area occupies — the finite values of
+ * `cs.y` widened to include `baseline`, since the fill spans from each value to
+ * the baseline (so the baseline must be in-domain or the fill clips). `null` if
+ * no value is finite. When `baseline` is `undefined` the area rests on the
+ * axis's own lower bound (resolved later), so only the values constrain the
+ * domain — matching {@link yExtent}.
+ *
+ * NaN values (the gap signal) are ignored, so a coast doesn't drag the domain.
+ */
+export function areaExtent(cs, baseline) {
+    let min = Infinity;
+    let max = -Infinity;
+    for (let i = 0; i < cs.length; i += 1) {
+        const v = cs.y[i];
+        if (Number.isFinite(v)) {
+            if (v < min)
+                min = v;
+            if (v > max)
+                max = v;
+        }
+    }
+    if (min === Infinity)
+        return null;
+    // The fill reaches the baseline, so it must be inside the domain (an
+    // above/below-axis area with baseline 0 has to show the zero line).
+    if (baseline !== undefined) {
+        if (baseline < min)
+            min = baseline;
+        if (baseline > max)
+            max = baseline;
+    }
+    return [min, max];
+}
+/**
+ * Fill the area between `cs`'s value line and a horizontal `baseline`, with a
+ * vertical gradient (most opaque at the line, fading to transparent at the
+ * baseline) and an outline stroke on top.
+ *
+ * Two forms, selected by `baseline`:
+ *
+ * - **Elevation** (`baseline` = the axis lower bound, supplied as the resolved
+ *   `baselineValue`): the line sits above the baseline, the shade grades down
+ *   from it — the estela elevation look.
+ * - **Above/below axis** (`baseline` = `0`): positive values fill up, negative
+ *   fill down (d3's `area` handles the zero crossing in one path). The gradient
+ *   is anchored at the baseline pixel so each side grades *away* from the axis —
+ *   opaque at the line, transparent at the axis — in both directions. Compose
+ *   two layers (e.g. an "in" column and an "out" column) for the esnet
+ *   two-colour traffic look; each layer's colour is its own `as` token (the
+ *   single styling channel).
+ *
+ * **Gap handling is driven by `gaps`** (a {@link GapMode}, default `'empty'`).
+ * In every mode **the fill obeys the mode's break/bridge decision**: `'none'`
+ * fills straight across the gap (interior gaps interpolated via
+ * {@link bridgeGaps}, so the value edge bridges and the fill spans it); every
+ * other mode breaks the fill (`.defined(Number.isFinite)` — a coast is a hole in
+ * the shade, never a slab to the baseline, `docs/rfcs/charts.md` trap #2). For
+ * `'dashed'` / `'step'` / `'fade'` the **outline** (the value line on top)
+ * additionally gets an inferred bridge across each interior gap — a dashed line,
+ * a flat dashed line at the average of the edge values, or estela's
+ * fade-to-baseline — while the *fill* stays broken. `dashed` / `step` are drawn
+ * faint (`gapConnectorOpacity`). So the shade is always honest about absence;
+ * only the line offers the inferred connector.
+ *
+ * `cs.y` (a `Float64Array`) is the datum iterable; accessors read by index, so
+ * there's no per-point object allocation. The gradient + `globalAlpha` are
+ * 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) {
+    const baselinePx = yScale(baselineValue);
+    // `none` interpolates interior gaps so the fill + outline bridge them; every
+    // other mode keeps NaN so d3 breaks both (the inferred line bridge, if any, is
+    // a separate overlay pass below).
+    const ys = gaps === 'none' ? bridgeGaps(cs.y, cs.length) : cs.y;
+    const gen = d3area()
+        .defined((v) => Number.isFinite(v))
+        .x((_, i) => xScale(cs.x[i]))
+        .y0(() => baselinePx)
+        .y1((v) => yScale(v))
+        .curve(curve)
+        .context(ctx);
+    ctx.save();
+    // The fill: a vertical gradient anchored at the baseline pixel, opaque at the
+    // line and transparent at the baseline (see buildGradient — handles both the
+    // one-sided elevation form and the two-sided above/below form). The gradient
+    // spans the drawn region; `ys` (gap-bridged for `none`) is what's drawn.
+    ctx.fillStyle = buildGradient(ctx, ys, cs.length, yScale, baselinePx, style);
+    ctx.globalAlpha = style.fillOpacity;
+    ctx.beginPath();
+    gen(ys);
+    ctx.fill();
+    ctx.restore();
+    // The outline on top: the area's top edge as a line (`lineY1` inherits the
+    // area's `defined`, `curve`, and `context`, so it breaks at the same gaps),
+    // at full opacity over the graded fill.
+    const outline = gen.lineY1();
+    ctx.save();
+    ctx.beginPath();
+    outline(ys);
+    ctx.strokeStyle = style.color;
+    ctx.lineWidth = style.width;
+    ctx.stroke();
+    ctx.restore();
+    // Inferred bridges for the line edge (fill stays broken). `dashed` / `step`
+    // are faint dashed connectors (gapConnectorOpacity); only `fade` drops to the
+    // area's own baseline pixel (the fill floor).
+    if (gaps === 'dashed' || gaps === 'step' || gaps === 'fade') {
+        const edges = collectGapEdges(cs.length, cs.x, (i) => cs.y[i], xScale, (i) => yScale(cs.y[i]));
+        if (gaps === 'dashed') {
+            drawGapBridges(ctx, edges, style.color, style.width, gapConnectorOpacity);
+        }
+        else if (gaps === 'step') {
+            drawGapSteps(ctx, edges, style.color, style.width, gapConnectorOpacity);
+        }
+        else {
+            drawGapFades(ctx, edges, baselinePx, style.color, style.width);
+        }
+    }
+}
+/**
+ * A vertical `CanvasGradient` for the fill, spanning the drawn region's pixel
+ * extent (the finite values plus the baseline) and anchored so the shade is
+ * most opaque at the line and fully transparent at the baseline.
+ *
+ * - **One-sided** (all values on one side of the baseline — the elevation form,
+ *   and any single-signed traffic channel): a plain two-stop grade, opaque at
+ *   the line edge → transparent at the baseline edge.
+ * - **Two-sided** (values straddle the baseline — a signed above/below series):
+ *   a three-stop grade, opaque at the top, transparent at the baseline pixel,
+ *   opaque again at the bottom — so each side fades toward the axis.
+ *
+ * The gradient colour is `style.fill` at full alpha (the layer's `globalAlpha`
+ * carries `fillOpacity`); the transparent stop is the same colour at alpha 0.
+ * Falls back to a solid `style.fill` when the region is degenerate (a single
+ * finite point, or values exactly on the baseline) — a zero-height gradient
+ * would paint nothing.
+ */
+function buildGradient(ctx, ys, length, yScale, baselinePx, style) {
+    let topPx = Infinity; // smallest pixel y (highest on screen)
+    let bottomPx = -Infinity; // largest pixel y (lowest on screen)
+    for (let i = 0; i < length; i += 1) {
+        const v = ys[i];
+        if (!Number.isFinite(v))
+            continue;
+        const py = yScale(v);
+        if (py < topPx)
+            topPx = py;
+        if (py > bottomPx)
+            bottomPx = py;
+    }
+    if (topPx === Infinity)
+        return style.fill; // no finite values (caller no-ops)
+    // The drawn region runs from the topmost of {values, baseline} to the
+    // bottommost — the fill reaches the baseline, so include it.
+    const regionTop = Math.min(topPx, baselinePx);
+    const regionBottom = Math.max(bottomPx, baselinePx);
+    if (regionBottom - regionTop < 1e-6)
+        return style.fill; // degenerate height
+    const opaque = style.fill;
+    const transparent = withAlpha(style.fill, 0);
+    const grad = ctx.createLinearGradient(0, regionTop, 0, regionBottom);
+    // Baseline position within the region, as a 0..1 offset.
+    const baseOffset = (baselinePx - regionTop) / (regionBottom - regionTop);
+    if (baseOffset <= 1e-6 || baseOffset >= 1 - 1e-6) {
+        // One-sided: the baseline is at an edge of the region (elevation form, or a
+        // single-signed traffic channel), so a plain two-stop grade runs opaque at
+        // the line edge → transparent at the baseline edge. Both edges map to the
+        // same stop shape (0 opaque, 1 transparent) — the opaque end is always the
+        // line because the region's other extreme is the baseline.
+        grad.addColorStop(0, baseOffset <= 1e-6 ? transparent : opaque);
+        grad.addColorStop(1, baseOffset <= 1e-6 ? opaque : transparent);
+    }
+    else {
+        // Two-sided: values straddle the baseline — opaque at both extremes,
+        // transparent at the baseline pixel, so each side fades toward the axis.
+        grad.addColorStop(0, opaque);
+        grad.addColorStop(baseOffset, transparent);
+        grad.addColorStop(1, opaque);
+    }
+    return grad;
+}
+//# sourceMappingURL=area.js.map

package/dist/band.d.ts

@@ -0,0 +1,31 @@
+import { type CurveFactory } from 'd3-shape';
+import type { BandSeries } from './data.js';
+import type { Scale } from './line.js';
+import type { BandStyle } from './theme.js';
+/**
+ * The `[min, max]` vertical extent of the **drawn** band — the lowest `lower`
+ * and highest `upper` over samples where both edges are finite — or `null` if
+ * none are. Gap samples (either edge `NaN`) are excluded, matching what
+ * {@link drawBand} fills, so they don't drag the y-domain.
+ */
+export declare function bandExtent(band: BandSeries): [number, number] | null;
+/**
+ * Fill the variance envelope between `band.lower` and `band.upper`, connecting
+ * edges with `curve` (d3-shape; default linear).
+ *
+ * Built on d3-shape's `area()` (`y0`=lower, `y1`=upper). A **gap** — a sample
+ * with either edge non-finite — **breaks the fill**: a sample counts only where
+ * *both* edges are finite (`.defined`), so a gap ends the current subpath and
+ * the next finite run starts a fresh one, leaving an honest hole in the envelope
+ * (`docs/rfcs/charts.md` trap #2).
+ *
+ * Unlike {@link LineChart} / {@link AreaChart}, a band has **no `gaps` mode** — a
+ * filled envelope's break wants its own treatment (sharp edge vs. blurred),
+ * still to be designed; for now a band always breaks honestly at a gap.
+ *
+ * `band.lower` (a `Float64Array`) is the datum iterable; every accessor reads by
+ * index, so there's no per-point object allocation. `globalAlpha` carries the
+ * opacity and is restored so it doesn't leak into later layers.
+ */
+export declare function drawBand(ctx: CanvasRenderingContext2D, band: BandSeries, xScale: Scale, yScale: Scale, style: BandStyle, curve?: CurveFactory): void;
+//# sourceMappingURL=band.d.ts.map

package/dist/band.js

@@ -0,0 +1,57 @@
+import { area as d3area, curveLinear } from 'd3-shape';
+/**
+ * The `[min, max]` vertical extent of the **drawn** band — the lowest `lower`
+ * and highest `upper` over samples where both edges are finite — or `null` if
+ * none are. Gap samples (either edge `NaN`) are excluded, matching what
+ * {@link drawBand} fills, so they don't drag the y-domain.
+ */
+export function bandExtent(band) {
+    let min = Infinity;
+    let max = -Infinity;
+    for (let i = 0; i < band.length; i += 1) {
+        const lo = band.lower[i];
+        const hi = band.upper[i];
+        if (Number.isFinite(lo) && Number.isFinite(hi)) {
+            if (lo < min)
+                min = lo;
+            if (hi > max)
+                max = hi;
+        }
+    }
+    return min === Infinity ? null : [min, max];
+}
+/**
+ * Fill the variance envelope between `band.lower` and `band.upper`, connecting
+ * edges with `curve` (d3-shape; default linear).
+ *
+ * Built on d3-shape's `area()` (`y0`=lower, `y1`=upper). A **gap** — a sample
+ * with either edge non-finite — **breaks the fill**: a sample counts only where
+ * *both* edges are finite (`.defined`), so a gap ends the current subpath and
+ * the next finite run starts a fresh one, leaving an honest hole in the envelope
+ * (`docs/rfcs/charts.md` trap #2).
+ *
+ * Unlike {@link LineChart} / {@link AreaChart}, a band has **no `gaps` mode** — a
+ * filled envelope's break wants its own treatment (sharp edge vs. blurred),
+ * still to be designed; for now a band always breaks honestly at a gap.
+ *
+ * `band.lower` (a `Float64Array`) is the datum iterable; every accessor reads by
+ * index, so there's no per-point object allocation. `globalAlpha` carries the
+ * opacity and is restored so it doesn't leak into later layers.
+ */
+export function drawBand(ctx, band, xScale, yScale, style, curve = curveLinear) {
+    const gen = d3area()
+        .defined((_, i) => Number.isFinite(band.lower[i]) && Number.isFinite(band.upper[i]))
+        .x((_, i) => xScale(band.x[i]))
+        .y0((_, i) => yScale(band.lower[i]))
+        .y1((_, i) => yScale(band.upper[i]))
+        .curve(curve)
+        .context(ctx);
+    ctx.save();
+    ctx.fillStyle = style.fill;
+    ctx.globalAlpha = style.opacity;
+    ctx.beginPath();
+    gen(band.lower);
+    ctx.fill();
+    ctx.restore();
+}
+//# sourceMappingURL=band.js.map

package/dist/bars.d.ts

@@ -0,0 +1,96 @@
+import type { BarSeries } from './data.js';
+import type { Scale } from './line.js';
+import type { BarStyle } from './theme.js';
+/**
+ * The `[min, max]` vertical extent the bars occupy — the finite values of `cs.y`
+ * **widened to include `0`**, since a bar spans from its value to the baseline
+ * and the baseline must be in-domain or the bar clips. `null` if no value is
+ * finite.
+ *
+ * Including `0` is the bar analog of {@link areaExtent} pulling a fixed baseline
+ * into the domain: an all-positive series auto-fits to `[0, max]` so the bars
+ * rest on a visible floor (the zero line), and a series that straddles zero
+ * shows the zero line both above and below it. An explicit `<YAxis min>` still
+ * wins — `resolveBarBaseline` rests the bars on that floor instead. NaN values
+ * (the gap signal) are ignored, so a sparse bucket doesn't drag the domain.
+ */
+export declare function barExtent(cs: BarSeries): [number, number] | null;
+/**
+ * The value a bar rests on, in **data** units — the baseline edge opposite its
+ * value. Resolved late from the axis's own domain (so it tracks the auto-fit):
+ *
+ * - When the domain spans `0` (floor ≤ 0 ≤ top — the common all-positive
+ *   auto-fit case, since {@link barExtent} pulls `0` in): the bars rest on the
+ *   **zero line**.
+ * - When the domain sits entirely above `0` (an explicit `<YAxis min={…}>` above
+ *   zero): the bars rest on the **axis floor**, so a thin bar still reads from
+ *   the bottom of the plot rather than hanging off a zero line below it.
+ * - When the domain sits entirely below `0`: the bars hang from the **axis top**
+ *   (`0` clamped down into the domain) — the symmetric case.
+ *
+ * I.e. `0` clamped into `[floor, top]`. The domain bounds come from the plain
+ * `(value) => pixel` scale the row hands `draw`/`hitTest`; the runtime object is
+ * a d3 `ScaleLinear` carrying `.domain()`, read through a localized shape rather
+ * than widening the contract to d3-scale (same approach as `AreaChart`).
+ */
+export declare function resolveBarBaseline(yScale: Scale): number;
+/**
+ * The pixel rect of bar `i` — `[x0, x1, yTop, yBottom]`, with `x0 <= x1` and
+ * `yTop <= yBottom` — or `null` for a gap (non-finite value). The x-span comes
+ * from {@link barSpanPx} (the key's `[begin, end]`, inset by `gapPx`, floored at
+ * `minWidthPx`); the y-span runs between the value and the `baseline` pixel,
+ * normalized so a value above *or* below the baseline both yield an ascending
+ * rect. Shared by {@link drawBars} and {@link barAt} so the drawn rect and the
+ * hit rect are the same geometry.
+ */
+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;
+/**
+ * Fill one rectangle per bar in `cs`, each spanning its key's `[begin, end]`
+ * (inset by `gapPx`) from the resolved `baseline` to the value.
+ *
+ * A gap (non-finite value) is skipped — no bar, no zero-height sliver. A bar
+ * matching the current `selection` (same `begin` **and** the layer's own `label`)
+ * draws in the style's `highlight` colour **and outlined**, so a click reads back
+ * on the canvas; a bar matching `hovered` draws in `highlight` **without** the
+ * outline (a lighter "this bar is live" on pointer-over); all others use the flat
+ * `fill`. `globalAlpha` carries the fill opacity and is restored so it doesn't
+ * leak into later layers.
+ *
+ * O(N) over the events, one fill (+ optional stroke) per bar, no per-bar
+ * allocation beyond the rect tuple.
+ */
+export declare function drawBars(ctx: CanvasRenderingContext2D, cs: BarSeries, xScale: Scale, yScale: Scale, style: BarStyle, baseline: number, gapPx: number, label: string, selection: {
+    key: number;
+    label: string;
+} | null, hovered: {
+    key: number;
+    label: string;
+} | null): void;
+/**
+ * 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
+ * cursor analog of {@link barAt}'s rect-containment: unlike nearest-by-`begin`,
+ * it doesn't flip to the next bar once the cursor passes a wide bar's midpoint
+ * (the readout-on-the-wrong-bar bug). At a shared edge (`end[i] === begin[i+1]`,
+ * contiguous bars) the left bar wins (first match). A gap bar (non-finite value)
+ * still owns its span here; the caller drops it on the finiteness check, so
+ * hovering a gap reads no value — as the line/area tracker breaks at a gap.
+ *
+ * O(N) over the bars (view-scale counts; the cursor moves often but the scan is
+ * cheap and allocation-free).
+ */
+export declare function barIndexAtTime(cs: BarSeries, time: number): number;
+/**
+ * Hit-test plot-pixel `(px, py)` against `cs`'s bars — the **first** bar whose
+ * rect contains the point, or `null`. The geometry is {@link barRect}, so the
+ * hit rect is exactly the drawn rect (same `baseline`/`gapPx`/`minWidth`). The
+ * returned tuple is `[index, begin, value]` for the chart to assemble a
+ * `SelectInfo` (it owns the colour + label); keeping this layer free of the
+ * theme keeps it unit-testable without a `ChartTheme`.
+ *
+ * O(N) over the events (no spatial index — bar counts are view-scale, hundreds
+ * not millions; click is a rare event). Bars don't overlap in x for a sorted
+ * series, so "first match" is unambiguous in practice.
+ */
+export declare function barAt(cs: BarSeries, px: number, py: number, xScale: Scale, yScale: Scale, baseline: number, gapPx: number, minWidthPx: number): [index: number, begin: number, value: number] | null;
+//# sourceMappingURL=bars.d.ts.map

package/dist/bars.js

@@ -0,0 +1,171 @@
+import { barSpanPx } from './range.js';
+/**
+ * The `[min, max]` vertical extent the bars occupy — the finite values of `cs.y`
+ * **widened to include `0`**, since a bar spans from its value to the baseline
+ * and the baseline must be in-domain or the bar clips. `null` if no value is
+ * finite.
+ *
+ * Including `0` is the bar analog of {@link areaExtent} pulling a fixed baseline
+ * into the domain: an all-positive series auto-fits to `[0, max]` so the bars
+ * rest on a visible floor (the zero line), and a series that straddles zero
+ * shows the zero line both above and below it. An explicit `<YAxis min>` still
+ * wins — `resolveBarBaseline` rests the bars on that floor instead. NaN values
+ * (the gap signal) are ignored, so a sparse bucket doesn't drag the domain.
+ */
+export function barExtent(cs) {
+    let min = Infinity;
+    let max = -Infinity;
+    for (let i = 0; i < cs.length; i += 1) {
+        const v = cs.y[i];
+        if (Number.isFinite(v)) {
+            if (v < min)
+                min = v;
+            if (v > max)
+                max = v;
+        }
+    }
+    if (min === Infinity)
+        return null;
+    // The bar reaches the baseline (0), so it must be inside the domain.
+    if (0 < min)
+        min = 0;
+    if (0 > max)
+        max = 0;
+    return [min, max];
+}
+/**
+ * The value a bar rests on, in **data** units — the baseline edge opposite its
+ * value. Resolved late from the axis's own domain (so it tracks the auto-fit):
+ *
+ * - When the domain spans `0` (floor ≤ 0 ≤ top — the common all-positive
+ *   auto-fit case, since {@link barExtent} pulls `0` in): the bars rest on the
+ *   **zero line**.
+ * - When the domain sits entirely above `0` (an explicit `<YAxis min={…}>` above
+ *   zero): the bars rest on the **axis floor**, so a thin bar still reads from
+ *   the bottom of the plot rather than hanging off a zero line below it.
+ * - When the domain sits entirely below `0`: the bars hang from the **axis top**
+ *   (`0` clamped down into the domain) — the symmetric case.
+ *
+ * I.e. `0` clamped into `[floor, top]`. The domain bounds come from the plain
+ * `(value) => pixel` scale the row hands `draw`/`hitTest`; the runtime object is
+ * a d3 `ScaleLinear` carrying `.domain()`, read through a localized shape rather
+ * than widening the contract to d3-scale (same approach as `AreaChart`).
+ */
+export function resolveBarBaseline(yScale) {
+    const d = yScale.domain?.();
+    if (!d || d.length === 0)
+        return 0;
+    const floor = Math.min(d[0], d[d.length - 1]);
+    const top = Math.max(d[0], d[d.length - 1]);
+    return Math.min(Math.max(0, floor), top);
+}
+/**
+ * The pixel rect of bar `i` — `[x0, x1, yTop, yBottom]`, with `x0 <= x1` and
+ * `yTop <= yBottom` — or `null` for a gap (non-finite value). The x-span comes
+ * from {@link barSpanPx} (the key's `[begin, end]`, inset by `gapPx`, floored at
+ * `minWidthPx`); the y-span runs between the value and the `baseline` pixel,
+ * normalized so a value above *or* below the baseline both yield an ascending
+ * rect. Shared by {@link drawBars} and {@link barAt} so the drawn rect and the
+ * hit rect are the same geometry.
+ */
+export function barRect(cs, i, xScale, yScale, baseline, gapPx, minWidthPx) {
+    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 yValue = yScale(v);
+    const yBase = yScale(baseline);
+    return [x0, x1, Math.min(yValue, yBase), Math.max(yValue, yBase)];
+}
+/**
+ * Fill one rectangle per bar in `cs`, each spanning its key's `[begin, end]`
+ * (inset by `gapPx`) from the resolved `baseline` to the value.
+ *
+ * A gap (non-finite value) is skipped — no bar, no zero-height sliver. A bar
+ * matching the current `selection` (same `begin` **and** the layer's own `label`)
+ * draws in the style's `highlight` colour **and outlined**, so a click reads back
+ * on the canvas; a bar matching `hovered` draws in `highlight` **without** the
+ * outline (a lighter "this bar is live" on pointer-over); all others use the flat
+ * `fill`. `globalAlpha` carries the fill opacity and is restored so it doesn't
+ * leak into later layers.
+ *
+ * O(N) over the events, one fill (+ optional stroke) per bar, no per-bar
+ * allocation beyond the rect tuple.
+ */
+export function drawBars(ctx, cs, xScale, yScale, style, baseline, gapPx, label, selection, hovered) {
+    ctx.save();
+    ctx.globalAlpha = style.opacity;
+    for (let i = 0; i < cs.length; i += 1) {
+        const rect = barRect(cs, i, xScale, yScale, baseline, gapPx, style.minWidth);
+        if (rect === null)
+            continue;
+        const [x0, x1, yTop, yBottom] = rect;
+        // Match by key (begin) **and** label, so two series sharing a timestamp don't
+        // both light up. Both the committed selection and the transient hover use the
+        // `highlight` fill; only the selection adds the outline, so hover reads as a
+        // lighter "this bar is live" and select as the committed pick.
+        const selected = selection !== null &&
+            selection.key === cs.begin[i] &&
+            selection.label === label;
+        const isHovered = hovered !== null &&
+            hovered.key === cs.begin[i] &&
+            hovered.label === label;
+        ctx.fillStyle = selected || isHovered ? style.highlight : style.fill;
+        ctx.fillRect(x0, yTop, x1 - x0, yBottom - yTop);
+        if (selected) {
+            // The selected bar gets an outline so it reads at full strength over the
+            // (alpha'd) fills. Stroke at full opacity (reset within the save bracket).
+            ctx.globalAlpha = 1;
+            ctx.lineWidth = style.outlineWidth;
+            ctx.strokeStyle = style.highlight;
+            ctx.strokeRect(x0, yTop, x1 - x0, yBottom - yTop);
+            ctx.globalAlpha = style.opacity;
+        }
+    }
+    ctx.restore();
+}
+/**
+ * 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
+ * cursor analog of {@link barAt}'s rect-containment: unlike nearest-by-`begin`,
+ * it doesn't flip to the next bar once the cursor passes a wide bar's midpoint
+ * (the readout-on-the-wrong-bar bug). At a shared edge (`end[i] === begin[i+1]`,
+ * contiguous bars) the left bar wins (first match). A gap bar (non-finite value)
+ * still owns its span here; the caller drops it on the finiteness check, so
+ * hovering a gap reads no value — as the line/area tracker breaks at a gap.
+ *
+ * O(N) over the bars (view-scale counts; the cursor moves often but the scan is
+ * cheap and allocation-free).
+ */
+export function barIndexAtTime(cs, time) {
+    for (let i = 0; i < cs.length; i += 1) {
+        if (time >= cs.begin[i] && time <= cs.end[i])
+            return i;
+    }
+    return -1;
+}
+/**
+ * Hit-test plot-pixel `(px, py)` against `cs`'s bars — the **first** bar whose
+ * rect contains the point, or `null`. The geometry is {@link barRect}, so the
+ * hit rect is exactly the drawn rect (same `baseline`/`gapPx`/`minWidth`). The
+ * returned tuple is `[index, begin, value]` for the chart to assemble a
+ * `SelectInfo` (it owns the colour + label); keeping this layer free of the
+ * theme keeps it unit-testable without a `ChartTheme`.
+ *
+ * O(N) over the events (no spatial index — bar counts are view-scale, hundreds
+ * not millions; click is a rare event). Bars don't overlap in x for a sorted
+ * series, so "first match" is unambiguous in practice.
+ */
+export function barAt(cs, px, py, xScale, yScale, baseline, gapPx, minWidthPx) {
+    for (let i = 0; i < cs.length; i += 1) {
+        const rect = barRect(cs, i, xScale, yScale, baseline, gapPx, minWidthPx);
+        if (rect === null)
+            continue;
+        const [x0, x1, yTop, yBottom] = rect;
+        if (px >= x0 && px <= x1 && py >= yTop && py <= yBottom) {
+            return [i, cs.begin[i], cs.y[i]];
+        }
+    }
+    return null;
+}
+//# sourceMappingURL=bars.js.map

package/dist/box.d.ts

@@ -0,0 +1,59 @@
+import type { BoxSeries } from './data.js';
+import type { Scale } from './line.js';
+import type { BoxStyle } from './theme.js';
+/**
+ * The `[min, max]` vertical extent of the **drawn** boxes — the lowest `lower`
+ * whisker and highest `upper` whisker over keys where **all five** quantiles are
+ * finite — or `null` if none are. Gap keys (any quantile `NaN`) are excluded,
+ * matching what {@link drawBox} draws, so they don't drag the y-domain.
+ *
+ * Only `lower`/`upper` bound the extent: they are the outermost reach of a key
+ * (the whisker ends), so `q1`/`median`/`q3` lie within `[lower, upper]` for any
+ * well-formed quantile set and never widen it. (A malformed set where, say,
+ * `q3 > upper` would clip — that's an upstream data error, not the chart's to
+ * paper over; document, don't defend.)
+ */
+export declare function boxExtent(box: BoxSeries): [number, number] | null;
+/**
+ * The index of the box whose interval `[x, xEnd]` contains `time` — the box
+ * **under the cursor** — or `-1` if `time` is in no box. The box analog of
+ * `barIndexAtTime`: containment, not nearest-by-`begin` (which flips to the next
+ * box past a wide box's midpoint). Boxes are sorted by `x`; at a shared edge the
+ * left box wins. A gap box (some quantile non-finite) still owns its span here;
+ * the caller drops it on the finiteness check. O(N) over the boxes (view-scale).
+ */
+export declare function boxIndexAtTime(box: BoxSeries, time: number): number;
+/**
+ * How a box renders its spread (pjm17971): **`whisker`** (today's thin stems +
+ * end-caps), **`solid`** (the candlestick look — a light outer bar over the full
+ * `lower→upper` range with a more-prominent inner `q1→q3` box, no stems), or
+ * **`none`** (the `q1→q3` box only, no spread marks). The median line is drawn
+ * separately and is always optional (`showMedian`).
+ */
+export type BoxShape = 'whisker' | 'solid' | 'none';
+/**
+ * Draw a discrete box per key of `box`, mapping data→pixels through
+ * `xScale`/`yScale`. The bar-chart analog of {@link drawBand}: each key gets its
+ * own mark over its interval x-span (`barSpanPx`, inset by `gapPx` so adjacent
+ * boxes breathe), in the chosen {@link BoxShape}:
+ *
+ * - **`whisker`** (default) — the graded `q1→q3` box fill + outline, two whisker
+ *   stems with end-caps out to `lower`/`upper`.
+ * - **`solid`** — a light outer bar over `lower→upper` (the spread) with a
+ *   more-prominent inner `q1→q3` box (the same fill at rising opacity — so it
+ *   reads darker on a light ground, brighter on a dark one), no stems/outline.
+ * - **`none`** — the `q1→q3` box fill + outline only, no spread marks.
+ *
+ * Then, if `showMedian`, the median line across the box on top. Fills are
+ * bracketed by `save`/`restore` so their `globalAlpha` doesn't leak.
+ *
+ * **Gap-aware**: a key with any quantile non-finite is skipped entirely (no
+ * partial box) — the same contract as a band gap.
+ *
+ * O(N) over the keys, a fixed number of path ops each — no per-key allocation
+ * beyond the `barSpanPx` tuple.
+ */
+export declare function drawBox(ctx: CanvasRenderingContext2D, box: BoxSeries, xScale: Scale, yScale: Scale, style: BoxStyle, gapPx?: number, minWidthPx?: number, shape?: BoxShape, showMedian?: boolean): void;
+/** All five quantiles finite at `i` — i.e. this key is drawn. */
+export declare function isFiniteBox(box: BoxSeries, i: number): boolean;
+//# sourceMappingURL=box.d.ts.map