@pond-ts/charts 0.54.0 → 0.56.2

package/dist/ListTable.js

@@ -0,0 +1,143 @@
+import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
+/**
+ * @internal The shared row-table shell behind {@link BarList} / {@link BoxList}.
+ *
+ * Renders a real `<table>` — the point of the list family is table semantics
+ * (label cells that can be links, aligned data cells, a `colSpan` detail row
+ * for the expander, screen-reader-legible rows), which a canvas plot can't
+ * carry and which hand-rolled flex rows re-implement badly (per-row cell
+ * alignment is exactly what table layout solves). The glyph cell takes
+ * `width: 100%` so it absorbs the free width; every text cell shrinks to fit.
+ *
+ * Not exported from the package: the public surface is the two sisters, so the
+ * shared shell can evolve without a compatibility contract.
+ */
+import { Fragment, useState } from 'react';
+/** The turquoise the selected-row edge falls back to when the theme has no
+ *  annotation register — the same built-in the annotation layer uses. */
+const FALLBACK_ACCENT = '#0d9488';
+/** The shared text ink: the band-label tone when the theme has one (stronger
+ *  than tick labels — these cells are primary content), else the tick ink. */
+export function listInk(theme) {
+    return theme.axis.band?.label ?? theme.axis.label;
+}
+export function ListTable({ rows, kind, renderGlyphs, before = [], after = [], renderExpanded, defaultExpanded, onExpandToggle, selected, onRowClick, divided = true, baseline = false, markers = [], theme, }) {
+    // Uncontrolled expansion, keyed on row identity so it survives a re-sort.
+    const [expanded, setExpanded] = useState(() => new Set(defaultExpanded ?? []));
+    const [hovered, setHovered] = useState(null);
+    const interactive = onRowClick !== undefined;
+    const toggle = (key) => {
+        const open = !expanded.has(key);
+        setExpanded((prev) => {
+            const next = new Set(prev);
+            if (open)
+                next.add(key);
+            else
+                next.delete(key);
+            return next;
+        });
+        onExpandToggle?.(key, open);
+    };
+    const ink = listInk(theme);
+    const accent = theme.annotation?.color ?? FALLBACK_ACCENT;
+    const divider = divided ? `1px solid ${theme.axis.grid}` : undefined;
+    // Label + before + glyph + after (+ expander) — the detail row spans them all.
+    const span = 2 + before.length + after.length + (renderExpanded ? 1 : 0);
+    const textCell = (align) => ({
+        padding: '6px 12px',
+        whiteSpace: 'nowrap',
+        textAlign: align ?? 'left',
+        verticalAlign: 'middle',
+    });
+    // The glyph cell's shared horizontal geometry — the label strip must use
+    // the SAME left/right padding (and baseline border) as the data rows, or
+    // its percentages would resolve against a different content width and the
+    // labels would sit off their rules.
+    const glyphCellStyle = (vertical) => ({
+        width: '100%',
+        padding: baseline ? `${vertical} 8px ${vertical} 5px` : `${vertical} 8px`,
+        verticalAlign: 'middle',
+        borderLeft: baseline ? `1px solid ${theme.axis.grid}` : undefined,
+    });
+    const drawnMarkers = markers.filter((m) => m.frac !== null);
+    return (_jsx("table", { "data-list": kind, style: {
+            width: '100%',
+            borderCollapse: 'collapse',
+            font: `${theme.font.size}px/${1.5} ${theme.font.family}`,
+            color: ink,
+            background: theme.background,
+        }, children: _jsxs("tbody", { children: [drawnMarkers.some((m) => m.label !== undefined) && (
+                // The marker label strip: one synthetic row above the data, its
+                // glyph cell sharing the data rows' horizontal geometry so each
+                // label centres exactly on its rule below.
+                _jsxs("tr", { "data-list-marker-labels": "", children: [_jsx("td", { style: textCell() }), before.map((cell) => (_jsx("td", { style: textCell(cell.align) }, cell.key))), _jsx("td", { style: glyphCellStyle('0px'), children: _jsx("div", { style: {
+                                    position: 'relative',
+                                    height: theme.font.size + 6,
+                                }, children: drawnMarkers.map((m, mi) => m.label !== undefined && (_jsx("span", { "data-list-marker-label": "", style: {
+                                        position: 'absolute',
+                                        left: `${m.frac * 100}%`,
+                                        bottom: 0,
+                                        transform: 'translateX(-50%)',
+                                        whiteSpace: 'nowrap',
+                                        color: accent,
+                                    }, children: m.label }, mi))) }) }), after.map((cell) => (_jsx("td", { style: textCell(cell.align) }, cell.key))), renderExpanded !== undefined && _jsx("td", {})] })), rows.map((row, i) => {
+                    const isSelected = selected != null && selected === row.key;
+                    const isOpen = renderExpanded !== undefined && expanded.has(row.key);
+                    return (_jsxs(Fragment, { children: [_jsxs("tr", { "data-list-row": row.key, ...(isSelected ? { 'data-selected': '' } : {}), onClick: onRowClick === undefined ? undefined : () => onRowClick(row), 
+                                // A clickable row is keyboard-reachable too: focusable, and
+                                // Enter / Space activate it (Space's default scroll is eaten).
+                                tabIndex: interactive ? 0 : undefined, onKeyDown: onRowClick === undefined
+                                    ? undefined
+                                    : (e) => {
+                                        if (e.key === 'Enter' || e.key === ' ') {
+                                            e.preventDefault();
+                                            onRowClick(row);
+                                        }
+                                    }, onPointerEnter: interactive ? () => setHovered(row.key) : undefined, onPointerLeave: interactive ? () => setHovered(null) : undefined, style: {
+                                    borderTop: i > 0 ? divider : undefined,
+                                    cursor: interactive ? 'pointer' : undefined,
+                                    background: interactive && hovered === row.key
+                                        ? (theme.legend?.border ?? theme.axis.grid)
+                                        : undefined,
+                                    // The selection accent: an inset edge in the annotation
+                                    // register (a *user's* mark, so it takes the marks colour,
+                                    // not a data hue) — reads on any ground, moves no layout.
+                                    boxShadow: isSelected ? `inset 3px 0 0 ${accent}` : undefined,
+                                }, children: [_jsx("td", { "data-list-cell": "label", style: textCell(), children: row.label ?? row.key }), before.map((cell) => (_jsx("td", { "data-list-cell": cell.key, style: textCell(cell.align), children: cell.render(row) }, cell.key))), _jsx("td", { "data-list-cell": "glyphs", 
+                                        // 100% absorbs the table's free width; every text cell
+                                        // shrinks to its content, staying aligned down the list.
+                                        // The baseline rule marks the scale origin: left padding
+                                        // narrows to a 5px breath so the glyphs start just off the
+                                        // rule, and border-collapse joins the rows' rules into one
+                                        // continuous vertical — the same thin `axis.grid` ink as
+                                        // the row dividers, so the two read as one quiet grid.
+                                        style: glyphCellStyle('6px'), children: _jsxs("div", { style: { position: 'relative' }, children: [renderGlyphs(row), drawnMarkers.map((m, mi) => (
+                                                // One dotted segment per row, bleeding through the
+                                                // row's vertical padding (+ divider) so adjacent rows'
+                                                // segments join into one continuous rule. Annotation
+                                                // register — a reference is a user's mark, not data.
+                                                _jsx("div", { "data-list-marker": "", style: {
+                                                        position: 'absolute',
+                                                        top: -7,
+                                                        bottom: -7,
+                                                        left: `calc(${m.frac * 100}% - 0.5px)`,
+                                                        width: 0,
+                                                        borderLeft: `1px dotted ${accent}`,
+                                                        pointerEvents: 'none',
+                                                    } }, mi)))] }) }), after.map((cell) => (_jsx("td", { "data-list-cell": cell.key, style: textCell(cell.align), children: cell.render(row) }, cell.key))), renderExpanded !== undefined && (_jsx("td", { style: { padding: '0 4px', verticalAlign: 'middle' }, children: _jsx("button", { type: "button", "data-list-expander": "", "aria-expanded": isOpen, "aria-label": isOpen ? 'Collapse row' : 'Expand row', onClick: (e) => {
+                                                // The chevron toggles; it must not double as a row click.
+                                                e.stopPropagation();
+                                                toggle(row.key);
+                                            }, style: {
+                                                background: 'none',
+                                                border: 'none',
+                                                cursor: 'pointer',
+                                                color: theme.axis.label,
+                                                font: 'inherit',
+                                                padding: '2px 6px',
+                                                transform: isOpen ? 'rotate(90deg)' : undefined,
+                                                transition: 'transform 120ms',
+                                            }, children: "\u25B8" }) }))] }), isOpen && (_jsx("tr", { "data-list-detail": row.key, children: _jsx("td", { colSpan: span, style: { padding: '2px 12px 12px' }, children: renderExpanded(row) }) }))] }, row.key));
+                })] }) }));
+}
+//# sourceMappingURL=ListTable.js.map

