@sportsdataverse/sdvplot 0.0.0-stage → 0.1.0

package/dist/react.d.ts

@@ -0,0 +1,101 @@
+import { ImgHTMLAttributes, ReactElement } from 'react';
+import { L as LogoUrlOptions, C as ColorOptions } from './marks-DH-tQIP-.js';
+import { E as EspnHeadshotLeague } from './headshots-B2J_LOO8.js';
+import { V as Value, R as ResolveOptions } from './resolve-CQW-jzvr.js';
+import { S as SelectionStore, a as SelectionState } from './selection-D4T3PkRt.js';
+import { H as HeadshotIdSystem, L as League, V as Variant, M as MarkType, T as TeamId } from './types-C7n6gJF3.js';
+
+type ImgProps = Omit<ImgHTMLAttributes<HTMLImageElement>, "src" | "alt" | "height" | "width">;
+interface TeamLogoProps extends ImgProps {
+    team: Value;
+    league: League;
+    season?: LogoUrlOptions["season"];
+    variant?: Variant;
+    markType?: MarkType;
+    /** Rendered `height` in px; width is left unset so the browser keeps the aspect. */
+    size?: number;
+    /** Defaults to the team's name. */
+    alt?: string;
+}
+/**
+ * Team logo `<img>`. Loads the league index on first use; renders nothing until resolved and for an unknown team.
+ *
+ * @example
+ * ```tsx
+ * import { TeamLogo } from "@sportsdataverse/sdvplot/react";
+ *
+ * <TeamLogo team="KC" league="nfl" size={64} />;
+ * ```
+ */
+declare function TeamLogo({ team, league, season, variant, markType, size, alt, ...imgProps }: TeamLogoProps): ReactElement | null;
+/** `TeamLogo` with `markType="wordmark"`. */
+declare function Wordmark(props: Omit<TeamLogoProps, "markType">): ReactElement | null;
+interface HeadshotProps extends ImgProps {
+    playerId: Value;
+    league: EspnHeadshotLeague;
+    idSystem?: HeadshotIdSystem;
+    /** Height in px (default 60); width follows the 600:436 headshot aspect. */
+    height?: number;
+    /** Default `name`, then "Player headshot". `""` marks it decorative (the initials box is then `aria-hidden`). */
+    alt?: string;
+    /**
+     * `"initials"`: when there is no headshot URL or the image fails to load, show up to three initials of `name` in a
+     * box of the headshot's size (blazing-the-nets `main` `components/Headshot.tsx:15-29`). Default `"none"`: a failed
+     * load leaves the `<img>`, and an id with no URL renders nothing.
+     */
+    fallback?: "none" | "initials";
+    /** The player's name, for the initials and the default alt text. */
+    name?: string;
+}
+/**
+ * Player headshot `<img>`: sync for ESPN ids; gsis ids render once the gsis map has loaded. Renders nothing for an
+ * unknown/malformed id, or a league/idSystem `headshotUrl` rejects, unless `fallback="initials"` and a `name` are
+ * given, which show the player's initials instead.
+ *
+ * @example
+ * ```tsx
+ * import { Headshot } from "@sportsdataverse/sdvplot/react";
+ *
+ * <Headshot playerId="3918298" league="nfl" height={80} alt="Josh Allen" />;
+ * ```
+ */
+declare function Headshot({ playerId, league, idSystem, height, alt, fallback, name, ...imgProps }: HeadshotProps): ReactElement | null;
+/** `{team: "#hex"}` for a league once loaded (`undefined` before); reloads when `league`/`which` change. */
+declare function useTeamColors(league: League, { which }?: {
+    which?: ColorOptions["which"];
+}): Record<string, string> | undefined;
+/** Sync resolver `(value, opts?) => TeamId | undefined` once the league is loaded (`undefined` before); reloads when `league` changes. */
+declare function useResolve(league: League): ((value: Value, opts?: ResolveOptions) => TeamId | undefined) | undefined;
+/**
+ * The state of a `createSelection` store (J31), re-rendering on every change and never on a no-op patch. On the
+ * server, and in the first client render, it reads the store's current state, so server and client markup agree.
+ * Redrawing from it is the component's choice: filter rows with `state.predicate`, emphasise `state.selected`.
+ *
+ * @example
+ * ```tsx
+ * import { createSelection } from "@sportsdataverse/sdvplot";
+ * import { useSelection } from "@sportsdataverse/sdvplot/react";
+ * import type { ReactElement } from "react";
+ *
+ * const store = createSelection();
+ * store.set({ selected: ["KC", "BUF"] });
+ * function Picked(): ReactElement {
+ *   const { selected } = useSelection(store); // re-renders on every change of the store
+ *   return (
+ *     <table>
+ *       <tbody>
+ *         {[...selected].map((id) => (
+ *           <tr key={id}>
+ *             <td>{id}</td>
+ *           </tr>
+ *         ))}
+ *       </tbody>
+ *     </table>
+ *   );
+ * }
+ * <Picked />;
+ * ```
+ */
+declare function useSelection<Row>(store: SelectionStore<Row>): SelectionState<Row>;
+
+export { Headshot, type HeadshotProps, TeamLogo, type TeamLogoProps, Wordmark, useResolve, useSelection, useTeamColors };

