@sportsdataverse/sdvplot 0.0.0-stage → 0.2.0

package/dist/axis-CraWQRUJ.d.ts

@@ -0,0 +1,49 @@
+import * as Plot from '@observablehq/plot';
+import { L as League, S as SeasonInput, V as Variant, M as MarkType, I as IdSystem } from './types-C7n6gJF3.js';
+
+type Axis = "x" | "y" | "fx" | "fy";
+/**
+ * Plot's axis options sdvplot does not own pass through: `ticks`, `tickSpacing`, `tickPadding`, `tickRotate`,
+ * `fontSize`, `fill`, `ariaLabel`, `ariaDescription`, `facetAnchor`, `className`, the margins, and the rest. A
+ * `render` you pass wraps sdvplot's (it sees the images). sdvplot owns `tickFormat` (the tick text becomes the
+ * image); `anchor`, `tickSize` and `label` are sdvplot's own options below.
+ */
+type AxisPassThrough = Omit<Plot.AxisXOptions, "tickFormat" | "anchor" | "tickSize" | "label">;
+/**
+ * Options for `axisLogos`. Each drawn image is named by the tick it replaces ("KC logo", "KC wordmark"), so assistive
+ * technology reads the category the text showed. The images are sized by `height` (a fraction of the frame); a caller
+ * margin on the anchored side smaller than the computed one can clip them.
+ */
+interface AxisLogosOptions extends AxisPassThrough {
+    league: League;
+    season?: SeasonInput;
+    /** Fraction of the frame height in (0, 1]; default 0.1. */
+    height?: number;
+    variant?: Variant;
+    markType?: MarkType;
+    idSystem?: IdSystem;
+    anchor?: "top" | "bottom" | "left" | "right";
+    tickSize?: number;
+    label?: string | null;
+}
+/**
+ * Axis mark whose tick text is swapped for the team image; categories that do not resolve keep their text.
+ *
+ * @example
+ * ```ts
+ * import * as Plot from "@observablehq/plot";
+ * import { loadLeague } from "@sportsdataverse/sdvplot";
+ * import { axisLogos } from "@sportsdataverse/sdvplot/plot";
+ *
+ * await loadLeague("nfl");
+ * const wins = [
+ *   { team: "KC", wins: 15 },
+ *   { team: "BUF", wins: 13 },
+ *   { team: "LAC", wins: 11 },
+ * ];
+ * Plot.plot({ marks: [Plot.barY(wins, { x: "team", y: "wins" }), axisLogos("x", { league: "nfl" })] });
+ * ```
+ */
+declare function axisLogos(axis: Axis, o: AxisLogosOptions): Plot.Markish;
+
+export { type Axis as A, type AxisLogosOptions as a, type AxisPassThrough as b, axisLogos as c };

package/dist/bins.d.ts