package/dist/ScatterChart.d.ts

@@ -1,24 +1,9 @@
 import { ValueSeries } from 'pond-ts';
 import type { SeriesSchema, TimeSeries, ValueSeriesSchema } from 'pond-ts';
+import type { NumericColumn, ValueNumericColumn } from './column-names.js';
 import { type ColorEncoding, type RadiusEncoding } from './encoding.js';
 import type { DecimateOption } from './decimate.js';
-export interface ScatterChartProps<S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema> {
-    /**
-     * The source series. A `TimeSeries` scatters against the time axis; a
-     * `ValueSeries` (`series.byValue('cumDist')`, or `ValueSeries.fromColumns`
-     * for natively value-keyed data — IV marks keyed by strike) against its
-     * value axis — the container infers which from the data, no axis-type prop
-     * (mirrors `<LineChart>`). Either way the key / axis column supplies each
-     * point's x and `column` supplies y.
-     *
-     * **Live charts:** `series.byValue(…)` mints a *fresh* projection each call,
-     * so passing `series={s.byValue('dist')}` inline re-registers this layer
-     * every render — memoize the projection (`useMemo`) on a frequently
-     * re-rendering chart.
-     */
-    series: TimeSeries<S> | ValueSeries<VS>;
-    /** Name of the numeric value column — each point's y. */
-    column: string;
+export interface ScatterChartCommon<S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema> {
     /**
      * The scatter's semantic identifier — what the marks _are_ / how they should
      * read. The theme maps it to a {@link ScatterStyle} (`theme.scatter[as] ??
@@ -109,6 +94,30 @@ export interface ScatterChartProps<S extends SeriesSchema = SeriesSchema, VS ext
      */
     index?: number;
 }
+/**
+ * ScatterChart's source + column props, a **union over the series kind** so the
+ * column names are checked against the schema that was actually passed
+ * ([PND-CHARTAPI]). A single member carrying `NumericColumn<S> |
+ * ValueNumericColumn<VS>` would silently widen to `string`: only one of the
+ * two generics is ever inferred, and the other falls back (measured in
+ * `spikes/charts-type-seam/`). Loosely-typed series still accept any name.
+ */
+type ScatterChartSource<S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema> = {
+    /**
+     * The source series. **Live charts:** `series.byValue(…)` mints a
+     * *fresh* projection each call, so an inline `series={s.byValue('d')}`
+     * re-registers this layer every render — on a frequently re-rendering
+     * (e.g. scrub-driven) chart, memoize the projection (`useMemo`) so the
+     * layer isn't rebuilt each frame.
+     */
+    series: TimeSeries<S>;
+    column: NumericColumn<S>;
+} | {
+    series: ValueSeries<VS>;
+    column: ValueNumericColumn<VS>;
+};
+/** `<ScatterChart>`'s props: the shared knobs plus one series-kind source shape. */
+export type ScatterChartProps<S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema> = ScatterChartCommon<S, VS> & ScatterChartSource<S, VS>;
 /**
  * A scatter draw layer: one mark per finite point at `(x, column-value)`
  * — x from the series' key / axis column (time or value axis) —
@@ -138,4 +147,5 @@ export interface ScatterChartProps<S extends SeriesSchema = SeriesSchema, VS ext
  * ```
  */
 export declare function ScatterChart<S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema>({ series, column, as: semantic, id, axis, radius, color, label, offset, decimate, legend, index, }: ScatterChartProps<S, VS>): null;
+export {};
 //# sourceMappingURL=ScatterChart.d.ts.map

package/dist/YAxis.d.ts

@@ -20,6 +20,34 @@ export interface YAxisProps {
      *   that has headroom (auto-fit / padded) so it doesn't crowd the top tick.
      */
     labelPlacement?: 'rotated' | 'top';
+    /**
+     * Which scale the axis maps its domain through. **Default `'linear'`.**
+     *
+     * `'log'` gives a base-10 logarithmic axis — for data spanning orders of
+     * magnitude, where a linear axis flattens everything below the top decade
+     * onto the baseline. Ticks land on the decades, and `format` still formats
+     * the **value**, so a readout says `1.2 PB`, not its logarithm.
+     *
+     * A log domain cannot contain zero or negative numbers — d3 maps them to
+     * `NaN`, which has no position on the plot. So:
+     *
+     * - **Auto-fit ignores non-positive extents** when picking the low end (a
+     *   `BarChart`, whose extent always reaches zero so its bars can meet their
+     *   baseline, can therefore share the axis), and rounds the domain out to
+     *   whole powers of ten.
+     * - **An explicit `min`/`max` that is not positive is refused**, and that
+     *   side auto-fits instead. A positive bound is always honoured exactly; when
+     *   only one side is given and the domain would invert, the *auto* side moves
+     *   — the same policy a linear axis follows.
+     * - **Layers that fill to a baseline** (`AreaChart`, `BarChart`, a stacked
+     *   histogram) rest it on the bottom of the domain rather than on zero.
+     * - **A value with no position gaps the line**, rather than its neighbours
+     *   being joined straight across it.
+     *
+     * 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.
+     */
+    scale?: 'linear' | 'log';
     /** Explicit domain bounds; omit to auto-fit the charts linked to this axis. */
     min?: number;
     max?: number;
@@ -100,5 +128,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, min, max, format, ticks, tickCount, pad, boundaryLabels, width, labelPlacement, color, index, }: YAxisProps): import("react/jsx-runtime").JSX.Element;
+export declare function YAxis({ id, side, label, scale, min, max, format, ticks, tickCount, pad, boundaryLabels, width, labelPlacement, color, index, }: YAxisProps): import("react/jsx-runtime").JSX.Element;
 //# sourceMappingURL=YAxis.d.ts.map