package/dist/react.js

@@ -0,0 +1,164 @@
+"use client";
+import { logoUrlSync } from './chunk-KKH6ABMA.js';
+import { loadLeague, resolveSync, getLeagueSync, loadGsis, headshotUrl, palette, HEADSHOT_ASPECT } from './chunk-TAXO3VXH.js';
+import './chunk-E7G7VSLV.js';
+import { useState, useEffect, useRef, useSyncExternalStore, useLayoutEffect } from 'react';
+import { jsx } from 'react/jsx-runtime';
+
+function TeamLogo({
+  team,
+  league,
+  season,
+  variant,
+  markType,
+  size,
+  alt,
+  ...imgProps
+}) {
+  const [mark, setMark] = useState();
+  useEffect(() => {
+    let live = true;
+    (async () => {
+      await loadLeague(league);
+      if (!live) return;
+      const o = {};
+      if (season !== void 0) o.season = season;
+      if (variant !== void 0) o.variant = variant;
+      if (markType !== void 0) o.markType = markType;
+      const src = logoUrlSync(team, league, o);
+      const id = resolveSync(team, league, { season });
+      const name = getLeagueSync(league).teams.find((t) => t.team_id === id)?.name ?? "";
+      setMark(src === void 0 ? void 0 : { src, name });
+    })().catch(() => {
+      if (live) setMark(void 0);
+    });
+    return () => {
+      live = false;
+    };
+  }, [team, league, season, variant, markType]);
+  if (mark === void 0) return null;
+  return /* @__PURE__ */ jsx("img", { src: mark.src, alt: alt ?? mark.name, height: size, ...imgProps });
+}
+function Wordmark(props) {
+  return /* @__PURE__ */ jsx(TeamLogo, { ...props, markType: "wordmark" });
+}
+var initialsOf = (name) => name.split(" ").map((w) => Array.from(w)[0] ?? "").join("").slice(0, 3);
+var useClientLayoutEffect = typeof document === "undefined" ? useEffect : useLayoutEffect;
+function Headshot({
+  playerId,
+  league,
+  idSystem,
+  height = 60,
+  alt,
+  fallback = "none",
+  name,
+  ...imgProps
+}) {
+  const [, setGsisReady] = useState(false);
+  const [failed, setFailed] = useState();
+  const img = useRef(null);
+  useEffect(() => {
+    if (idSystem !== "gsis") return;
+    let live = true;
+    loadGsis().then(
+      () => {
+        if (live) setGsisReady(true);
+      },
+      () => {
+      }
+    );
+    return () => {
+      live = false;
+    };
+  }, [idSystem]);
+  let src;
+  try {
+    src = headshotUrl(playerId, league, idSystem === void 0 ? {} : { idSystem });
+  } catch {
+    src = void 0;
+  }
+  const label = alt ?? (name || void 0) ?? "Player headshot";
+  const width = Math.round(height * HEADSHOT_ASPECT);
+  useClientLayoutEffect(() => {
+    if (img.current?.complete && img.current.naturalWidth === 0) setFailed(src);
+  }, [src]);
+  if (src === void 0 || fallback === "initials" && src === failed) {
+    if (fallback !== "initials" || name === void 0) return null;
+    return /* @__PURE__ */ jsx(
+      "span",
+      {
+        ...label === "" ? { "aria-hidden": true } : { role: "img", "aria-label": label },
+        className: imgProps.className,
+        style: {
+          display: "inline-flex",
+          alignItems: "center",
+          justifyContent: "center",
+          width,
+          height,
+          background: "var(--sdv-line, #e2e2e2)",
+          color: "var(--sdv-muted, #525252)",
+          ...imgProps.style
+        },
+        children: initialsOf(name)
+      }
+    );
+  }
+  const shown = src;
+  return (
+    // biome-ignore lint/a11y/useAltText: alt always defaults to a string; imgProps cannot carry it
+    /* @__PURE__ */ jsx(
+      "img",
+      {
+        ref: img,
+        src: shown,
+        alt: label,
+        height,
+        width,
+        ...imgProps,
+        onError: (e) => {
+          setFailed(shown);
+          imgProps.onError?.(e);
+        }
+      }
+    )
+  );
+}
+function useTeamColors(league, { which } = {}) {
+  const [colors, setColors] = useState();
+  useEffect(() => {
+    let live = true;
+    setColors(void 0);
+    palette(league, void 0, which === void 0 ? {} : { which }).then((c) => {
+      if (live) setColors(c);
+    }).catch(() => {
+      if (live) setColors(void 0);
+    });
+    return () => {
+      live = false;
+    };
+  }, [league, which]);
+  return colors;
+}
+function useResolve(league) {
+  const [ready, setReady] = useState();
+  useEffect(() => {
+    let live = true;
+    setReady(void 0);
+    loadLeague(league).then(() => {
+      if (live) setReady(league);
+    }).catch(() => {
+      if (live) setReady(void 0);
+    });
+    return () => {
+      live = false;
+    };
+  }, [league]);
+  return ready === void 0 ? void 0 : (value, opts) => resolveSync(value, ready, opts);
+}
+function useSelection(store) {
+  return useSyncExternalStore(store.subscribe, store.getState, store.getState);
+}
+
+export { Headshot, TeamLogo, Wordmark, useResolve, useSelection, useTeamColors };
+//# sourceMappingURL=react.js.map
+//# sourceMappingURL=react.js.map

