@sportsdataverse/sdvplot 0.1.0 → 0.2.0

package/dist/three.d.ts

@@ -0,0 +1,223 @@
+import { Units, Sport, LeagueOf, OptionsOf } from '@sportsdataverse/sporty';
+import { W as Which, S as SeasonInput, I as IdSystem, L as League } from './types-C7n6gJF3.js';
+
+/**
+ * The Baseball Savant (Statcast) pitch fields `statcastPitchPath` reads, by their Savant CSV column names: feet, feet
+ * per second and feet per second squared, in Statcast's frame (catcher's view: x to the catcher's right, the
+ * first-base side; y from the point of home plate towards the mound; z up).
+ */
+interface StatcastPitch {
+    /** Velocity at y = 50 ft, ft/s. */
+    vx0: number;
+    vy0: number;
+    vz0: number;
+    /** Acceleration (constant over the flight), ft/s². */
+    ax: number;
+    ay: number;
+    az: number;
+    /**
+     * Where the pitch crossed home plate, ft: at its front edge (y = 17/12 ft) through 2025, and at its middle
+     * (y = 8.5/12 ft, "to align with the ABS system") from 2026, per Savant's CSV documentation.
+     */
+    plate_x: number;
+    plate_z: number;
+    /** The release point's distance from home plate, ft (60.5 less the pitcher's extension). */
+    release_pos_y: number;
+    /** The season: it says which plate plane plate_x and plate_z are at (see `StatcastPathOptions.plate`). */
+    game_year?: number;
+}
+/** `statcastPitchPath` options. */
+interface StatcastPathOptions {
+    /** Steps from release to the plate, equal in time: the path has `steps + 1` points. Default 40. */
+    steps?: number;
+    /**
+     * The plane plate_x and plate_z were measured at: "front" (the plate's front edge, Savant through 2025) or "middle"
+     * (halfway along it, from 2026). Default: from the pitch's `game_year`; with neither it is an InputError, as a wrong
+     * plane moves the whole path 8.5 inches along its flight.
+     */
+    plate?: "front" | "middle";
+}
+/**
+ * A pitch's flight from release to the front of home plate, as `[x, y, z]` points in feet in Statcast's frame, which
+ * is sporty's baseball frame too (home plate's point at the origin, y towards the mound), so the path draws over
+ * `surfaceMesh("baseball", "mlb")` unconverted. Statcast describes each pitch with the PITCHf/x nine-parameter fit:
+ * constant acceleration (ax, ay, az) and the velocity (vx0, vy0, vz0) at y = 50 ft, so
+ * `p(t) = p50 + v0 t + a t² / 2` (Baseball Savant CSV documentation, https://baseballsavant.mlb.com/csv-docs: "vx0,
+ * vy0, vz0: the velocity of the pitch, in feet per second, in x, y, and z dimensions, determined at y=50 feet"; "ax,
+ * ay, az: the acceleration of the pitch, in feet per second per second ... determined at y=50 feet"; A. M. Nathan,
+ * "Determining Pitch Movement from PITCHf/x Data", 2012, https://baseball.physics.illinois.edu/Movement.pdf). Savant's
+ * CSV leaves out x and z at y = 50, so they are solved from where the fit crosses the plate (plate_x, plate_z: at its
+ * front edge, y = 17/12 ft, through 2025; at its middle, y = 8.5/12 ft, from 2026, per the same documentation); the
+ * path then runs, equal steps in time, from y = release_pos_y to that plane. The 2026 middle-of-plate rule is from
+ * Savant's documentation of its MLB search: for its World Baseball Classic or minor-league searches, pass `plate`
+ * explicitly rather than rely on `game_year`. Each field must be a number: filter out rows with an empty CSV cell
+ * first, since `Number("")` is 0 and would pass as a real value. Traced back to the release, it lands on
+ * Savant's own release_pos_x / release_pos_z within their 0.01 ft rounding (checked on 2024 and 2026 pitches).
+ *
+ * @example
+ * ```ts
+ * import { statcastPitchPath } from "@sportsdataverse/sdvplot/three";
+ *
+ * // a 96.3 mph four-seamer, Yankees at Red Sox, 2024-06-15 (Baseball Savant: game 746946, at-bat 48, pitch 4)
+ * const pitch = {
+ *   vx0: -6.245145230392043, vy0: -140.0548111003631, vz0: -4.647911601289857,
+ *   ax: 12.681580763686934, ay: 32.15363682007945, az: -12.428443024407864,
+ *   plate_x: 0.42927397039380755, plate_z: 3.546869816011372, release_pos_y: 54.12, game_year: 2024,
+ * };
+ * const path = statcastPitchPath(pitch); // 41 points, release to plate
+ * path[0]; // about [2.05, 54.12, 6.17]: Savant's release_pos_x, release_pos_y, release_pos_z
+ * ```
+ */
+declare function statcastPitchPath(pitch: StatcastPitch, o?: StatcastPathOptions): [x: number, y: number, z: number][];
+
+/** One closed loop of `surfaceMesh`: where its vertices and triangles sit in the mesh buffers. */
+interface SurfaceLoop {
+    /** The sporty feature it comes from (e.g. "infield_dirt"), or "background" for the surface's own background. */
+    name: string;
+    /** The feature's sporty fill, `#rrggbb` or `#rrggbbaa`, as sporty gives it. */
+    color: string;
+    /** Its first vertex and number of vertices. */
+    vertexStart: number;
+    vertexCount: number;
+    /** Its first index and number of indices (three per triangle). */
+    indexStart: number;
+    indexCount: number;
+}
+/**
+ * A sporty playing surface as one triangle mesh in the z = 0 plane, in the surface's own units and frame (feet for a
+ * baseball field or a rink, metres for a pitch; origin where sporty puts it), ready for a three.js `BufferGeometry`.
+ */
+interface SurfaceMesh {
+    /** x, y, z per vertex; z is 0. */
+    positions: Float32Array;
+    /** r, g, b, a per vertex, 0 to 1, in linear sRGB (three.js's working colour space): a vertex-colour attribute. */
+    colors: Float32Array;
+    /** Three vertex indices per triangle, counter-clockwise seen from +z, back to front. */
+    indices: Uint32Array;
+    /** Every loop, in drawing order (later ones lie over earlier ones in the same plane). */
+    loops: SurfaceLoop[];
+    units: Units;
+    /** The surface's extent, `[x0, y0, x1, y1]`. */
+    bbox: readonly [x0: number, y0: number, x1: number, y1: number];
+}
+/**
+ * sporty's playing surface for `sport` and `league` (sporty's own league keys, e.g. `surfaceMesh("baseball", "mlb")`,
+ * `surfaceMesh("hockey", "nhl")`) as one triangle mesh in the z = 0 plane: plain buffers (positions, linear-sRGB
+ * vertex colours, indices), with no three.js import, ready for `new BufferGeometry()` in three.js or the `<Surface3D>`
+ * component in `sdvplot/react`. World units: the surface's own (feet for a baseball field or a rink, metres for a
+ * pitch), in sporty's frame: a baseball field has home plate's point at the origin and +y towards centre field,
+ * Statcast's frame, so `statcastPitchPath` points draw over it unconverted; the other surfaces have the origin at
+ * their centre. The surface's background colour (a baseball field's outfield grass) is the first loop, over the
+ * extent; then each closed loop of each polygon feature, in sporty's drawing order (a faceoff circle is two loops,
+ * its half rings), filled with its colour, alpha included. Hidden features (a `#rrggbb00` fill) and text (a football
+ * field's numbers) are left out, and sporty's heights (goal frames, backboards) are flattened: z is 0 throughout.
+ * Every loop lies in one plane, so draw the mesh in order without depth writes (`depthWrite: false`), first
+ * (`renderOrder` -1), with `vertexColors`, `transparent` and `toneMapped: false`, as `<Surface3D>` does: later loops
+ * then paint over earlier ones with no z-fighting. `o` is passed to sporty's `surface()` (`colorUpdates`, `units`,
+ * `rotation`, ...).
+ *
+ * @example
+ * ```ts
+ * import { surfaceMesh } from "@sportsdataverse/sdvplot/three";
+ *
+ * const field = surfaceMesh("baseball", "mlb");
+ * // in three.js: geometry.setAttribute("position", new BufferAttribute(field.positions, 3)), and so on
+ * field.loops.map((l) => l.name);
+ * ```
+ */
+declare function surfaceMesh<S extends Sport>(sport: S, league: LeagueOf<S>, o?: OptionsOf<S>): SurfaceMesh;
+
+/** `teamColorPalette` options. */
+interface ThreeColorOptions {
+    /** "primary" (default) or "secondary": the team colour each team gets. */
+    which?: Which;
+    season?: SeasonInput;
+    idSystem?: IdSystem;
+    /** The colour of a team that does not resolve. Default "#808080". */
+    fallback?: string;
+    /**
+     * The scene's background (what the colours are seen against, such as the surface under them). Given, a colour under
+     * 3:1 contrast against it is swapped for the team's other colour, else moved towards white (on a dark background)
+     * or black (a light one) until it reads; a colour that would then sit too close to an earlier team's (CIE76 ΔE under
+     * 20) takes the team's other colour, or the nearest colour to its own that is distinct and still reads; failing that
+     * it is kept, with one warning. A team that does not resolve keeps `fallback` and stays out of that search.
+     */
+    background?: string;
+}
+/**
+ * One colour per team, in order, for each team's mesh material (a `Trajectory`'s `color`, a `MeshBasicMaterial`'s
+ * `color`). With `background`, every colour keeps 3:1 contrast against it (dark mode) and the teams aim to stay
+ * distinct (when they cannot, it keeps the readable colour and warns once). A team listed twice gets one colour.
+ *
+ * @example
+ * ```ts
+ * import { loadLeague } from "@sportsdataverse/sdvplot";
+ * import { teamColorPalette } from "@sportsdataverse/sdvplot/three";
+ *
+ * await loadLeague("mlb");
+ * teamColorPalette("mlb", ["NYY", "CWS"], { background: "#395d33" }); // readable on sporty's baseball grass
+ * ```
+ */
+declare function teamColorPalette(league: League, teams: readonly unknown[], o?: ThreeColorOptions): string[];
+/** A point in world units: `[x, y, z]`, z up. */
+type Point3 = readonly [x: number, y: number, z: number];
+/** `trajectoryTube` options: the radius in world units, and either a colour or a team. */
+interface TrajectoryTubeOptions extends Omit<ThreeColorOptions, "fallback"> {
+    /**
+     * The tube's radius in world units: the points' own units (feet for a pitch over a baseball field), not px. Three.js
+     * draws in the scene's units, so a tube is as thick as this whatever the camera; a baseball's radius 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;
+    /** The colour of a team that does not resolve. Default "#808080". */
+    fallback?: string;
+}
+/** A tube mesh, ready for a three.js `BufferGeometry` (world units). */
+interface TubeMesh {
+    /** x, y, z per vertex: `radialSegments` vertices round each point of the path, ring after ring. */
+    positions: Float32Array;
+    /** The outward unit normal of each vertex. */
+    normals: Float32Array;
+    /** Three vertex indices per triangle, counter-clockwise seen from outside the tube. */
+    indices: Uint32Array;
+    /** The tube's colour, `#rrggbb` (sRGB, as a three.js `Color` takes it). */
+    color: string;
+    radius: number;
+    /** The path's length, world units. */
+    length: number;
+}
+/**
+ * A tube along a 3D polyline (a pitch, a ball flight, a skater's path) as plain mesh buffers, in the points' own world
+ * units: ready for `new BufferGeometry()` in three.js, or the `<Trajectory>` component in `sdvplot/react` for
+ * react-three-fiber. The tube is `radius` round (world units, not px), one ring of `radialSegments` vertices at each
+ * point, the rings turned along the path without twisting (each ring's frame is the last one's, carried along: a
+ * parallel-transport frame), with open ends. Its colour is `color`, or the team's (`team` and `league`; `background`
+ * makes it read against the scene, as `teamColorPalette` does); draw it with that colour unlit and not tone-mapped
+ * (`MeshBasicMaterial`, `toneMapped: false`) to show the team's colour as it is. A repeated point is skipped.
+ *
+ * @example
+ * ```ts
+ * import { loadLeague } from "@sportsdataverse/sdvplot";
+ * import { statcastPitchPath, trajectoryTube } from "@sportsdataverse/sdvplot/three";
+ *
+ * await loadLeague("mlb");
+ * // a 96.3 mph four-seamer, Yankees at Red Sox, 2024-06-15 (Baseball Savant: game 746946, at-bat 48, pitch 4)
+ * const pitch = {
+ *   vx0: -6.245145230392043, vy0: -140.0548111003631, vz0: -4.647911601289857,
+ *   ax: 12.681580763686934, ay: 32.15363682007945, az: -12.428443024407864,
+ *   plate_x: 0.42927397039380755, plate_z: 3.546869816011372, release_pos_y: 54.12, game_year: 2024,
+ * };
+ * const tube = trajectoryTube(statcastPitchPath(pitch), { radius: 0.121, team: "NYY", league: "mlb" });
+ * // in three.js: geometry.setAttribute("position", new BufferAttribute(tube.positions, 3)), and so on
+ * tube.color;
+ * ```
+ */
+declare function trajectoryTube(points: readonly Point3[], o: TrajectoryTubeOptions): TubeMesh;
+
+export { type Point3, type StatcastPathOptions, type StatcastPitch, type SurfaceLoop, type SurfaceMesh, type ThreeColorOptions, type TrajectoryTubeOptions, type TubeMesh, statcastPitchPath, surfaceMesh, teamColorPalette, trajectoryTube };