package/dist/YAxis.js

@@ -3,6 +3,7 @@ import { useContext, useEffect, useMemo } from 'react';
 import { ContainerContext, RowContext } from './context.js';
 import { resolveAxisFormat } from './format.js';
 import { useSlotKey } from './use-slot-key.js';
+import { yTickValues } from './yticks.js';
 const DEFAULT_WIDTH = 50;
 /** Fallback tick count before the row has published its resolved count (the
  *  first render, pre-registration). The row's height-derived value takes over
@@ -16,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, min, max, format, ticks, tickCount, pad = 0, boundaryLabels = true, width = DEFAULT_WIDTH, labelPlacement = 'rotated', color, index = 0, }) {
+export function YAxis({ id, side = 'left', label, scale = 'linear', min, max, format, ticks, tickCount, pad = 0, boundaryLabels = true, width = DEFAULT_WIDTH, labelPlacement = 'rotated', color, index = 0, }) {
     const container = useContext(ContainerContext);
     if (container === null) {
         throw new Error('<YAxis> must be rendered inside a <ChartContainer>');
@@ -29,6 +30,7 @@ export function YAxis({ id, side = 'left', label, min, max, format, ticks, tickC
         id,
         side,
         width,
+        scale,
         min,
         max,
         pad,
@@ -41,6 +43,7 @@ export function YAxis({ id, side = 'left', label, min, max, format, ticks, tickC
         id,
         side,
         width,
+        scale,
         min,
         max,
         pad,
@@ -72,14 +75,25 @@ export function YAxis({ id, side = 'left', label, min, max, format, ticks, tickC
     // a cursor value read identically. `count` calibrates the default formatter's
     // precision to the tick density, exactly as the axis is.
     const fmt = yScale ? resolveAxisFormat(yScale, count, format) : String;
+    // A **horizontal categorical** layer on this axis supplies its category
+    // names ([PND-HCAT]); with no explicit `ticks`, label one per unit slot at
+    // its centre (`i + 0.5`) instead of the scale's numeric ticks — a slot index
+    // is not a number anyone wants to read. Explicit `ticks` still win, and a
+    // non-categorical row is unaffected (no layer answers, so this is `null`).
+    const layerCategories = row.layers
+        .filter((e) => (e.axisId ?? row.defaultAxisId) === id)
+        .map((e) => e.layer.binCategories?.() ?? null)
+        .find((c) => c !== null) ?? null;
     // Explicit `{ at, label }` ticks render verbatim (each label at its `at`),
     // overriding the auto-picked d3 ticks; otherwise label the scale's ticks via `fmt`.
     const tickList = ticks
         ? ticks.map((t) => ({ value: t.at, label: t.label }))
-        : (yScale ? yScale.ticks(count) : []).map((t) => ({
-            value: t,
-            label: fmt(t),
-        }));
+        : layerCategories !== null
+            ? layerCategories.map((label, i) => ({ value: i + 0.5, label }))
+            : (yScale ? yTickValues(yScale, count) : []).map((t) => ({
+                value: t,
+                label: fmt(t),
+            }));
     // The row reserves a slot per axis column (the widest in that column across
     // rows). Size the box to the slot and align this axis's own (narrower)
     // content toward the plot — left axes flush right, right axes flush left — so

package/dist/area.js

@@ -1,6 +1,6 @@
 import { area as d3area, curveLinear } from 'd3-shape';
 import { strokeAffinePolyline } from './line.js';
-import { bridgeGaps, collectGapEdges, drawGapBridges, drawGapFades, drawGapSteps, withAlpha, DEFAULT_GAP_MODE, DEFAULT_GAP_CONNECTOR_OPACITY, } from './gaps.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';
 import { affineOf } from './affine.js';
@@ -191,6 +191,15 @@ export function drawArea(ctx, cs, xScale, yScale, style, baselineValue, curve =
     else {
         cs = cullChartSeries(source, xScale);
     }
+    // Values with no position on the y scale (zero / negative on a log axis)
+    // become ordinary NaN gaps, so the fill and outline break at them rather than
+    // bridging over a dropped `lineTo(x, NaN)`. Deliberately **after** the
+    // gradient above: that reads the pre-cull buffer, whose finite extent is
+    // memoized per `Float64Array` ([PND-GRADX]), and a fresh array here would miss
+    // that cache on every frame. A no-op on an affine (linear) y scale.
+    const scaledY = gapUnscalable(cs.y, cs.length, yScale);
+    if (scaledY !== cs.y)
+        cs = { ...cs, y: scaledY };
     // `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).
@@ -277,20 +286,42 @@ export function drawArea(ctx, cs, xScale, yScale, style, baselineValue, curve =
 function buildGradient(ctx, valueExtent, yScale, baselinePx, style) {
     if (valueExtent === null)
         return style.fill; // no finite values (caller no-ops)
-    // The pixel extent is the two value extremes mapped through the (monotonic,
-    // always-`scaleLinear`) y scale; min/max them so the result is flip-agnostic,
-    // exactly as the former per-point pixel scan produced. [PND-GRADX] moved the
-    // O(N) walk into the memoized {@link columnFiniteExtent}.
-    const pa = yScale(valueExtent[0]);
-    const pb = yScale(valueExtent[1]);
-    const topPx = Math.min(pa, pb); // smallest pixel y (highest on screen)
-    const bottomPx = Math.max(pa, pb); // largest pixel y (lowest on screen)
-    // 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
+    // Stacked areas opt out of the grade entirely: a band that fades to
+    // transparent at the baseline shows every band beneath it (see AreaStyle).
+    if (style.flatFill === true)
+        return style.fill;
+    // The pixel extent is the two value extremes mapped through the (monotonic)
+    // y scale; min/max them so the result is flip-agnostic, exactly as the former
+    // per-point pixel scan produced. [PND-GRADX] moved the O(N) walk into the
+    // memoized {@link columnFiniteExtent}.
+    //
+    // **An extreme with no position on the scale is dropped**, not min/maxed in.
+    // `valueExtent` is the data's own `[min, max]`, and on a **log** axis a
+    // non-positive extreme — a series that touches zero, which is the ordinary
+    // shape of traffic or storage data — maps to `NaN`. `Math.min(NaN, pb)` is
+    // `NaN`, `NaN` propagates to the height, and `NaN < 1e-6` is **false**, so the
+    // degenerate guard below waved it through to `createLinearGradient(0, NaN, 0,
+    // NaN)` — which throws `IndexSizeError` on a real canvas and takes the whole
+    // chart down. The region is seeded from the baseline pixel (always in-domain,
+    // via `resolveAreaBaseline`) and widened only by extremes that have a
+    // position, so the grade still spans the part of the series that draws.
+    let regionTop = baselinePx;
+    let regionBottom = baselinePx;
+    const widen = (px) => {
+        if (!Number.isFinite(px))
+            return;
+        if (px < regionTop)
+            regionTop = px;
+        if (px > regionBottom)
+            regionBottom = px;
+    };
+    widen(yScale(valueExtent[0]));
+    widen(yScale(valueExtent[1]));
+    // `!(… >= 1e-6)` rather than `< 1e-6`, so a non-finite height — a baseline
+    // that somehow has no position either, leaving nothing finite to anchor on —
+    // falls back to the flat fill instead of reaching the gradient calls.
+    if (!(regionBottom - regionTop >= 1e-6))
+        return style.fill; // degenerate
     const opaque = style.fill;
     const transparent = withAlpha(style.fill, 0);
     const grad = ctx.createLinearGradient(0, regionTop, 0, regionBottom);

package/dist/band.js

@@ -1,6 +1,7 @@
 import { area as d3area, curveLinear } from 'd3-shape';
 import { cullBandSeries } from './culling.js';
 import { decimateBand } from './decimate.js';
+import { gapUnscalable } from './gaps.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
@@ -60,6 +61,18 @@ export function drawBand(ctx, band, xScale, yScale, style, curve = curveLinear,
         band = decimateBand(band, xScale, ctx, k);
         decimated = band !== before;
     }
+    // An edge with no position on the y scale becomes an ordinary NaN gap, so the
+    // envelope breaks there rather than emitting dropped path ops that stitch the
+    // neighbouring samples together. A `lower` of `0` is the common shape — a band
+    // measured from nothing — and on a log axis zero has no position, so without
+    // this the fill silently spanned the samples it could not draw. Gapping either
+    // edge gaps the sample, which is already the band's contract: a sample counts
+    // only where **both** edges do. A no-op on an affine (linear) y scale.
+    const gapLower = gapUnscalable(band.lower, band.length, yScale);
+    const gapUpper = gapUnscalable(band.upper, band.length, yScale);
+    if (gapLower !== band.lower || gapUpper !== band.upper) {
+        band = { ...band, lower: gapLower, upper: gapUpper };
+    }
     const gen = d3area()
         .defined((_, i) => Number.isFinite(band.lower[i]) && Number.isFinite(band.upper[i]))
         .x((_, i) => xScale(band.x[i]))

package/dist/bars.d.ts

@@ -50,8 +50,10 @@ export declare function resolveBarBaseline(yScale: Scale): number;
  * 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.
+ * rect. This is the **ink** — what {@link drawBars} paints. Hit-testing uses
+ * {@link barSlotRect} instead (the bar's whole slot), so the drawn rect and the
+ * 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;
 /**
@@ -75,9 +77,12 @@ export interface BarMark {
  * no-id layer passes `undefined` and never matches — plus the bar's identity,
  * see {@link barMatches}) 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.
+ * draws **without** the outline (a lighter "this bar is live" on pointer-over)
+ * in the style's optional `hover` colour, or in `highlight` when the theme
+ * doesn't set one; all others use the flat `fill`. Either live state fills at
+ * **full opacity** — the resting `opacity` applies to resting bars only, and is
+ * restored so it doesn't leak into later layers. A bar that is both selected
+ * and hovered reads as **selected**.
  *
  * **Which identity.** A selection carrying a `mark` matches against the series'
  * stable per-bar name ({@link BarSeries.marks} — the sample's own axis key,
@@ -94,11 +99,12 @@ export interface BarMark {
  * (an `undefined` entry falls back to the flat `fill`). This is the
  * direction-coloured financial volume row (rising / falling) and the
  * value-band case on a time axis. Highlight follows {@link drawStacks}'s
- * binFills convention rather than the flat path's: the bar **keeps its own
- * colour** under hover / selection — the highlight pops `globalAlpha` to 1
- * (and outlines the selection in the bar's own fill) — so a red / green bar
- * stays red / green while live, instead of swapping to the single
- * `highlight` colour and losing its meaning.
+ * binFills convention: the bar **keeps its own colour** under hover /
+ * selection — the highlight pops `globalAlpha` to 1 (and outlines the
+ * selection in the bar's own fill) — so a red / green bar stays red / green
+ * while live, instead of swapping to the single `highlight` colour and losing
+ * its meaning. (Both paths now pop to 1; what still differs is the *colour* —
+ * the flat path swaps to `highlight`, this one keeps `binFills[i]`.)
  *
  * **M4 column decimation ([PND-MARKDEC]):** once the *visible* bars are denser
  * than ~2 per device pixel, they overplot into a solid silhouette, so
@@ -129,19 +135,68 @@ export declare function drawBars(ctx: CanvasRenderingContext2D, cs: BarSeries, x
  * cheap and allocation-free).
  */
 export declare function barIndexAtTime(cs: BarSeries, time: number): number;