package/dist/react.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/react/index.tsx"],"names":[],"mappings":"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","file":"react.js","sourcesContent":["import {\n  type ImgHTMLAttributes,\n  type ReactElement,\n  useEffect,\n  useLayoutEffect,\n  useRef,\n  useState,\n  useSyncExternalStore,\n} from \"react\";\nimport { type ColorOptions, palette } from \"../colors.js\";\nimport { type EspnHeadshotLeague, HEADSHOT_ASPECT, headshotUrl, loadGsis } from \"../headshots.js\";\nimport { getLeagueSync, loadLeague } from \"../index-data.js\";\nimport { type LogoUrlOptions, logoUrlSync } from \"../marks.js\";\nimport { type ResolveOptions, type Value, resolveSync } from \"../resolve.js\";\nimport type { SelectionState, SelectionStore } from \"../selection.js\";\nimport type { HeadshotIdSystem, League, MarkType, TeamId, Variant } from \"../types.js\";\n\ntype ImgProps = Omit<ImgHTMLAttributes<HTMLImageElement>, \"src\" | \"alt\" | \"height\" | \"width\">;\n\nexport interface TeamLogoProps extends ImgProps {\n  team: Value;\n  league: League;\n  season?: LogoUrlOptions[\"season\"];\n  variant?: Variant;\n  markType?: MarkType;\n  /** Rendered `height` in px; width is left unset so the browser keeps the aspect. */\n  size?: number;\n  /** Defaults to the team's name. */\n  alt?: string;\n}\n\n/**\n * Team logo `<img>`. Loads the league index on first use; renders nothing until resolved and for an unknown team.\n *\n * @example\n * ```tsx\n * import { TeamLogo } from \"@sportsdataverse/sdvplot/react\";\n *\n * <TeamLogo team=\"KC\" league=\"nfl\" size={64} />;\n * ```\n */\nexport function TeamLogo({\n  team,\n  league,\n  season,\n  variant,\n  markType,\n  size,\n  alt,\n  ...imgProps\n}: TeamLogoProps): ReactElement | null {\n  const [mark, setMark] = useState<{ src: string; name: string } | undefined>();\n  useEffect(() => {\n    let live = true;\n    // One async body: any throw (bad league, bad variant, lookup error) becomes a rejection the .catch swallows.\n    (async () => {\n      await loadLeague(league);\n      if (!live) return;\n      const o: LogoUrlOptions = {};\n      if (season !== undefined) o.season = season;\n      if (variant !== undefined) o.variant = variant;\n      if (markType !== undefined) o.markType = markType;\n      const src = logoUrlSync(team, league, o);\n      const id = resolveSync(team, league, { season });\n      const name = getLeagueSync(league).teams.find((t) => t.team_id === id)?.name ?? \"\";\n      setMark(src === undefined ? undefined : { src, name });\n    })().catch(() => {\n      if (live) setMark(undefined);\n    });\n    return () => {\n      live = false;\n    };\n  }, [team, league, season, variant, markType]);\n  if (mark === undefined) return null;\n  // biome-ignore lint/a11y/useAltText: alt is always set (prop or team name); imgProps cannot carry it\n  return <img src={mark.src} alt={alt ?? mark.name} height={size} {...imgProps} />;\n}\n\n/** `TeamLogo` with `markType=\"wordmark\"`. */\nexport function Wordmark(props: Omit<TeamLogoProps, \"markType\">): ReactElement | null {\n  return <TeamLogo {...props} markType=\"wordmark\" />;\n}\n\nexport interface HeadshotProps extends ImgProps {\n  playerId: Value;\n  league: EspnHeadshotLeague;\n  idSystem?: HeadshotIdSystem;\n  /** Height in px (default 60); width follows the 600:436 headshot aspect. */\n  height?: number;\n  /** Default `name`, then \"Player headshot\". `\"\"` marks it decorative (the initials box is then `aria-hidden`). */\n  alt?: string;\n  /**\n   * `\"initials\"`: when there is no headshot URL or the image fails to load, show up to three initials of `name` in a\n   * box of the headshot's size (blazing-the-nets `main` `components/Headshot.tsx:15-29`). Default `\"none\"`: a failed\n   * load leaves the `<img>`, and an id with no URL renders nothing.\n   */\n  fallback?: \"none\" | \"initials\";\n  /** The player's name, for the initials and the default alt text. */\n  name?: string;\n}\n\n/**\n * The first character of every space-separated word, up to three, as blazing-the-nets `main` does\n * (`Headshot.tsx:16-20`): suffixes and particles are words (\"Brian Thomas Jr.\" is \"BTJ\"), \"De'Von\" is one word.\n * It differs from `main` only on an astral first character, which it keeps whole where `w[0]` leaves half of it.\n */\nconst initialsOf = (name: string): string =>\n  name\n    .split(\" \")\n    .map((w) => Array.from(w)[0] ?? \"\")\n    .join(\"\")\n    .slice(0, 3);\n\n// useLayoutEffect warns during React 18 server rendering; on the server no effect runs anyway.\nconst useClientLayoutEffect = typeof document === \"undefined\" ? useEffect : useLayoutEffect;\n\n/**\n * Player headshot `<img>`: sync for ESPN ids; gsis ids render once the gsis map has loaded. Renders nothing for an\n * unknown/malformed id, or a league/idSystem `headshotUrl` rejects, unless `fallback=\"initials\"` and a `name` are\n * given, which show the player's initials instead.\n *\n * @example\n * ```tsx\n * import { Headshot } from \"@sportsdataverse/sdvplot/react\";\n *\n * <Headshot playerId=\"3918298\" league=\"nfl\" height={80} alt=\"Josh Allen\" />;\n * ```\n */\nexport function Headshot({\n  playerId,\n  league,\n  idSystem,\n  height = 60,\n  alt,\n  fallback = \"none\",\n  name,\n  ...imgProps\n}: HeadshotProps): ReactElement | null {\n  const [, setGsisReady] = useState(false); // re-render once loadGsis resolves\n  const [failed, setFailed] = useState<string | undefined>(); // the src that failed to load\n  const img = useRef<HTMLImageElement>(null);\n  useEffect(() => {\n    if (idSystem !== \"gsis\") return;\n    let live = true;\n    loadGsis().then(\n      () => {\n        if (live) setGsisReady(true);\n      },\n      () => {},\n    );\n    return () => {\n      live = false;\n    };\n  }, [idSystem]);\n  let src: string | undefined;\n  try {\n    src = headshotUrl(playerId, league, idSystem === undefined ? {} : { idSystem });\n  } catch {\n    src = undefined;\n  }\n  const label = alt ?? (name || undefined) ?? \"Player headshot\";\n  const width = Math.round(height * HEADSHOT_ASPECT);\n  // React replays no error that fired before hydration (or before mount): read the settled image instead. A\n  // loading image is not complete yet, and a loaded one has a natural width.\n  useClientLayoutEffect(() => {\n    if (img.current?.complete && img.current.naturalWidth === 0) setFailed(src);\n  }, [src]);\n  if (src === undefined || (fallback === \"initials\" && src === failed)) {\n    if (fallback !== \"initials\" || name === undefined) return null;\n    return (\n      <span\n        {...(label === \"\" ? { \"aria-hidden\": true } : { role: \"img\", \"aria-label\": label })}\n        className={imgProps.className}\n        style={{\n          display: \"inline-flex\",\n          alignItems: \"center\",\n          justifyContent: \"center\",\n          width,\n          height,\n          background: \"var(--sdv-line, #e2e2e2)\",\n          color: \"var(--sdv-muted, #525252)\",\n          ...imgProps.style,\n        }}\n      >\n        {initialsOf(name)}\n      </span>\n    );\n  }\n  const shown = src;\n  return (\n    // biome-ignore lint/a11y/useAltText: alt always defaults to a string; imgProps cannot carry it\n    <img\n      ref={img}\n      src={shown}\n      alt={label}\n      height={height}\n      width={width}\n      {...imgProps}\n      onError={(e) => {\n        setFailed(shown);\n        imgProps.onError?.(e);\n      }}\n    />\n  );\n}\n\n/** `{team: \"#hex\"}` for a league once loaded (`undefined` before); reloads when `league`/`which` change. */\nexport function useTeamColors(\n  league: League,\n  { which }: { which?: ColorOptions[\"which\"] } = {},\n): Record<string, string> | undefined {\n  const [colors, setColors] = useState<Record<string, string> | undefined>();\n  useEffect(() => {\n    let live = true;\n    setColors(undefined);\n    palette(league, undefined, which === undefined ? {} : { which })\n      .then((c) => {\n        if (live) setColors(c);\n      })\n      .catch(() => {\n        if (live) setColors(undefined);\n      });\n    return () => {\n      live = false;\n    };\n  }, [league, which]);\n  return colors;\n}\n\n/** Sync resolver `(value, opts?) => TeamId | undefined` once the league is loaded (`undefined` before); reloads when `league` changes. */\nexport function useResolve(\n  league: League,\n): ((value: Value, opts?: ResolveOptions) => TeamId | undefined) | undefined {\n  const [ready, setReady] = useState<League | undefined>();\n  useEffect(() => {\n    let live = true;\n    setReady(undefined);\n    loadLeague(league)\n      .then(() => {\n        if (live) setReady(league);\n      })\n      .catch(() => {\n        if (live) setReady(undefined);\n      });\n    return () => {\n      live = false;\n    };\n  }, [league]);\n  return ready === undefined ? undefined : (value, opts) => resolveSync(value, ready, opts);\n}\n\n/**\n * The state of a `createSelection` store (J31), re-rendering on every change and never on a no-op patch. On the\n * server, and in the first client render, it reads the store's current state, so server and client markup agree.\n * Redrawing from it is the component's choice: filter rows with `state.predicate`, emphasise `state.selected`.\n *\n * @example\n * ```tsx\n * import { createSelection } from \"@sportsdataverse/sdvplot\";\n * import { useSelection } from \"@sportsdataverse/sdvplot/react\";\n * import type { ReactElement } from \"react\";\n *\n * const store = createSelection();\n * store.set({ selected: [\"KC\", \"BUF\"] });\n * function Picked(): ReactElement {\n *   const { selected } = useSelection(store); // re-renders on every change of the store\n *   return (\n *     <table>\n *       <tbody>\n *         {[...selected].map((id) => (\n *           <tr key={id}>\n *             <td>{id}</td>\n *           </tr>\n *         ))}\n *       </tbody>\n *     </table>\n *   );\n * }\n * <Picked />;\n * ```\n */\nexport function useSelection<Row>(store: SelectionStore<Row>): SelectionState<Row> {\n  // The store's methods are closures (no `this`), so they pass unbound; getState is referentially stable between\n  // changes, which is all useSyncExternalStore needs.\n  return useSyncExternalStore(store.subscribe, store.getState, store.getState);\n}\n"]}