package/dist/three.js

@@ -0,0 +1,50 @@
+export { surfaceMesh } from './chunk-B2MP37SR.js';
+export { teamColorPalette, trajectoryTube } from './chunk-AMXASQHT.js';
+import './chunk-UL5M6KDE.js';
+import './chunk-7ULOCCFL.js';
+import './chunk-ZAEQXFJM.js';
+import './chunk-J6R2LEJ7.js';
+import { InputError } from './chunk-E7G7VSLV.js';
+
+// src/three/statcast.ts
+var FIELDS = ["vx0", "vy0", "vz0", "ax", "ay", "az", "plate_x", "plate_z", "release_pos_y"];
+var PLATE_Y = { front: 17 / 12, middle: 8.5 / 12 };
+var Y0 = 50;
+function statcastPitchPath(pitch, o = {}) {
+  for (const k of FIELDS)
+    if (!Number.isFinite(pitch[k]))
+      throw new InputError(`statcastPitchPath needs a number in the pitch's ${k} (a Baseball Savant column)`);
+  const steps = o.steps ?? 40;
+  if (!(Number.isInteger(steps) && steps >= 1))
+    throw new InputError(`steps is a whole number, 1 or more, got ${String(steps)}`);
+  const year = pitch.game_year;
+  const plate = o.plate ?? (Number.isFinite(year) ? year >= 2026 ? "middle" : "front" : void 0);
+  if (plate !== "front" && plate !== "middle")
+    throw new InputError(
+      `statcastPitchPath needs the pitch's game_year, or plate: "front" (through 2025) or "middle" (from 2026), to know where plate_x and plate_z were measured`
+    );
+  const { vx0, vy0, vz0, ax, ay, az, plate_x, plate_z, release_pos_y } = pitch;
+  const when = (y) => {
+    const c = Y0 - y;
+    const d = vy0 * vy0 - 2 * ay * c;
+    if (!(vy0 < 0 && d >= 0))
+      throw new InputError(`the pitch never reaches y = ${y} ft (vy0 ${vy0}, ay ${ay})`);
+    return 2 * c / (-vy0 + Math.sqrt(d));
+  };
+  const tp = when(PLATE_Y[plate]);
+  const tr = when(release_pos_y);
+  const x50 = plate_x - vx0 * tp - ax * tp * tp / 2;
+  const z50 = plate_z - vz0 * tp - az * tp * tp / 2;
+  const at = (t) => [
+    x50 + vx0 * t + ax * t * t / 2,
+    Y0 + vy0 * t + ay * t * t / 2,
+    z50 + vz0 * t + az * t * t / 2
+  ];
+  const path = Array.from({ length: steps + 1 }, (_, i) => at(tr + (tp - tr) * i / steps));
+  path[steps] = [plate_x, PLATE_Y[plate], plate_z];
+  return path;
+}
+
+export { statcastPitchPath };
+//# sourceMappingURL=three.js.map
+//# sourceMappingURL=three.js.map