+/**
+ * The pixel rect of bar `i`'s **slot** — the region that *belongs* to the bar,
+ * as opposed to the ink {@link barRect} puts on the canvas. It spans the key's
+ * full `[begin, end]` in x (**no `gapPx` inset**) and the **whole plot height**
+ * in y. `null` for a gap (non-finite value), which owns no slot to select.
+ *
+ * The distinction is the point: a bar *is* the full width of its interval, and
+ * the drawing gap is a display affordance so adjacent columns read as discrete.
+ * Hit-testing the drawn rect made that affordance interactive — the gap became
+ * a dead channel you could point at and select nothing, and the empty plot
+ * space above a short bar likewise. Slots tile the axis, so every x inside the
+ * data range belongs to exactly one bar, which is what a column chart's hover
+ * should feel like and what {@link barIndexAtTime} (the x-scrub cursor) has
+ * always done.
+ *
+ * The plot's y extent is read from the `yScale`'s own domain, the same
+ * localized shape {@link resolveBarBaseline} uses. When it isn't readable (a
+ * bare test stub with no `.domain()`), this falls back to {@link barRect}'s
+ * value→baseline span, so a scale-less caller keeps the old behaviour rather
+ * than getting an unbounded hit region.
+ *
+ * `minWidthPx` still floors the span, so a lone point-keyed bar (zero-width
+ * key) stays selectable.
+ *
+ * **Two consequences worth knowing before you compose with it.**
+ *
+ * 1. **It reaches across the whole plot height, so it can shadow layers below
+ *    it.** `resolveSelection` returns the topmost hit, so a `<BarChart>`
+ *    declared *after* a `<ScatterChart>` / `<BoxPlot>` / another `<BarChart>`
+ *    in the same row now claims every hit inside its x-range, at any y — where
+ *    the drawn-rect target only claimed the bar's own ink. Declare a bar layer
+ *    **below** the marks you want to stay clickable (which is also the usual
+ *    z-order for bars-as-context). No shipped story composes that way, so this
+ *    is latent rather than a live regression.
+ * 2. **Only the single-series vertical path uses it.** A stacked, `bins`,
+ *    `categories` or horizontal `<BarChart>` hit-tests through
+ *    {@link stackAt}, which still targets the drawn segment — a stack has to,
+ *    since segments share a bin's x-range and only y tells them apart. So
+ *    `<BarChart>` has two hit models; this is the one for a plain bar.
+ */
+export declare function barSlotRect(cs: BarSeries, i: number, xScale: Scale, yScale: Scale, baseline: number, minWidthPx: number): [x0: number, x1: number, yTop: number, yBottom: number] | null;
 /**
  * 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`.
+ * **slot** contains the point, or `null`. The geometry is {@link barSlotRect}:
+ * the bar's full interval width and the full plot height, *not* the drawn rect.
+ * Pointing at the gap between two columns, or above a short one, selects the
+ * bar whose slot you are in. 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`.
+ *
+ * **Shared edges.** Contiguous bars meet exactly (`end[i] === begin[i+1]`) once
+ * the gap is gone, and both ends are inclusive, so a point landing precisely on
+ * the boundary matches **the left bar** — first match wins, the same rule
+ * {@link barIndexAtTime} documents, so hover and the x-scrub cursor agree.
+ *
+ * A **gap** bar (non-finite value) owns no slot and is skipped, so hovering
+ * where the data is missing selects nothing rather than a `NaN`.
  *
  * 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.
+ * not millions; click is a rare event).
  */