package/dist/resolve-CQW-jzvr.d.ts

@@ -0,0 +1,28 @@
+import { S as SeasonInput, I as IdSystem, T as TeamId, L as League } from './types-C7n6gJF3.js';
+
+type Value = string | number | bigint | null | undefined;
+type Resolved<T> = T extends readonly Value[] ? (TeamId | undefined)[] : TeamId | undefined;
+interface ResolveOptions {
+    season?: SeasonInput | readonly SeasonInput[];
+    idSystem?: IdSystem;
+    strict?: boolean;
+}
+declare function resolveSync<T extends Value | readonly Value[]>(values: T, league: League, opts?: ResolveOptions): Resolved<T>;
+/**
+ * Resolve team values (abbreviations, ids, names) to ESPN team ids, loading the league first. Unknown values give
+ * `undefined` and one warning per call; `strict: true` throws `UnresolvedTeamError`.
+ *
+ * @example
+ * ```ts
+ * import { resolve } from "@sportsdataverse/sdvplot";
+ *
+ * await resolve(["KC", "Kansas City Chiefs", "OAK"], "nfl", { season: 2019 });
+ * ```
+ */
+declare function resolve<T extends Value | readonly Value[]>(values: T, league: League, opts?: ResolveOptions): Promise<Resolved<T>>;
+/** Port of `suggest`: difflib.get_close_matches(cutoff 0.6): SequenceMatcher(a=candidate, b=query).ratio() ≥ 0.6, best first, ties by candidate key descending; never picks one. */
+declare function suggest(value: Value, league: League, opts?: {
+    n?: number;
+}): Promise<Array<[TeamId, string]>>;
+
+export { type ResolveOptions as R, type Value as V, type Resolved as a, resolveSync as b, resolve as r, suggest as s };

