@pond-ts/charts 0.56.2 → 0.58.0

package/dist/BarChart.js

@@ -1,10 +1,15 @@
 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, resolveBarBaseline, stackAt, stackBinExtent, stackValueExtent, } from './bars.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
@@ -24,14 +29,21 @@ import { useSlotKey } from './use-slot-key.js';
  * domain spans zero, or on the axis floor when an explicit `<YAxis min>` sits
  * above zero (see {@link resolveBarBaseline}).
  *
- * **Baseline (stacked).** A stack is **cumulative from value 0** — the segments
- * sum upward from the zero line, so its value axis **must include 0**. The
- * auto-fit guarantees this: {@link stackValueExtent} always returns `[0, maxTotal]`.
- * An explicit `<YAxis min>` **above** 0 is therefore unsupported for a stack — it
- * would hide the bottom of the cumulative column; only the portion above the floor
- * draws (clipped cleanly at the plot floor, as any bar below an explicit floor is).
- * Segment values are assumed **non-negative** (a negative or zero segment is
- * skipped — diverging stacks are out of scope).
+ * **Baseline (stacked).** A stack is **cumulative from value 0** — so its value
+ * axis **must include 0**. The auto-fit guarantees this:
+ * {@link stackValueExtent} returns `[minNegativeTotal, maxPositiveTotal]`, both
+ * seeded at `0`. An explicit `<YAxis min>` **above** 0 is therefore unsupported
+ * for a stack — it would hide the bottom of the cumulative column; only the
+ * portion above the floor draws (clipped cleanly at the plot floor, as any bar
+ * below an explicit floor is).
+ *
+ * **Signed stacks are supported** ([PND-SIGNSTACK]): each bin keeps two running
+ * totals, so positive segments stack **up** from the zero line and negative
+ * ones stack **down** from it — the signed histogram (net flow by category,
+ * inflow/outflow, buy/sell pressure by venue). A **zero** segment is still
+ * skipped, having no extent to draw or hit-test. This changed in the
+ * threshold-banding wave: negative segments were previously dropped outright
+ * and silently, so a mixed-sign series rendered as an all-positive chart.
  *
  * **Interaction (opt-in via `id`).** Hover lights the bar / segment under the
  * cursor (hit-tested by pixel rect, so it works in both orientations); click
