@sportsdataverse/sdvplot 0.0.0-stage → 0.2.0

package/dist/react.d.ts

@@ -0,0 +1,377 @@
+import { ReactElement, ImgHTMLAttributes } 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 { L as League, S as SeasonInput, I as IdSystem, V as Variant, M as MarkType, W as Which, H as HeadshotIdSystem, T as TeamId } from './types-C7n6gJF3.js';
+import { NivoLayerOptions } from './nivo.js';
+import './_web-D7Aa5Rd8.js';
+
+/**
+ * `<SurfaceBackdrop>` props: the league whose surface to draw, how to paint it (the options of sdvplot's other
+ * `surface` functions), and which axes place it. The sporty-specific options are typed loosely, so `sdvplot/react`'s
+ * types never name `@sportsdataverse/sporty` (an optional peer); sporty checks them when the surface is built.
+ */
+interface SurfaceBackdropProps {
+    /** The league whose court, field or rink to draw, e.g. "nba". */
+    league: League;
+    /** The team whose colours paint the surface. */
+    team?: Value;
+    /** The season the team's colours are taken from. */
+    season?: SeasonInput;
+    /** Overrides on top of the team painting, keyed by sporty colour key (e.g. `{ painted_area: "#0e2240" }`). */
+    colorUpdates?: Readonly<Record<string, string>>;
+    /** Degrees to rotate the surface by. */
+    rotation?: number;
+    /** A sporty display range for the league's sport, e.g. "defense"; one the sport does not know throws. */
+    displayRange?: string;
+    xlim?: readonly [number, number];
+    ylim?: readonly [number, number];
+    units?: "ft" | "m" | "yd" | "in" | "cm" | "mm";
+    /** Sporty parameter overrides for the league's surface. */
+    updates?: Readonly<Record<string, unknown>>;
+    arcResolution?: number;
+    xTrans?: number;
+    yTrans?: number;
+    /** The `xAxisId` of the numeric x axis the surface's units are on. Default 0. */
+    xAxisId?: string | number;
+    /** The `yAxisId` of the numeric y axis the surface's units are on. Default 0. */
+    yAxisId?: string | number;
+}
+/**
+ * A team-painted court, field or rink under a Recharts chart's series: place it as a child of the chart (before the
+ * series), as Recharts 3 renders any element there (`<Customized>` is deprecated). The surface is drawn in the
+ * numeric axes' units: set both axes' `domain` to the surface's bbox (sporty's `surface(...).bbox`) to fill the plot
+ * area, or to any range in those units to show part of it. recharts (3.8 or later) and `@sportsdataverse/sporty`
+ * load when it first renders, never with `sdvplot/react`; either missing throws `OptionalDependencyError` then. A
+ * server render draws nothing (it loads on the client).
+ *
+ * @example
+ * ```tsx
+ * import { SurfaceBackdrop } from "@sportsdataverse/sdvplot/react";
+ * import { surface } from "@sportsdataverse/sporty";
+ * import { Scatter, ScatterChart, XAxis, YAxis } from "recharts";
+ *
+ * const [x0, y0, x1, y1] = surface("basketball", "nba", { displayRange: "defense" }).bbox;
+ * <ScatterChart width={500} height={470}>
+ *   <XAxis type="number" dataKey="x" domain={[x0, x1]} hide />
+ *   <YAxis type="number" dataKey="y" domain={[y0, y1]} hide />
+ *   <SurfaceBackdrop league="nba" team="DEN" displayRange="defense" />
+ *   <Scatter data={[{ x: 0, y: 5.25 }]} />
+ * </ScatterChart>;
+ * ```
+ */
+declare function SurfaceBackdrop(props: SurfaceBackdropProps): ReactElement;
+
+/**
+ * `<LogoBump>` props: the series, the league their ids belong to, and how to draw the logos; every other prop goes to
+ * nivo's `Bump` as is (typed loosely, so `sdvplot/react`'s types never name `@nivo/bump`, an optional peer).
+ */
+interface LogoBumpProps {
+    /** nivo Bump series, `{ id, data: [{ x, y }] }`: each `id` is a team (abbreviation, name or id). */
+    data: readonly {
+        readonly id: string;
+        readonly data: readonly {
+            x: number | string;
+            y: number | null;
+        }[];
+    }[];
+    /** The league the series' teams belong to, e.g. "nfl". */
+    league: League;
+    /** The season the teams are resolved for. */
+    season?: SeasonInput;
+    /** How the series' ids are read. Default "auto". */
+    idSystem?: IdSystem;
+    /** The chart's background: the line colours keep 3:1 contrast against it and aim to stay distinct (`teamColors`). */
+    background?: string;
+    /** Logo height as a fraction of the plot height, in (0, 1]. Default 0.08. */
+    logoHeight?: number;
+    /** Which points get a logo: "last" (default), "first" or "all". */
+    at?: NivoLayerOptions["at"];
+    /** Logo variant, e.g. "dark". Default "default". */
+    variant?: Variant;
+    /** "logo" (default) or "wordmark". */
+    markType?: MarkType;
+    /** Width and height in px. Both given: a fixed-size `Bump`; otherwise a `ResponsiveBump` that fills its parent. */
+    width?: number;
+    /** Chart height in px (see `width`). */
+    height?: number;
+    /**
+     * nivo's layers. Default nivo's own: grid, axes, labels, lines, points, then the logos, then mesh. Given, the logos
+     * are appended after them all, after any "mesh" too, which is harmless: the logo layer has `pointer-events: none`.
+     */
+    layers?: readonly unknown[];
+    /** Any other nivo `Bump` prop (margin, axes, pointSize, animate, theme, ...). */
+    [prop: string]: unknown;
+}
+/**
+ * A nivo bump chart of teams: each line in its team's colour (`teamColors`), a logo at the end of each line
+ * (`logoLayer`). `@nivo/bump` (0.99 or later) loads when it first renders, never with `sdvplot/react`; missing, it
+ * throws `OptionalDependencyError` then. A server render draws nothing (it loads on the client). For anything this
+ * does not cover, use `teamColors` and `logoLayer` from `sdvplot/nivo` on nivo's own `Bump`. A `colors` prop replaces
+ * the team colours (it is passed to nivo after them).
+ */
+declare function LogoBump({ league, season, idSystem, background, logoHeight, at, variant, markType, layers, ...rest }: LogoBumpProps): ReactElement;
+
+interface Shared {
+    /** The league the teams belong to, e.g. "nfl". */
+    league: League;
+    /** Logo variant, e.g. "dark". Default "default". */
+    variant?: Variant;
+    /** How the team values are read. Default "auto". */
+    idSystem?: IdSystem;
+    /** "logo" (default) or "wordmark". */
+    markType?: MarkType;
+    /** url → data URI map from `embedSources`, to inline the images. */
+    embed?: ReadonlyMap<string, string>;
+}
+/**
+ * `<LogoPoint>` props: yours (the league, the datum field holding the team, ...), plus the point Victory hands its
+ * `dataComponent` (`x`, `y`, `size`, `datum`, `events`), which you leave out.
+ */
+interface LogoPointProps extends Shared {
+    /** The field of each datum (each data row) holding the team: abbreviation, name or id (see `idSystem`). */
+    team: string;
+    /** A season (number or string) for every point, or the name of the datum field holding each one's season. */
+    season?: SeasonInput;
+    /** Opacity in [0, 1]. Default 1. */
+    alpha?: number;
+    /** Set by Victory: the point's centre in px. */
+    x?: number;
+    /** Set by Victory: the point's centre in px. */
+    y?: number;
+    /** Set by Victory: the point's radius in px (the scatter's `size`). The logo is twice it tall. */
+    size?: number;
+    /** Set by Victory: the data row the point was drawn from. */
+    datum?: object;
+    /** Set by Victory: the point's event handlers (tooltips, voronoi, your `events`). */
+    events?: object;
+}
+/**
+ * `<LogoTick>` props: yours (the league, the logo size, ...), plus the tick label Victory hands its
+ * `tickLabelComponent` (`x`, `y`, `text`, the anchors, and VictoryLabel's other props), which you leave out.
+ */
+interface LogoTickProps extends Shared {
+    /** The season the axis' teams are resolved for. */
+    season?: SeasonInput;
+    /** The logo's height in px, 1 or more (Victory hands a tick label no plot height). Default 24. */
+    size?: number;
+    /** Set by Victory: the label's anchor in px. */
+    x?: number;
+    /** Set by Victory: the label's anchor in px. */
+    y?: number;
+    /** Set by Victory: the tick's label, the team (abbreviation, name or id; see `idSystem`). */
+    text?: unknown;
+    /** Set by Victory: which side of the anchor the label would run. VictoryLabel's default "start". */
+    textAnchor?: string;
+    /** Set by Victory: which side of the anchor the label would hang. VictoryLabel's default "middle". */
+    verticalAnchor?: string;
+}
+/**
+ * Team logos as a Victory scatter's points: `<VictoryScatter dataComponent={<LogoPoint league team />}>`. Each point
+ * draws the logo of its datum's `team` field, centred on the point and as tall as the point it replaces (twice the
+ * scatter's `size`, in px: set `size` on the `VictoryScatter`). A team with no logo draws nothing and warns once, as
+ * `sdvplot/echarts` does. Victory's event handlers (tooltips, voronoi) stay on the image. Synchronous: call it after
+ * `loadLeague(league)`. Needs nothing from victory itself, so it also renders on the server.
+ *
+ * @example
+ * ```tsx
+ * import { loadLeague } from "@sportsdataverse/sdvplot";
+ * import { LogoPoint } from "@sportsdataverse/sdvplot/react";
+ * import { VictoryChart, VictoryScatter } from "victory";
+ *
+ * await loadLeague("nfl");
+ * const rows = [
+ *   { team: "KC", pf: 385, pa: 326 },
+ *   { team: "LAC", pf: 402, pa: 301 },
+ *   { team: "DEN", pf: 425, pa: 311 },
+ * ];
+ * <VictoryChart domainPadding={30}>
+ *   <VictoryScatter data={rows} x="pf" y="pa" size={14} dataComponent={<LogoPoint league="nfl" team="team" />} />
+ * </VictoryChart>;
+ * ```
+ */
+declare function LogoPoint(props: LogoPointProps): ReactElement | null;
+/**
+ * Team logos as an axis' tick labels: `<VictoryAxis tickLabelComponent={<LogoTick league />} />` on an axis whose
+ * labels are teams. The logo sits where the label would, on the side of Victory's anchor the label would run (under
+ * a bottom axis, left of a left one), `size` px tall. A label that resolves to no logo keeps its text, drawn by
+ * Victory's own `VictoryLabel` (loaded from victory when it first draws one; it then also warns once), as
+ * `sdvplot/echarts`' `withAxisLogos` does. Logos do not
+ * rotate with a tick's `angle`. Synchronous: call it after `loadLeague(league)`.
+ *
+ * @example
+ * ```tsx
+ * import { loadLeague } from "@sportsdataverse/sdvplot";
+ * import { LogoTick } from "@sportsdataverse/sdvplot/react";
+ * import { VictoryAxis, VictoryBar, VictoryChart } from "victory";
+ *
+ * await loadLeague("nfl");
+ * const rows = [
+ *   { team: "KC", wins: 15 },
+ *   { team: "BUF", wins: 13 },
+ *   { team: "LAC", wins: 11 },
+ * ];
+ * <VictoryChart domainPadding={40} padding={{ top: 20, bottom: 60, left: 50, right: 20 }}>
+ *   <VictoryAxis tickLabelComponent={<LogoTick league="nfl" size={32} />} />
+ *   <VictoryAxis dependentAxis />
+ *   <VictoryBar data={rows} x="team" y="wins" />
+ * </VictoryChart>;
+ * ```
+ */
+declare function LogoTick(props: LogoTickProps): ReactElement;
+
+/** `<Surface3D>` props: sporty's sport and league, and sporty's `surface()` options. */
+interface Surface3DProps {
+    /** sporty's sport, e.g. "baseball". */
+    sport: string;
+    /** sporty's league key for it, e.g. "mlb". */
+    league: string;
+    /** sporty's `surface()` options (`colorUpdates`, `units`, `rotation`, ...). */
+    options?: Record<string, unknown>;
+    /** The mesh's `renderOrder`. Default -1: drawn before the scene's other objects, as a ground should be. */
+    renderOrder?: number;
+}
+/**
+ * sporty's playing surface in a react-three-fiber scene: `surfaceMesh` as one mesh in the z = 0 plane, in the
+ * surface's own units (feet for a baseball field or a rink, metres for a pitch), z up, so set the camera's
+ * `up={[0, 0, 1]}`. Drawn unlit in sporty's colours, before the scene's other objects and without depth writes, so its
+ * features paint over each other in order with no z-fighting. Put it inside your `<Canvas>`. `three` and
+ * `@react-three/fiber` (0.186.1 and 9.8.1 or later) and `@sportsdataverse/sporty` load when it first renders, never
+ * with `sdvplot/react`; a missing peer throws `OptionalDependencyError` then. The failed load is kept until the page
+ * reloads, so installing the peer needs a reload. A server render draws nothing.
+ *
+ * See it drawn in the Three.js guide (`sdvplot/three/statcast-pitches` in the gallery).
+ */
+declare function Surface3D(props: Surface3DProps): ReactElement;
+/** `<Trajectory>` props: the path, the tube's radius in world units, and its colour or team. */
+interface TrajectoryProps {
+    /** The path, `[x, y, z]` points in world units (`statcastPitchPath` gives a pitch's). */
+    points: readonly (readonly [x: number, y: number, z: number])[];
+    /** The tube's radius in the points' world units, not px (a baseball's is 0.121 ft). */
+    radius: number;
+    /** Vertices round each ring, 3 or more. Default 12. */
+    radialSegments?: number;
+    /** The tube's colour, `#rrggbb`. Give this or `team` and `league`. */
+    color?: string;
+    /** The team whose colour the tube takes (abbreviation, name or id), with `league`. */
+    team?: unknown;
+    league?: League;
+    season?: SeasonInput;
+    idSystem?: IdSystem;
+    /** "primary" (default) or "secondary". */
+    which?: Which;
+    /** What the tube is seen against: the colour keeps 3:1 contrast against it (`teamColorPalette`). */
+    background?: string;
+    /** The colour of a team that does not resolve. Default "#808080". */
+    fallback?: string;
+    /** The mesh's `renderOrder`. Default 0. */
+    renderOrder?: number;
+}
+/**
+ * A team-coloured tube along a 3D path (a pitch, a ball flight) in a react-three-fiber scene: `trajectoryTube` as one
+ * mesh, `radius` round in the points' world units, drawn unlit and not tone-mapped so the team's colour shows as it
+ * is. Put it inside your `<Canvas>`, over a `<Surface3D>` in the same units. `three` and `@react-three/fiber` load
+ * when it first renders, never with `sdvplot/react`; a missing peer throws `OptionalDependencyError` then (kept until
+ * the page reloads, so installing the peer needs a reload), and a bad radius or colour throws `InputError`. With
+ * `team`, the team's league must be loaded for its colour: until it is, the tube draws nothing (one warning), and in
+ * the browser it loads the league and then draws. A server render draws nothing.
+ *
+ * See it drawn in the Three.js guide (`sdvplot/three/statcast-pitches` in the gallery).
+ */
+declare function Trajectory({ points, renderOrder, ...o }: TrajectoryProps): ReactElement | null;
+
+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, LogoBump, type LogoBumpProps, LogoPoint, type LogoPointProps, LogoTick, type LogoTickProps, Surface3D, type Surface3DProps, SurfaceBackdrop, type SurfaceBackdropProps, TeamLogo, type TeamLogoProps, Trajectory, type TrajectoryProps, Wordmark, useResolve, useSelection, useTeamColors };