@pond-ts/charts 0.57.0 → 0.58.0

package/dist/AreaChart.d.ts

@@ -14,6 +14,17 @@ export interface AreaChartCommon<S extends SeriesSchema = SeriesSchema, VS exten
      * single styling channel).
      */
     as?: string;
+    /**
+     * **Opt in to selection** — see `<LineChart id>`; the currency is identical
+     * because the premise is ([PND-TRACESEL]): a click commits a **series-scoped**
+     * `SelectInfo` (`NaN` key/value plus a stable `mark`), a sweep commits a
+     * `SpanSelection` with **no marks**.
+     *
+     * What differs is only the **hit test**: an area is a filled region, so the
+     * pointer counts as on it when it lies **between the trace and the
+     * baseline** — the whole shape is the target, not the 1.5px edge.
+     */
+    id?: string;
     /**
      * Which `<YAxis>` (by its `id`) this area scales against — picks the *scale*,
      * where `as` picks the *style*. **Omitted ⇒ the row's default axis.**
@@ -140,6 +151,6 @@ export declare function resolveAreaBaseline(baseline: number | undefined, yScale
  * </Layers>
  * ```
  */
-export declare function AreaChart<S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema>({ series, column, readout, as: semantic, axis, baseline, curve, gaps, decimate, legend, index, }: AreaChartProps<S, VS>): null;
+export declare function AreaChart<S extends SeriesSchema = SeriesSchema, VS extends ValueSeriesSchema = ValueSeriesSchema>({ series, column, readout, as: semantic, axis, id, baseline, curve, gaps, decimate, legend, index, }: AreaChartProps<S, VS>): null;
 export {};
 //# sourceMappingURL=AreaChart.d.ts.map

package/dist/AreaChart.js

@@ -1,10 +1,12 @@
 import { useContext, useEffect, useMemo } from 'react';
 import { ValueSeries } from 'pond-ts';
 import { assertNumericColumn, fromTimeSeries, fromValueSeries, } from './data.js';
-import { areaExtent, drawArea } from './area.js';
+import { areaExtent, areaHitIndex, areaStateStyle, drawArea } from './area.js';
+import { drawPartitioned, plotExtentOf, strokeSpanEdges, } from './line.js';
+import { sweepSpan } from './sweep.js';
 import { resolveCurve } from './curve.js';
 import { DEFAULT_GAP_MODE, DEFAULT_GAP_CONNECTOR_OPACITY, } from './gaps.js';
-import { ContainerContext, LayersContext } from './context.js';
+import { ContainerContext, LayersContext, } from './context.js';
 import { legendLabelFor, useLegendItems, } from './swatch.js';
 import { useSlotKey } from './use-slot-key.js';
 /** Read a d3 linear scale's domain lower bound (the axis floor) from the plain
@@ -54,7 +56,7 @@ function domainFloor(yScale) {
  * </Layers>
  * ```
  */