@@ -48,7 +60,7 @@ import { useSlotKey } from './use-slot-key.js';
  * </Layers>
  * ```
  */
-export function BarChart({ series, bins, categories, column, columns, as: semantic, colors, binColors, orientation = 'vertical', ordinal = false, id, axis, gap, decimate = true, legend, index = 0, }) {
+export function BarChart({ series, bins, categories, column, columns, as: semantic, colors, binColors, thresholds, bandColors, orientation = 'vertical', ordinal = false, id, axis, gap, decimate = true, legend, index = 0, }) {
     const container = useContext(ContainerContext);
     if (container === null) {
         throw new Error('<BarChart> must be rendered inside a <ChartContainer>');
@@ -183,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)
@@ -232,17 +250,136 @@ export function BarChart({ series, bins, categories, column, columns, as: semant
     // The stacked path's bar-thickness floor comes from `bar.default` (not the `as`
     // role — `as` is single-series only), matching how `gapPx` sources its default.
     const stackMinWidth = bar.default.minWidth;
+    // ── Threshold ladder ([PND-BANDBAR2]) ────────────────────────────────────
+    // Resolved once here rather than per bar per frame: normalize the breakpoints
+    // (sort, drop non-finite), then pair them with `bandColors` → the role's
+    // `BarStyle.bands`. Everything that can go wrong with the pairing is a
+    // *silent* wrong-looking chart, so each case dev-warns — this feature exists
+    // because a quietly-unbanded bar was the workaround's failure mode.
+    // Value-compare the two array props rather than relying on their identity.
+    // `thresholds={[1, 2]}` inline is the documented usage and the shape every
+    // story and doc example uses — and a fresh array each render would rebuild
+    // the ladder, hence the layer `entry` below, hence a `registerLayer` call
+    // **every render**. That is a repaint treadmill, not just a noisy warning.
+    // The same value-compare-on-registration reasoning `<YAxis ticks>` already
+    // applies.
+    const thresholdKey = thresholds === undefined ? '' : thresholds.join(',');
+    const bandColorKey = bandColors === undefined ? '' : bandColors.join(',');
+    const bandLadder = useMemo(() => {
+        const steps = normalizeThresholds(thresholds);
+        if (steps === null) {
+            if (isDev && thresholds !== undefined && thresholds.length > 0) {
+                console.warn('<BarChart thresholds>: no usable breakpoints, so no banding was ' +
+                    'applied — each must be finite and greater than zero. Bars draw ' +
+                    'in the flat fill.');
+            }
+            return undefined;
+        }
+        // Some, but not all, entries dropped. Silently banding on a subset of what
+        // the caller wrote is exactly the class of quiet wrongness this feature is
+        // meant to remove, so say so.
+        if (isDev && thresholds !== undefined && steps.length < thresholds.length) {
+            console.warn(`<BarChart thresholds>: dropped ${thresholds.length - steps.length} ` +
+                'breakpoint(s) that were not finite and greater than zero. The ' +
+                'ladder is walked on the magnitude and mirrored onto whichever side ' +
+                'of zero a bar is on, so a negative breakpoint has no meaning; ' +
+                `banding on [${steps.join(', ')}].`);
+        }
+        const want = steps.length + 1;
+        const supplied = bandColors ?? singleStyle.bands;
+        if (supplied === undefined || supplied.length === 0) {
+            if (isDev) {
+                console.warn(`<BarChart thresholds>: ${steps.length} breakpoint(s) need ${want} ` +
+                    'band colours, but neither `bandColors` nor the theme role’s ' +
+                    '`BarStyle.bands` supplies any. Bars draw in the flat fill.');
+            }
+            return undefined;
+        }
+        if (supplied.length < want && isDev) {
+            console.warn(`<BarChart thresholds>: ${steps.length} breakpoint(s) need ${want} ` +
+                `band colours but only ${supplied.length} were supplied; bands ` +
+                'above the last colour fall back to the flat fill.');
+        }
+        // Pad a short ladder with the flat fill so the draw path can index freely.
+        const resolved = supplied.length >= want
+            ? supplied.slice(0, want)
+            : [
+                ...supplied,
+                ...Array.from({ length: want - supplied.length }, () => singleStyle.fill),
+            ];
+        return { thresholds: steps, colors: resolved };
+        // eslint-disable-next-line react-hooks/exhaustive-deps -- `thresholdKey` /
+        // `bandColorKey` are the value-compared stand-ins for the array props.
+    }, [thresholdKey, bandColorKey, singleStyle]);
+    // Conflicts between the ladder and the shapes it can't apply to. In an effect
+    // so a re-render doesn't re-log; each fires once per genuinely new pairing.
+    const multiGroup = shape.kind === 'stacked' && shape.ss.groups.length > 1;
+    const hasLadder = bandLadder !== undefined;
+    const hasBinColors = binColors !== undefined;
+    useEffect(() => {
+        if (!isDev || !hasLadder)
+            return;
+        if (hasBinColors) {
+            console.warn('<BarChart>: `thresholds` and `binColors` are both set. They are two ' +
+                'answers to “what colour is this bar”; `binColors` wins as the more ' +
+                'specific one, and the threshold bands are ignored.');
+        }
+        if (multiGroup) {
+            console.warn('<BarChart>: `thresholds` is ignored on a multi-group stack — a ' +
+                'segment that is already one slice of a total has no defined ' +
+                'banding. Threshold bands apply to single-value bars (`series` / ' +
+                '`bins` / `categories`), in either orientation.');
+        }
+    }, [hasLadder, hasBinColors, multiGroup]);
     // Stacked style: per-group fills (colors override → theme role → default),
     // plus the shared opacity / outline from the default bar style. Memoized on the
     // groups + colours so a selection change doesn't rebuild it.
     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
+            // path can read the same `fill → hover → highlight` channel every other
+            // bar does, instead of accepting those theme values and ignoring them.
+            highlight: base.highlight,
+            ...(base.hover !== undefined ? { hover: base.hover } : {}),
+            ...(base.selectedOutline !== undefined
+                ? { selectedOutline: base.selectedOutline }
+                : {}),
+            ...(base.emphasisOpacity !== undefined
+                ? { emphasisOpacity: base.emphasisOpacity }
+                : {}),
+            ...(base.dimmed !== undefined ? { dimmed: base.dimmed } : {}),
             ...(binColors !== undefined ? { binFills: binColors } : {}),
         };
     }, [bar, groups, colors, binColors]);
@@ -251,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') {
@@ -303,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
@@ -312,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
@@ -330,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),
+                    draw: (ctx, xScale, yScale) => drawBars(ctx, bs, xScale, yScale, singleStyle, resolveBarBaseline(yScale), gapPx, id, selection, hover, decimate, binColors, bandLadder, layerSpans),
                 },
                 axisId: axis,
                 index,
@@ -390,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),
+                draw: (ctx, xScale, yScale) => drawStacks(ctx, ss, orientation, xScale, yScale, stackStyle, gapPx, stackMinWidth, id, selection, hover, bandLadder, layerSpans),
             },
             axisId: axis,
             index,
@@ -405,6 +658,7 @@ export function BarChart({ series, bins, categories, column, columns, as: semant
         singleStyle,
         stackStyle,
         binColors,
+        bandLadder,
         label,
         id,
         gapPx,
@@ -412,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`.** */

