@pond-ts/charts 0.57.0 → 0.59.0

package/dist/ListTable.js

@@ -12,20 +12,304 @@ import { jsx as _jsx, jsxs as _jsxs } from "react/jsx-runtime";
  * 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';
+import { Fragment, useEffect, useMemo, useRef, 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';
+/**
+ * Stable identity for "nothing hovered" — the same module-constant trick
+ * `ChartContainer` uses for `EMPTY_SELECTION`, so the (overwhelmingly common)
+ * no-hover case doesn't mint a fresh set on every render.
+ */
+const EMPTY_HOVER = new Set();
+/** The same trick for "nothing selected" — see {@link EMPTY_HOVER}. */
+const EMPTY_SELECTED = new Set();
 /** 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, }) {
+export function ListTable({ rows, kind, renderGlyphs, before = [], after = [], renderExpanded, defaultExpanded, onExpandToggle, selected, onRowClick, onRowSelect, hovered, onHover, 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 interactive = onRowClick !== undefined || onRowSelect !== undefined;
+    // The drag-range gesture, armed by the MOUNT (interaction RFC A4.2 rule 1 —
+    // the same reason a bare `<MultiSelector />` enables the canvas sweep).
+    const ranges = onRowSelect !== undefined;
+    // Hover: controlled (`hovered`) or uncontrolled (internal), mirroring the
+    // canvas layers' channel on `ChartContainer` (RFC `interaction.md` A3.1 —
+    // the list family speaks the same vocabulary, not a parallel one).
+    const [internalHovered, setInternalHovered] = useState(null);
+    const controlledHover = hovered !== undefined;
+    // Rows track + light hover when there's a click affordance (as they always
+    // have) or when the consumer wired either half of the hover channel.
+    const hoverWired = controlledHover || onHover !== undefined;
+    const tracksHover = interactive || hoverWired;
+    // Normalize the prop's three accepted shapes — one key, a set, or nothing —
+    // into the single shape the render asks its question in ("is this row in the
+    // hovered set"), the same normalization `ChartContainer` does for its
+    // `SelectInfo` union. `EMPTY_HOVER` keeps the empty case identity-stable.
+    const hoveredKeys = useMemo(() => {
+        const raw = controlledHover ? hovered : internalHovered;
+        if (raw === null || raw === undefined)
+            return EMPTY_HOVER;
+        return new Set(typeof raw === 'string' ? [raw] : raw);
+    }, [controlledHover, hovered, internalHovered]);
+    // …and the identical normalization for `selected`, which now takes the same
+    // union. It is deliberately the same three shapes and the same question
+    // ("is this row in the set"): the two channels of one vocabulary should not
+    // differ in how a consumer spells them.
+    const selectedKeys = useMemo(() => {
+        if (selected === null || selected === undefined)
+            return EMPTY_SELECTED;
+        return new Set(typeof selected === 'string' ? [selected] : selected);
+    }, [selected]);
+    const rowByKey = useMemo(() => new Map(rows.map((row) => [row.key, row])), [rows]);
+    /**
+     * The live drag-range: the row index the press landed on, the one the
+     * pointer is over now, and whether it has ever left the first.
+     *
+     * **Crossing into another row is what makes it a range** — not a pixel slop.
+     * A row is tall and discrete, so "did the pointer reach a different row" is
+     * the question the gesture actually turns on, and asking it directly means a
+     * press-and-release on one row can never accidentally commit a range (nor
+     * can a horizontal wobble, which on a stack of rows means nothing at all).
+     * It also needs no coordinates: `pointerenter` per row answers it.
+     *
+     * A ref, not state, for the reason the canvas gesture keeps one: the
+     * handlers must never read a state mirror that may not have committed.
+     */
+    const dragRef = useRef(null);
+    /** The run the drag currently covers — the live preview, painted as hover. */
+    const [dragRun, setDragRun] = useState(null);
+    /**
+     * A press is armed — used only to suppress **native text selection** for the
+     * gesture's duration.
+     *
+     * It has to be state rather than the ref above, because the suppression is a
+     * style: `user-select` must already be `none` in the DOM before the browser
+     * starts extending a selection, which it does on the first move after the
+     * press. `pointerdown` is a discrete event, so React flushes this update
+     * synchronously — the style lands before any `pointermove` arrives.
+     *
+     * Scoped to the press rather than to the whole list on purpose: a data list's
+     * labels are hostnames and ticker symbols, and people copy them. Mounting a
+     * range gesture should not cost the list its selectable text.
+     */
+    const [armed, setArmed] = useState(false);
+    /**
+     * The **selection anchor** — the row a range extends *from*, shared by both
+     * input methods so they are one model rather than two: click a row, then
+     * Shift-Arrow, and the run starts where you clicked.
+     *
+     * A plain move (arrow, click, Enter) re-anchors; a shift-extend deliberately
+     * does not, so repeated Shift-Down grows one run instead of walking a
+     * two-row window down the list.
+     */
+    const anchorRef = useRef(null);
+    const tableRef = useRef(null);
+    /**
+     * This table's own row elements, in display order.
+     *
+     * Scoped with `:scope >` because an expanded row's detail may contain a
+     * whole nested list, whose rows carry the same attribute — a plain
+     * descendant query would walk into it and the arrow keys would navigate
+     * somebody else's list. (`handlePointerOver` guards the same hazard.)
+     */
+    const rowEls = () => Array.from(tableRef.current?.querySelectorAll(':scope > tbody > tr[data-list-row]') ?? []);
+    /** A ranged drag ends in a `click` too; this swallows that one. */
+    const rangedClickRef = useRef(false);
+    /**
+     * Keyboard parity with the pointer: there is no drag on a keyboard, so the
+     * range has to arrive as a **modifier** there.
+     *
+     * That is not the contradiction with `SelectModifiers`' "an ordinal range is
+     * a gesture, not a modifier" that it looks like. The note is about not
+     * overloading a *pointer* chord that already means something else (a region
+     * drag); a keyboard has no competing gesture and Shift-Arrow is the one
+     * range idiom every platform already teaches.
+     *
+     * - **Arrow Up/Down** — move focus one row; re-anchor.
+     * - **Home/End** — move focus to the first/last row; re-anchor.
+     * - **Shift** with any of those — move focus and report the run from the
+     *   anchor, which stays put.
+     * - **Enter/Space** — select the focused row (with modifiers, so ⌘/Ctrl-Enter
+     *   adds); re-anchor.
+     *
+     * Focus is moved by focusing the row element rather than by tracking an
+     * index in state: the browser is already the source of truth for what has
+     * focus, and a second copy of that would be one more thing to keep in sync.
+     */
+    const onRowKeyDown = (e, i) => {
+        if (!interactive)
+            return;
+        // **Only when the ROW itself has focus.** A row may contain its own
+        // interactive content — the expander chevron is a real `<button>`, and a
+        // consumer's `render` cell could be anything — and `keydown` bubbles. The
+        // chevron stops propagation on `click` but a button cannot stop what it
+        // does not know about, so without this guard Enter on the chevron reached
+        // here, got `preventDefault`ed, and selected the row instead of expanding
+        // it (and worse, the cancelled keydown suppresses the button's own Space
+        // activation). Arrow keys would likewise yank focus out of the button.
+        if (e.target !== e.currentTarget)
+            return;
+        if (e.key === 'Enter' || e.key === ' ') {
+            e.preventDefault();
+            anchorRef.current = i;
+            onRowClick?.(rows[i]);
+            onRowSelect?.([rows[i]], mods(e));
+            return;
+        }
+        const last = rows.length - 1;
+        const to = e.key === 'ArrowDown'
+            ? Math.min(i + 1, last)
+            : e.key === 'ArrowUp'
+                ? Math.max(i - 1, 0)
+                : e.key === 'Home'
+                    ? 0
+                    : e.key === 'End'
+                        ? last
+                        : null;
+        if (to === null)
+            return;
+        // Claim the key before anything else can act on it: Arrow and Home/End
+        // would otherwise scroll the page out from under the list.
+        e.preventDefault();
+        rowEls()[to]?.focus();
+        if (!e.shiftKey || !ranges) {
+            anchorRef.current = to;
+            return;
+        }
+        // Extending: the anchor holds, so Shift-Down repeatedly grows ONE run.
+        // With no anchor yet (arrowing in from a Tab, never having selected), the
+        // row we left is the honest one to start from.
+        const from = anchorRef.current ?? i;
+        anchorRef.current = from;
+        onRowSelect?.(runOf(from, to), mods(e));
+    };
+    /** The rows of the inclusive index run `[a, b]`, in display order. */
+    const runOf = (a, b) => rows.slice(Math.min(a, b), Math.max(a, b) + 1);
+    const mods = (e) => ({
+        // `metaKey || ctrlKey`, character-for-character what `Layers` resolves
+        // for a canvas select. Deliberately NOT a `navigator.platform` sniff:
+        // whatever the better rule might be, a list and a chart in the same app
+        // must not disagree about what "add to selection" means — and
+        // `navigator.platform` is deprecated and absent in some hosts anyway.
+        additive: e.metaKey || e.ctrlKey,
+        ctrlKey: e.ctrlKey,
+        metaKey: e.metaKey,
+        shiftKey: e.shiftKey,
+        altKey: e.altKey,
+    });
+    /** Press: arm a potential range on this row. Nothing commits yet. */
+    const beginDrag = (i, e) => {
+        if (!ranges)
+            return;
+        // **Touch is excluded, deliberately.** A vertical drag over a list on a
+        // touch device is how you SCROLL, and claiming it for a range would make
+        // the list impossible to scroll past. A touch range gesture needs its own
+        // affordance (a long-press, or an explicit multi-select mode) rather than
+        // stealing the one gesture the platform already spent. Touch keeps
+        // click-to-select, which still reports through `onRowSelect`.
+        if (e.pointerType === 'touch')
+            return;
+        // The press is a plain move: it re-anchors, so a later Shift-Arrow
+        // extends from the row the user actually grabbed.
+        anchorRef.current = i;
+        dragRef.current = { anchor: i, current: i, ranged: false };
+        setArmed(true);
+        setDragRun(null);
+    };
+    /** The pointer reached row `i` with the button still down. */
+    const extendDrag = (i) => {
+        const d = dragRef.current;
+        if (d === null || i === d.current)
+            return;
+        d.current = i;
+        d.ranged = i !== d.anchor;
+        setDragRun(new Set(runOf(d.anchor, i).map((r) => r.key)));
+    };
+    /** Release: a range commits here; a single row is left to the click. */
+    const endDrag = (e) => {
+        const d = dragRef.current;
+        dragRef.current = null;
+        setDragRun(null);
+        setArmed(false);
+        if (d === null)
+            return;
+        // Hand the hover channel back, to the row the pointer actually ended on.
+        // The press suppressed reporting for its whole duration, so without this
+        // the list believes nothing is hovered until the pointer moves again —
+        // the row under the cursor would go dark on release and light again on
+        // the next twitch.
+        reportHover(rows[d.current]?.key ?? null);
+        if (!d.ranged)
+            return;
+        rangedClickRef.current = true;
+        onRowSelect?.(runOf(d.anchor, d.current), mods(e));
+    };
+    // A release **outside** the rows would otherwise leave the drag armed, so a
+    // later stray `pointerenter` would resume a gesture the user had finished. It
+    // commits rather than cancels: the run the user let go of is the run they
+    // meant, and where the pointer happened to be when they did is not the
+    // library's business. Registered only while a range gesture is possible — a
+    // list with no `onRowSelect` adds no listener at all.
+    useEffect(() => {
+        if (!ranges)
+            return;
+        const onUp = (e) => {
+            const d = dragRef.current;
+            if (d === null)
+                return;
+            dragRef.current = null;
+            setDragRun(null);
+            setArmed(false);
+            // Released off the rows, so there is no row under the pointer to hand
+            // the hover back to — unlike `endDrag`, which knows exactly which.
+            reportHover(null);
+            if (!d.ranged)
+                return;
+            rangedClickRef.current = true;
+            onRowSelect?.(runOf(d.anchor, d.current), mods(e));
+        };
+        window.addEventListener('pointerup', onUp);
+        return () => window.removeEventListener('pointerup', onUp);
+    });
+    // The last key we reported, so `onHover` fires on a row transition rather
+    // than on every pointer move within a row — the canvas `onHover` dedup rule.
+    // A ref (not state): it must not drive a render of its own.
+    const lastHoverRef = useRef(null);
+    const reportHover = (key) => {
+        // **A held press owns the hover channel** — the same rule the canvas
+        // follows (`Layers` clears the single-mark hover the moment a sweep arms).
+        // Reporting "you are hovering row d" while a run b→d is being previewed
+        // would have the two channels contradict each other, with no way for the
+        // consumer to tell which was current.
+        //
+        // Gated on the press being ARMED, not on the run having started: hover is
+        // delegated at the table (`handlePointerOver`) while the range extends
+        // per row, and React dispatches the ancestor's handler FIRST — so
+        // checking `ranged` here would let the crossing that *starts* the run
+        // report a hover on its way past, and only suppress the ones after it.
+        if (dragRef.current !== null)
+            return;
+        if (lastHoverRef.current === key)
+            return;
+        lastHoverRef.current = key;
+        if (!controlledHover)
+            setInternalHovered(key);
+        onHover?.(key === null ? null : (rowByKey.get(key) ?? null));
+    };
+    // Delegated at the table rather than per-row, so moving from one row to its
+    // neighbour reports the new row once — per-row enter/leave would emit a
+    // spurious `null` in between, which the canvas channel never does.
+    const handlePointerOver = (e) => {
+        const rowEl = e.target?.closest('[data-list-row]');
+        // A row of a NESTED list (an expanded detail may hold one) is not ours to
+        // report — only rows belonging to this table's own `data-list` count.
+        const own = rowEl != null && rowEl.closest('[data-list]') === e.currentTarget;
+        reportHover(own ? rowEl.getAttribute('data-list-row') : null);
+    };
     const toggle = (key) => {
         const open = !expanded.has(key);
         setExpanded((prev) => {
@@ -40,6 +324,11 @@ export function ListTable({ rows, kind, renderGlyphs, before = [], after = [], r
     };
     const ink = listInk(theme);
     const accent = theme.annotation?.color ?? FALLBACK_ACCENT;
+    // The row-chart register. Absent ⇒ the pre-token look exactly: a hover band
+    // borrowed from `legend.border`, a selection rail from the annotation
+    // register, and no dimmed state — so a hand-built theme's rows do not
+    // shift under it (the same back-compatibility `theme.brush` was given).
+    const reg = theme.list;
     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);
@@ -60,9 +349,15 @@ export function ListTable({ rows, kind, renderGlyphs, before = [], after = [], r
         borderLeft: baseline ? `1px solid ${theme.axis.grid}` : undefined,
     });
     const drawnMarkers = markers.filter((m) => m.frac !== null);
-    return (_jsx("table", { "data-list": kind, style: {
+    return (_jsx("table", { ref: tableRef, "data-list": kind, onPointerOver: tracksHover ? handlePointerOver : undefined, onPointerLeave: tracksHover ? () => reportHover(null) : undefined, style: {
             width: '100%',
             borderCollapse: 'collapse',
+            // Suppress native text selection **only while a press is armed**. A
+            // drag across rows would otherwise sweep up the label text along the
+            // way — the run gets picked out in the browser's own selection colour,
+            // fighting the band and the rail for the same meaning. Released, the
+            // labels are selectable again (see `armed`).
+            ...(armed ? { userSelect: 'none' } : {}),
             font: `${theme.font.size}px/${1.5} ${theme.font.family}`,
             color: ink,
             background: theme.background,
@@ -81,28 +376,87 @@ export function ListTable({ rows, kind, renderGlyphs, before = [], after = [], r
                                         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 isSelected = selectedKeys.has(row.key);
+                    // **A live drag owns the surface**, exactly as the canvas sweep does
+                    // (`Layers` clears the single-mark hover the moment a sweep arms):
+                    // while a run is being drawn it IS what "would be selected if you
+                    // released now", so it replaces the pointer's own hover rather than
+                    // being unioned with it. `hovered` and `onHover` are untouched — the
+                    // consumer's channel is not hijacked, it is simply out-ranked for
+                    // the duration.
+                    const isHovered = dragRun !== null ? dragRun.has(row.key) : hoveredKeys.has(row.key);
+                    // Dimmed means *something else* is selected — nothing recedes while
+                    // the selection is empty. Only meaningful once a register exists;
+                    // without one there is no dimmed state at all.
+                    const isDimmed = reg !== undefined && selectedKeys.size > 0 && !isSelected;
+                    // **Selection outranks hover on the band**, because selection is
+                    // committed and hover is transient: a hovered selected row must not
+                    // read as merely hovered. The rail follows the band so the two
+                    // never disagree about which state the row is in.
+                    const band = isSelected
+                        ? reg?.selectedBand
+                        : isHovered
+                            ? (reg?.hoverBand ?? theme.legend?.border ?? theme.axis.grid)
+                            : undefined;
+                    const rail = isSelected
+                        ? (reg?.selectedRail ?? accent)
+                        : isHovered
+                            ? reg?.hoverRail
+                            : undefined;
                     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
+                    return (_jsxs(Fragment, { children: [_jsxs("tr", { "data-list-row": row.key, ...(isSelected ? { 'data-selected': '' } : {}), ...(isHovered ? { 'data-hovered': '' } : {}), onClick: !interactive
                                     ? undefined
                                     : (e) => {
-                                        if (e.key === 'Enter' || e.key === ' ') {
-                                            e.preventDefault();
-                                            onRowClick(row);
+                                        // A ranged drag also fires a click; swallow that one,
+                                        // or the release would both commit the run and then
+                                        // immediately report the single row under the pointer.
+                                        if (rangedClickRef.current) {
+                                            rangedClickRef.current = false;
+                                            return;
                                         }
-                                    }, onPointerEnter: interactive ? () => setHovered(row.key) : undefined, onPointerLeave: interactive ? () => setHovered(null) : undefined, style: {
+                                        anchorRef.current = i;
+                                        onRowClick?.(row);
+                                        // `onRowSelect` is a strict SUPERSET of `onRowClick`,
+                                        // the way `<MultiSelector>` is of `<Selector>`: below
+                                        // the range gesture a click is still a click, and it
+                                        // reports one row plus its modifiers. Both fire when
+                                        // both are mounted — each consumer does its own job.
+                                        onRowSelect?.([row], mods(e));
+                                    }, ...(ranges
+                                    ? {
+                                        onPointerDown: (e) => beginDrag(i, e),
+                                        // Per-row `pointerenter` rather than pointer capture:
+                                        // capture would route every later event to the pressed
+                                        // row and the other rows would never hear the pointer
+                                        // arrive. The cost is that a release outside the table
+                                        // is not seen here — the window listener below is what
+                                        // covers that.
+                                        onPointerEnter: (e) => {
+                                            if (e.buttons !== 0)
+                                                extendDrag(i);
+                                        },
+                                        onPointerUp: endDrag,
+                                    }
+                                    : {}), 
+                                // A clickable row is keyboard-reachable too: focusable, and
+                                // Enter / Space activate it (Space's default scroll is eaten).
+                                tabIndex: interactive ? 0 : undefined, onKeyDown: interactive ? (e) => onRowKeyDown(e, i) : 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,
+                                    background: band,
+                                    // The rail: a 3px inset edge — reads on any ground and
+                                    // moves no layout. It is chrome for the whole ROW, so it
+                                    // resolves from the list register rather than from
+                                    // `bar[as]`; a row may carry several metrics and there is
+                                    // only ever one rail.
+                                    boxShadow: rail === undefined ? undefined : `inset 3px 0 0 ${rail}`,
+                                    // The row is the target, not the bar (see `ChartTheme.list`):
+                                    // a 4% row would otherwise be a sliver to aim at, so the
+                                    // whole band is one hit area of at least 44px.
+                                    // (`height`, not `minHeight`: a table row ignores the
+                                    // latter, while the former is treated as a MINIMUM — the
+                                    // used height is max(specified, content).)
+                                    ...(interactive || hoverWired ? { height: 44 } : {}),
                                 }, 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.
@@ -111,7 +465,11 @@ export function ListTable({ rows, kind, renderGlyphs, before = [], after = [], r
                                         // 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) => (
+                                        style: glyphCellStyle('6px'), children: _jsxs("div", { style: { position: 'relative' }, children: [renderGlyphs(row, {
+                                                    selected: isSelected,
+                                                    hovered: isHovered,
+                                                    dimmed: isDimmed,
+                                                }), 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
@@ -124,7 +482,7 @@ export function ListTable({ rows, kind, renderGlyphs, before = [], after = [], r
                                                         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) => {
+                                                    } }, 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' : 'Expand'} ${row.label ?? row.key}`, onClick: (e) => {
                                                 // The chevron toggles; it must not double as a row click.
                                                 e.stopPropagation();
                                                 toggle(row.key);

package/dist/ScatterChart.d.ts

@@ -132,8 +132,9 @@ export type ScatterChartProps<S extends SeriesSchema = SeriesSchema, VS extends
  * the nearest-point readout. Scatter reuses the shared tracker rather than
  * adding a separate `onNearest` channel, so a scatter reads out exactly like a
  * line. Click selection hit-tests each point's disc (`hitTest`) — **opt-in via
- * `id`**; the selected point (matching the selection's series `id` and the sample
- * `key`) gets a highlight ring. Without an `id` the scatter is display-only.
+ * `id`**; every selected point (matching a selection member's series `id` and
+ * the sample `key`) gets a highlight ring, and every hovered one a fainter
+ * version of it. Without an `id` the scatter is display-only.
  *
  * ```tsx
  * <Layers>

package/dist/ScatterChart.js

@@ -3,9 +3,11 @@ import { ValueSeries } from 'pond-ts';
 import { fromTimeSeries, fromValueSeries } from './data.js';
 import { drawScatter, hitTestScatter, nearestIndex, scatterExtent, } from './scatter.js';
 import { resolveEncoding, } from './encoding.js';
-import { ContainerContext, LayersContext } from './context.js';
+import { spansForLayer } from './span.js';
+import { ContainerContext, LayersContext, } from './context.js';
 import { legendLabelFor, useLegendItems, } from './swatch.js';
 import { useSlotKey } from './use-slot-key.js';
+import { sweep2D } from './sweep.js';
 /**
  * A scatter draw layer: one mark per finite point at `(x, column-value)`
  * — x from the series' key / axis column (time or value axis) —
@@ -20,8 +22,9 @@ import { useSlotKey } from './use-slot-key.js';
  * the nearest-point readout. Scatter reuses the shared tracker rather than
  * adding a separate `onNearest` channel, so a scatter reads out exactly like a
  * line. Click selection hit-tests each point's disc (`hitTest`) — **opt-in via
- * `id`**; the selected point (matching the selection's series `id` and the sample
- * `key`) gets a highlight ring. Without an `id` the scatter is display-only.
+ * `id`**; every selected point (matching a selection member's series `id` and
+ * the sample `key`) gets a highlight ring, and every hovered one a fainter
+ * version of it. Without an `id` the scatter is display-only.
  *
  * ```tsx
  * <Layers>
@@ -93,6 +96,12 @@ export function ScatterChart({ series, column, as: semantic, id, axis, radius, c
     // axis, the axis value on a value axis; either way it's cs.x[i], the key
     // column's begin buffer. Used for selection identity.
     const keyAt = useMemo(() => (i) => cs.x[i], [cs]);
+    // The selection's span entries, narrowed to this layer (interaction RFC
+    // A5.2). Every point shares one label (the series label), so a span's `rows`
+    // channel resolves here once; the `x`/`y` intervals ride through for the
+    // draw's per-point test. Reference-stable when empty, so other layers' spans
+    // never re-register (or repaint) this one.
+    const layerSpans = useMemo(() => spansForLayer(container.selectedSpans, id, seriesLabel), [container.selectedSpans, id, seriesLabel]);
     const entry = useMemo(() => ({
         layer: {
             as: semantic,
@@ -130,8 +139,61 @@ export function ScatterChart({ series, column, as: semantic, id, axis, radius, c
                 ? {}
                 : {
                     hitTest: (px, py, xScale, yScale) => hitTestScatter(cs, px, py, xScale, yScale, encoding, keyAt, id, seriesLabel, offset),
+                    /**
+                     * The **free rect** ([PND-INTERACT2D]). A point is a position,
+                     * not a column, so `sweep2D` gets `begin === end` and its x cut
+                     * means "keys inside the window"; the y half is a plain scan of
+                     * that run, because a scatter's second dimension is continuous
+                     * and has nothing to snap to.
+                     *
+                     * Each materialised hit is exactly what `hitTestScatter` reports
+                     * for that point, so a swept point and a clicked one are the
+                     * same currency.
+                     */
+                    // A point/cell owns a position, not a column: the sweep is a rect, and
+                    // the resting cursor is the small crosshair rather than a band.
+                    sweepsRect: true,
+                    beginSweep: () => cs.length === 0
+                        ? null
+                        : sweep2D({
+                            id,
+                            // A point layer: no span either side of the key.
+                            begin: cs.x,
+                            end: cs.x,
+                            length: cs.length,
+                            spanFrom: 'drag',
+                            materialize: (lo, hi, y0, y1) => {
+                                const out = [];
+                                for (let i = lo; i < hi; i += 1) {
+                                    const v = cs.y[i];
+                                    // Half-open in y, matching `SpanSelection.y`'s own
+                                    // containment test — so replaying the committed span
+                                    // reproduces exactly this set.
+                                    if (!Number.isFinite(v) || v < y0 || v >= y1)
+                                        continue;
+                                    out.push({
+                                        id,
+                                        key: keyAt(i),
+                                        value: v,
+                                        color: encoding.colorAt(i),
+                                        label: seriesLabel,
+                                    });
+                                }
+                                return out;
+                            },
+                            // The committed window is the drag's own, not the
+                            // points' tight bounds: the rect is what the user drew,
+                            // and a tightened box would quietly exclude a point that
+                            // arrives later inside the same region.
+                            channels: (_hits, y0, y1) => ({ y: [y0, y1] }),
+                        }),
                 }),
-            draw: (ctx, xScale, yScale) => drawScatter(ctx, cs, xScale, yScale, style, encoding, keyAt, labelAt, font, container.selected, id, offset, decimate),
+            draw: (ctx, xScale, yScale) => drawScatter(ctx, cs, xScale, yScale, style, encoding, keyAt, labelAt, font, 
+            // Both sets whole. `selected` has been plural since [PND-MULTISEL]
+            // and `hovered` since RFC A4.3, and the draw rings every member
+            // naming this layer — reading `[0]` here quietly showed one ring
+            // for a three-mark selection.
+            container.selected, container.hovered, id, offset, decimate, layerSpans),
         },
         axisId: axis,
         index,
@@ -147,6 +209,8 @@ export function ScatterChart({ series, column, as: semantic, id, axis, radius, c
         labelAt,
         font,
         container.selected,
+        container.hovered,
+        layerSpans,
         offset,
         decimate,
         axis,