-export function AreaChart({ series, column, readout, as: semantic, axis, baseline, curve, gaps = DEFAULT_GAP_MODE, decimate = true, legend, index = 0, }) {
+export function AreaChart({ series, column, readout, as: semantic, axis, id, baseline, curve, gaps = DEFAULT_GAP_MODE, decimate = true, legend, index = 0, }) {
     const container = useContext(ContainerContext);
     if (container === null) {
         throw new Error('<AreaChart> must be rendered inside a <ChartContainer>');
@@ -91,6 +93,45 @@ export function AreaChart({ series, column, readout, as: semantic, axis, baselin
     // Faintness of the inferred dashed connectors (dashed / step) — theme-level,
     // falling back to the shared default so a theme without it still renders faint.
     const gapConnectorOpacity = container.theme.gap?.connectorOpacity ?? DEFAULT_GAP_CONNECTOR_OPACITY;
+    // ── The trace's interaction state ([PND-TRACESEL]) — see `<LineChart>` for
+    // the reasoning; this is the same derivation over `AreaStyle`'s channels.
+    const selectedEntries = container.selected;
+    const hoveredEntries = container.hovered;
+    // The committed spans, plus the **live** ones of a sweep in flight. A
+    // previewed span draws exactly as a committed one, so releasing changes
+    // nothing visually — the preview cannot promise a picture the commit does not
+    // deliver. The live channel wins while it is non-empty, because during a drag
+    // it IS the current answer.
+    const previewing = container.previewSpans.length > 0;
+    const allSpans = previewing
+        ? container.previewSpans
+        : container.selectedSpans;
+    const traceState = useMemo(() => {
+        if (id === undefined)
+            return 'rest';
+        if (allSpans.some((sp) => sp.id === id))
+            return 'rest';
+        const mine = (e) => e.id === id;
+        if (selectedEntries.some(mine))
+            return 'selected';
+        if (hoveredEntries.some(mine))
+            return 'hover';
+        if (selectedEntries.length > 0 || allSpans.length > 0)
+            return 'dimmed';
+        return 'rest';
+    }, [id, selectedEntries, hoveredEntries, allSpans]);
+    // **`spanColor` only when this is the ONLY swept trace.** The hue is
+    // justified by identity not being in question inside a single series — but
+    // sweep two traces and both would go blue, so inside the window you could no
+    // longer tell them apart, which is the very thing the rule exists to prevent.
+    // With more than one, the window thickens and every trace keeps its colour.
+    const soleSpannedTrace = allSpans.length === 1;
+    const spanX = useMemo(() => {
+        if (id === undefined)
+            return null;
+        const mine = allSpans.find((sp) => sp.id === id);
+        return mine === undefined ? null : mine.x;
+    }, [id, allSpans]);
     const entry = useMemo(() => ({
         layer: {
             as: semantic,
@@ -99,6 +140,36 @@ export function AreaChart({ series, column, readout, as: semantic, axis, baselin
             // ValueSeries plots on a value axis, a TimeSeries on time.
             xKind: series instanceof ValueSeries ? 'value' : 'time',
             xExtent: () => cs.length === 0 ? null : [cs.x[0], cs.x[cs.length - 1]],
+            // ── Selection, gated on `id` ([PND-TRACESEL]). Same currency as
+            // `<LineChart>`; only `hitTest` differs, because a fill is not a stroke.
+            ...(id === undefined
+                ? {}
+                : {
+                    sweepsRect: false,
+                    sweepAxis: 'x',
+                    sweepSpanOnly: true,
+                    hitTest: (px, py, xScale, yScale) => {
+                        const i = areaHitIndex(cs, baseline, px, py, xScale, yScale);
+                        if (i === null)
+                            return null;
+                        return {
+                            id,
+                            // Series-scoped, with a stable `mark` for identity — see
+                            // `<LineChart>`'s hitTest for why both halves are needed.
+                            key: NaN,
+                            value: NaN,
+                            color: style.fill,
+                            label,
+                            mark: label,
+                        };
+                    },
+                    beginSweep: () => cs.length === 0
+                        ? null
+                        : sweepSpan({
+                            id,
+                            bounds: [cs.x[0], cs.x[cs.length - 1]],
+                        }),
+                }),
             sampleAt: (x) => {
                 // No readout past the data (tracker policy — nearest clamps to an
                 // endpoint outside the span); bounds from the columnar x axis.
@@ -151,16 +222,49 @@ export function AreaChart({ series, column, readout, as: semantic, axis, baselin
                     ]
                     : [];
             },
-            draw: (ctx, xScale, yScale) => drawArea(ctx, cs, xScale, yScale, style, 
-            // Omitted baseline rests on the axis floor (resolved late from the
-            // scale, so it tracks the auto-fit domain); a fixed baseline is used
-            // verbatim.
-            // A log axis has no position for zero — or anything at or below
-            // it — so an explicit out-of-domain `baseline` would scale to
-            // `NaN` and poison every coordinate in the fill path. Fall back
-            // to the axis floor, which is exactly what an omitted baseline
-            // already resolves to.
-            resolveAreaBaseline(baseline, yScale), curveFactory, gaps, gapConnectorOpacity, decimate),
+            draw: (ctx, xScale, yScale) => {
+                const fill = (st, alpha) => () => {
+                    const prior = ctx.globalAlpha;
+                    if (alpha !== 1)
+                        ctx.globalAlpha = prior * alpha;
+                    const out = drawAreaWith(st);
+                    ctx.globalAlpha = prior;
+                    return out;
+                };
+                if (spanX === null) {
+                    const [st, alpha] = areaStateStyle(style, traceState);
+                    return fill(st, alpha)();
+                }
+                // EXPERIMENT: annotation-register rules at the window's edges,
+                // underneath the trace ink (drawn first). See `strokeSpanEdges`.
+                //
+                // **Committed spans only.** While the drag is live the brush band
+                // already strokes its own edges at the same two x positions, so
+                // drawing these too put two rules a fraction of a pixel apart on each
+                // boundary — which read as one muddy smear rather than as either. The
+                // handoff is the honest reading anyway: the band is the gesture's
+                // mark and belongs to the drag; these preview the annotation you
+                // would get, and belong to the result.
+                if (!previewing)
+                    strokeSpanEdges(ctx, [xScale(spanX[0]), xScale(spanX[1])], ctx.canvas.height, container.theme.annotation?.spanEdge ?? '#f0b26b');
+                const [outStyle, outAlpha] = areaStateStyle(style, 'dimmed');
+                const [inStyle] = areaStateStyle(style, 'selected');
+                return drawPartitioned(ctx, [xScale(spanX[0]), xScale(spanX[1])], plotExtentOf(ctx, xScale, yScale).height, fill(outStyle, outAlpha), fill(style.spanColor === undefined || !soleSpannedTrace
+                    ? inStyle
+                    : { ...inStyle, color: style.spanColor, fill: style.spanColor }, 1), true, 0, plotExtentOf(ctx, xScale, yScale).width);
+                function drawAreaWith(st) {
+                    return drawArea(ctx, cs, xScale, yScale, st, 
+                    // Omitted baseline rests on the axis floor (resolved late from the
+                    // scale, so it tracks the auto-fit domain); a fixed baseline is used
+                    // verbatim.
+                    // A log axis has no position for zero — or anything at or below
+                    // it — so an explicit out-of-domain `baseline` would scale to
+                    // `NaN` and poison every coordinate in the fill path. Fall back
+                    // to the axis floor, which is exactly what an omitted baseline
+                    // already resolves to.
+                    resolveAreaBaseline(baseline, yScale), curveFactory, gaps, gapConnectorOpacity, decimate);
+                }
+            },
         },
         axisId: axis,
         index,
@@ -178,6 +282,11 @@ export function AreaChart({ series, column, readout, as: semantic, axis, baselin
         gapConnectorOpacity,
         decimate,
         axis,
+        id,
+        traceState,
+        spanX,
+        soleSpannedTrace,
+        previewing,
         index,
     ]);
     // A stable per-instance slot (see useSlotKey) keeps this layer's z-position
@@ -194,6 +303,15 @@ export function AreaChart({ series, column, readout, as: semantic, axis, baselin
     useEffect(() => {
         registerTrackerSource(slot, entry.layer);
     }, [registerTrackerSource, slot, entry.layer]);
+    // Advertise selectability (only when an `id` was given) — see the same block
+    // in `LineChart.tsx` for why a trace was missing from this set.
+    const { registerSelectable, unregisterSelectable } = container;
+    useEffect(() => {
+        if (id === undefined)
+            return;
+        registerSelectable(slot);
+        return () => unregisterSelectable(slot);
+    }, [registerSelectable, unregisterSelectable, slot, id]);
     // And a legend row: the readout identity + the resolved area style (top line
     // over the translucent fill), so a `<Legend>` swatch can never drift.
     const legendRows = useMemo(() => {

package/dist/BarChart.js

@@ -2,10 +2,14 @@ import { useContext, useEffect, useMemo } from 'react';
 import { Interval, ValueSeries } from 'pond-ts';
 import { barsFromTimeSeries, barsFromBins, barsFromValueSeries, categoryStack, stacksFromBins, stacksFromColumns, stacksFromGroups, } from './data.js';
 import { barAt, barExtent, barIndexAtTime, drawBars, drawStacks, normalizeThresholds, resolveBarBaseline, stackAt, stackBinExtent, stackValueExtent, } from './bars.js';
+import { spansForLayer } from './span.js';
 import { isDev } from './dev.js';
 import { ContainerContext, LayersContext, } from './context.js';
+import { sweep1D } from './sweep.js';
 import { legendLabelFor, useLegendItems, } from './swatch.js';
 import { useSlotKey } from './use-slot-key.js';
+/** Stable "nothing selected" identity for the narrowed mark lists below. */
+const EMPTY_MARKS = [];
 /**
  * A bar / histogram draw layer. In its simplest form, one rectangle per event
  * spanning the key's `[begin, end]` from the axis baseline to a numeric
@@ -191,15 +195,21 @@ export function BarChart({ series, bins, categories, column, columns, as: semant
                 : series instanceof ValueSeries
                     ? 'value'
                     : 'time';
-    // The bars' `[begin, end)` spans as pond `Interval`s — the region cursor's snap
-    // buckets (a region drag snaps bar by bar; a hover highlights the bar under the
-    // pointer). Published only for a **vertical** bar layer on a **continuous**
-    // (time / value) x axis: a horizontal chart puts the value/count on x (snapping
-    // it is meaningless) and a categorical (ordinal-slot) axis is out of the region
-    // cursor's scope. Memoized off the shape alone, so a hover / selection change
-    // (which rebuilds the layer entry) doesn't re-allocate the intervals.
+    // The bars' `[begin, end)` spans as pond `Interval`s — the shared snap
+    // buckets (a region drag snaps bar by bar; a `<MultiSelector>` sweep's band
+    // extends bar by bar). Published for any **vertical** bar layer: a
+    // horizontal chart puts the value/count on x (snapping it is meaningless).
+    // On a **category** axis the buckets are the unit slots `[i, i+1)` — the
+    // region cursor still ignores them (its band gates on a continuous axis),
+    // but the sweep's band needs them to snap to the slots' **outer edges**:
+    // the band scale's `invert` snaps a pixel to the slot *centre*, so a
+    // freeform sweep band ran centre-to-centre while capture and the committed
+    // span snapped outward (RFC A7.6's edge rule) — the band disagreed with
+    // what release would select. Memoized off the shape alone, so a hover /
+    // selection change (which rebuilds the layer entry) doesn't re-allocate
+    // the intervals.
     const binBuckets = useMemo(() => {
-        if (orientation !== 'vertical' || binAxisKind === 'category')
+        if (orientation !== 'vertical')
             return null;
         const { begin, end, length } = shape.kind === 'single' ? shape.bs : shape.ss;
         if (length === 0)
@@ -327,9 +337,35 @@ export function BarChart({ series, bins, categories, column, columns, as: semant
     const groups = shape.kind === 'stacked' ? shape.ss.groups : undefined;
     const stackStyle = useMemo(() => {
         const base = bar.default;
-        const fills = (groups ?? []).map((g) => colors?.[g] ?? (bar[g] ?? base).fill);
+        // The theme's **group ramp** — multi-group only, since a ramp exists to
+        // tell groups apart and `G === 1` (every categorical and single-series
+        // chart runs this same path) has nothing to tell apart. Resolution per
+        // group: `colors` → a role named after the group → the ramp → `fill`.
+        const multi = (groups?.length ?? 0) > 1;
+        const ramp = multi ? base.groups : undefined;
+        const rampDim = multi ? base.groupsDimmed : undefined;
+        const rampHover = multi ? base.groupsHover : undefined;
+        const at = (r, i) => r[i % r.length];
+        const fills = (groups ?? []).map((g, i) => colors?.[g] ??
+            bar[g]?.fill ??
+            (ramp !== undefined ? at(ramp, i) : base.fill));
+        // A ramp entry the call site overrode is no longer the ramp's colour, so
+        // its receded counterpart would be wrong — the whole ramp only means
+        // anything when it is the ramp that painted it.
+        const ramped = ramp !== undefined && colors === undefined;
         return {
             fills,
+            ...(ramped ? { groupColored: true } : {}),
+            ...(ramped && rampDim !== undefined
+                ? {
+                    dimmedFills: (groups ?? []).map((_g, i) => at(rampDim, i)),
+                }
+                : {}),
+            ...(ramped && rampHover !== undefined
+                ? {
+                    hoverFills: (groups ?? []).map((_g, i) => at(rampHover, i)),
+                }
+                : {}),
             opacity: base.opacity,
             outlineWidth: base.outlineWidth,
             // [PND-CATEMPH] Forward the themed emphasis so the category / horizontal
@@ -343,6 +379,7 @@ export function BarChart({ series, bins, categories, column, columns, as: semant
             ...(base.emphasisOpacity !== undefined
                 ? { emphasisOpacity: base.emphasisOpacity }
                 : {}),
+            ...(base.dimmed !== undefined ? { dimmed: base.dimmed } : {}),
             ...(binColors !== undefined ? { binFills: binColors } : {}),
         };
     }, [bar, groups, colors, binColors]);
@@ -351,24 +388,32 @@ export function BarChart({ series, bins, categories, column, columns, as: semant
     // (id, key). Read here so a change re-registers the layer → the canvas repaints.
     const selected = container.selected;
     const hoveredMark = container.hovered;
-    const selection = useMemo(() => selected === null
-        ? null
-        : {
-            id: selected.id,
-            key: selected.key,
-            label: selected.label,
-            ...(selected.mark !== undefined ? { mark: selected.mark } : {}),
-        }, [selected]);
-    const hover = useMemo(() => hoveredMark === null
-        ? null
-        : {
-            id: hoveredMark.id,
-            key: hoveredMark.key,
-            label: hoveredMark.label,
-            ...(hoveredMark.mark !== undefined
-                ? { mark: hoveredMark.mark }
-                : {}),
-        }, [hoveredMark]);
+    // The selection is a set ([PND-MULTISEL]); narrow each member to the identity
+    // the draw path matches on. `EMPTY_MARKS` keeps the no-selection case
+    // reference-stable so it doesn't re-identify the layer entry each render.
+    const selection = useMemo(() => selected.length === 0
+        ? EMPTY_MARKS
+        : selected.map((m) => ({
+            id: m.id,
+            key: m.key,
+            label: m.label,
+            ...(m.mark !== undefined ? { mark: m.mark } : {}),
+        })), [selected]);
+    const hover = useMemo(() => hoveredMark.length === 0
+        ? EMPTY_MARKS
+        : hoveredMark.map((m) => ({
+            id: m.id,
+            key: m.key,
+            label: m.label,
+            ...(m.mark !== undefined ? { mark: m.mark } : {}),
+        })), [hoveredMark]);
+    // The selection's span entries, narrowed to this layer (interaction RFC
+    // A5.2). On the single-series path every mark shares one label, so a span's
+    // `rows` channel resolves here (once) rather than per bar; the stacked path's
+    // labels vary per segment (group / category), so `rows` rides through for
+    // `drawStacks` to test. Empty (and reference-stable) when no span names us —
+    // this layer neither re-registers nor repaints for other layers' spans.
+    const layerSpans = useMemo(() => spansForLayer(container.selectedSpans, id, shape.kind === 'single' ? label : undefined), [container.selectedSpans, id, shape.kind, label]);
     const entry = useMemo(() => {
         // ── Single-series, vertical: the original bar path, pixels unchanged. ──
         if (shape.kind === 'single') {
@@ -403,7 +448,7 @@ export function BarChart({ series, bins, categories, column, columns, as: semant
                     ...(id === undefined
                         ? {}
                         : {
-                            hitTest: (px, py, xScale, yScale) => {
+                            hitTest: (px, py, xScale, yScale, mode) => {
                                 const baseline = resolveBarBaseline(yScale);
                                 // No `gapPx` — the hit region is the bar's whole slot (its
                                 // interval width, full plot height), not the inset rect the
@@ -412,6 +457,20 @@ export function BarChart({ series, bins, categories, column, columns, as: semant
                                 if (hit === null)
                                     return null;
                                 const [bi, begin, value] = hit;
+                                // A CLICK narrows the slot to the bar's drawn ink
+                                // vertically (the x keeps the slot, so the gap between
+                                // columns is still not a dead channel). Slots tile the
+                                // whole plot, so without this a click could never resolve
+                                // to null — and that null IS the deselect path (RFC §7's
+                                // empty commit). Hover keeps the full slot: the highlight
+                                // tracks continuously like the readout (#582).
+                                if (mode === 'select') {
+                                    const yValue = yScale(value);
+                                    const yBase = yScale(baseline);
+                                    if (py < Math.min(yValue, yBase) ||
+                                        py > Math.max(yValue, yBase))
+                                        return null;
+                                }
                                 // The bar's stable `mark` (its own axis key) rides the
                                 // selection, so the highlight match and a controlled echo key
                                 // on the *sample* rather than on the `begin` edge — which on a
@@ -430,8 +489,43 @@ export function BarChart({ series, bins, categories, column, columns, as: semant
                                     ...(stableMark !== undefined ? { mark: stableMark } : {}),
                                 };
                             },
+                            // The <MultiSelector> sweep's range query (RFC A7.6): bars
+                            // are sorted, non-overlapping intervals, so the covered set
+                            // is a contiguous run — sweep1D's two binary searches. Each
+                            // materialised hit is EXACTLY what hitTest reports for that
+                            // bar, so a swept bar and a clicked bar are the same currency.
+                            beginSweep: () => bs.length === 0
+                                ? null
+                                : sweep1D({
+                                    id,
+                                    begin: bs.begin,
+                                    end: bs.end,
+                                    length: bs.length,
+                                    // A gap bar (non-finite value) owns no membership.
+                                    selectable: (i) => Number.isFinite(bs.y[i]),
+                                    materialize: (lo, hi) => {
+                                        const out = [];
+                                        for (let i = lo; i < hi; i += 1) {
+                                            const v = bs.y[i];
+                                            if (!Number.isFinite(v))
+                                                continue;
+                                            const stableMark = bs.marks?.[i];
+                                            out.push({
+                                                id,
+                                                key: bs.begin[i],
+                                                value: v,
+                                                color: binColors?.[i] ?? singleStyle.fill,
+                                                label,
+                                                ...(stableMark !== undefined
+                                                    ? { mark: stableMark }
+                                                    : {}),
+                                            });
+                                        }
+                                        return out;
+                                    },
+                                }),
                         }),
-                    draw: (ctx, xScale, yScale) => drawBars(ctx, bs, xScale, yScale, singleStyle, resolveBarBaseline(yScale), gapPx, id, selection, hover, decimate, binColors, bandLadder),
+                    draw: (ctx, xScale, yScale) => drawBars(ctx, bs, xScale, yScale, singleStyle, resolveBarBaseline(yScale), gapPx, id, selection, hover, decimate, binColors, bandLadder, layerSpans),
                 },
                 axisId: axis,
                 index,
@@ -490,8 +584,67 @@ export function BarChart({ series, bins, categories, column, columns, as: semant
                                 ...(stableMark !== undefined ? { mark: stableMark } : {}),
                             };
                         },
+                        // The sweep, on the binned/stacked/categorical path — **either
+                        // orientation** ([PND-HSWEEP]). The session is identical, because
+                        // `sweep1D` cuts in KEY-axis units and does not care which screen
+                        // axis produced them; the bins are `ss.begin`/`ss.end` whichever
+                        // way the chart is drawn. What differs is only where the gesture
+                        // reads the pointer, which `sweepAxis` declares.
+                        //
+                        // The cut stays 1-D on a horizontal chart, deliberately: a
+                        // vertical bar's sweep ignores the value axis (drag anywhere
+                        // horizontally, take whole columns), so its transpose ignores it
+                        // too. A rect here would be value-filtering — a capability the
+                        // vertical chart has never had.
+                        //
+                        // A covered bin materialises every drawn segment (finite,
+                        // non-zero — the marks hitTest can hit), assembled exactly as
+                        // hitTest assembles them.
+                        sweepAxis: vertical ? 'x' : 'y',
+                        beginSweep: () => {
+                            const G = ss.groups.length;
+                            if (ss.length === 0 || G === 0)
+                                return null;
+                            const drawn = (b, g) => {
+                                const v = ss.values[b * G + g];
+                                return Number.isFinite(v) && v !== 0;
+                            };
+                            return sweep1D({
+                                id,
+                                begin: ss.begin,
+                                end: ss.end,
+                                length: ss.length,
+                                selectable: (b) => {
+                                    for (let g = 0; g < G; g += 1)
+                                        if (drawn(b, g))
+                                            return true;
+                                    return false;
+                                },
+                                materialize: (lo, hi) => {
+                                    const out = [];
+                                    for (let b = lo; b < hi; b += 1) {
+                                        const stableMark = ss.marks?.[b];
+                                        for (let g = 0; g < G; g += 1) {
+                                            if (!drawn(b, g))
+                                                continue;
+                                            out.push({
+                                                id,
+                                                key: ss.begin[b],
+                                                value: ss.values[b * G + g],
+                                                color: stackStyle.binFills?.[b] ?? stackStyle.fills[g],
+                                                label: stableMark ?? ss.groups[g],
+                                                ...(stableMark !== undefined
+                                                    ? { mark: stableMark }
+                                                    : {}),
+                                            });
+                                        }
+                                    }
+                                    return out;
+                                },
+                            });
+                        },
                     }),
-                draw: (ctx, xScale, yScale) => drawStacks(ctx, ss, orientation, xScale, yScale, stackStyle, gapPx, stackMinWidth, id, selection, hover, bandLadder),
+                draw: (ctx, xScale, yScale) => drawStacks(ctx, ss, orientation, xScale, yScale, stackStyle, gapPx, stackMinWidth, id, selection, hover, bandLadder, layerSpans),
             },
             axisId: axis,
             index,
@@ -513,6 +666,7 @@ export function BarChart({ series, bins, categories, column, columns, as: semant
         stackMinWidth,
         selection,
         hover,
+        layerSpans,
         axis,
         index,
     ]);

package/dist/BarList.d.ts

@@ -2,6 +2,7 @@ import { type ReactNode } from 'react';
 import type { SeriesSchema, ValueSeriesSchema } from 'pond-ts';
 import { type BarListColumn, type ListCellSpec, type ListMarker, type ListRow, type ListSortDirection } from './list.js';
 import { type ListRowsSource, type ListSeriesSource } from './list-source.js';
+import type { SelectModifiers } from './context.js';
 import { type ChartTheme } from './theme.js';
 /** The props both BarList source doors share. */
 export interface BarListCommon<R extends ListRow = ListRow> {
@@ -53,13 +54,92 @@ export interface BarListCommon<R extends ListRow = ListRow> {
     /** Observe a toggle (`expanded` is the row's **new** state). */
     onExpandToggle?: (key: string, expanded: boolean) => void;
     /**
-     * The selected row's `key`, marked with an inset edge in the annotation
-     * (marks) register — selection is a user's mark, not data. Consumer-owned
-     * state: pair with `onRowClick`. `null` / omitted ⇒ none.
+     * The selected row(s), marked with an inset edge in the annotation (marks)
+     * register — selection is a user's mark, not data. Consumer-owned state:
+     * pair with {@link onRowClick}. `null` / omitted ⇒ none.
+     *
+     * **Accepts one key or a set**, the same union {@link hovered} takes
+     * ([PND-INTERACTCONF] / RFC `interaction.md` A3.1 — the list family speaks
+     * the canvas's interaction vocabulary, not a parallel one). Plural because
+     * a range of rows can be selected at once; passing a bare key still means
+     * exactly what it looks like.
+     *
+     * The library applies **no set arithmetic** — it renders what you hand back.
      */
-    selected?: string | null;
-    /** Row click (rows show hover + pointer affordances only when provided). */
+    selected?: string | readonly string[] | null;
+    /** Row click (rows show the pointer affordance only when provided). */
     onRowClick?: (row: R) => void;
+    /**
+     * **Plural select** — the list's answer to `<MultiSelector>`, and how a user
+     * produces a multi-row {@link selected}.
+     *
+     * Fires with the rows the gesture took plus its modifiers:
+     *
+     * - a **click** reports `[row]` — so this is a strict *superset* of
+     *   {@link onRowClick}, the way `<MultiSelector>` is of `<Selector>`;
+     * - a **drag across rows** reports the whole inclusive run, in display
+     *   order.
+     *
+     * **Mounting it is what enables the drag** (interaction RFC A4.2 rule 1 —
+     * the same rule that makes a bare `<MultiSelector />` enable the canvas
+     * sweep). A list with only `onRowClick` behaves exactly as it always has.
+     *
+     * **Crossing into another row is what makes it a range**, not a pixel slop:
+     * a row is tall and discrete, so a press-and-release on one row is always a
+     * click, and a horizontal wobble — which on a stack of rows means nothing —
+     * can never commit one. While the drag runs, the covered rows light as
+     * *hovered*: that is the live preview of what releasing would take, and it
+     * out-ranks {@link hovered} for the duration without touching it.
+     *
+     * **The library holds no state and applies no set arithmetic.** You get the
+     * run and the modifiers; you decide whether to replace or union, and feed
+     * the result back through {@link selected}:
+     *
+     * ```tsx
+     * onRowSelect={(rows, m) =>
+     *   setSel((cur) => {
+     *     const keys = rows.map((r) => r.key);
+     *     return m.additive ? [...new Set([...cur, ...keys])] : keys;
+     *   })
+     * }
+     * ```
+     *
+     * `modifiers.additive` is the platform-idiomatic add chord already resolved
+     * (⌘ on macOS, Ctrl elsewhere). **`shiftKey` is reported but carries no
+     * built-in meaning** — an ordinal range is a gesture here, not a modifier
+     * (see `SelectModifiers`), so a shift-click extend is yours to define if you
+     * want one.
+     */
+    onRowSelect?: (rows: readonly R[], modifiers: SelectModifiers) => void;
+    /**
+     * Controlled **hover-highlight** — the transiently lit row key(s), or `null`.
+     * **Omitted ⇒ uncontrolled** (the list tracks its own pointer, as it always
+     * has). The hover analog of {@link selected}: pass it to light rows from
+     * _outside_ the list — the chart bar the pointer is on, a map segment, a
+     * sibling list.
+     *
+     * **Accepts one key or a set**, the same union `<Selector hovered>`
+     * takes ([PND-INTERACTCONF] / RFC `interaction.md` A3.1 — the list family
+     * speaks the canvas's interaction vocabulary, not a parallel one). Plural
+     * because a sweep lights several marks at once; a plain pointer-over carries
+     * 0 or 1, so passing a bare key still means exactly what it looks like.
+     *
+     * The library applies **no set arithmetic** — it reports what the pointer is
+     * over and renders what you hand back.
+     */
+    hovered?: string | readonly string[] | null;
+    /**
+     * Fires when the pointer enters a row (with that row) or leaves every row
+     * (`null`) — the hover analog of `onRowClick`, and the list's half of the
+     * bidirectional channel: mirror it out to light the matching chart bar,
+     * pairing with {@link hovered} to sync hover both ways.
+     *
+     * Notification only (fires controlled or uncontrolled) and **deduped by row
+     * key**, so it reports a row transition, not every pointer move. Moving from
+     * one row straight to the next reports the new row — no `null` in between;
+     * `null` means the pointer genuinely left the rows.
+     */
+    onHover?: (row: R | null) => void;
     /** Each bar line's height in px. **Omitted ⇒ `8`.** */
     barHeight?: number;
     /** Rule between rows (`theme.axis.grid`). **Omitted ⇒ `true`.** */