package/dist/three.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/three/statcast.ts"],"names":[],"mappings":"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","file":"three.js","sourcesContent":["import { InputError } from \"../errors.js\";\n\n/**\n * The Baseball Savant (Statcast) pitch fields `statcastPitchPath` reads, by their Savant CSV column names: feet, feet\n * per second and feet per second squared, in Statcast's frame (catcher's view: x to the catcher's right, the\n * first-base side; y from the point of home plate towards the mound; z up).\n */\nexport interface StatcastPitch {\n  /** Velocity at y = 50 ft, ft/s. */\n  vx0: number;\n  vy0: number;\n  vz0: number;\n  /** Acceleration (constant over the flight), ft/s². */\n  ax: number;\n  ay: number;\n  az: number;\n  /**\n   * Where the pitch crossed home plate, ft: at its front edge (y = 17/12 ft) through 2025, and at its middle\n   * (y = 8.5/12 ft, \"to align with the ABS system\") from 2026, per Savant's CSV documentation.\n   */\n  plate_x: number;\n  plate_z: number;\n  /** The release point's distance from home plate, ft (60.5 less the pitcher's extension). */\n  release_pos_y: number;\n  /** The season: it says which plate plane plate_x and plate_z are at (see `StatcastPathOptions.plate`). */\n  game_year?: number;\n}\n/** `statcastPitchPath` options. */\nexport interface StatcastPathOptions {\n  /** Steps from release to the plate, equal in time: the path has `steps + 1` points. Default 40. */\n  steps?: number;\n  /**\n   * The plane plate_x and plate_z were measured at: \"front\" (the plate's front edge, Savant through 2025) or \"middle\"\n   * (halfway along it, from 2026). Default: from the pitch's `game_year`; with neither it is an InputError, as a wrong\n   * plane moves the whole path 8.5 inches along its flight.\n   */\n  plate?: \"front\" | \"middle\";\n}\n\nconst FIELDS = [\"vx0\", \"vy0\", \"vz0\", \"ax\", \"ay\", \"az\", \"plate_x\", \"plate_z\", \"release_pos_y\"] as const;\n/** Where Statcast reports plate_x and plate_z, ft from home plate's point: its front edge, or halfway to it. */\nconst PLATE_Y = { front: 17 / 12, middle: 8.5 / 12 } as const;\n/** The plane Statcast's velocities (vx0, vy0, vz0) are measured at, ft from home plate. */\nconst Y0 = 50;\n\n/**\n * A pitch's flight from release to the front of home plate, as `[x, y, z]` points in feet in Statcast's frame, which\n * is sporty's baseball frame too (home plate's point at the origin, y towards the mound), so the path draws over\n * `surfaceMesh(\"baseball\", \"mlb\")` unconverted. Statcast describes each pitch with the PITCHf/x nine-parameter fit:\n * constant acceleration (ax, ay, az) and the velocity (vx0, vy0, vz0) at y = 50 ft, so\n * `p(t) = p50 + v0 t + a t² / 2` (Baseball Savant CSV documentation, https://baseballsavant.mlb.com/csv-docs: \"vx0,\n * vy0, vz0: the velocity of the pitch, in feet per second, in x, y, and z dimensions, determined at y=50 feet\"; \"ax,\n * ay, az: the acceleration of the pitch, in feet per second per second ... determined at y=50 feet\"; A. M. Nathan,\n * \"Determining Pitch Movement from PITCHf/x Data\", 2012, https://baseball.physics.illinois.edu/Movement.pdf). Savant's\n * CSV leaves out x and z at y = 50, so they are solved from where the fit crosses the plate (plate_x, plate_z: at its\n * front edge, y = 17/12 ft, through 2025; at its middle, y = 8.5/12 ft, from 2026, per the same documentation); the\n * path then runs, equal steps in time, from y = release_pos_y to that plane. The 2026 middle-of-plate rule is from\n * Savant's documentation of its MLB search: for its World Baseball Classic or minor-league searches, pass `plate`\n * explicitly rather than rely on `game_year`. Each field must be a number: filter out rows with an empty CSV cell\n * first, since `Number(\"\")` is 0 and would pass as a real value. Traced back to the release, it lands on\n * Savant's own release_pos_x / release_pos_z within their 0.01 ft rounding (checked on 2024 and 2026 pitches).\n *\n * @example\n * ```ts\n * import { statcastPitchPath } from \"@sportsdataverse/sdvplot/three\";\n *\n * // a 96.3 mph four-seamer, Yankees at Red Sox, 2024-06-15 (Baseball Savant: game 746946, at-bat 48, pitch 4)\n * const pitch = {\n *   vx0: -6.245145230392043, vy0: -140.0548111003631, vz0: -4.647911601289857,\n *   ax: 12.681580763686934, ay: 32.15363682007945, az: -12.428443024407864,\n *   plate_x: 0.42927397039380755, plate_z: 3.546869816011372, release_pos_y: 54.12, game_year: 2024,\n * };\n * const path = statcastPitchPath(pitch); // 41 points, release to plate\n * path[0]; // about [2.05, 54.12, 6.17]: Savant's release_pos_x, release_pos_y, release_pos_z\n * ```\n */\nexport function statcastPitchPath(\n  pitch: StatcastPitch,\n  o: StatcastPathOptions = {},\n): [x: number, y: number, z: number][] {\n  for (const k of FIELDS)\n    if (!Number.isFinite(pitch[k]))\n      throw new InputError(`statcastPitchPath needs a number in the pitch's ${k} (a Baseball Savant column)`);\n  const steps = o.steps ?? 40;\n  if (!(Number.isInteger(steps) && steps >= 1))\n    throw new InputError(`steps is a whole number, 1 or more, got ${String(steps)}`);\n  const year = pitch.game_year;\n  const plate =\n    o.plate ?? (Number.isFinite(year) ? ((year as number) >= 2026 ? \"middle\" : \"front\") : undefined);\n  if (plate !== \"front\" && plate !== \"middle\")\n    throw new InputError(\n      'statcastPitchPath needs the pitch\\'s game_year, or plate: \"front\" (through 2025) or \"middle\" (from 2026), ' +\n        \"to know where plate_x and plate_z were measured\",\n    );\n  const { vx0, vy0, vz0, ax, ay, az, plate_x, plate_z, release_pos_y } = pitch;\n  // the time (from y = 50 ft) at which y(t) = 50 + vy0 t + ay t^2 / 2 reaches y: the root nearer 0, written so it stays\n  // accurate however small ay is\n  const when = (y: number): number => {\n    const c = Y0 - y;\n    const d = vy0 * vy0 - 2 * ay * c;\n    if (!(vy0 < 0 && d >= 0))\n      throw new InputError(`the pitch never reaches y = ${y} ft (vy0 ${vy0}, ay ${ay})`);\n    return (2 * c) / (-vy0 + Math.sqrt(d));\n  };\n  const tp = when(PLATE_Y[plate]);\n  const tr = when(release_pos_y);\n  const x50 = plate_x - vx0 * tp - (ax * tp * tp) / 2;\n  const z50 = plate_z - vz0 * tp - (az * tp * tp) / 2;\n  const at = (t: number): [number, number, number] => [\n    x50 + vx0 * t + (ax * t * t) / 2,\n    Y0 + vy0 * t + (ay * t * t) / 2,\n    z50 + vz0 * t + (az * t * t) / 2,\n  ];\n  const path = Array.from({ length: steps + 1 }, (_, i) => at(tr + ((tp - tr) * i) / steps));\n  path[steps] = [plate_x, PLATE_Y[plate], plate_z]; // the measured crossing itself, free of rounding\n  return path;\n}\n"]}

