@sportsdataverse/sdvplot 0.0.0-stage → 0.1.0

package/dist/interact.d.ts

@@ -0,0 +1,567 @@
+import { S as SelectionStore, R as RowFilter } from './selection-D4T3PkRt.js';
+
+/** A row field name, or an accessor. Index-based accessors cannot apply: linked tables re-test their own rows. */
+type Field<R> = (keyof R & string) | ((row: R) => unknown);
+/**
+ * What `brushFilter` brushes: the figure's rows, the fields its brushed axes encode (x and y, or one alone), each row's
+ * link id, what a brush holding no row means, and the scales of a chart that has no `figure.scale`.
+ */
+interface BrushFilterOptions<R> {
+    /** The rows the figure was drawn from. */
+    data: readonly R[];
+    /** The field the figure's x scale encodes. Without `y`, a 1-D brush along x over the svg's full height. */
+    x?: Field<R>;
+    /** The field the figure's y scale encodes. Without `x`, a 1-D brush along y over the svg's full width. */
+    y?: Field<R>;
+    /** The link id per row: the same values as the marks' `id` / `linkIds` channel. Default: the row index. */
+    id?: Field<R>;
+    /**
+     * A brush that holds no row. `"dim"` (the default): its region stays in the store, so every mark dims and a linked
+     * table shows no row. `"clear"`: it is no filter at all; the store goes idle and, when the gesture ends, the drawn
+     * rectangle is removed (a date window over the All-Star break selects no game, and left drawn would look applied).
+     */
+    empty?: "dim" | "clear";
+    /**
+     * The brushed axes' scales, overriding `figure.scale`: how a d3-drawn chart, which has none, is brushed. A d3 scale
+     * goes in as it is (`d3.scaleUtc()`, whose `range()` is a method); a {@link ScaleLike} works too.
+     */
+    scales?: {
+        x?: ScaleLike | D3ScaleLike;
+        y?: ScaleLike | D3ScaleLike;
+    };
+}
+/** A live brush: drive it programmatically, or remove it. */
+interface BrushFilterHandle {
+    /**
+     * Brush a region in DATA coordinates, one range per brushed axis (`null` clears), as if the user had dragged it. Rows
+     * are tested against these exact bounds, never their pixel round trip: a row on a bound is inside.
+     */
+    move(region: {
+        x?: readonly [unknown, unknown];
+        y?: readonly [unknown, unknown];
+    } | null): void;
+    /** Remove the overlay and stop following the store; clears its selection and predicate if this brush set them. */
+    destroy(): void;
+}
+/** The slice of a materialised Plot scale the brush reads (`plot.scale("x")`); structural, so no Plot import. */
+interface ScaleLike {
+    /** Data value to pixel. */
+    apply(value: unknown): unknown;
+    /** Pixel to data value; absent on band and point scales, which a brush cannot invert. */
+    invert?(pixel: unknown): unknown;
+    /** The pixel range; the brush's extent spans it. Absent (or with no finite value), the svg's box on that axis. */
+    range?: Iterable<unknown>;
+}
+/**
+ * A d3-scale scale as `d3.scaleLinear()`, `d3.scaleUtc()` or `d3.scaleBand()` makes it: callable, with `range()` a
+ * METHOD (a {@link ScaleLike}'s `range` is the pixels themselves), and on a band scale `bandwidth()` and `domain()`
+ * methods too. `brushFilter` and `linkCursor` adapt it, so a d3-drawn chart passes its own scales as they are.
+ */
+interface D3ScaleLike {
+    /** Data value to pixel. */
+    (value: never): unknown;
+    /** Pixel to data value; absent on band and point scales, which a brush cannot invert. */
+    invert?(pixel: number): unknown;
+    /** The pixel range, read once when the brush or cursor is made. */
+    range(): Iterable<unknown>;
+    /** A band scale's band width in pixels (a `linkCursor` band). */
+    bandwidth?(): number;
+    /** The domain; a band scale's values are each band's first value (a `linkCursor` band). */
+    domain?(): Iterable<unknown>;
+}
+/**
+ * What `Plot.plot` returns: the `<svg>`, or a `<figure>` wrapping it, exposing its scales. Any `<svg>` fits: a d3-drawn
+ * chart has no `scale` and passes `scales` instead.
+ */
+type PlotFigure = Element & {
+    scale?(name: "x" | "y"): ScaleLike | undefined;
+};
+/**
+ * Overlay a d3-brush on a rendered Plot figure, or on a d3-drawn `<svg>` given its own `scales`. Each brush move sets
+ * the store's `predicate` (the region as a row test, for linked tables) and `selected` (the ids of `data` inside it,
+ * for highlighting) in ONE notification. Pass `x` and `y` for a rectangle, or one of them for a 1-D brush across the
+ * whole svg (a date window on a timeline). Clearing the brush, or a click on the empty chart, clears both, but only
+ * while the store still holds this brush's region. A selection made elsewhere since (a table row, a toggled mark)
+ * survives, and so does one made before that holds exactly the brushed ids: the store kept that set, so the brush
+ * wrote none of its own. The drawn brush follows the store: when its region is cleared or replaced elsewhere, the
+ * rectangle is removed with no second write. `empty` says what a brush holding no row means. The overlay is inserted
+ * BEHIND the marks, so hovering a mark still reaches it. On a figure with a Plot `tip`, the press that starts a brush
+ * also pins the tip showing at that moment (Plot's pointer toggles a sticky tip on `pointerdown`); the brush still
+ * works. Throws `InputError` without `x` or `y`, or unless each brushed axis has a continuous (invertible) scale, in
+ * Node too. Returns a HANDLE, not a teardown function, because a brush has more to do than tear down: `move` drives it
+ * and `destroy` removes it (`linkSelection` and `linkCursor`, whose teardown is all they have, return a function). A
+ * no-op handle without a DOM.
+ *
+ * @example
+ * ```ts
+ * import * as Plot from "@observablehq/plot";
+ * import { createSelection } from "@sportsdataverse/sdvplot";
+ * import { brushFilter } from "@sportsdataverse/sdvplot/interact";
+ * import { linkIds } from "@sportsdataverse/sdvplot/plot";
+ *
+ * const rows = [
+ *   { team: "KC", wins: 15, net_epa: 0.063 },
+ *   { team: "LAC", wins: 11, net_epa: 0.101 },
+ *   { team: "MIA", wins: 8, net_epa: -0.019 },
+ * ];
+ * const svg = Plot.plot({ marks: [Plot.dot(rows, { x: "wins", y: "net_epa", render: linkIds(rows, "team") })] });
+ * const store = createSelection<(typeof rows)[number]>();
+ * const brush = brushFilter(svg, store, { data: rows, x: "wins", y: "net_epa", id: "team" });
+ * brush.move({ x: [10, 16], y: [0, 0.15] }); // drag over the 10+ win teams with a positive net EPA
+ * [...store.getState().selected]; // ["KC", "LAC"]
+ * ```
+ *
+ * @example A 1-D date window that clears when it holds no game
+ * ```ts
+ * import * as Plot from "@observablehq/plot";
+ * import { createSelection } from "@sportsdataverse/sdvplot";
+ * import { brushFilter } from "@sportsdataverse/sdvplot/interact";
+ * import { linkIds } from "@sportsdataverse/sdvplot/plot";
+ *
+ * // five of Brooklyn's 2025-26 games
+ * const games = [
+ *   { game_id: "0022500130", game_date: "2025-10-29", matchup: "BKN vs. ATL" },
+ *   { game_id: "0022500149", game_date: "2025-11-02", matchup: "BKN vs. PHI" },
+ *   { game_id: "0022500156", game_date: "2025-11-03", matchup: "BKN vs. MIN" },
+ *   { game_id: "0022500173", game_date: "2025-11-05", matchup: "BKN @ IND" },
+ *   { game_id: "0022500031", game_date: "2025-11-07", matchup: "BKN vs. DET" },
+ * ];
+ * const day = (g: (typeof games)[number]): Date => new Date(`${g.game_date}T00:00:00Z`);
+ * const svg = Plot.plot({
+ *   height: 60,
+ *   x: { type: "utc" },
+ *   marks: [Plot.tickX(games, { x: day, render: linkIds(games, "game_id") })],
+ * });
+ * const store = createSelection<(typeof games)[number]>();
+ * // x alone: a brush along the dates; "clear": a window holding no game is no filter and is not left drawn
+ * const brush = brushFilter(svg, store, { data: games, x: day, id: "game_id", empty: "clear" });
+ * brush.move({ x: [new Date("2025-11-01"), new Date("2025-11-06")] });
+ * [...store.getState().selected]; // ["0022500149", "0022500156", "0022500173"]
+ * ```
+ *
+ * @example A d3-drawn chart brushed through its own d3 scale
+ * ```ts
+ * import { scaleUtc, select } from "d3";
+ * import { createSelection } from "@sportsdataverse/sdvplot";
+ * import { brushFilter } from "@sportsdataverse/sdvplot/interact";
+ *
+ * // five of Brooklyn's 2025-26 games
+ * const games = [
+ *   { game_id: "0022500130", game_date: "2025-10-29", matchup: "BKN vs. ATL" },
+ *   { game_id: "0022500149", game_date: "2025-11-02", matchup: "BKN vs. PHI" },
+ *   { game_id: "0022500156", game_date: "2025-11-03", matchup: "BKN vs. MIN" },
+ *   { game_id: "0022500173", game_date: "2025-11-05", matchup: "BKN @ IND" },
+ *   { game_id: "0022500031", game_date: "2025-11-07", matchup: "BKN vs. DET" },
+ * ];
+ * const day = (g: (typeof games)[number]): Date => new Date(`${g.game_date}T00:00:00Z`);
+ * const x = scaleUtc([new Date("2025-10-28"), new Date("2025-11-08")], [10, 630]);
+ * const svg = document.createElementNS("http://www.w3.org/2000/svg", "svg");
+ * svg.setAttribute("viewBox", "0 0 640 60");
+ * select(svg)
+ *   .selectAll("rect")
+ *   .data(games)
+ *   .join("rect")
+ *   .attr("x", (g) => x(day(g)) - 1.5)
+ *   .attr("y", 6)
+ *   .attr("width", 3)
+ *   .attr("height", 40)
+ *   .attr("data-sdv-id", (g) => g.game_id); // the stamp linkIds would write
+ * const store = createSelection<(typeof games)[number]>();
+ * // no figure.scale on a d3 chart: pass the d3 scale itself (its range() is a method; brushFilter reads it)
+ * brushFilter(svg, store, { data: games, x: day, id: "game_id", scales: { x } }).move({
+ *   x: [new Date("2025-11-04"), new Date("2025-11-08")],
+ * });
+ * [...store.getState().selected]; // ["0022500173", "0022500031"]
+ * ```
+ */
+declare function brushFilter<R>(figure: PlotFigure, store: SelectionStore<R>, o: BrushFilterOptions<R>): BrushFilterHandle;
+
+/** A scale a cursor maps through: a {@link ScaleLike}, plus a band scale's width and domain. */
+interface BandScaleLike extends ScaleLike {
+    /** The band width in pixels. A number marks a band scale, whose domain values are the bands' first values. */
+    readonly bandwidth?: number;
+    /** The domain; a band scale's must be all numbers. */
+    readonly domain?: Iterable<unknown>;
+}
+/**
+ * What a figure draws for the cursor. `axis: "x" | "y"`: a rule across the plot at the value, or with `width` a band
+ * `width` data units wide centred on it, or on a band scale (`bandwidth`) the band holding it. `cross` is the other
+ * axis' scale: the rule spans its range (default: the figure's own other scale on a Plot figure, else the svg's
+ * viewBox). `axis: "ring"`: an ellipse around `center` (data coordinates) whose radii are the value mapped through the
+ * x and y scales, such as a shot distance around the hoop. Every scale is a Plot figure's (`svg.scale("x")`) or a d3
+ * scale as it is ({@link D3ScaleLike}: `d3.scaleLinear()`, `d3.scaleBand()`), as `brushFilter`'s `scales` are.
+ */
+type CursorShape = {
+    readonly axis: "x" | "y";
+    readonly scale: BandScaleLike | D3ScaleLike;
+    readonly width?: number;
+    readonly cross?: ScaleLike | D3ScaleLike;
+} | {
+    readonly axis: "ring";
+    readonly x: ScaleLike | D3ScaleLike;
+    readonly y: ScaleLike | D3ScaleLike;
+    readonly center: readonly [number, number];
+};
+/** How {@link linkCursor} follows and emits the store's cursor. */
+interface LinkCursorOptions {
+    /** The cursor field this figure draws and emits, such as `"shot_distance"`; a cursor naming another field hides it. */
+    readonly field: string;
+    /** What to draw, through which scale. */
+    readonly shape: CursorShape;
+    /** Write the value under the pointer to the store. Default `true` for `"x"` / `"y"`; a ring never emits. */
+    readonly emit?: boolean;
+    /** Snap an emitted value on a linear scale, such as `(v) => Math.floor(v) + 0.5` for 1 ft bins. Default: none. */
+    readonly snap?: (value: number) => number;
+    /** A readout beside an `"x"` cursor, one line per string. */
+    readonly label?: (value: number) => readonly string[];
+    /** Past this fraction of the axis' pixel range (0, 1] the readout flips to the cursor's left. Default 30 / 35. */
+    readonly flipAt?: number;
+    /** A dot on the cursor at this OTHER-axis data value (a curve's value there); `null` hides it. Needs `cross`. */
+    readonly dot?: (value: number) => number | null;
+}
+/**
+ * Draw the store's cursor (J34: one shared hover VALUE, such as a shot distance) through THIS figure's own scale, and
+ * write the value under the pointer back. Every linked chart follows the same number its own way: a band on share bars
+ * (linear x), the band holding it on FG% bars (a band scale), a band on a side chart (y), a rule on a curve, a ring
+ * around the hoop. Moving inside one snapped bin writes nothing; crossing a bin edge is one update; leaving the figure
+ * (`pointerleave`, `pointercancel`) or the axis' range clears the cursor this figure wrote, while the store still holds
+ * it: never one an app `store.set` or another figure wrote since, nor an equal one set before (the store kept that one,
+ * so this figure wrote none). A cursor never dims marks or filters a table (it is not an id). A store change moves
+ * attributes only: no element is added or removed, so a cursor costs O(1) per figure. The move and press listeners
+ * capture, so a Plot `tip` that stops a press from reaching other listeners does not stop this one; the leave listeners
+ * do not, so a mark's own `pointerleave` (the pointer crossing a bar's edge inside one bin) writes nothing. Styled by
+ * `--sdv-cursor-color` and `--sdv-cursor-width`. Returns a teardown FUNCTION, not a handle, because teardown is all it
+ * has (as `linkSelection`'s; `brushFilter`, `nearestHover` and `tooltip` return a handle with `destroy()`). The scales'
+ * pixel ranges are read once, so after a resize, relink. The teardown removes the cursor and its listeners, and clears
+ * the store's cursor when it still holds the one this figure last wrote (as `linkSelection`'s teardown does with its
+ * hover): a chart redrawn under the pointer leaves no cursor that no pointer drives. Throws `InputError` on a bad
+ * option, in Node too; a no-op without a DOM.
+ *
+ * @example
+ * ```ts
+ * import * as Plot from "@observablehq/plot";
+ * import { createSelection } from "@sportsdataverse/sdvplot";
+ * import { linkCursor } from "@sportsdataverse/sdvplot/interact";
+ * import { fgPctByDistance } from "@sportsdataverse/sdvplot/shots";
+ *
+ * // Brooklyn shots from the sportsdataverse-data nba_stats_shots release, 2025-26
+ * const shots = [
+ *   { x_legacy: -1, y_legacy: 7, shot_distance: 1, shot_value: 2, shot_result: "Made" },
+ *   { x_legacy: 0, y_legacy: 0, shot_distance: 0, shot_value: 2, shot_result: "Missed" },
+ *   { x_legacy: -44, y_legacy: 252, shot_distance: 26, shot_value: 3, shot_result: "Made" },
+ * ];
+ * const bins = fgPctByDistance(shots, 1, 30);
+ * const svg = Plot.plot({
+ *   x: { label: "Shot distance (ft)" },
+ *   marks: [Plot.rectY(bins, { x1: "distance", x2: (b) => b.distance + 1, y: "attempts" })],
+ * });
+ * const store = createSelection();
+ * linkCursor(svg, store, {
+ *   field: "shot_distance",
+ *   shape: { axis: "x", scale: svg.scale("x")!, width: 1 },
+ *   snap: (feet) => Math.floor(feet) + 0.5, // one value per 1 ft bin
+ *   label: (feet) => [`@ ${Math.floor(feet)} ft`],
+ * });
+ * store.set({ cursor: { field: "shot_distance", value: 26.5 } }); // what a pointer 26.3 ft out writes
+ * svg; // the 26-27 ft band shaded, with its readout
+ * ```
+ */
+declare function linkCursor<R>(root: Element, store: SelectionStore<R>, o: LinkCursorOptions): () => void;
+
+/**
+ * Interaction needs a live DOM. Without one (Node / SSR) every `sdvplot/interact` function is a no-op, so a
+ * server-rendered figure is byte-identical with or without a link.
+ *
+ * @example
+ * ```ts
+ * import { hasDom } from "@sportsdataverse/sdvplot/interact";
+ *
+ * // it depends on where this runs: a browser (or the jsdom that prerendered this page) has a DOM, Node has none
+ * `this ran ${hasDom() ? "with a DOM: interact functions work" : "without a DOM: interact functions are no-ops"}`;
+ * ```
+ */
+declare function hasDom(): boolean;
+/**
+ * Emphasise the marks under `root` stamped (`data-sdv-id`) with one of `ids` and dim the rest; `null` clears and an
+ * empty set dims everything. A class toggle, never a redraw: each call touches only the marks whose state changed,
+ * plus the root's class, and one CSS rule (`--sdv-dim-opacity`, default 0.2) does the dimming. Marks Plot draws later
+ * (a `Plot.pointer` layer) are indexed as they appear; axis logos (`data-sdv-axis`) are decorations and never dim.
+ * Returns the ids that match no mark here (an id absent from this figure is not an error). No-op without a DOM.
+ *
+ * @example
+ * ```ts
+ * import * as Plot from "@observablehq/plot";
+ * import { highlight } from "@sportsdataverse/sdvplot/interact";
+ * import { linkIds } from "@sportsdataverse/sdvplot/plot";
+ *
+ * const rows = [
+ *   { team: "KC", wins: 15, pf: 385 },
+ *   { team: "BUF", wins: 13, pf: 525 },
+ *   { team: "MIA", wins: 8, pf: 345 },
+ * ];
+ * const svg = Plot.plot({ marks: [Plot.dot(rows, { x: "wins", y: "pf", r: 6, render: linkIds(rows, "team") })] });
+ * const missing = highlight(svg, new Set(["KC", "SEA"])); // ["SEA"]: no SEA dot here; BUF and MIA dim
+ * svg;
+ * ```
+ */
+declare function highlight(root: Element, ids: ReadonlySet<string> | null): string[];
+
+/** What an sdvtables engine emits on `subscribe` (structurally its `TableEvent`). */
+type LinkEvent = {
+    readonly type: "change";
+} | {
+    readonly type: "hover";
+    readonly id: string | null;
+} | {
+    readonly type: "select";
+    readonly ids: ReadonlySet<string>;
+};
+/** The slice of an sdvtables `Table` that linking needs. Structural, so sdvplot never depends on sdvtables. */
+interface LinkableTable<Row> {
+    /** Filter the table's rows by a row test (the store's brush region); `null` clears it. */
+    setExternalFilter(filter: RowFilter<Row> | null): void;
+    /** Select rows by id; the table renders them selected. */
+    setSelection(ids: ReadonlySet<string>): void;
+    /** Light one row by id (the store's first hover id); `null` clears it. A table holds one hover id. */
+    setHover(id: string | null): void;
+    /** Row hover and click events; returns the unsubscribe function. */
+    subscribe(fn: (event: LinkEvent) => void): () => void;
+}
+/** What {@link linkSelection} wires to a store: one figure and/or one table. */
+interface LinkSelectionOptions<Row, Datum = unknown> {
+    /**
+     * The figure whose marks carry `data-sdv-id`: what `Plot.plot` returns (stamped by `linkIds`), or a d3-drawn `<svg>`
+     * with its own stamps.
+     */
+    figure?: Element;
+    /**
+     * How the figure writes `hover`. `true` (the default): the stamped mark under the pointer (`mouseover`). `false`: it
+     * writes nothing, for a figure another writer hovers. `{ id }`: the datum Plot's own `tip`/`pointer` picks, the
+     * nearest within its `maxRadius`, published as the figure's `value` with an `input` event; `id` maps it to a link id
+     * (`null` clears). Pass `figure` as `Plot.plot` returned it: with a caption or legend that is a `<figure>`, and only the
+     * figure hears `input`. Anything else throws `InputError`, in Node too.
+     */
+    hover?: boolean | {
+        readonly id: (datum: Datum) => unknown;
+    };
+    /** A `createTable` engine: `useTable().table`, or the one passed to `hydrate`. */
+    table?: LinkableTable<Row>;
+    /**
+     * `"toggle"`: each stamped mark of `figure` becomes a checkbox (`role`, `tabindex="0"`, `aria-checked` kept in step
+     * with the store), and a click, Enter or Space toggles its id in `selected`. Each checkbox keeps the mark's own
+     * accessible name: name the marks through Plot's `ariaLabel` channel (`ariaLabel: "matchup"`, an `aria-label`) or its
+     * `title` channel (a `<title>`); a mark with neither is named by its link id until teardown. Throws `InputError` when
+     * a mark sits in an `<a href>`: a checkbox inside a link is nested interactive content with two tab stops; and, with
+     * a DOM, when the figure already has a live toggle link, whose click would then toggle twice (tear it down first).
+     * On a Plot figure with a `tip`, a click also pins Plot's tip; give the tip `pointerEvents: "none"` so the pinned tip
+     * never takes a click meant for a mark under it.
+     */
+    select?: "toggle";
+}
+/**
+ * Wire a figure and/or a table to a selection store (J31). Figure: pointer hover → `hover` (see
+ * {@link LinkSelectionOptions.hover}); every store change → `highlight(figure, focusIds(state))`. Table: row hover /
+ * click → `hover` / `selected`; every store change → `setSelection(selected)`, `setExternalFilter(predicate)` and
+ * `setHover` with the first hover id. Loop-free: the store and the engine drop no-op updates, and the events a table
+ * emits while the store is being applied to it are not written back (so a two-id hover is never narrowed to the one id
+ * a table holds). One figure or one table per call; link several by calling again with the same store. The store
+ * comes first because the call takes a figure, a table or both. Returns a teardown FUNCTION, not a handle: teardown is
+ * all a link has, so `useEffect(() => linkSelection(store, o), deps)` is one line (`brushFilter`, `nearestHover` and
+ * `tooltip`, which have more to do, return a handle with `destroy()`). The teardown clears `hover` when the store still
+ * holds the hover this link wrote (as `nearestHover`'s `destroy` does; an equal hover set first elsewhere is not one it
+ * wrote): a figure redrawn under the pointer leaves no stale hover dimming the others. It then restores the view it
+ * changed, so a figure or table unlinked and kept on the page shows no store state: the figure un-dims (once the last
+ * link on it goes), its toggled marks get their own attributes back, and the table drops the brush filter and the hover
+ * it showed. It never clears store state another writer owns: a brush's region and a selection stay in the store for
+ * the views still linked. To replace a figure, tear its link down before linking the new one, which otherwise reads the
+ * old figure's hover. Inert without a DOM, so server-rendered markup never changes. With `select: "toggle"`, the
+ * figure's marks are keyboard-reachable checkboxes over `selected` ({@link LinkSelectionOptions.select}).
+ *
+ * @example
+ * ```ts
+ * import * as Plot from "@observablehq/plot";
+ * import { createSelection } from "@sportsdataverse/sdvplot";
+ * import { linkSelection } from "@sportsdataverse/sdvplot/interact";
+ * import { linkIds } from "@sportsdataverse/sdvplot/plot";
+ * import { createTable, defineTable } from "@sportsdataverse/sdvtables";
+ *
+ * const rows = [
+ *   { team: "KC", wins: 15, net_epa: 0.063 },
+ *   { team: "BUF", wins: 13, net_epa: 0.19 },
+ *   { team: "MIA", wins: 8, net_epa: -0.019 },
+ * ];
+ * type Row = (typeof rows)[number];
+ * const svg = Plot.plot({ marks: [Plot.dot(rows, { x: "wins", y: "net_epa", r: 6, render: linkIds(rows, "team") })] });
+ * const spec = defineTable<Row>().columns((c) => [c.text("team"), c.int("wins")]).rowKey("team").build();
+ * const table = createTable(spec, rows); // the engine a hydrated table or <SdvTable table/> renders
+ * const store = createSelection<Row>();
+ * linkSelection(store, { figure: svg });
+ * linkSelection(store, { table });
+ * table.setSelection(new Set(["BUF"])); // what a click on Buffalo's row calls: the store and the figure follow
+ * svg; // Buffalo's dot lit, the rest dimmed
+ * ```
+ *
+ * @example Games as checkboxes: click a cell, or Tab to it and press Enter or Space
+ * ```ts
+ * import * as Plot from "@observablehq/plot";
+ * import { createSelection } from "@sportsdataverse/sdvplot";
+ * import { linkSelection } from "@sportsdataverse/sdvplot/interact";
+ * import { linkIds } from "@sportsdataverse/sdvplot/plot";
+ *
+ * // five of Brooklyn's 2025-26 games
+ * const games = [
+ *   { game_id: "0022500130", game_date: "2025-10-29", matchup: "BKN vs. ATL", wl: "L" },
+ *   { game_id: "0022500149", game_date: "2025-11-02", matchup: "BKN vs. PHI", wl: "L" },
+ *   { game_id: "0022500156", game_date: "2025-11-03", matchup: "BKN vs. MIN", wl: "L" },
+ *   { game_id: "0022500173", game_date: "2025-11-05", matchup: "BKN @ IND", wl: "W" },
+ *   { game_id: "0022500031", game_date: "2025-11-07", matchup: "BKN vs. DET", wl: "L" },
+ * ];
+ * const svg = Plot.plot({
+ *   height: 60,
+ *   x: { type: "band" },
+ *   marks: [
+ *     Plot.cell(games, { x: "game_date", fill: "wl", ariaLabel: "matchup", render: linkIds(games, "game_id") }),
+ *   ],
+ * });
+ * const store = createSelection<(typeof games)[number]>();
+ * linkSelection(store, { figure: svg, select: "toggle" }); // each cell: role="checkbox", tabindex="0", aria-checked
+ * svg.querySelector('[data-sdv-id="0022500173"]')?.dispatchEvent(new MouseEvent("click", { bubbles: true }));
+ * svg; // the win at Indiana checked and lit, the rest dimmed: click a game, or Tab to it and press Enter or Space
+ * ```
+ */
+declare function linkSelection<Row, Datum = unknown>(store: SelectionStore<Row>, o: LinkSelectionOptions<Row, Datum>): () => void;
+
+/** A hover target: a mark's centre in PIXELS, in the svg's user space (where its scales put it), and its link id. */
+interface HoverPoint {
+    /** Horizontal position, svg user units. */
+    readonly x: number;
+    /** Vertical position, svg user units. */
+    readonly y: number;
+    /** The link id the mark is stamped with (`data-sdv-id`). */
+    readonly id: string;
+}
+/** Options for {@link nearestHover}. */
+interface NearestHoverOptions {
+    /** Every hoverable mark's centre. Points with a non-finite coordinate are skipped. */
+    readonly points: readonly HoverPoint[];
+    /** `"xy"` (the default): nearest in the plane. `"x"` / `"y"`: nearest along that axis alone, ignoring the other. */
+    readonly dimension?: "x" | "y" | "xy";
+    /** Farthest hover, in px: Euclidean for `"xy"`, along the axis for `"x"` / `"y"`. Default: unlimited. */
+    readonly radius?: number;
+    /** A margin inside the svg's bounds, in px, where the pointer hovers nothing. Default 0. */
+    readonly padding?: number;
+    /** The tooltip for a hovered id, shown at its point; `null` shows none. Default: no tooltip. */
+    readonly label?: (id: string) => {
+        readonly lines: readonly string[];
+        readonly swatch?: string;
+    } | null;
+}
+/** A live {@link nearestHover}. */
+interface NearestHoverHandle {
+    /** Re-target after a zoom or a resize: the marks' new centres. */
+    update(points: readonly HoverPoint[]): void;
+    /** Remove the listeners and the tooltip; clears `hover` when it still holds what this handle wrote. */
+    destroy(): void;
+}
+/**
+ * Hover the NEAREST mark of a d3-drawn (or any non-Plot) figure, within a radius, rather than the element under the
+ * pointer: sparse or small marks stay easy to hit. `"xy"` finds it with a Delaunay triangulation (`Delaunay.find`,
+ * as blazing-the-nets' hex chart does within 18 px); `"x"` / `"y"` bisect the points sorted along that axis (a 1-D
+ * Voronoi, as its distance bars do). The pointer writes `hover: [id]`, once per distinct mark; beyond `radius`, inside
+ * the `padding` margin, on `pointerleave` / `pointercancel` or with no points, it writes `hover: []`. `label` shows a
+ * {@link tooltip} at the mark, not at the pointer. Link the same figure with `hover: false` in `linkSelection` so
+ * this is its only hover writer while `highlight` still follows the store. The pointer listeners capture,
+ * so a handler registered earlier on the svg that stops the event (Plot's `tip` on `pointerdown`) cannot hide it.
+ * A Plot figure hovers through its own `tip` instead (`linkSelection`'s `hover: { id }`). Throws `InputError` on a
+ * negative `radius` or `padding` or an unknown `dimension`, in Node too, and when `root` is not an `<svg>`. Returns a
+ * HANDLE, not a teardown function, because it has more to do than tear down: `update` re-targets it and `destroy`
+ * removes it (`linkSelection` and `linkCursor`, whose teardown is all they have, return a function). A no-op handle
+ * without a DOM.
+ *
+ * @example
+ * ```ts
+ * import { createSelection } from "@sportsdataverse/sdvplot";
+ * import { linkSelection, nearestHover } from "@sportsdataverse/sdvplot/interact";
+ * import * as d3 from "d3";
+ *
+ * const rows = [
+ *   { team: "KC", wins: 15, net_epa: 0.063 },
+ *   { team: "BUF", wins: 13, net_epa: 0.19 },
+ *   { team: "MIA", wins: 8, net_epa: -0.019 },
+ *   { team: "LV", wins: 4, net_epa: -0.146 },
+ * ];
+ * const x = d3.scaleLinear([0, 17], [30, 410]);
+ * const y = d3.scaleLinear([-0.2, 0.2], [190, 10]);
+ * const svg = d3.create("svg").attr("viewBox", "0 0 440 200").attr("width", 440);
+ * svg
+ *   .selectAll("circle")
+ *   .data(rows)
+ *   .join("circle")
+ *   .attr("data-sdv-id", (d) => d.team) // the d3 way to stamp link ids
+ *   .attr("cx", (d) => x(d.wins))
+ *   .attr("cy", (d) => y(d.net_epa))
+ *   .attr("r", 5)
+ *   .attr("fill", "currentColor");
+ * const node = svg.node() as SVGSVGElement;
+ * const store = createSelection();
+ * linkSelection(store, { figure: node, hover: false }); // highlight follows the store; nearestHover writes hover
+ * nearestHover(node, store, {
+ *   points: rows.map((d) => ({ x: x(d.wins), y: y(d.net_epa), id: d.team })),
+ *   radius: 18,
+ *   label: (team) => ({ lines: [team, `net EPA/play ${rows.find((d) => d.team === team)?.net_epa}`] }),
+ * });
+ * node; // hover near a dot: within 18 px it lights and its tooltip shows
+ * ```
+ */
+declare function nearestHover<R>(root: Element, store: SelectionStore<R>, o: NearestHoverOptions): NearestHoverHandle;
+
+/** Options for {@link tooltip}. */
+interface TooltipOptions {
+    /** The width the box stays inside, in the svg's user units. Default: the svg's viewBox width. */
+    readonly width?: number;
+    /** The height the box stays inside. Default: the svg's viewBox height. */
+    readonly height?: number;
+    /** Text size in px; the box is sized from it. Default 11. */
+    readonly fontSize?: number;
+}
+/** A live tooltip that {@link tooltip} returns. */
+interface TooltipHandle {
+    /**
+     * Show `lines` (the first bold) beside the point `x`, `y` in the svg's user space, with an optional colour swatch
+     * at the right. Placed 12 px right of the point and above it; flipped to its left when it would pass the right
+     * edge, and kept inside the top and bottom.
+     */
+    show(x: number, y: number, lines: readonly string[], swatch?: string): void;
+    /** Hide the box; `show` brings it back. */
+    hide(): void;
+    /** Remove the box. */
+    destroy(): void;
+}
+/**
+ * An in-SVG tooltip for d3-drawn and other non-Plot figures (a Plot figure uses its own `tip` mark): a rounded box of
+ * text lines, the first bold, with an optional 12 px colour swatch, kept inside the svg. It is drawn hidden, with
+ * `pointer-events="none"`, and re-appended last on each `show` so it stays above the marks. Its size is ESTIMATED from
+ * the text (`0.6 * fontSize` per character, `1.35 * fontSize` per line), never measured, so it renders the same under
+ * jsdom and in every browser. Colours: `--sdv-tip-bg` (default `rgba(34,34,34,.85)`) and `--sdv-tip-fg` (default
+ * `#ddd`). Throws `InputError` on a non-positive `fontSize` or a negative size, in Node too, and when `root` is not an
+ * `<svg>`. Returns a HANDLE (`show`, `hide`, `destroy`), not a teardown function, because it has more to do than tear
+ * down. A no-op handle without a DOM: a server render never holds a tooltip.
+ *
+ * @example
+ * ```ts
+ * import { loadLeague, teamColorsSync } from "@sportsdataverse/sdvplot";
+ * import { tooltip } from "@sportsdataverse/sdvplot/interact";
+ * import * as d3 from "d3";
+ *
+ * await loadLeague("nfl");
+ * const red = teamColorsSync("nfl", "KC");
+ * const svg = d3.create("svg").attr("viewBox", "0 0 320 120").attr("width", 320);
+ * svg.append("circle").attr("cx", 280).attr("cy", 80).attr("r", 6).attr("fill", red ?? "currentColor");
+ * // Kansas City's 2024 line, as a chart shows it on hover: no room right of the dot, so the box flips to its left
+ * tooltip(svg.node() as SVGSVGElement).show(280, 80, ["KC 15-2", "Net EPA/play 0.063", "QB Patrick Mahomes"], red);
+ * svg.node();
+ * ```
+ */
+declare function tooltip(root: Element, o?: TooltipOptions): TooltipHandle;
+
+export { type BandScaleLike, type BrushFilterHandle, type BrushFilterOptions, type CursorShape, type D3ScaleLike, type Field, type HoverPoint, type LinkCursorOptions, type LinkEvent, type LinkSelectionOptions, type LinkableTable, type NearestHoverHandle, type NearestHoverOptions, type PlotFigure, type ScaleLike, type TooltipHandle, type TooltipOptions, brushFilter, hasDom, highlight, linkCursor, linkSelection, nearestHover, tooltip };