package/dist/BarList.js

@@ -36,7 +36,7 @@ export function BarList(props) {
     // One normalized view of the union — `isSeriesSource` is the runtime
     // narrowing; the doors are mutually exclusive by construction now.
     const source = props;
-    const { rows, series, label, columns, domain, sortBy, sortDirection = 'desc', sort, before, after, renderExpanded, defaultExpanded, onExpandToggle, selected, onRowClick, markers, barHeight = 8, divided, baseline, theme = defaultTheme, } = source;
+    const { rows, series, label, columns, domain, sortBy, sortDirection = 'desc', sort, before, after, renderExpanded, defaultExpanded, onExpandToggle, selected, onRowClick, onRowSelect, hovered, onHover, markers, barHeight = 8, divided, baseline, theme = defaultTheme, } = source;
     // A runtime guard for JS consumers and `any`-typed call sites — the
     // props union makes both branches unreachable from typed TS, but a
     // silently-ignored source prop is a worse failure than a throw.
@@ -55,9 +55,30 @@ export function BarList(props) {
         frac: listFraction(m.value, scale),
         ...(m.label !== undefined ? { label: m.label } : {}),
     })), [markers, scale]);
-    return (_jsx(ListTable, { rows: sorted, kind: "bar", markers: resolvedMarkers, before: before, after: after, renderExpanded: renderExpanded, defaultExpanded: defaultExpanded, onExpandToggle: onExpandToggle, selected: selected, onRowClick: onRowClick, divided: divided, baseline: baseline, theme: theme, renderGlyphs: (row) => (_jsx(_Fragment, { children: columns.map((col, ci) => {
+    return (_jsx(ListTable, { rows: sorted, kind: "bar", markers: resolvedMarkers, before: before, after: after, renderExpanded: renderExpanded, defaultExpanded: defaultExpanded, onExpandToggle: onExpandToggle, selected: selected, onRowClick: onRowClick, onRowSelect: onRowSelect, hovered: hovered, onHover: onHover, divided: divided, baseline: baseline, theme: theme, renderGlyphs: (row, state) => (_jsx(_Fragment, { children: columns.map((col, ci) => {
                 const style = theme.bar[col.as ?? 'default'] ?? theme.bar.default;
                 const frac = listFraction(row.values[col.column], scale);
+                // **The fill's state treatment — decorative, never load-bearing.**
+                // The band and the rail have already said "selected"; this only
+                // agrees with them. It is skipped entirely on a multi-metric row
+                // because there the fill IS the metric's identity, and recolouring
+                // it would trade a distinction the reader needs for one they
+                // already have (`ChartTheme.list`'s channel rule).
+                //
+                // Which is also why nothing below may be the *only* signal: strip
+                // this block and a selected row still reads as selected.
+                const soleMetric = columns.length === 1;
+                const fill = state.selected && soleMetric
+                    ? style.highlight
+                    : state.dimmed
+                        ? (style.dimmed ?? style.fill)
+                        : style.fill;
+                // A `dimmed` token carries its own alpha (`rgba(…,0.32)`), so
+                // multiplying `opacity` on top of it would dim twice. Fall back to
+                // the raw 0.32 only when the theme names no dimmed colour.
+                const fillOpacity = state.dimmed && style.dimmed === undefined
+                    ? style.opacity * 0.32
+                    : style.opacity;
                 return (_jsxs("div", { "data-list-track": col.column, style: {
                         position: 'relative',
                         height: barHeight,
@@ -75,8 +96,8 @@ export function BarList(props) {
                                 bottom: 0,
                                 left: 0,
                                 width: `${frac * 100}%`,
-                                background: style.fill,
-                                opacity: style.opacity,
+                                background: fill,
+                                opacity: fillOpacity,
                                 borderRadius: barHeight / 2,
                             } }))] }, `${ci} ${col.column}`));
             }) })) }));