@sportsdataverse/sdvplot 0.0.0-stage → 0.2.0

package/dist/g2.js

@@ -0,0 +1,102 @@
+import { colorPalette, aspect, imageSource, markPlacements } from './chunk-UL5M6KDE.js';
+export { embedSources } from './chunk-UL5M6KDE.js';
+import { placeSync, placedName, checkAlpha } from './chunk-7ULOCCFL.js';
+import './chunk-ZAEQXFJM.js';
+import './chunk-J6R2LEJ7.js';
+import { InputError } from './chunk-E7G7VSLV.js';
+
+// src/g2.ts
+function teamColorPalette(league, teams, o = {}) {
+  return colorPalette(league, teams, o);
+}
+function teamColorScale(league, teams, o = {}) {
+  const seen = /* @__PURE__ */ new Map();
+  for (const t of teams) if (!seen.has(String(t))) seen.set(String(t), t);
+  return { type: "ordinal", domain: [...seen.values()], range: colorPalette(league, [...seen.keys()], o) };
+}
+function checkSize(size) {
+  if (!(typeof size === "number" && Number.isFinite(size) && size > 0))
+    throw new InputError(`size is an image height in px > 0, got ${String(size)}`);
+  if (size < 1)
+    throw new InputError(
+      `size is a height in px, not a fraction of the plot (echarts' \`height\`): got ${size}, which draws a sub-pixel image`
+    );
+  return size;
+}
+var width = (d) => d.sdv_width;
+var height = (d) => d.sdv_height;
+function imageMark(rows, kind, o) {
+  const h = checkSize(o.size ?? 24);
+  const opacity = checkAlpha(o.alpha ?? 1);
+  const ps = markPlacements(rows, kind, o);
+  return {
+    type: "image",
+    // the whole row, not only x and y: a view's encode (say color: "team") reaches this mark too, and a caller's own
+    // style callback on it (opacity by wins, say) reads the row's fields
+    data: ps.map((p) => ({
+      ...rows[p.index],
+      sdv_id: p.id,
+      sdv_src: imageSource(p, o.embed),
+      sdv_width: h * aspect(p),
+      sdv_height: h
+    })),
+    encode: { x: o.x, y: o.y, src: "sdv_src" },
+    style: { width, height, opacity },
+    tooltip: false,
+    legend: false
+  };
+}
+function logoMark(rows, o) {
+  return imageMark(rows, "logo", o);
+}
+function wordmarkMark(rows, o) {
+  return imageMark(rows, "wordmark", o);
+}
+function headshotMark(rows, o) {
+  return imageMark(rows, "headshot", o);
+}
+var escapeHtml = (s) => s.replace(/[&<>"']/g, (c) => `&#${c.charCodeAt(0)};`);
+function axisLogos(o) {
+  const h = checkSize(o.size ?? 24);
+  const kind = o.markType ?? "logo";
+  return {
+    labelRender: (datum) => {
+      const value = datum.label;
+      const p = placeSync([0], [0], [value], {
+        league: o.league,
+        kind,
+        ...o.season === void 0 ? {} : { season: o.season },
+        ...o.variant === void 0 ? {} : { variant: o.variant },
+        ...o.idSystem === void 0 ? {} : { idSystem: o.idSystem }
+      })[0];
+      if (p === void 0)
+        return `<span style="display:block;width:max-content;transform:translateX(-50%)">${escapeHtml(String(value ?? ""))}</span>`;
+      const alt = escapeHtml(`${placedName(p, o.league, value)} ${kind}`);
+      const w = h * aspect(p);
+      return `<img src="${imageSource(p, o.embed)}" alt="${alt}" data-sdv-id="${escapeHtml(p.id)}" style="display:block;margin-left:${-w / 2}px;width:${w}px;height:${h}px">`;
+    },
+    labelOpacity: 1,
+    labelAutoHide: false,
+    labelAutoRotate: false,
+    transform: []
+  };
+}
+var isImageMark = (v) => typeof v === "object" && v !== null && v.type === "image" && Array.isArray(v.data) && v.encode?.src === "sdv_src";
+function drawnMarks(spec) {
+  if (Array.isArray(spec)) return spec.flatMap(drawnMarks);
+  if (typeof spec !== "object" || spec === null) return [];
+  if (isImageMark(spec))
+    return spec.data.map((d) => [
+      d.sdv_id,
+      d[spec.encode.x],
+      d[spec.encode.y],
+      spec.style.height(d),
+      d.sdv_src
+    ]);
+  const { children, annotations } = spec;
+  return [...drawnMarks(children), ...drawnMarks(annotations)];
+}
+
+export { axisLogos, drawnMarks, headshotMark, logoMark, teamColorPalette, teamColorScale, wordmarkMark };
+//# sourceMappingURL=g2.js.map
+//# sourceMappingURL=g2.js.map

package/dist/g2.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/g2.ts"],"names":[],"mappings":"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","file":"g2.js","sourcesContent":["/**\n * The G2 5 adapter, and so Ant Design Charts (`@ant-design/plots`), whose configs are G2 specs underneath: team colours\n * as a `scale.color` (`teamColorScale`) or a list (`teamColorPalette`), logos / wordmarks / headshots as G2 `image`\n * marks (`logoMark`, `wordmarkMark`, `headshotMark`), and logos as a band axis' labels (`axisLogos`). Each returns\n * plain spec pieces: a mark goes in a view's `children` (`chart.options(...)`) or an Ant Design Charts config's\n * `annotations`, a scale in `scale.color`, the axis labels in `axis.x`. Pure: @antv/g2 is never imported (the types\n * are structural, checked against G2 5.4's own). Call after `loadLeague(league)` / `preloadAll()`.\n */\nimport {\n  type DrawnMark,\n  type Row,\n  aspect,\n  checkAlpha,\n  colorPalette,\n  imageSource,\n  markPlacements,\n  place,\n} from \"./_web.js\";\nimport { InputError } from \"./errors.js\";\nimport type { EspnHeadshotLeague } from \"./headshots.js\";\nimport { type Placement, placedName } from \"./placement.js\";\nimport type { Value } from \"./resolve.js\";\nimport type { HeadshotIdSystem, IdSystem, League, MarkType, SeasonInput, Variant, Which } from \"./types.js\";\nexport type { DrawnMark, Row } from \"./_web.js\";\nexport { embedSources } from \"./_web.js\"; // public: build `embed` with it, as for the other adapters\n\n/** `teamColorPalette` / `teamColorScale` options. */\nexport interface G2ColorOptions {\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 * One colour per team, in order, for anything that takes colours by position. With `background`, every colour keeps\n * 3:1 contrast against it (dark mode) and aims to stay distinct from the others. `teamColorScale` puts the same\n * colours on a G2 `scale.color`, keyed by team.\n *\n * @example\n * ```ts\n * import { loadLeague } from \"@sportsdataverse/sdvplot\";\n * import { teamColorPalette } from \"@sportsdataverse/sdvplot/g2\";\n *\n * await loadLeague(\"nfl\");\n * teamColorPalette(\"nfl\", [\"KC\", \"LAC\", \"DEN\", \"LV\"], { background: \"#141414\" });\n * ```\n */\nexport function teamColorPalette(\n  league: League,\n  teams: readonly unknown[],\n  o: G2ColorOptions = {},\n): string[] {\n  return colorPalette(league, teams, o);\n}\n\n/** A G2 `scale.color`: an ordinal scale from each team value to its colour. */\nexport interface G2ColorScale<T = unknown> {\n  /** Ordinal: a numeric team column (ESPN ids, say) keeps one colour per id, never a gradient. */\n  type: \"ordinal\";\n  /** The team values exactly as the data holds them (numbers stay numbers), each once and in order. */\n  domain: T[];\n  /** Their colours, in the same order. */\n  range: string[];\n}\n/**\n * Team colours as a G2 `scale.color` (`{ type: \"ordinal\", domain, range }`): the mark's `encode.color` field holds the\n * team values, and each draws in its own colour; the legend lists the teams in this order. With `background` the\n * colours read on it (dark mode). Pass the teams as the data holds them: G2 matches the domain to the data by exact\n * value, so a numeric id stays a number here (12, not \"12\"); a value given twice (also 12 and \"12\") is kept once.\n *\n * @example\n * ```ts\n * import { loadLeague } from \"@sportsdataverse/sdvplot\";\n * import { teamColorScale } from \"@sportsdataverse/sdvplot/g2\";\n *\n * await loadLeague(\"nfl\");\n * // { type: \"interval\", encode: { x: \"team\", y: \"wins\", color: \"team\" }, scale: { color: <this> } }\n * teamColorScale(\"nfl\", [\"KC\", \"LAC\", \"DEN\", \"LV\"]);\n * ```\n */\nexport function teamColorScale<T>(\n  league: League,\n  teams: readonly T[],\n  o: G2ColorOptions = {},\n): G2ColorScale<T> {\n  const seen = new Map<string, T>(); // keyed by String(v): the first of 12 and \"12\" wins\n  for (const t of teams) if (!seen.has(String(t))) seen.set(String(t), t);\n  return { type: \"ordinal\", domain: [...seen.values()], range: colorPalette(league, [...seen.keys()], o) };\n}\n\ninterface Shared {\n  /** Image height in px, 1 or more (G2 sizes an image mark in px). Default 24. */\n  size?: number;\n  /** Opacity in [0, 1]. Default 1. */\n  alpha?: number;\n  /** url → data URI map from `embedSources`, to inline the images. */\n  embed?: ReadonlyMap<string, string>;\n}\n/** `logoMark` / `wordmarkMark` options. */\nexport interface G2MarkOptions extends Shared {\n  /** Name of the row field holding each mark's x position (the field the chart's x channel encodes). */\n  x: string;\n  /** Name of the row field holding each mark's y position. */\n  y: string;\n  /** Name of the row field holding the team (abbreviation, name or id; see `idSystem`). */\n  team: string;\n  /** The league the teams belong to, e.g. \"nfl\". */\n  league: League;\n  /** A season (number or string) for every row, or the name of a row field holding each row's season. */\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/** `headshotMark` options. */\nexport interface G2HeadshotOptions extends Shared {\n  /** Name of the row field holding each headshot's x position. */\n  x: string;\n  /** Name of the row field holding each headshot's y position. */\n  y: string;\n  /** Name of the row field holding the player id. */\n  player: string;\n  /** The league the players belong to, e.g. \"nfl\". */\n  league: EspnHeadshotLeague;\n  /** ESPN athlete ids, or nflverse gsis ids (needs `loadGsis()` first). Default \"espn\". */\n  idSystem?: HeadshotIdSystem;\n}\n\n/** One datum of an sdvplot image mark: the caller's row and what it draws. */\nexport type G2ImageDatum = Row & {\n  /** The resolved team id or player id. */\n  sdv_id: string;\n  /** The image's URL (or data URI). */\n  sdv_src: string;\n  /** Its size in px. */\n  sdv_width: number;\n  sdv_height: number;\n};\n/**\n * A G2 `image` mark (G2 5's `ImageMark`, structurally): one image per drawable row, centred on the row's (x, y) in\n * the view's own scales. Out of the tooltip and the legend.\n */\nexport interface G2ImageMark {\n  type: \"image\";\n  data: G2ImageDatum[];\n  encode: { x: string; y: string; src: \"sdv_src\" };\n  style: {\n    width: (d: G2ImageDatum) => number;\n    height: (d: G2ImageDatum) => number;\n    opacity: number;\n  };\n  tooltip: false;\n  legend: false;\n}\n\nfunction checkSize(size: unknown): number {\n  if (!(typeof size === \"number\" && Number.isFinite(size) && size > 0))\n    throw new InputError(`size is an image height in px > 0, got ${String(size)}`);\n  if (size < 1)\n    throw new InputError(\n      `size is a height in px, not a fraction of the plot (echarts' \\`height\\`): got ${size}, which draws a sub-pixel image`,\n    );\n  return size;\n}\nconst width = (d: G2ImageDatum): number => d.sdv_width;\nconst height = (d: G2ImageDatum): number => d.sdv_height;\n\nfunction imageMark(\n  rows: readonly Row[],\n  kind: \"logo\" | \"wordmark\" | \"headshot\",\n  o: G2MarkOptions | G2HeadshotOptions,\n): G2ImageMark {\n  const h = checkSize(o.size ?? 24);\n  const opacity = checkAlpha(o.alpha ?? 1);\n  // markPlacements reads the x/y fields only to drop rows with a missing one; G2 reads them itself, by field name\n  const ps: Placement[] = markPlacements(rows, kind, o);\n  return {\n    type: \"image\",\n    // the whole row, not only x and y: a view's encode (say color: \"team\") reaches this mark too, and a caller's own\n    // style callback on it (opacity by wins, say) reads the row's fields\n    data: ps.map((p) => ({\n      ...rows[p.index],\n      sdv_id: p.id,\n      sdv_src: imageSource(p, o.embed),\n      sdv_width: h * aspect(p),\n      sdv_height: h,\n    })),\n    encode: { x: o.x, y: o.y, src: \"sdv_src\" },\n    style: { width, height, opacity },\n    tooltip: false,\n    legend: false,\n  };\n}\n\n/**\n * Team logos as a G2 `image` mark: one logo per row, `size` px tall, centred on the row's (`x`, `y`) fields in the\n * view's scales. Put it last in a view's `children` (G2: `chart.options({ type: \"view\", children: [..., mark] })`), or\n * in an Ant Design Charts config's `annotations`, which reach G2 as they are. A team with no logo draws nothing and\n * warns once.\n *\n * @example\n * ```ts\n * import { loadLeague } from \"@sportsdataverse/sdvplot\";\n * import { logoMark } from \"@sportsdataverse/sdvplot/g2\";\n *\n * await loadLeague(\"nfl\");\n * const rows = [\n *   { team: \"KC\", pf: 385, pa: 326 },\n *   { team: \"LAC\", pf: 402, pa: 301 },\n * ];\n * // chart.options({ type: \"view\", data: rows, children: [{ type: \"point\", encode: { x: \"pf\", y: \"pa\" } }, <this>] })\n * logoMark(rows, { x: \"pf\", y: \"pa\", team: \"team\", league: \"nfl\", size: 32 });\n * ```\n */\nexport function logoMark(rows: readonly Row[], o: G2MarkOptions): G2ImageMark {\n  return imageMark(rows, \"logo\", o);\n}\n/**\n * Team wordmarks as a G2 `image` mark, `size` px tall at their own aspect ratio; as `logoMark` otherwise.\n *\n * @example\n * ```ts\n * import { loadLeague } from \"@sportsdataverse/sdvplot\";\n * import { drawnMarks, wordmarkMark } from \"@sportsdataverse/sdvplot/g2\";\n *\n * await loadLeague(\"nfl\");\n * // [team id, x, y, height in px, wordmark URL]: each wordmark 20 px tall, as wide as its own shape\n * drawnMarks(wordmarkMark([{ team: \"LV\", wins: 4, week: 18 }], { x: \"week\", y: \"wins\", team: \"team\", league: \"nfl\", size: 20 }));\n * ```\n */\nexport function wordmarkMark(rows: readonly Row[], o: G2MarkOptions): G2ImageMark {\n  return imageMark(rows, \"wordmark\", o);\n}\n/**\n * ESPN player headshots as a G2 `image` mark, from the row's `player` field; an id with no headshot draws nothing and\n * warns once. `idSystem: \"gsis\"` needs `loadGsis()` first.\n *\n * @example\n * ```ts\n * import { headshotMark } from \"@sportsdataverse/sdvplot/g2\";\n *\n * // Patrick Mahomes (ESPN id 3139477) at his 2024 passing yards and touchdowns, 40 px tall\n * const rows = [{ qb: \"3139477\", yards: 3928, tds: 26 }];\n * headshotMark(rows, { x: \"yards\", y: \"tds\", player: \"qb\", league: \"nfl\", size: 40 }).data;\n * ```\n */\nexport function headshotMark(rows: readonly Row[], o: G2HeadshotOptions): G2ImageMark {\n  return imageMark(rows, \"headshot\", o);\n}\n\n/** `axisLogos` options: the axis' categories are the teams. */\nexport interface G2AxisOptions {\n  /** The league the teams belong to, e.g. \"nfl\". */\n  league: League;\n  /** The season the axis' teams are resolved for. */\n  season?: SeasonInput;\n  /** Image height in px, 1 or more. Default 24. */\n  size?: number;\n  /** Logo variant, e.g. \"dark\". Default \"default\". */\n  variant?: Variant;\n  /** \"logo\" (default) or \"wordmark\". */\n  markType?: MarkType;\n  /** How the axis categories are read. Default \"auto\". */\n  idSystem?: IdSystem;\n  /** url → data URI map from `embedSources`, to inline the images. */\n  embed?: ReadonlyMap<string, string>;\n}\n/** What G2 hands an axis' `labelRender`: the subset read here. */\nexport interface G2AxisDatum {\n  /** The tick's label: the category, as the axis' `labelFormatter` shows it. */\n  label?: unknown;\n}\n/** Axis options for a G2 band axis whose categories are teams: spread them into `axis.x`. */\nexport interface G2AxisLabels {\n  /** HTML for each label: the team's logo, or the category's own text where it has none. */\n  labelRender: (datum: G2AxisDatum) => string;\n  /** G2's theme draws labels at 0.45 opacity: a logo is drawn whole. */\n  labelOpacity: 1;\n  /** No label is hidden or rotated: each logo box is one band wide, so they never overlap. */\n  labelAutoHide: false;\n  labelAutoRotate: false;\n  transform: [];\n}\n\nconst escapeHtml = (s: string): string => s.replace(/[&<>\"']/g, (c) => `&#${c.charCodeAt(0)};`);\n\n/**\n * Team logos as a horizontal band axis' labels (a column chart's `axis.x`), through G2's `labelRender`: each label is\n * HTML, the logo `size` px tall and centred on its tick. Needs `@antv/component` 2.1.12 or later (G2's axis package,\n * an optional peer): 2.1.11 and earlier lay an HTML label out differently, and each logo would sit half a band left. A category with no logo keeps its text and warns once. G2\n * lays an HTML label out one band wide along a horizontal axis only; for a vertical axis (a bar chart's, or under\n * `transpose`) draw a `logoMark` at the axis' position instead. HTML labels are page elements over the chart, not\n * pixels on its canvas: a `toDataURL` export leaves them out.\n *\n * @example\n * ```ts\n * import { loadLeague } from \"@sportsdataverse/sdvplot\";\n * import { axisLogos } from \"@sportsdataverse/sdvplot/g2\";\n *\n * await loadLeague(\"nfl\");\n * // { type: \"interval\", encode: { x: \"team\", y: \"wins\" }, axis: { x: { ...<this>, title: false } } }\n * axisLogos({ league: \"nfl\", size: 28 }).labelRender({ label: \"KC\" });\n * ```\n */\nexport function axisLogos(o: G2AxisOptions): G2AxisLabels {\n  const h = checkSize(o.size ?? 24);\n  const kind = o.markType ?? \"logo\";\n  return {\n    labelRender: (datum) => {\n      const value = datum.label as Value;\n      const p = place([0], [0], [value], {\n        league: o.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      })[0];\n      // G2's axis (@antv/component 2.1.12) puts an HTML label's box with its left edge on the tick: each label shifts\n      // itself left by half its own width to centre there. (2.1.11 and earlier centred the box: see the guide.)\n      if (p === undefined)\n        return `<span style=\"display:block;width:max-content;transform:translateX(-50%)\">${escapeHtml(String(value ?? \"\"))}</span>`;\n      const alt = escapeHtml(`${placedName(p, o.league, value)} ${kind}`);\n      const w = h * aspect(p);\n      // G2 reads the label's height from its inline style; imageSource escapes quotes and angle brackets\n      return `<img src=\"${imageSource(p, o.embed)}\" alt=\"${alt}\" data-sdv-id=\"${escapeHtml(p.id)}\" style=\"display:block;margin-left:${-w / 2}px;width:${w}px;height:${h}px\">`;\n    },\n    labelOpacity: 1,\n    labelAutoHide: false,\n    labelAutoRotate: false,\n    transform: [],\n  };\n}\n\nconst isImageMark = (v: unknown): v is G2ImageMark =>\n  typeof v === \"object\" &&\n  v !== null &&\n  (v as { type?: unknown }).type === \"image\" &&\n  Array.isArray((v as { data?: unknown }).data) &&\n  (v as { encode?: { src?: unknown } }).encode?.src === \"sdv_src\";\n/**\n * Test hook: [id, x, y, height in px, url] per image of every sdvplot mark in `spec`: a mark, a list of them, a G2\n * spec (its `children`, at any depth) or an Ant Design Charts config (its `children` and `annotations`). The height is\n * what the mark's own style hands G2.\n */\nexport function drawnMarks(spec: unknown): DrawnMark[] {\n  if (Array.isArray(spec)) return spec.flatMap(drawnMarks);\n  if (typeof spec !== \"object\" || spec === null) return [];\n  if (isImageMark(spec))\n    return spec.data.map((d) => [\n      d.sdv_id,\n      d[spec.encode.x],\n      d[spec.encode.y],\n      spec.style.height(d),\n      d.sdv_src,\n    ]);\n  const { children, annotations } = spec as { children?: unknown; annotations?: unknown };\n  return [...drawnMarks(children), ...drawnMarks(annotations)];\n}\n"]}