package/dist/selection-D4T3PkRt.d.ts

@@ -0,0 +1,140 @@
+/**
+ * A row test, true to keep the row: the brush region (or any caller's) as a predicate. The one definition: sdvtables
+ * re-exports this type for `setExternalFilter`, so a linked table applies a store's predicate as is (not a
+ * `ValuePredicate`, which tests one column's cell). Both compare it by identity: the same function again is a no-op.
+ */
+type RowFilter<Row> = (row: Row) => boolean;
+/**
+ * A shared hover VALUE (J34): a number along one data field, such as the shot distance under the pointer, that every
+ * linked chart draws through its own scale (a rule, a band, a ring). Not an id: it never dims marks or filters a table.
+ * Unrelated to sdvtables' `TableCursor` (a grid's keyboard row).
+ */
+interface Cursor {
+    /** The data field the value is in, e.g. `"shot_distance"`. Never `""`. */
+    readonly field: string;
+    /** The value along that field. Always finite. */
+    readonly value: number;
+}
+/**
+ * What a {@link SelectionStore} holds. Immutable: every change replaces it, and a snapshot is read-only at runtime too
+ * (its sets' `add`, `delete` and `clear`, and a write to it or its cursor, throw a `TypeError`): pass changes to
+ * `store.set`, or copy a set with `new Set(ids)`.
+ */
+interface SelectionState<Row = unknown> {
+    /** Ids under the pointer right now (transient). */
+    readonly hover: ReadonlySet<string>;
+    /** Ids picked by a table-row click or a brush (sticky). */
+    readonly selected: ReadonlySet<string>;
+    /** The brush region as a row test; null when nothing is brushed. */
+    readonly predicate: RowFilter<Row> | null;
+    /** The shared hover value; null when the pointer is on no linked chart. */
+    readonly cursor: Cursor | null;
+}
+/**
+ * A partial update for {@link SelectionStore.set}: an absent field keeps its value. Each id goes through
+ * {@link toId}: a number is stringified (`12` and `"12"` are the same id) and null, undefined, NaN and `""` are
+ * dropped. A bare string throws `InputError` rather than being split into letters: pass `["KC"]`, not `"KC"`.
+ */
+interface SelectionPatch<Row = unknown> {
+    /** The new hover ids (replaces the set; `[]` clears it). */
+    readonly hover?: Iterable<string>;
+    /** The new selected ids (replaces the set; `[]` clears it). */
+    readonly selected?: Iterable<string>;
+    /** The new brush region; `null` clears it. */
+    readonly predicate?: RowFilter<Row> | null;
+    /** The new hover value; `null` clears it. An equal cursor (same field, same value) is a no-op. */
+    readonly cursor?: Cursor | null;
+}
+/** The linked-interactivity hub that {@link createSelection} returns. */
+interface SelectionStore<Row = unknown> {
+    /** Referentially stable until the next change: what `useSyncExternalStore` reads. */
+    getState(): SelectionState<Row>;
+    /** Apply a patch. ONE notification when anything changed, none when nothing did, so linked components cannot ping-pong. */
+    set(patch: SelectionPatch<Row>): void;
+    /** Clear hover, selected, predicate and cursor. */
+    clear(): void;
+    /**
+     * Call `fn` after every change; returns the unsubscribe function. A listener that throws stops neither the others
+     * nor `set`: its error is rethrown in a microtask, as an `EventTarget` listener's is, so it still reaches
+     * `window.onerror` (or Node's `uncaughtException`) but one broken view cannot freeze the rest. A listener removed
+     * during a notification is not called for it.
+     */
+    subscribe(fn: (state: SelectionState<Row>) => void): () => void;
+}
+/**
+ * The link id of a value: `String(v)`, or `""` (never matched) for null, undefined, NaN and `""`. A figure and a table
+ * link only when they hold the same ids, so an ESPN team id (`"12"`) never matches an abbreviation (`"KC"`).
+ *
+ * @example
+ * ```ts
+ * import { toId } from "@sportsdataverse/sdvplot";
+ *
+ * [toId(12), toId("KC"), toId(null), toId(Number.NaN)];
+ * ```
+ */
+declare function toId(v: unknown): string;
+/**
+ * Whether two id sets hold the same ids, in any order.
+ *
+ * @example
+ * ```ts
+ * import { sameIds } from "@sportsdataverse/sdvplot";
+ *
+ * sameIds(new Set(["KC", "BUF"]), new Set(["BUF", "KC"]));
+ * ```
+ */
+declare function sameIds(a: ReadonlySet<string>, b: ReadonlySet<string>): boolean;
+/**
+ * Whether two cursors are the same: the same field and an `===`-equal value, so `0` and `-0` are one hover value
+ * (NaN never gets into the store). `null` equals only `null`.
+ *
+ * @example
+ * ```ts
+ * import { sameCursor } from "@sportsdataverse/sdvplot";
+ *
+ * const rim = { field: "shot_distance", value: 0.5 }; // the centre of the 0-1 ft bin
+ * [
+ *   sameCursor(rim, { field: "shot_distance", value: 0.5 }), // a new object, the same value: true
+ *   sameCursor(rim, { field: "shot_distance", value: 1.5 }), // the next bin: false
+ *   sameCursor(rim, null), // the pointer left: false
+ *   sameCursor(null, null),
+ * ];
+ * ```
+ */
+declare function sameCursor(a: Cursor | null, b: Cursor | null): boolean;
+/**
+ * What a figure should emphasise. `null`: nothing is active, draw everything normally. A set, possibly EMPTY
+ * (a brush that encloses no point): emphasise those ids and dim the rest. Hover and selected are unioned. The
+ * cursor is ignored: a shared hover value never dims anything.
+ *
+ * @example
+ * ```ts
+ * import { createSelection, focusIds } from "@sportsdataverse/sdvplot";
+ *
+ * const store = createSelection();
+ * const idle = focusIds(store.getState()); // null: draw everything normally
+ * store.set({ selected: ["KC"], hover: ["BUF"] });
+ * ({ idle, focus: [...(focusIds(store.getState()) ?? [])] });
+ * ```
+ */
+declare function focusIds<Row>(s: SelectionState<Row>): ReadonlySet<string> | null;
+/**
+ * The linked-interactivity hub (J31): hover and selected id sets plus a row predicate. Pure data, zero deps, no DOM:
+ * creating or updating one in Node changes nothing a server renders. Ids are strings, normalised by {@link toId}
+ * (see {@link SelectionPatch}).
+ *
+ * @example
+ * ```ts
+ * import { createSelection } from "@sportsdataverse/sdvplot";
+ *
+ * const store = createSelection();
+ * let updates = 0;
+ * store.subscribe(() => updates++);
+ * store.set({ selected: ["KC", "BUF"] });
+ * store.set({ selected: ["BUF", "KC"] }); // the same ids: silent, so linked views cannot ping-pong
+ * ({ updates, selected: [...store.getState().selected] });
+ * ```
+ */
+declare function createSelection<Row = unknown>(): SelectionStore<Row>;
+
+export { type Cursor as C, type RowFilter as R, type SelectionStore as S, type SelectionState as a, type SelectionPatch as b, createSelection as c, sameIds as d, focusIds as f, sameCursor as s, toId as t };