package/dist/{tiers-B6pUBPcE.d.ts → tiers-BN4md-GB.d.ts}

@@ -1,33 +1,5 @@
-import { L as League, S as SeasonInput, V as Variant, I as IdSystem, H as HeadshotIdSystem, a as MarkRow, T as TeamId } from './types-C7n6gJF3.js';
 import { V as Value } from './resolve-CQW-jzvr.js';
-
-type Kind = "logo" | "wordmark" | "headshot";
-/** One point to draw: the caller's own x/y, the image URL and its width / height ratio (null when unknown). `index` is the row's position in the input arrays (skipped rows leave gaps). */
-interface Placement {
-    index: number;
-    id: string;
-    x: Value;
-    y: Value;
-    url: string;
-    aspect: number | null;
-    mark: MarkRow | null;
-}
-interface PlaceOptions {
-    league: League;
-    season?: SeasonInput | readonly SeasonInput[];
-    kind?: Kind;
-    variant?: Variant;
-    /** Team id system for logos/wordmarks (default "auto"); "espn" or "gsis" for headshots (default "espn"). */
-    idSystem?: IdSystem | HeadshotIdSystem;
-    strict?: boolean;
-    warn?: boolean;
-}
-
-declare function checkHeight(height: unknown): number;
-declare function checkAlpha(alpha: unknown): number;
-/** Port of `_placement.place` (post-preload): pairs each (x, y) with its team's mark or player's headshot, dropping and warning (once per reason) on rows that cannot be drawn. Needs `loadLeague(league)` (or `preloadAll()`) first; gsis headshots also need `loadGsis()`. */
-declare function placeSync(xs: readonly Value[], ys: readonly Value[], teams: readonly Value[], o: PlaceOptions): Placement[];
-declare function place(xs: readonly Value[], ys: readonly Value[], teams: readonly Value[], o: PlaceOptions): Promise<Placement[]>;
+import { T as TeamId, V as Variant, L as League } from './types-C7n6gJF3.js';
 
 declare const TIER_DESC: Readonly<Record<number, string>>;
 declare const TIERS_SUBTITLE = "created with the #sdvplot Tiermaker";
@@ -90,4 +62,4 @@ declare function wrapLabel(text: string): string;
 /** Port of `sdvplot._tiers.prepare`: validate the rows and compute everything a tier plot draws. */
 declare function prepareTiers(rows: readonly TierRow[], league: League, o?: TiersOptions): Tiers;
 