@@ -0,0 +1,174 @@
+/** One bin of either shape (`hexbin`, `squarebin`): the points in it, plus its centre in the points' own units. */
+type BinOf<T> = T[] & {
+    x: number;
+    y: number;
+};
+/**
+ * Bin points into pointy-top hexagons of circumradius `radius`, in the points' OWN units (data space, not
+ * pixels). Points with a NaN coordinate are skipped. Centres of `-0` are folded to `0` (blazing-the-nets
+ * `main` `lib/data/aggregate.ts:101`), so equal hexes share one key. Throws `InputError` unless `radius` is a finite
+ * number greater than 0.
+ *
+ * Each point goes to the centre upstream d3-hexbin picks, which is close to but not exactly the nearest one: it
+ * compares two candidates' squared distances in lattice units (x over √3·radius, y over 1.5·radius; `:43`), so
+ * about 1-2% of points sit just outside the hexagon drawn for their bin (on the real BKN fixture, 22 of 2000 shots
+ * at radius 10 and 37 of 2000 at radius 15). That is faithful to d3-hexbin and to blazing-the-nets, which draw the
+ * same; do not "fix" it. Squares (`squarebin`) contain every point they bin.
+ *
+ * @example
+ * ```ts
+ * import { hexbin } from "@sportsdataverse/sdvplot/bins";
+ *
+ * // three Brooklyn shots of 2025-26 in tenths of a foot from the hoop (sportsdataverse-data nba_stats_shots): the
+ * // two at the rim share a 1 ft hexagon, so this is 2
+ * const shots = [
+ *   { x_legacy: 0, y_legacy: 0 },
+ *   { x_legacy: -1, y_legacy: 7 },
+ *   { x_legacy: -44, y_legacy: 252 },
+ * ];
+ * hexbin(shots, { radius: 10, x: (s) => s.x_legacy, y: (s) => s.y_legacy }).length;
+ * ```
+ */
+declare function hexbin<T>(points: readonly T[], o: {
+    radius: number;
+    x: (p: T) => number;
+    y: (p: T) => number;
+}): BinOf<T>[];
+/**
+ * An SVG path for a hexagon of circumradius `r` centred on the current point, byte-identical to d3-hexbin's
+ * `hexbin.hexagon(r)`: `selection.attr("transform", translate(cx, cy)).attr("d", hexagonPath(r))`.
+ *
+ * @example
+ * ```ts
+ * import { hexagonPath } from "@sportsdataverse/sdvplot/bins";
+ *
+ * hexagonPath(10);
+ * ```
+ */
+declare function hexagonPath(r: number): string;
+
+/** The cell shape of a lattice. */
+type BinShape = "hex" | "square";
+/**
+ * A cell lattice as plain JSON: pointy-top hexagons of circumradius `radius` (d3-hexbin's), squares of side `side`,
+ * or (`equalArea: true`) the square with the same area as a hexagon of circumradius `radius`.
+ */
+type BinnerOptions = {
+    readonly shape?: "hex";
+    readonly radius: number;
+} | {
+    readonly shape: "square";
+    readonly side: number;
+} | {
+    readonly shape: "square";
+    readonly radius: number;
+    readonly equalArea: true;
+};
+/** A lattice with `equalArea` resolved: what an index stores so a later binning reproduces the same cells. */
+type Lattice = {
+    readonly shape?: "hex";
+    readonly radius: number;
+} | {
+    readonly shape: "square";
+    readonly side: number;
+};
+/** One lattice, either shape. */
+interface Binner {
+    /** `"hex"` or `"square"`. */
+    readonly shape: BinShape;
+    /** The full cell size in the points' units: the hexagon's circumradius, or the square's side. */
+    readonly size: number;
+    /** The resolved options: `{ radius }` for hexagons, `{ shape: "square", side }` for squares. */
+    readonly lattice: Lattice;
+    /** Bin points (`hexbin` or `squarebin`). */
+    bins<T>(points: readonly T[], o: {
+        x: (p: T) => number;
+        y: (p: T) => number;
+    }): BinOf<T>[];
+    /** An SVG path for one cell of size `s` (default `size`) centred on the current point. */
+    cell(s?: number): string;
+}
+/**
+ * Bin points into axis-aligned squares of side `side`, in the points' OWN units. As in d3-hexbin's lattice, a cell
+ * is centred on the origin, so centres are `(i·side, j·side)`. Cells are half-open, `[c − side/2, c + side/2)` on
+ * each axis: a point exactly on an edge goes to the higher cell, because the cell index is `Math.round(x / side)`,
+ * the rounding d3-hexbin uses (`hexbin.js:33-34`). Bins come out in first-seen order; points with a NaN coordinate
+ * are skipped; centres of `-0` fold to `0`. Throws `InputError` unless `side` is a finite number greater than 0.
+ *
+ * @example
+ * ```ts
+ * import { squarebin } from "@sportsdataverse/sdvplot/bins";
+ *
+ * // three Brooklyn shots of 2025-26 (sportsdataverse-data nba_stats_shots); x = 5 sits on a cell edge and goes to
+ * // the higher cell: [[0, 0, 1], [0, 10, 1], [10, 90, 1]]
+ * const shots = [
+ *   { x_legacy: 0, y_legacy: 0 },
+ *   { x_legacy: -1, y_legacy: 7 },
+ *   { x_legacy: 5, y_legacy: 91 },
+ * ];
+ * squarebin(shots, { side: 10, x: (s) => s.x_legacy, y: (s) => s.y_legacy }).map((b) => [b.x, b.y, b.length]);
+ * ```
+ */
+declare function squarebin<T>(points: readonly T[], o: {
+    side: number;
+    x: (p: T) => number;
+    y: (p: T) => number;
+}): BinOf<T>[];
+/**
+ * An SVG path for a square of side `s` centred on the current point, drawn the way `hexagonPath` is:
+ * `selection.attr("transform", translate(cx, cy)).attr("d", squarePath(s))`.
+ *
+ * @example
+ * ```ts
+ * import { squarePath } from "@sportsdataverse/sdvplot/bins";
+ *
+ * squarePath(10); // "m-5,-5h10v10h-10z"
+ * ```
+ */
+declare function squarePath(s: number): string;
+/**
+ * A cell's vertices around (0, 0), in the points' units: a hexagon of circumradius `size` (d3-hexbin's vertex
+ * order) or a square of side `size`. Add a bin's centre to each to outline that cell as a polygon.
+ *
+ * @example
+ * ```ts
+ * import { cellPoints } from "@sportsdataverse/sdvplot/bins";
+ *
+ * cellPoints("square", 10); // [[-5, -5], [5, -5], [5, 5], [-5, 5]]
+ * ```
+ */
+declare function cellPoints(shape: BinShape, size: number): [number, number][];
+/**
+ * A cell's relative SVG path, `hexagonPath(size)` or `squarePath(size)`, drawn with a `translate` to each bin centre.
+ *
+ * @example
+ * ```ts
+ * import { cellPath } from "@sportsdataverse/sdvplot/bins";
+ *
+ * cellPath("square", 10); // "m-5,-5h10v10h-10z"
+ * ```
+ */
+declare function cellPath(shape: BinShape, size: number): string;
+/**
+ * One binning API for both lattices: `binner({ radius: 15 })` is d3-hexbin's, `binner({ shape: "square", side: 15 })`
+ * squares, and `binner({ shape: "square", radius: 15, equalArea: true })` squares of side 15·√(3√3/2) ≈ 24.18,
+ * each the area of a radius-15 hexagon. Works on any x/y data, not just shots. Throws `InputError` on an unknown
+ * `shape` or a size that is not a positive finite number, naming the option passed.
+ *
+ * @example
+ * ```ts
+ * import { binner } from "@sportsdataverse/sdvplot/bins";
+ *
+ * const b = binner({ shape: "square", radius: 10, equalArea: true }); // side 16.1185…: a radius-10 hexagon's area
+ * // three Brooklyn shots of 2025-26 (sportsdataverse-data nba_stats_shots): the two at the rim share a square
+ * const shots = [
+ *   { x_legacy: 0, y_legacy: 0 },
+ *   { x_legacy: -1, y_legacy: 7 },
+ *   { x_legacy: -44, y_legacy: 252 },
+ * ];
+ * b.bins(shots, { x: (s) => s.x_legacy, y: (s) => s.y_legacy }).map((c) => [c.x, c.y, c.length]);
+ * ```
+ */
+declare function binner(o: BinnerOptions): Binner;
+
+export { type BinOf, type BinShape, type Binner, type BinnerOptions, type Lattice, binner, cellPath, cellPoints, hexagonPath, hexbin, squarePath, squarebin };

package/dist/bins.js

@@ -0,0 +1,4 @@
+export { binner, cellPath, cellPoints, hexagonPath, hexbin, squarePath, squarebin } from './chunk-C2CDY5OG.js';
+import './chunk-E7G7VSLV.js';
+//# sourceMappingURL=bins.js.map
+//# sourceMappingURL=bins.js.map

package/dist/bins.js.map

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