-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;
+export declare function barAt(cs: BarSeries, px: number, py: number, xScale: Scale, yScale: Scale, baseline: number, minWidthPx: number): [index: number, begin: number, value: number] | null;
 /**
  * A resolved per-group stack style: `fills` aligned index-for-index to
  * {@link StackedBarSeries.groups} (segment `g` uses `fills[g]`), plus the shared
@@ -196,6 +251,22 @@ export declare function stackValueExtent(ss: StackedBarSeries): [number, number]
  * the x auto-fit for a vertical histogram, the y auto-fit for a horizontal one.
  */
 export declare function stackBinExtent(ss: StackedBarSeries): [number, number] | null;
+/**
+ * The value a stack's **first** segment rests on, in data units — the same
+ * `0`-clamped-into-the-domain rule {@link resolveBarBaseline} applies to a plain
+ * bar, read off whichever scale carries the stacked value (`yScale` when the
+ * bars grow up, `xScale` when they grow right).
+ *
+ * Both stack walks used to start at a literal `0`, which is right only while the
+ * domain contains zero — and a **log** domain never can. `yScale(0)` on a log
+ * scale is `NaN`, `fillRect` with a `NaN` argument is a silent canvas no-op, and
+ * the same rect feeds {@link stackAt} — so the bottom segment of every stack
+ * both vanished *and* became unhittable, with nothing to see but a stack that
+ * starts one segment up. The linear case is unaffected: the value extents pull
+ * `0` into the domain, so this returns exactly `0` and the geometry is
+ * unchanged.
+ */
+export declare function stackBase(orientation: Orientation, xScale: Scale, yScale: Scale): number;
 /**
  * The pixel rect `[x0, x1, yTop, yBottom]` (ascending on both axes) of bin `b`'s
  * segment `g`, stacked so it sits atop `cumBefore` (the summed value of the