package/dist/headshots-B2J_LOO8.d.ts

@@ -0,0 +1,40 @@
+import { V as Value } from './resolve-CQW-jzvr.js';
+import { H as HeadshotIdSystem } from './types-C7n6gJF3.js';
+
+/** Port of `_headshots.ESPN_HEADSHOT_LEAGUES`. */
+declare const ESPN_HEADSHOT_LEAGUES: {
+    readonly nfl: "nfl";
+    readonly nba: "nba";
+    readonly wnba: "wnba";
+    readonly mlb: "mlb";
+    readonly nhl: "nhl";
+    readonly cfb: "college-football";
+    readonly mbb: "mens-college-basketball";
+    readonly wbb: "womens-college-basketball";
+};
+/** Leagues with ESPN headshots (gsis ids are nfl-only, and nfl is one of these). */
+type EspnHeadshotLeague = keyof typeof ESPN_HEADSHOT_LEAGUES;
+/** Width / height of a headshot image box (the ESPN combiner crop). */
+declare const HEADSHOT_ASPECT: number;
+declare function nbaHeadshotUrl(id: string | number): string;
+declare function wnbaHeadshotUrl(id: string | number): string;
+declare function mlbHeadshotUrl(id: string | number): string;
+declare function nhlHeadshotUrl(id: string | number): string;
+/** Loads the bundled nflverse gsis map (its own ~3 MB chunk, imported only on demand); required before `headshotUrl(…, { idSystem: "gsis" })`. Nothing is downloaded. */
+declare function loadGsis(): Promise<void>;
+/**
+ * Sync port of `_headshots.headshot_url`. ESPN ids need no data; gsis ids need `await loadGsis()` (or `preloadAll()`)
+ * first.
+ *
+ * @example
+ * ```ts
+ * import { headshotUrl } from "@sportsdataverse/sdvplot";
+ *
+ * headshotUrl("3139477", "nfl"); // Patrick Mahomes, by ESPN athlete id
+ * ```
+ */
+declare function headshotUrl(playerId: Value, league: EspnHeadshotLeague, { idSystem }?: {
+    idSystem?: HeadshotIdSystem;
+}): string | undefined;
+
+export { type EspnHeadshotLeague as E, HEADSHOT_ASPECT as H, ESPN_HEADSHOT_LEAGUES as a, nhlHeadshotUrl as b, headshotUrl as h, loadGsis as l, mlbHeadshotUrl as m, nbaHeadshotUrl as n, wnbaHeadshotUrl as w };