-export { type Kind as K, type Placement as P, type TiersOptions as T, type TierRow as a, type PlaceOptions as b, TIERS_SUBTITLE as c, TIER_DESC as d, TIER_THEMES as e, type Tiers as f, checkAlpha as g, checkHeight as h, placeSync as i, prepareTiers as j, place as p, wrapLabel as w };
+export { type TiersOptions as T, type TierRow as a, TIERS_SUBTITLE as b, TIER_DESC as c, TIER_THEMES as d, type Tiers as e, prepareTiers as p, wrapLabel as w };

package/dist/unovis.d.ts

@@ -0,0 +1,127 @@
+import { E as EspnHeadshotLeague } from './headshots-B2J_LOO8.js';
+import { W as Which, S as SeasonInput, I as IdSystem, H as HeadshotIdSystem, V as Variant, L as League } from './types-C7n6gJF3.js';
+import './resolve-CQW-jzvr.js';
+
+/** `teamColorPalette` / `teamColorScale` options. */
+interface UnovisColorOptions {
+    /** "primary" (default) or "secondary" colour. */
+    which?: Which;
+    /** The season the teams are resolved for (a number or string). */
+    season?: SeasonInput;
+    /** How the team values are read. Default "auto". */
+    idSystem?: IdSystem;
+    /** The colour of an unresolved team. Default "#808080". */
+    fallback?: string;
+    /**
+     * The chart's background. Given, a team colour under 3:1 contrast against it is swapped for the team's other
+     * colour, else moved towards white (on a dark background) or black (a light one) until it reads: dark mode. A
+     * colour that would then sit too close to an earlier team's (CIE76 ΔE under 20) takes the team's other colour, or
+     * the nearest colour to its own that is distinct and still reads; failing that it is kept, with one warning.
+     */
+    background?: string;
+}
+/**
+ * One colour per team, in order: an XY component's `color` (one per `y` accessor), or anything else that takes
+ * colours by position. With `background`, every colour keeps 3:1 contrast against it (dark mode) and aims to stay
+ * distinct from the others. `teamColorScale` gives the same colours keyed by team, for accessors.
+ *
+ * @example
+ * ```ts
+ * import { loadLeague } from "@sportsdataverse/sdvplot";
+ * import { teamColorPalette } from "@sportsdataverse/sdvplot/unovis";
+ *
+ * await loadLeague("nfl");
+ * // new Line({ x, y: [kc, phi], color: <this> })
+ * teamColorPalette("nfl", ["KC", "PHI"], { background: "#111827" });
+ * ```
+ */
+declare function teamColorPalette(league: League, teams: readonly unknown[], o?: UnovisColorOptions): string[];
+/** A team's colour: call it from a Unovis colour accessor with the team value the datum holds. */
+interface UnovisTeamColorScale<T = unknown> {
+    /** The colour of `team`: its own for a team of the domain (by any value naming it), else `fallback`. */
+    (team: unknown): string;
+    /** The team values exactly as given (numbers stay numbers), each once and in order. */
+    readonly domain: readonly T[];
+    /** Their colours, in the same order. */
+    readonly range: readonly string[];
+}
+/**
+ * Team colours for Unovis's colour accessors: `color(d.team)` from a Graph's `nodeFill`, `nodeStroke` or
+ * `linkStroke`, a Sankey's `nodeColor` or `linkColor`, a Chord's `nodeColor`. Give every team the chart draws, so
+ * the colours are worked out together: with `background` they read on it (dark mode) and stay distinct. The domain
+ * keeps the values as the data holds them (12 and "12" are both kept); the colours are the resolved team's, so 12,
+ * "12" and "KC" draw in one colour. A value outside the domain gets `fallback`, with one warning.
+ *
+ * @example
+ * ```ts
+ * import { loadLeague } from "@sportsdataverse/sdvplot";
+ * import { teamColorScale } from "@sportsdataverse/sdvplot/unovis";
+ *
+ * await loadLeague("nfl");
+ * const color = teamColorScale("nfl", ["KC", "PHI"]);
+ * // new Sankey({ linkColor: (l) => color(l.team), ... })
+ * [color("KC"), color(21), color.range];
+ * ```
+ */
+declare function teamColorScale<T>(league: League, teams: readonly T[], o?: UnovisColorOptions): UnovisTeamColorScale<T>;
+/** `logoIcons` options. */
+interface UnovisLogoOptions {
+    /** The season the teams are resolved for (a number or string). */
+    season?: SeasonInput;
+    /** Logo variant, e.g. "dark". Default "default". */
+    variant?: Variant;
+    /** How the team values are read. Default "auto". */
+    idSystem?: IdSystem;
+}
+/** `headshotIcons` options. */
+interface UnovisHeadshotOptions {
+    /** ESPN athlete ids, or nflverse gsis ids (needs `loadGsis()` first). Default "espn". */
+    idSystem?: HeadshotIdSystem;
+}
+/** Images for a Graph's node icons: call it from `nodeIcon` with the team (or player) the node holds. */
+interface UnovisIcons<T = unknown> {
+    /** `#<symbol id>` of the image of `value` (by any value naming the same team or player), else undefined. */
+    (value: unknown): string | undefined;
+    /** The values that have an image, as given (numbers stay numbers), each once and in order. */
+    readonly domain: readonly T[];
+    /** Their `#<symbol id>`s, in the same order. */
+    readonly range: readonly string[];
+    /** One `<symbol>` per image: the chart container's `svgDefs` (join two sets' with `+`). */
+    readonly svgDefs: string;
+}
+/**
+ * Team logos for a Unovis Graph's nodes: `nodeIcon: (n) => logos(n.team)`, with
+ * `svgDefs: logos.svgDefs` on the container. Unovis draws each icon as a `<use>` of the logo's `<symbol>`, `nodeIconSize` px across, the logo
+ * fitted inside, uncut; a node's fill shows round it. A team with no logo has no icon, with one warning. Every value
+ * naming a team finds its logo (12, "12" and "KC").
+ *
+ * @example
+ * ```ts
+ * import { loadLeague } from "@sportsdataverse/sdvplot";
+ * import { logoIcons } from "@sportsdataverse/sdvplot/unovis";
+ *
+ * await loadLeague("nfl");
+ * const logos = logoIcons("nfl", ["KC", "LV"], { variant: "dark" });
+ * // new SingleContainer(el, { component: new Graph({ nodeIcon: (n) => logos(n.team), nodeIconSize: 28 }),
+ * //   svgDefs: logos.svgDefs }, data)
+ * [logos("KC"), logos.range];
+ * ```
+ */
+declare function logoIcons<T>(league: League, teams: readonly T[], o?: UnovisLogoOptions): UnovisIcons<T>;
+/**
+ * ESPN player headshots for a Unovis Graph's nodes, as `logoIcons`: `nodeIcon: (n) => heads(n.player)`, with the
+ * container's `svgDefs: heads.svgDefs`. A gsis id with no headshot has no icon, with one warning; an ESPN id's URL is
+ * built without checking the image exists, so an id ESPN has no photo for keeps an empty icon, with no warning.
+ *
+ * @example
+ * ```ts
+ * import { headshotIcons } from "@sportsdataverse/sdvplot/unovis";
+ *
+ * // Patrick Mahomes and Travis Kelce, by ESPN athlete id
+ * const heads = headshotIcons("nfl", [3139477, 15847]);
+ * [heads(3139477), heads.svgDefs.length > 0];
+ * ```
+ */
+declare function headshotIcons<T>(league: EspnHeadshotLeague, players: readonly T[], o?: UnovisHeadshotOptions): UnovisIcons<T>;
+
+export { type UnovisColorOptions, type UnovisHeadshotOptions, type UnovisIcons, type UnovisLogoOptions, type UnovisTeamColorScale, headshotIcons, logoIcons, teamColorPalette, teamColorScale };

