@sportsdataverse/sdvplot 0.0.0-stage → 0.2.0

package/dist/plot.d.ts

@@ -0,0 +1,451 @@
+import * as Plot from '@observablehq/plot';
+import { E as EspnHeadshotLeague } from './headshots-B2J_LOO8.js';
+import { P as Placement, K as Kind } from './placement-UWkqUzpa.js';
+import { V as Value } from './resolve-CQW-jzvr.js';
+import { H as HeadshotIdSystem, L as League, S as SeasonInput, V as Variant, I as IdSystem, W as Which } from './types-C7n6gJF3.js';
+export { A as Axis, a as AxisLogosOptions, b as AxisPassThrough, c as axisLogos } from './axis-CraWQRUJ.js';
+import { T as TiersOptions, a as TierRow } from './tiers-BN4md-GB.js';
+import { Scene, FrameName, Frame, BasketballZone, BasketballZoneArea } from '@sportsdataverse/sporty';
+import { surfaceScales } from '@sportsdataverse/sporty/plot';
+import { S as SurfaceSceneOptions } from './surfaces-W-odWLpT.js';
+export { a as SURFACES, b as SURFACE_BASE, c as colorUpdates } from './surfaces-W-odWLpT.js';
+import { BinShape } from './bins.js';
+import { DiffScale, SignaturePoint, Split, CellVsLeague } from './shots.js';
+
+/** A column name, an accessor, or an array of values (one per row). */
+type Channel<R> = keyof R | ((d: R, i: number) => Value) | readonly Value[];
+/** Rows to draw: any iterable, or an Arrow-like table `Plot.valueof` accepts. */
+type Data<R> = Iterable<R> | {
+    numRows: number;
+};
+/**
+ * Every `Plot.image` option sdvplot does not compute passes through untouched: `x`, `y`, `fx`, `fy`, `tip`, `href`,
+ * `target`, `title`, `ariaLabel`, `ariaDescription`, `sort`, `filter`, `reverse`, `dx`, `dy`, `clip`, `className`,
+ * `opacity`, `rotate`, `frameAnchor`, `channels`, and `transform` / `initializer` / `render` (so Plot's transforms and
+ * `Plot.pointer` wrap the mark). sdvplot owns `src`, `width` and `height` (the image and its size).
+ */
+type ImagePassThrough = Omit<Plot.ImageOptions, "src" | "width" | "height" | "r" | "preserveAspectRatio">;
+/** sdvplot's own image-mark options (shared by `logos`, `wordmarks` and `headshots`); the rest are Plot's. */
+interface ImageMarkOptions extends ImagePassThrough {
+    /** Fraction of the (facet) frame height in (0, 1]; default 0.1. */
+    height?: number;
+    /**
+     * Opacity in [0, 1]; default 1. `alpha` is the Python sdvplot name for a constant `opacity`, kept for parity; Plot's
+     * `opacity` also takes a per-row channel. Passing both throws `InputError`.
+     */
+    alpha?: number;
+    /**
+     * Read by `Plot.dodgeX` / `Plot.dodgeY` as the collision radius in pixels (dodge's own option); the image is never
+     * clipped or sized by it. Half the drawn height (`height` × frame height / 2) makes neighbours just touch; a smaller
+     * `r` lets them overlap (by design: the images keep their size). Plot's own image mark uses `r` to clip the image to
+     * a circle, while sdvplot uses `r` only for dodge spacing and never clips.
+     */
+    r?: Plot.ChannelValue;
+}
+interface MarkOptions<R> extends ImageMarkOptions {
+    league: League;
+    team: Channel<R>;
+    /** A literal season (number, null, or a 4-digit string like "2023"), or a channel: any other string is a column name; functions and arrays are per-row channels. */
+    season?: SeasonInput | Channel<R>;
+    variant?: Variant;
+    idSystem?: IdSystem;
+    /**
+     * The link id stamped as each image's `data-sdv-id`, which `sdvplot/interact` matches against a store or a linked
+     * table's `rowKey` (`id: "team"` for a table keyed by abbreviation). One value per row, like every channel: ids
+     * index the data row, never the draw position, so each follows its row through `sort`, `filter`, facets
+     * (`fx`/`fy`) and `Plot.dodgeY`. It changes only the stamp: each image keeps its team's accessible name and tip.
+     * Default: the resolved ESPN team id ("12" for KC), which never matches "KC".
+     */
+    id?: Channel<R>;
+}
+interface HeadshotOptions<R> extends ImageMarkOptions {
+    league: EspnHeadshotLeague;
+    player: Channel<R>;
+    /** "espn" (default) or "gsis". "gsis" is sync and needs `loadGsis()` to have run first, else this throws InputError. */
+    idSystem?: HeadshotIdSystem;
+    /** The link id stamped as each image's `data-sdv-id`, as `logos`' `id`. Default: the player id. */
+    id?: Channel<R>;
+}
+/**
+ * Plot `render` transform: size each `<image>` to `height` x the (facet) frame height, keep the mark's
+ * aspect, re-centre on the point and stamp the `data-sdv-*` attributes `drawnMarks` reads.
+ * `placed` is looked up by original row index (`Placement.index`), which is what Plot hands `render`; so are `ids`,
+ * the link ids by row (the `id` option), stamped in place of each placement's resolved id.
+ */
+declare function sizeRender(height: number, placed: readonly Placement[], kind: Kind, ids?: readonly string[]): Plot.RenderFunction;
+/**
+ * Team logos as an Observable Plot mark at (x, y), `height` a fraction of the (facet) frame height. Needs
+ * `loadLeague(league)` first; a team that does not resolve is left out, with one warning. Every other `Plot.image`
+ * option passes through (`tip`, `href`, `fx`/`fy`, `sort`, `filter`, `dx`/`dy`, `className`, `clip`, …), and Plot's
+ * row-preserving transforms wrap it (`Plot.dodgeY`, `Plot.stackY`, `Plot.windowY`, `Plot.selectLast`, `Plot.pointer`);
+ * an aggregating transform (`bin`, `group`, `hexbin`) throws `InputError`. Each image is named for its team ("KC logo").
+ * `ariaLabel` is Plot's per-image channel, so a string is a COLUMN name (`ariaLabel: "qb"` names each image by its
+ * row's `qb`); pass an accessor or an array for any other text.
+ *
+ * @example
+ * ```ts
+ * import * as Plot from "@observablehq/plot";
+ * import { loadLeague } from "@sportsdataverse/sdvplot";
+ * import { logos } from "@sportsdataverse/sdvplot/plot";
+ *
+ * await loadLeague("nfl");
+ * const afc = [
+ *   { team: "KC", pf: 385, pa: 326 },
+ *   { team: "BUF", pf: 525, pa: 368 },
+ *   { team: "DEN", pf: 425, pa: 311 },
+ * ];
+ * Plot.plot({ marks: [logos(afc, { league: "nfl", x: "pf", y: "pa", team: "team", tip: true })] });
+ * ```
+ *
+ * @example A beeswarm: Plot.dodgeY reads r as the collision radius in pixels, about half the drawn height.
+ * ```ts
+ * import * as Plot from "@observablehq/plot";
+ * import { loadLeague } from "@sportsdataverse/sdvplot";
+ * import { logos } from "@sportsdataverse/sdvplot/plot";
+ *
+ * await loadLeague("nfl");
+ * const afc = [
+ *   { team: "KC", net_epa: 0.063 },
+ *   { team: "LAC", net_epa: 0.101 },
+ *   { team: "DEN", net_epa: 0.108 },
+ *   { team: "BUF", net_epa: 0.19 },
+ * ];
+ * Plot.plot({ height: 160, marks: [logos(afc, Plot.dodgeY({ league: "nfl", team: "team", x: "net_epa", r: 12, height: 0.18 }))] });
+ * ```
+ */
+declare function logos<R>(data: Data<R>, o: MarkOptions<R>): Plot.Markish;
+/** Team wordmarks, as `logos` (same options and pass-through); each image is named for its team ("KC wordmark"). */
+declare function wordmarks<R>(data: Data<R>, o: MarkOptions<R>): Plot.Markish;
+/** ESPN player headshots, as `logos` with a `player` channel; each image is named for its player id ("3139477 headshot"; pass `ariaLabel` for names). */
+declare function headshots<R>(data: Data<R>, o: HeadshotOptions<R>): Plot.Markish;
+
+/**
+ * Plot `render` transform that stamps `data-sdv-id` on every element a one-element-per-row mark draws (dot, cell,
+ * rect / bar, text, tick, image), so `sdvplot/interact` can highlight it by class toggle, never a redraw. `id`
+ * defaults to the row index, which is also a linked table's id when its spec has no `rowKey`. Plot hands `render`
+ * the source row indexes, so a row Plot drops (a null coordinate) leaves the others aligned. A mark that draws one
+ * element per series (line, area) is left unstamped, with one warning.
+ *
+ * @example
+ * ```ts
+ * import * as Plot from "@observablehq/plot";
+ * import { linkIds } from "@sportsdataverse/sdvplot/plot";
+ *
+ * const rows = [
+ *   { team: "KC", wins: 15, net_epa: 0.063 },
+ *   { team: "BUF", wins: 13, net_epa: 0.19 },
+ * ];
+ * const svg = Plot.plot({ marks: [Plot.dot(rows, { x: "wins", y: "net_epa", render: linkIds(rows, "team") })] });
+ * Array.from(svg.querySelectorAll("circle")).map((c) => c.getAttribute("data-sdv-id"));
+ * ```
+ */
+declare function linkIds<R>(data: Data<R>, id?: Channel<R>): Plot.RenderFunction;
+
+interface TeamColorOptions {
+    /** "primary" (default) or "secondary". */
+    which?: Which;
+    /** Season for era-aware resolution; passing it avoids the ambiguity warning for reused abbreviations. */
+    season?: SeasonInput;
+    idSystem?: IdSystem;
+    strict?: boolean;
+    /** Colour for values that resolve to no team; default "grey". Never gets `alpha`. */
+    naValue?: string;
+    /** Opacity in [0, 1], appended as an 8-bit hex alpha to team colours only. */
+    alpha?: number;
+    /** Domain = these distinct values; default every team_id and abbr of the league. */
+    values?: readonly Value[];
+    legend?: boolean;
+}
+/**
+ * Plot colour-scale options that colour a team column by team colour. The same scale serves `fill` and
+ * `stroke` (Plot has one colour scale), so `teamFill` is this function. Without `values` the domain is every
+ * `team_id` and `abbr`; some abbreviations are reused across eras, so pass `season` to avoid the
+ * ambiguity warning. Needs `loadLeague(league)` first.
+ *
+ * @example
+ * ```ts
+ * import * as Plot from "@observablehq/plot";
+ * import { loadLeague } from "@sportsdataverse/sdvplot";
+ * import { teamColor } from "@sportsdataverse/sdvplot/plot";
+ *
+ * await loadLeague("nfl");
+ * const wins = [
+ *   { team: "KC", wins: 15 },
+ *   { team: "BUF", wins: 13 },
+ *   { team: "LAC", wins: 11 },
+ * ];
+ * Plot.plot({
+ *   color: teamColor("nfl", { values: wins.map((w) => w.team) }),
+ *   marks: [Plot.barY(wins, { x: "team", y: "wins", fill: "team" })],
+ * });
+ * ```
+ */
+declare function teamColor(league: League, o?: TeamColorOptions): Plot.ScaleOptions;
+declare const teamFill: typeof teamColor;
+
+/**
+ * Plot's rule options sdvplot does not own pass through to both rules: `fx`, `fy`, `tip`, `title`, `className`,
+ * `ariaLabel`, `ariaDescription`, `dx`, `dy`, `clip`, and the rest. sdvplot owns the rule positions (`x`, `y`, `x1`,
+ * `x2`, `y1`, `y2`): the reducer computes them per facet, top-level or mark-level.
+ */
+type RuleLinePassThrough = Omit<Plot.RuleXOptions, "x" | "y" | "x1" | "x2" | "y1" | "y2">;
+interface RefLineOptions<R> extends RuleLinePassThrough {
+    x?: Channel<R>;
+    y?: Channel<R>;
+    /** Default "red". */
+    stroke?: string;
+    /** Default "4 4". */
+    strokeDasharray?: string;
+    /** Default 1. */
+    strokeWidth?: number;
+    strokeOpacity?: number;
+}
+/** A vertical rule at mean(x) and/or a horizontal rule at mean(y), per facet. Throws InputError if neither is given. */
+declare function meanLines<R>(data: Data<R>, o: RefLineOptions<R>): Plot.Markish[];
+/** Like `meanLines`, at the median. */
+declare function medianLines<R>(data: Data<R>, o: RefLineOptions<R>): Plot.Markish[];
+
+interface TitleImageOptions {
+    /** A team (resolved in `league`), or an https image URL when `league` is not given. */
+    image: Value;
+    league?: League;
+    season?: SeasonInput;
+    /** Required when `figure` is a bare `<svg>`: it becomes the new `<h2>`. */
+    title?: string;
+    side?: "left" | "right";
+    /** Pixels (unlike the marks' fraction of the plot height); at least 1, default 24. */
+    height?: number;
+}
+/** Puts a team logo (or an https image) in the `<h2>` of a Plot figure and returns the `<figure>` (a bare `<svg>` is wrapped in a new one). An unknown team draws the title alone (the resolver warned once). */
+declare function titleImage(figure: HTMLElement | SVGSVGElement, o: TitleImageOptions): HTMLElement;
+
+/** Options for a tier plot (see `prepareTiers`), plus `devel` (draw team abbreviations as text, not logos) and `width` (px, default 640). */
+type TeamTiersOptions = TiersOptions & {
+    league: League;
+    devel?: boolean;
+    width?: number;
+    /** Plot's tip on the logos, naming the team on hover (opt-in; default false). Ignored with `devel`. */
+    tip?: boolean;
+};
+/**
+ * A tier plot as `Plot.plot` options (SSR-composable; the caller runs `Plot.plot`): tier 1 on top, logos ranked
+ * within each tier, separator rules, wrapped tier labels on the y axis.
+ *
+ * @example
+ * ```ts
+ * import * as Plot from "@observablehq/plot";
+ * import { loadLeague } from "@sportsdataverse/sdvplot";
+ * import { teamTiers } from "@sportsdataverse/sdvplot/plot";
+ *
+ * await loadLeague("nfl");
+ * const rows = [
+ *   { team: "BUF", tier_no: 1 },
+ *   { team: "KC", tier_no: 1 },
+ *   { team: "MIA", tier_no: 2 },
+ *   { team: "NE", tier_no: 3 },
+ * ];
+ * Plot.plot(teamTiers(rows, { league: "nfl" }));
+ * ```
+ */
+declare function teamTiers(rows: readonly TierRow[], o: TeamTiersOptions): Plot.PlotOptions;
+
+/** Sporty's surface options plus `team` painting; `colorUpdates` overrides are keyed by sporty colour keys. */
+interface SurfaceOpts extends SurfaceSceneOptions {
+    /**
+     * A team logo at the surface centre (0, 0): `true` is 0.25 of the frame height, a number is that fraction in (0, 1] (0 or
+     * out of range throws InputError). Ignored without a `team`. xTrans/yTrans or a half-court displayRange can move (0, 0) off-frame.
+     */
+    centerLogo?: boolean | number;
+}
+/**
+ * Plot marks + scales for a team-painted sporty surface, for any key of `SURFACES`. An unsupported key, or a `team` on a key
+ * without team identities, throws `InputError`; sporty's own
+ * errors (`SportyError` subclasses: unknown displayRange/unit, bad arcResolution) propagate unwrapped.
+ *
+ * @example
+ * ```ts
+ * import * as Plot from "@observablehq/plot";
+ * import { loadLeague } from "@sportsdataverse/sdvplot";
+ * import { surface } from "@sportsdataverse/sdvplot/plot";
+ *
+ * await loadLeague("nhl");
+ * // arcResolution: points per arc (default 200); 24 is plenty at 480 px and keeps the SVG small
+ * const rink = surface("nhl", { team: "BOS", displayRange: "offense", arcResolution: 24 });
+ * Plot.plot({ ...rink.scales, width: 480, marks: rink.marks });
+ * ```
+ */
+declare function surface(league: League | (string & {}), o?: SurfaceOpts): {
+    marks: Plot.Markish[];
+    scales: ReturnType<typeof surfaceScales>;
+    scene: Scene;
+};
+
+/**
+ * Plot's geo options sdvplot does not own pass through (tip, title, href, fx, fy, filter, className, clip, …). `x` and
+ * `y` are sdvplot's: a cell's tip anchors on the cell's centre and a zone's on samples inside the zone, so neither
+ * needs a mark-level anchor.
+ */
+type GeoPassThrough = Omit<Plot.GeoOptions, "geometry" | "fill" | "r" | "x" | "y">;
+/** Options for `shotCells`. */
+interface ShotCellsOptions extends GeoPassThrough {
+    /**
+     * Size per cell in legacy tenths (`sizeCells(cells, …).r`) or one size for all: a hexagon's circumradius, or a
+     * square's side. 0 hides a cell.
+     */
+    r: readonly number[] | number;
+    /** The cells' shape, as binned (`binShots`, `leagueIndex`); default `"hex"`. */
+    shape?: BinShape;
+    /** Colour of each cell's shrunk FG% vs league; default `diffScale()`. */
+    scale?: DiffScale;
+    /** `shrunkDiff` prior in attempts; default 25 (`main`), 0 = the raw difference (`master`). */
+    prior?: number;
+    /** Legacy tenths to plot coordinates: a sporty frame name or `Frame`; default `"nba-legacy"`. */
+    frame?: FrameName | Frame;
+    /** Default `var(--sdv-muted, #525252)`, so near-average cells stay visible (`hexShotChart.ts:159-161`). */
+    stroke?: Plot.ChannelValueSpec;
+    /** Default 0.85 px. */
+    strokeWidth?: Plot.ChannelValueSpec;
+    /**
+     * Drop the cells centred outside the plot's frame, as blazing-the-nets `main` drops those past its viewport
+     * (`hexShotChart.ts:74`); a cell centred inside is drawn whole. Not Plot's `clip` (which cuts paths, and passes
+     * through). Default true. Was `clip` before Phase 11.
+     */
+    dropOutside?: boolean;
+}
+/**
+ * Data-space hexagons or squares (the dual encoding: `r` from `sizeCells`, `fill` from `diffScale`) drawn as
+ * `Plot.geo` through the plot's x/y scales, so they sit on a sporty court at any orientation. Fewest attempts first,
+ * so busy cells stay on top (blazing-the-nets `main` `lib/charts/hexShotChart.ts:79`); `r = 0` is not drawn, nor
+ * (by default, `dropOutside`) a cell centred outside the plot's frame. Each path carries `data-sdv-id="x,y"`, the cell's
+ * legacy centre. Marks paint in array order: after `...court.marks` the cells cover the court lines under them, as
+ * in `main`.
+ * `tip: true` shows attempts, FG%, league FG% and the shrunk difference (formats `.1%`, `+.1%`; a `tip` object's
+ * `format` overrides them key by key); every other
+ * `Plot.geo` option passes through, and the cells are the mark's data, so `fx`/`fy`, `filter`, `sort` (replacing the
+ * default order) and `title` read the caller's fields. A `transform` or `initializer` that makes new rows
+ * (`Plot.group`, `Plot.hexbin`) throws `InputError`.
+ *
+ * @example
+ * ```ts
+ * import * as Plot from "@observablehq/plot";
+ * import { shotCells, surface } from "@sportsdataverse/sdvplot/plot";
+ * import { cellsVsLeague, leagueIndex } 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" },
+ * ];
+ * // the three shots stand in for the league; the gallery's hex chart uses the 2025-26 league's index
+ * const cells = cellsVsLeague(shots, leagueIndex(shots, 15));
+ * const court = surface("nba", { displayRange: "defense" });
+ * Plot.plot({ ...court.scales, marks: [...court.marks, shotCells(cells, { r: 15 })] });
+ * ```
+ */
+declare function shotCells(cells: readonly CellVsLeague[], o: ShotCellsOptions): Plot.Markish;
+/** Options for `shotZones`. */
+interface ShotZonesOptions extends GeoPassThrough {
+    /** Fill per zone (e.g. `diffScale()` of the zone's shrunk diff). */
+    fill: (zone: BasketballZone) => string;
+    /**
+     * A label per zone at its anchor, haloed so it reads over any fill (`hexShotChart.ts:83-95`); omit for none. Labels
+     * take no pointer events, so a click or hover on one reaches the zone under it. They are hidden from assistive
+     * technology, so each zone's accessible name carries its label's text after the zone's name ("Paint (non-RA),
+     * 136/326").
+     */
+    text?: (zone: BasketballZone) => string;
+    /** The SAME frame as the shots (zones built with `scale: 10` are in legacy tenths); default `"nba-legacy"`. */
+    frame?: FrameName | Frame;
+    /** Default 0.85 (`hexShotChart.ts:110`). */
+    fillOpacity?: Plot.ChannelValueSpec;
+    /** Per-zone makes and attempts (`statsByZone(shots)`): with `tip`, each zone shows them. */
+    stats?: Readonly<Record<BasketballZone, Split>>;
+}
+/**
+ * sporty's zone areas (built with `scale: 10`, legacy tenths) filled per zone, plus optional haloed labels, the
+ * corner strips' set vertically (blazing-the-nets `main` zones mode, `lib/charts/hexShotChart.ts:97-136`). Each
+ * area's path carries `data-sdv-id` = its zone.
+ *
+ * Returns the zone paths, then the labels (with `text`), then the tip (with `tip`). Marks paint in array order and
+ * the tip is last, so spread these marks LAST, or add other marks before them: a mark added after them paints over
+ * the tip. After `...court.marks` the zone fills dim the court lines under them; `main` draws its lines after the
+ * zones, but moving the court mark last would hide the zones under its floor (sporty draws lines as filled polygons).
+ * For lines on top, put a second `surface` right after the paths, its `colorUpdates` setting `plot_background`,
+ * `defensive_half_court`, `offensive_half_court`, `court_apron`, `two_point_range`, `painted_area`,
+ * `center_circle_fill` and `free_throw_circle_fill` to `"#00000000"` so only the lines remain:
+ * `const [paths, ...rest] = shotZones(areas, o)`, then `marks: [...court.marks, paths, ...lines.marks, ...rest]`.
+ * The areas are the mark's data and each path is named by its zone (with `text`, then its label's text). `tip: true`
+ * adds a `Plot.tip` mark that names the zone under the pointer and, with `stats` (`statsByZone(shots)`), its
+ * makes/attempts and FG%. It follows the nearest of a grid of anchors inside the zones (a fortieth of their extent
+ * apart, 1.25 ft on an NBA half court), so within about that of a zone edge it may name the neighbour. The tip's data
+ * is the areas, so `channels` (shown in the tip) read the caller's fields; a `tip` object's `format` overrides
+ * sdvplot's key by key. Every other `Plot.geo` option passes through to the zone paths.
+ *
+ * @example
+ * ```ts
+ * import * as Plot from "@observablehq/plot";
+ * import { basketballZones } from "@sportsdataverse/sporty";
+ * import { shotZones, surface } from "@sportsdataverse/sdvplot/plot";
+ *
+ * const court = surface("nba", { displayRange: "defense" });
+ * const zones = shotZones(basketballZones("nba", { scale: 10 }), { fill: () => "#f7f7f7", text: (z) => z });
+ * Plot.plot({ ...court.scales, marks: [...court.marks, ...zones] });
+ * ```
+ */
+declare function shotZones(areas: readonly BasketballZoneArea[], o: ShotZonesOptions): Plot.Markish[];
+/** Options for `shootingSignature`. */
+interface ShootingSignatureOptions {
+    /** Colour of `colourDiff`; default `diffScale()`. */
+    fill?: DiffScale;
+    /** `"monotone-x"` (default, `main`) or `"basis"` (`master` `ShootingSignature/index.js:96`). */
+    curve?: "monotone-x" | "basis";
+    /**
+     * Ribbon half-width in y units. Default `main`'s 20 px at the busiest distance on its 190 px [0, 1] axis, never
+     * under 0.75 px (`shootingSignature.ts:13-15`, `:131-132`): `max(share / maxShare * 20, 0.75) / 190`. `master`:
+     * `(p) => (1 + p.share * 199) / 200` (`ShootingSignature/index.js:73-75`, `:88-90`).
+     */
+    halfWidth?: (p: SignaturePoint, maxShare: number) => number;
+    /** The dashed league line, faint everywhere and full strength under the ribbon (`:165-181`); default true. */
+    league?: boolean;
+    /**
+     * A tip that follows the pointer along x: distance, FG%, league FG% and shot share (`Plot.tip` + `Plot.pointerX`).
+     * An options object's `format` overrides sdvplot's key by key.
+     */
+    tip?: boolean | Plot.TipOptions;
+}
+/**
+ * The shooting signature: a ribbon along FG% by distance, as wide as the shot share and coloured along x by the
+ * shrunk FG% vs league (blazing-the-nets `main` `lib/charts/shootingSignature.ts:117-213`; `master`
+ * `src/components/ShootingSignature/index.js`). Input: `signaturePoints(...)`; a null `fgPct` is a gap. The gradient
+ * id is a hash of its stops and its pixel x range, so two signatures on a page, or one drawn at two widths, never
+ * share one (`master`'s fixed id did, `Gradient.js:10`).
+ *
+ * y is not clamped: the ribbon's edges are `fgPct ± halfWidth` in y units, so near 0% or 100% they pass a [0, 1]
+ * domain (`main` clamps the ribbon's centre instead, which misstates FG%). To clamp them, pass
+ * `y: { domain: [0, 1], clamp: true }`.
+ * `tip` adds a `Plot.tip` that follows the pointer along x (`Plot.pointerX`): distance, FG%, league FG% and share.
+ * It is the last mark returned, and a mark added after it paints over it, so spread these marks LAST, or add other
+ * marks (a `Plot.ruleY`, say) before them.
+ *
+ * @example
+ * ```ts
+ * import * as Plot from "@observablehq/plot";
+ * import { shootingSignature } from "@sportsdataverse/sdvplot/plot";
+ * import { fgPctByDistance, signaturePoints, vsLeague } 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" },
+ * ];
+ * // the makes against all three attempts, which stand in for the league (the gallery's uses the 2025-26 league)
+ * const made = fgPctByDistance(shots.filter((s) => s.shot_result === "Made"));
+ * const points = signaturePoints(vsLeague(made, fgPctByDistance(shots)), { minAttempts: 1 });
+ * Plot.plot({ y: { domain: [0, 1] }, marks: shootingSignature(points) });
+ * ```
+ */
+declare function shootingSignature(points: readonly SignaturePoint[], o?: ShootingSignatureOptions): Plot.Markish[];
+
+export { type Channel, type Data, type GeoPassThrough, type HeadshotOptions, type ImageMarkOptions, type ImagePassThrough, type MarkOptions, type RefLineOptions, type RuleLinePassThrough, type ShootingSignatureOptions, type ShotCellsOptions, type ShotZonesOptions, type SurfaceOpts, type TeamColorOptions, type TeamTiersOptions, type TitleImageOptions, headshots, linkIds, logos, meanLines, medianLines, shootingSignature, shotCells, shotZones, sizeRender, surface, teamColor, teamFill, teamTiers, titleImage, wordmarks };