package/dist/index.d.ts

@@ -0,0 +1,183 @@
+import { A as Alias, a as MarkRow, S as SeasonInput, L as League, b as LeagueData, c as Team } from './types-C7n6gJF3.js';
+export { E as EXPLICIT_ONLY, H as HeadshotIdSystem, d as INDEX_VERSION, I as IdSystem, e as LEAGUES, M as MarkType, P as PRIORITY, T as TeamId, f as VARIANTS, V as Variant, W as Which } from './types-C7n6gJF3.js';
+import { R as ResolveOptions, V as Value } from './resolve-CQW-jzvr.js';
+export { a as Resolved, r as resolve, b as resolveSync, s as suggest } from './resolve-CQW-jzvr.js';
+export { C as ColorOptions, a as ColorResult, L as LogoUrlOptions, S as SelectOptions, l as logoUrl, b as logoUrlSync, m as marks, p as palette, s as selectMark, c as selectMarkSync, t as teamColors, d as teamColorsSync } from './marks-DH-tQIP-.js';
+export { K as Kind, a as PlaceOptions, P as Placement, c as checkAlpha, b as checkHeight, p as place, d as placeSync } from './placement-UWkqUzpa.js';
+export { a as ESPN_HEADSHOT_LEAGUES, E as EspnHeadshotLeague, H as HEADSHOT_ASPECT, h as headshotUrl, l as loadGsis, m as mlbHeadshotUrl, n as nbaHeadshotUrl, b as nhlHeadshotUrl, w as wnbaHeadshotUrl } from './headshots-B2J_LOO8.js';
+export { C as Cursor, R as RowFilter, b as SelectionPatch, a as SelectionState, S as SelectionStore, c as createSelection, f as focusIds, s as sameCursor, d as sameIds, t as toId } from './selection-D4T3PkRt.js';
+export { b as TIERS_SUBTITLE, c as TIER_DESC, d as TIER_THEMES, a as TierRow, e as Tiers, T as TiersOptions, p as prepareTiers, w as wrapLabel } from './tiers-BN4md-GB.js';
+
+declare const MANIFEST_URL = "https://sdv.nyc3.cdn.digitaloceanspaces.com/assets/public/manifest/marks.csv";
+interface ManifestRow {
+    level: string;
+    league: string;
+    entity_id: string;
+    mark_type: string;
+    variant: string;
+    valid_from: string;
+    valid_to: string;
+    source: string;
+    sha256: string;
+    ext: string;
+    width: string;
+    height: string;
+    archive_url: string;
+    first_seen: string;
+}
+/** RFC 4180 over the whole text (quoted commas, doubled quotes, embedded newlines; CRLF or LF); rows keyed by header name. */
+declare function parseManifestCsv(text: string): ManifestRow[];
+/** Alias-mapped, safe-URL-filtered, ranked marks of one league; `archive_url` is derived, never copied. Not deduped. */
+declare function manifestMarks(league: string, rows: readonly ManifestRow[], aliases: readonly Alias[]): MarkRow[];
+declare function resetManifestCache(): void;
+/** The CDN manifest, fetched once per process (a failure is not cached). */
+declare function fetchManifest(o?: {
+    fetch?: typeof fetch;
+}): Promise<ManifestRow[]>;
+
+interface Rankable {
+    source_rank: number;
+    valid_from: number | null;
+    valid_to: number | null;
+    first_seen: string;
+    sha256: string;
+}
+/** Python `_ranked`: source_rank asc, open-ended (valid_to null) first, valid_to desc, first_seen desc, valid_from desc, sha256 asc; nulls last. */
+declare function compareMarks(a: Rankable, b: Rankable): number;
+
+declare class SdvplotError extends Error {
+    constructor(message: string, options?: ErrorOptions);
+}
+declare class InputError extends SdvplotError {
+}
+declare class UnresolvedTeamError extends SdvplotError {
+}
+declare class UnsupportedTargetError extends SdvplotError {
+}
+/** An optional peer dependency (resvg, playwright, react) is not installed. */
+declare class OptionalDependencyError extends SdvplotError {
+}
+declare class OfflineError extends SdvplotError {
+}
+declare class DownloadError extends OfflineError {
+    readonly url: string;
+    readonly status?: number | undefined;
+    constructor(message: string, url: string, status?: number | undefined);
+}
+type WarningHandler = (message: string) => void;
+declare function setWarningHandler(fn: WarningHandler | null): void;
+declare function resetWarnings(): void;
+/** One warning per `key` per process (spec §4.3): a 10k-row join must not print 10k lines. */
+declare function warn(key: string, message: string): void;
+
+/** Port of `_normalize.norm_value`: trimmed, accents + typographic punctuation folded, case-folded, integral numbers without ".0". */
+declare function normValue(value: unknown): string | null;
+declare function normSeason(value: SeasonInput, league?: League): number | null;
+
+/**
+ * Load a league's bundled teams, aliases and marks (one code-split chunk; nothing is downloaded). Every `*Sync`
+ * function needs it first. Async throughout: an unknown league rejects (never throws synchronously); a failed chunk
+ * load can be retried.
+ *
+ * @example
+ * ```ts
+ * import { loadLeague } from "@sportsdataverse/sdvplot";
+ *
+ * const nfl = await loadLeague("nfl");
+ * nfl.teams.find((t) => t.abbr === "KC");
+ * ```
+ */
+declare function loadLeague(league: League): Promise<LeagueData>;
+/** Every league shard plus the gsis map, so every *Sync variant works afterwards. */
+declare function preloadAll(): Promise<void>;
+/** Port of `_index.season_bounds`: [first, last]; last = max(latest alias season, next year). */
+declare function seasonBounds(league?: League): readonly [number, number] | null;
+/**
+ * The latest season any dated alias of `league` names (the last relocation or rename the index records), or `null`
+ * when no alias is dated. It is not the current season: the NHL's is 1997. A value resolved without a season is
+ * matched at this season first.
+ */
+declare const latestSeason: (league: League) => number | null;
+
+/** All teams for one league, or every league (in `LEAGUES` order) when omitted. */
+declare function teams(league?: League): Promise<readonly Team[]>;
+
+/** Column form → `Row[]` (flat objects, one per index). Columns must be equal length; `{}` → `[]`. */
+declare function rowsFrom(columns: Record<string, readonly unknown[]>): Record<string, unknown>[];
+
+/** Options for {@link matchupColors}: the league, how to resolve the two teams, and the backgrounds. */
+interface MatchupColorOptions extends ResolveOptions {
+    /** The league both teams belong to. */
+    league: League;
+    /** The background each theme's pair must read on; default `{ light: "#ffffff", dark: "#181a1b" }` (Game on Paper's pages). */
+    theme?: {
+        light?: string;
+        dark?: string;
+    };
+}
+/** One `[teamA, teamB]` colour pair per theme, as lowercase `#rrggbb`. */
+interface MatchupColors {
+    /** The pair for a light background. */
+    light: [string, string];
+    /** The pair for a dark background. */
+    dark: [string, string];
+}
+/**
+ * {@link matchupColors} once the league is loaded (`loadLeague` or `preloadAll`).
+ *
+ * @example
+ * ```ts
+ * import { loadLeague, matchupColorsSync } from "@sportsdataverse/sdvplot";
+ *
+ * await loadLeague("cfb");
+ * matchupColorsSync("Alabama", "Georgia", { league: "cfb" });
+ * ```
+ */
+declare function matchupColorsSync(teamA: Value, teamB: Value, opts: MatchupColorOptions): MatchupColors;
+/**
+ * Two team colours that tell the teams apart on a chart: Game on Paper's "game colours" picker.
+ *
+ * @remarks
+ * One pair per theme, each the first candidate whose colours are at least 20 apart in CIEDE2000 and each
+ * at least 2.5:1 (WCAG) against that theme's background. Candidates, in order: both primaries, teamB's
+ * secondary, teamA's secondary, both secondaries; so a team keeps its primary whenever it works, and teamA
+ * (Game on Paper's home team) keeps it first. When no candidate works, an unreadable colour's L* moves just
+ * far enough to read; then both colours' L* move, least total movement first, until they separate; failing
+ * that, the widest readable separation found. A team with no colour gets `#2394fd`. Deterministic.
+ *
+ * @example
+ * ```ts
+ * import { matchupColors } from "@sportsdataverse/sdvplot";
+ *
+ * // two crimson teams; light: ["#9e1b32", "#2c2a29"] (Georgia's secondary), dark: ["#ffffff", "#ba0c2f"]
+ * // in a page, pick the pair for the theme:
+ * // const [alabama, georgia] = window.matchMedia("(prefers-color-scheme: dark)").matches ? dark : light;
+ * await matchupColors("Alabama", "Georgia", { league: "cfb" });
+ * ```
+ */
+declare function matchupColors(teamA: Value, teamB: Value, opts: MatchupColorOptions): Promise<MatchupColors>;
+
+/** A color as lowercase `#rrggbb`: accepts `#rgb`, `#rrggbb`, `#rgba`, `#rrggbbaa` (`#` optional). Transparency throws unless `dropAlpha`. */
+declare function hex6(color: string, opts?: {
+    dropAlpha?: boolean;
+}): string;
+/** WCAG relative luminance, 0 (black) to 1 (white). */
+declare function luminance(color: string): number;
+/** WCAG contrast ratio, 1 (same) to 21 (black on white). */
+declare function contrast(a: string, b: string): number;
+/** Black or white, whichever reads better on `background`. */
+declare function onColor(background: string): string;
+/** The color `t` of the way from `a` to `b` in sRGB (`t` in [0, 1]). */
+declare function mix(a: string, b: string, t: number): string;
+/** The opaque `#rrggbb` a hex color shows as over `background`: a translucent color is alpha-composited onto it. */
+declare function solid(color: string, background?: string): string;
+
+declare function versions(): {
+    sdvplot: string;
+    index: string;
+    manifestLastModified: string;
+};
+
+declare const VERSION: string;
+
+export { Alias, DownloadError, InputError, League, LeagueData, MANIFEST_URL, type ManifestRow, MarkRow, type MatchupColorOptions, type MatchupColors, OfflineError, OptionalDependencyError, type Rankable, ResolveOptions, SdvplotError, SeasonInput, Team, UnresolvedTeamError, UnsupportedTargetError, VERSION, Value, type WarningHandler, compareMarks, contrast, fetchManifest, hex6, latestSeason, loadLeague, luminance, manifestMarks, matchupColors, matchupColorsSync, mix, normSeason, normValue, onColor, parseManifestCsv, preloadAll, resetManifestCache, resetWarnings, rowsFrom, seasonBounds, setWarningHandler, solid, teams, versions, warn };