package/dist/unovis.js

@@ -0,0 +1,108 @@
+import { contentId } from './chunk-WQT4IVLX.js';
+import { colorPalette, imageSource, aspect } from './chunk-UL5M6KDE.js';
+import { placeSync } from './chunk-7ULOCCFL.js';
+import { resolveSync, normValue } from './chunk-ZAEQXFJM.js';
+import './chunk-J6R2LEJ7.js';
+import { warn } from './chunk-E7G7VSLV.js';
+
+// src/unovis.ts
+function teamColorPalette(league, teams, o = {}) {
+  return colorPalette(league, teams, o);
+}
+var keyOf = (v) => `${typeof v}:${String(v)}`;
+function distinct(values) {
+  const seen = /* @__PURE__ */ new Map();
+  for (const v of values) if (!seen.has(keyOf(v))) seen.set(keyOf(v), v);
+  return [...seen.values()];
+}
+var shown = (v) => typeof v === "string" ? JSON.stringify(v) : String(v);
+function teamColorScale(league, teams, o = {}) {
+  const domain = distinct(teams);
+  const ro = {
+    ...o.season === void 0 ? {} : { season: o.season },
+    ...o.idSystem === void 0 ? {} : { idSystem: o.idSystem }
+  };
+  const fallback = o.fallback ?? "#808080";
+  const ids = resolveSync(domain, league, ro);
+  const known = [...new Set(ids.filter((id) => id !== void 0))];
+  const palette = colorPalette(league, known, {
+    ...ro,
+    idSystem: "team_id",
+    ...o.which === void 0 ? {} : { which: o.which },
+    ...o.background === void 0 ? {} : { background: o.background },
+    fallback
+  });
+  const byTeam = new Map(known.map((id, j) => [id, palette[j]]));
+  const memo = new Map(domain.map((t, i) => [keyOf(t), byTeam.get(ids[i]) ?? fallback]));
+  const scale = (team) => {
+    const k = keyOf(team);
+    let c = memo.get(k);
+    if (c === void 0) {
+      const id = resolveSync(team, league, ro);
+      c = id === void 0 ? void 0 : byTeam.get(id);
+      if (c === void 0)
+        warn(
+          `unovis:${league}:color:${k}`,
+          `teamColorScale: ${shown(team)} is not one of its teams; drawn in ${fallback}`
+        );
+      c ??= fallback;
+      memo.set(k, c);
+    }
+    return c;
+  };
+  return Object.assign(scale, { domain, range: domain.map((t) => memo.get(keyOf(t))) });
+}
+var escapeAttr = (s) => s.replace(/[&<>"]/g, (c) => `&#${c.charCodeAt(0)};`);
+var n = (v) => String(Math.round(v * 1e4) / 1e4);
+function icons(kind, league, values, o) {
+  const given = distinct(values);
+  const at = given.map(() => 0);
+  const placed = placeSync(at, at, given, {
+    league,
+    kind,
+    ...o.season === void 0 ? {} : { season: o.season },
+    ...o.variant === void 0 ? {} : { variant: o.variant },
+    ...o.idSystem === void 0 ? {} : { idSystem: o.idSystem }
+  });
+  const idOf = (v) => kind === "headshot" ? o.idSystem === "gsis" ? String(v).trim() : normValue(v) ?? void 0 : resolveSync(v, league, {
+    ...o.season === void 0 ? {} : { season: o.season },
+    ...o.idSystem === void 0 ? {} : { idSystem: o.idSystem }
+  });
+  const byId = /* @__PURE__ */ new Map();
+  let svgDefs = "";
+  for (const p of placed) {
+    if (byId.has(p.id)) continue;
+    const href = imageSource(p);
+    const id = contentId(`sdv-${kind}`, href);
+    const w = 100 * aspect(p);
+    if (!svgDefs.includes(`id="${id}"`))
+      svgDefs += `<symbol id="${id}" viewBox="0 0 ${n(w)} 100" preserveAspectRatio="xMidYMid meet"><image href="${escapeAttr(href)}" width="${n(w)}" height="100" preserveAspectRatio="xMidYMid meet"/></symbol>`;
+    byId.set(p.id, `#${id}`);
+  }
+  const memo = new Map(
+    placed.map((p) => [keyOf(given[p.index]), byId.get(p.id)])
+  );
+  const icon = (value) => {
+    const k = keyOf(value);
+    if (!memo.has(k)) {
+      const id = value === null || value === void 0 ? void 0 : idOf(value);
+      memo.set(k, id === void 0 ? void 0 : byId.get(id));
+    }
+    return memo.get(k);
+  };
+  return Object.assign(icon, {
+    domain: placed.map((p) => given[p.index]),
+    range: placed.map((p) => byId.get(p.id)),
+    svgDefs
+  });
+}
+function logoIcons(league, teams, o = {}) {
+  return icons("logo", league, teams, o);
+}
+function headshotIcons(league, players, o = {}) {
+  return icons("headshot", league, players, o);
+}
+
+export { headshotIcons, logoIcons, teamColorPalette, teamColorScale };
+//# sourceMappingURL=unovis.js.map
+//# sourceMappingURL=unovis.js.map

package/dist/unovis.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/unovis.ts"],"names":[],"mappings":"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","file":"unovis.js","sourcesContent":["/**\n * The Unovis 1.7 adapter: accessor helpers in Unovis's own idiom, for `@unovis/ts` (plain JavaScript, Svelte, any\n * framework) and `@unovis/react`. Team colours as a function a colour accessor calls (`teamColorScale`: a Graph's\n * `nodeFill` / `nodeStroke` / `linkStroke`, a Sankey's `nodeColor` / `linkColor`, a Chord's `nodeColor`), or as a list\n * (`teamColorPalette`, for an XY component's `color`). Logos and headshots for a Graph's nodes (`logoIcons`,\n * `headshotIcons`): Unovis draws a node icon that starts with `#` as an SVG `<use>` of that id, and the icons' `svgDefs`\n * (for the container's `svgDefs`) hold one `<symbol>` per image. A Sankey's node icon is text only, so a Sankey takes\n * team colours, not logos. Pure: `@unovis/*` is never imported. Call after `loadLeague(league)` / `preloadAll()`.\n */\nimport { aspect, colorPalette, imageSource } from \"./_web.js\";\nimport { contentId } from \"./content-id.js\";\nimport { warn } from \"./errors.js\";\nimport type { EspnHeadshotLeague } from \"./headshots.js\";\nimport { normValue } from \"./normalize.js\";\nimport { type Kind, placeSync } from \"./placement.js\";\nimport { type Value, resolveSync } from \"./resolve.js\";\nimport type { HeadshotIdSystem, IdSystem, League, SeasonInput, Variant, Which } from \"./types.js\";\n\n/** `teamColorPalette` / `teamColorScale` options. */\nexport interface UnovisColorOptions {\n  /** \"primary\" (default) or \"secondary\" colour. */\n  which?: Which;\n  /** The season the teams are resolved for (a number or string). */\n  season?: SeasonInput;\n  /** How the team values are read. Default \"auto\". */\n  idSystem?: IdSystem;\n  /** The colour of an unresolved team. Default \"#808080\". */\n  fallback?: string;\n  /**\n   * The chart's background. Given, a team colour under 3:1 contrast against it is swapped for the team's other\n   * colour, else moved towards white (on a dark background) or black (a light one) until it reads: dark mode. A\n   * colour that would then sit too close to an earlier team's (CIE76 ΔE under 20) takes the team's other colour, or\n   * the nearest colour to its own that is distinct and still reads; failing that it is kept, with one warning.\n   */\n  background?: string;\n}\n\n/**\n * One colour per team, in order: an XY component's `color` (one per `y` accessor), or anything else that takes\n * colours by position. With `background`, every colour keeps 3:1 contrast against it (dark mode) and aims to stay\n * distinct from the others. `teamColorScale` gives the same colours keyed by team, for accessors.\n *\n * @example\n * ```ts\n * import { loadLeague } from \"@sportsdataverse/sdvplot\";\n * import { teamColorPalette } from \"@sportsdataverse/sdvplot/unovis\";\n *\n * await loadLeague(\"nfl\");\n * // new Line({ x, y: [kc, phi], color: <this> })\n * teamColorPalette(\"nfl\", [\"KC\", \"PHI\"], { background: \"#111827\" });\n * ```\n */\nexport function teamColorPalette(\n  league: League,\n  teams: readonly unknown[],\n  o: UnovisColorOptions = {},\n): string[] {\n  return colorPalette(league, teams, o);\n}\n\n/** A value's key as the data holds it: 12 and \"12\" are two keys, each kept. */\nconst keyOf = (v: unknown): string => `${typeof v}:${String(v)}`;\nfunction distinct<T>(values: readonly T[]): T[] {\n  const seen = new Map<string, T>();\n  for (const v of values) if (!seen.has(keyOf(v))) seen.set(keyOf(v), v);\n  return [...seen.values()];\n}\nconst shown = (v: unknown): string => (typeof v === \"string\" ? JSON.stringify(v) : String(v));\n\n/** A team's colour: call it from a Unovis colour accessor with the team value the datum holds. */\nexport interface UnovisTeamColorScale<T = unknown> {\n  /** The colour of `team`: its own for a team of the domain (by any value naming it), else `fallback`. */\n  (team: unknown): string;\n  /** The team values exactly as given (numbers stay numbers), each once and in order. */\n  readonly domain: readonly T[];\n  /** Their colours, in the same order. */\n  readonly range: readonly string[];\n}\n/**\n * Team colours for Unovis's colour accessors: `color(d.team)` from a Graph's `nodeFill`, `nodeStroke` or\n * `linkStroke`, a Sankey's `nodeColor` or `linkColor`, a Chord's `nodeColor`. Give every team the chart draws, so\n * the colours are worked out together: with `background` they read on it (dark mode) and stay distinct. The domain\n * keeps the values as the data holds them (12 and \"12\" are both kept); the colours are the resolved team's, so 12,\n * \"12\" and \"KC\" draw in one colour. A value outside the domain gets `fallback`, with one warning.\n *\n * @example\n * ```ts\n * import { loadLeague } from \"@sportsdataverse/sdvplot\";\n * import { teamColorScale } from \"@sportsdataverse/sdvplot/unovis\";\n *\n * await loadLeague(\"nfl\");\n * const color = teamColorScale(\"nfl\", [\"KC\", \"PHI\"]);\n * // new Sankey({ linkColor: (l) => color(l.team), ... })\n * [color(\"KC\"), color(21), color.range];\n * ```\n */\nexport function teamColorScale<T>(\n  league: League,\n  teams: readonly T[],\n  o: UnovisColorOptions = {},\n): UnovisTeamColorScale<T> {\n  const domain = distinct(teams);\n  const ro = {\n    ...(o.season === undefined ? {} : { season: o.season }),\n    ...(o.idSystem === undefined ? {} : { idSystem: o.idSystem }),\n  };\n  const fallback = o.fallback ?? \"#808080\";\n  const ids = resolveSync(domain as readonly Value[], league, ro);\n  // keyed by the resolved team: a team named twice (12 and \"KC\") is one team, with one colour\n  const known = [...new Set(ids.filter((id) => id !== undefined))];\n  const palette = colorPalette(league, known, {\n    ...ro,\n    idSystem: \"team_id\",\n    ...(o.which === undefined ? {} : { which: o.which }),\n    ...(o.background === undefined ? {} : { background: o.background }),\n    fallback,\n  });\n  const byTeam = new Map<string, string>(known.map((id, j) => [id, palette[j] as string]));\n  const memo = new Map(domain.map((t, i) => [keyOf(t), byTeam.get(ids[i] as string) ?? fallback]));\n  const scale = (team: unknown): string => {\n    const k = keyOf(team);\n    let c = memo.get(k);\n    if (c === undefined) {\n      const id = resolveSync(team as Value, league, ro);\n      c = id === undefined ? undefined : byTeam.get(id);\n      if (c === undefined)\n        warn(\n          `unovis:${league}:color:${k}`,\n          `teamColorScale: ${shown(team)} is not one of its teams; drawn in ${fallback}`,\n        );\n      c ??= fallback;\n      memo.set(k, c);\n    }\n    return c;\n  };\n  return Object.assign(scale, { domain, range: domain.map((t) => memo.get(keyOf(t)) as string) });\n}\n\n/** `logoIcons` options. */\nexport interface UnovisLogoOptions {\n  /** The season the teams are resolved for (a number or string). */\n  season?: SeasonInput;\n  /** Logo variant, e.g. \"dark\". Default \"default\". */\n  variant?: Variant;\n  /** How the team values are read. Default \"auto\". */\n  idSystem?: IdSystem;\n}\n/** `headshotIcons` options. */\nexport interface UnovisHeadshotOptions {\n  /** ESPN athlete ids, or nflverse gsis ids (needs `loadGsis()` first). Default \"espn\". */\n  idSystem?: HeadshotIdSystem;\n}\n/** Images for a Graph's node icons: call it from `nodeIcon` with the team (or player) the node holds. */\nexport interface UnovisIcons<T = unknown> {\n  /** `#<symbol id>` of the image of `value` (by any value naming the same team or player), else undefined. */\n  (value: unknown): string | undefined;\n  /** The values that have an image, as given (numbers stay numbers), each once and in order. */\n  readonly domain: readonly T[];\n  /** Their `#<symbol id>`s, in the same order. */\n  readonly range: readonly string[];\n  /** One `<symbol>` per image: the chart container's `svgDefs` (join two sets' with `+`). */\n  readonly svgDefs: string;\n}\n\nconst escapeAttr = (s: string): string => s.replace(/[&<>\"]/g, (c) => `&#${c.charCodeAt(0)};`);\nconst n = (v: number): string => String(Math.round(v * 1e4) / 1e4);\n\nfunction icons<T>(\n  kind: Kind,\n  league: League,\n  values: readonly T[],\n  o: { season?: SeasonInput; variant?: Variant; idSystem?: IdSystem | HeadshotIdSystem },\n): UnovisIcons<T> {\n  const given = distinct(values);\n  const at = given.map(() => 0); // a node's place is Unovis's layout: placeSync only pairs each value with its image\n  const placed = placeSync(at, at, given as readonly Value[], {\n    league,\n    kind,\n    ...(o.season === undefined ? {} : { season: o.season }),\n    ...(o.variant === undefined ? {} : { variant: o.variant }),\n    ...(o.idSystem === undefined ? {} : { idSystem: o.idSystem }),\n  });\n  // a node's value -> the id its image is keyed by: the resolved team, or the player id as placeSync normalises it\n  const idOf = (v: unknown): string | undefined =>\n    kind === \"headshot\"\n      ? o.idSystem === \"gsis\"\n        ? String(v).trim()\n        : (normValue(v) ?? undefined)\n      : resolveSync(v as Value, league, {\n          ...(o.season === undefined ? {} : { season: o.season }),\n          ...(o.idSystem === undefined ? {} : { idSystem: o.idSystem as IdSystem }),\n        });\n  const byId = new Map<string, string>();\n  let svgDefs = \"\";\n  for (const p of placed) {\n    if (byId.has(p.id)) continue;\n    const href = imageSource(p);\n    const id = contentId(`sdv-${kind}`, href);\n    // the symbol's box is the image's own aspect: a `<use>` of it fits the image, uncut, in nodeIconSize\n    const w = 100 * aspect(p);\n    if (!svgDefs.includes(`id=\"${id}\"`))\n      svgDefs += `<symbol id=\"${id}\" viewBox=\"0 0 ${n(w)} 100\" preserveAspectRatio=\"xMidYMid meet\"><image href=\"${escapeAttr(href)}\" width=\"${n(w)}\" height=\"100\" preserveAspectRatio=\"xMidYMid meet\"/></symbol>`;\n    byId.set(p.id, `#${id}`);\n  }\n  const memo = new Map<string, string | undefined>(\n    placed.map((p) => [keyOf(given[p.index]), byId.get(p.id)]),\n  );\n  const icon = (value: unknown): string | undefined => {\n    const k = keyOf(value);\n    if (!memo.has(k)) {\n      const id = value === null || value === undefined ? undefined : idOf(value);\n      memo.set(k, id === undefined ? undefined : byId.get(id));\n    }\n    return memo.get(k);\n  };\n  return Object.assign(icon, {\n    domain: placed.map((p) => given[p.index] as T),\n    range: placed.map((p) => byId.get(p.id) as string),\n    svgDefs,\n  });\n}\n\n/**\n * Team logos for a Unovis Graph's nodes: `nodeIcon: (n) => logos(n.team)`, with\n * `svgDefs: logos.svgDefs` on the container. Unovis draws each icon as a `<use>` of the logo's `<symbol>`, `nodeIconSize` px across, the logo\n * fitted inside, uncut; a node's fill shows round it. A team with no logo has no icon, with one warning. Every value\n * naming a team finds its logo (12, \"12\" and \"KC\").\n *\n * @example\n * ```ts\n * import { loadLeague } from \"@sportsdataverse/sdvplot\";\n * import { logoIcons } from \"@sportsdataverse/sdvplot/unovis\";\n *\n * await loadLeague(\"nfl\");\n * const logos = logoIcons(\"nfl\", [\"KC\", \"LV\"], { variant: \"dark\" });\n * // new SingleContainer(el, { component: new Graph({ nodeIcon: (n) => logos(n.team), nodeIconSize: 28 }),\n * //   svgDefs: logos.svgDefs }, data)\n * [logos(\"KC\"), logos.range];\n * ```\n */\nexport function logoIcons<T>(league: League, teams: readonly T[], o: UnovisLogoOptions = {}): UnovisIcons<T> {\n  return icons(\"logo\", league, teams, o);\n}\n\n/**\n * ESPN player headshots for a Unovis Graph's nodes, as `logoIcons`: `nodeIcon: (n) => heads(n.player)`, with the\n * container's `svgDefs: heads.svgDefs`. A gsis id with no headshot has no icon, with one warning; an ESPN id's URL is\n * built without checking the image exists, so an id ESPN has no photo for keeps an empty icon, with no warning.\n *\n * @example\n * ```ts\n * import { headshotIcons } from \"@sportsdataverse/sdvplot/unovis\";\n *\n * // Patrick Mahomes and Travis Kelce, by ESPN athlete id\n * const heads = headshotIcons(\"nfl\", [3139477, 15847]);\n * [heads(3139477), heads.svgDefs.length > 0];\n * ```\n */\nexport function headshotIcons<T>(\n  league: EspnHeadshotLeague,\n  players: readonly T[],\n  o: UnovisHeadshotOptions = {},\n): UnovisIcons<T> {\n  return icons(\"headshot\", league, players, o);\n}\n"]}