package/dist/index.js

@@ -0,0 +1,9 @@
+export { VERSION, matchupColors, matchupColorsSync, rowsFrom, teams, versions } from './chunk-J4P4HDBF.js';
+export { TIERS_SUBTITLE, TIER_DESC, TIER_THEMES, prepareTiers, wrapLabel } from './chunk-DYMUVE6K.js';
+export { createSelection, focusIds, sameCursor, sameIds, toId } from './chunk-4C3GX6QO.js';
+export { MANIFEST_URL, checkAlpha, checkHeight, compareMarks, fetchManifest, logoUrl, logoUrlSync, manifestMarks, marks, parseManifestCsv, place, placeSync, resetManifestCache, selectMark, selectMarkSync } from './chunk-7ULOCCFL.js';
+export { ESPN_HEADSHOT_LEAGUES, EXPLICIT_ONLY, HEADSHOT_ASPECT, INDEX_VERSION, LEAGUES, PRIORITY, VARIANTS, headshotUrl, latestSeason, loadGsis, loadLeague, mlbHeadshotUrl, nbaHeadshotUrl, nhlHeadshotUrl, normSeason, normValue, palette, preloadAll, resolve, resolveSync, seasonBounds, suggest, teamColors, teamColorsSync, wnbaHeadshotUrl } from './chunk-ZAEQXFJM.js';
+export { contrast, hex6, luminance, mix, onColor, solid } from './chunk-J6R2LEJ7.js';
+export { DownloadError, InputError, OfflineError, OptionalDependencyError, SdvplotError, UnresolvedTeamError, UnsupportedTargetError, resetWarnings, setWarningHandler, warn } from './chunk-E7G7VSLV.js';
+//# sourceMappingURL=index.js.map
+//# sourceMappingURL=index.js.map

package/dist/index.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"names":[],"mappings":"","file":"index.js"}