@pitchkit/react 0.1.0 → 0.3.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Yohahn Ribeiro
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,173 @@
+# @pitchkit/react
+
+[![npm](https://img.shields.io/npm/v/@pitchkit/react)](https://www.npmjs.com/package/@pitchkit/react)
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](https://github.com/yribeiro/pitchkit/blob/main/LICENSE)
+
+Declarative React components for football pitch visualisation — mplsoccer's feature set for
+the web. Responsive by default, themed with CSS variables, SSR-safe.
+
+**Docs and live examples: [pitchkitjs.com](https://pitchkitjs.com)**
+
+> **Early days.** `0.1.x` is the first public release. Usable and tested, but the API isn't
+> stable yet — expect breaking changes before `1.0`.
+
+## Install
+
+```bash
+npm install @pitchkit/react
+```
+
+React >= 18 is a peer dependency. [`@pitchkit/core`](https://www.npmjs.com/package/@pitchkit/core)
+is installed automatically.
+
+## Usage
+
+```tsx
+import { Pitch, Scatter } from "@pitchkit/react";
+
+const shots = [
+  { x: 112, y: 39, xg: 0.76, outcome: "goal" },
+  { x: 105, y: 44, xg: 0.31, outcome: "saved" },
+  { x: 99, y: 47, xg: 0.13, outcome: "off target" },
+];
+
+export function ShotMap() {
+  return (
+    <Pitch type="statsbomb">
+      <Scatter
+        data={shots}
+        x={(s) => s.x}
+        y={(s) => s.y}
+        r={(s) => 3 + s.xg * 9}
+        fill={(s) => (s.outcome === "goal" ? "#fb923c" : "#38bdf8")}
+        tooltip={(s) => `${s.outcome} · xG ${s.xg.toFixed(2)}`}
+      />
+    </Pitch>
+  );
+}
+```
+
+`<Pitch>` owns the coordinate system; children are layers drawn into it, stacked in render
+order. Every visual prop accepts a static value **or** a function of the datum — `fill="red"`
+and `fill={(d) => d.teamColor}` are the same prop.
+
+## Components
+
+| Component          | Draws                                                       |
+| ------------------ | ----------------------------------------------------------- |
+| `<Pitch>`          | The pitch surface + coordinate context (horizontal)         |
+| `<VerticalPitch>`  | Same, rotated to a vertical framing                         |
+| `<Scatter>`        | Circles — shots, players, events                            |
+| `<Annotate>`       | Text labels                                                 |
+| `<Arrows>`         | Straight arrows — passes, carries                           |
+| `<Comet>`          | Tapered lines with direction implied by width               |
+| `<Heatmap>`        | Binned density on Canvas (client-only)                      |
+| `<PositionalHeatmap>` | Juego de Posición zone density on Canvas (client-only)   |
+| `<Hexbin>`         | Hexagonal density on Canvas (client-only)                   |
+| `<KDE>`            | Smooth kernel density surface on Canvas (client-only)       |
+| `<Polygon>`        | Arbitrary closed shapes                                     |
+| `<ConvexHull>`     | Convex hull of a point set                                  |
+| `<Voronoi>`        | Voronoi cells, clipped to the pitch                         |
+| `<GoalAngle>`      | The angle-to-goal wedge from a shot location                |
+| `<Flow>`           | Binned direction + magnitude vectors                        |
+| `usePitch()`       | Hook exposing the pixel transform for custom SVG            |
+
+## Sizing
+
+Responsive is the default — with no size props the pitch fills its container via
+`ResizeObserver` and recomputes on resize. Explicit sizing is the opt-out:
+
+```tsx
+<Pitch type="statsbomb" />                          {/* fills container */}
+<Pitch type="statsbomb" width={1200} height={800} /> {/* fixed — exports, OG images */}
+```
+
+## Layer order
+
+Markings paint *below* the layer children by default, so discrete marks sit on top of the
+lines. An opaque density fill will therefore cover them — set `appearance.linesOnTop` to paint
+the markings above instead (mplsoccer's `line_zorder`):
+
+```tsx
+<Pitch type="statsbomb" appearance={{ linesOnTop: true }}>
+  <KDE data={touches} x={(t) => t.x} y={(t) => t.y} />
+</Pitch>
+```
+
+Only the markings move — the grass surface and stripes stay at the bottom either way.
+
+## Pitch types
+
+`statsbomb` · `opta` · `uefa`, each using the provider's real coordinate space so event data
+goes in unmodified.
+
+```tsx
+import { cropForHalf, getPitchDimensions } from "@pitchkit/core";
+
+const dimensions = getPitchDimensions("statsbomb");
+
+<VerticalPitch type="statsbomb" crop={cropForHalf(dimensions)}>{/* … */}</VerticalPitch>
+```
+
+## Theming
+
+CSS variables only — no theme objects, no providers. Define once; every chart inherits,
+including dark mode:
+
+```css
+:root {
+  --pitch-surface: #1a472a;
+  --pitch-stripe: #1d4f30;
+  --pitch-lines: rgba(255, 255, 255, 0.8);
+}
+```
+
+Marks accept `className`, so Tailwind works directly:
+
+```tsx
+<Scatter data={shots} x={(s) => s.x} y={(s) => s.y} className="fill-emerald-400 stroke-white" />
+```
+
+Setting `className` without an explicit `fill`/`stroke` makes the mark drop its themed default
+so your class wins. For marks whose JSX you don't own, every element carries
+`data-pitchkit-mark` / `-layer` / `-part` attributes to target instead.
+
+## Next.js / SSR
+
+SVG marks server-render cleanly. Because layer components take accessor *functions* as props,
+the `<Pitch>` tree must originate inside a `"use client"` component — React Server Components
+can't pass functions across the client boundary. SSR still happens; only the prop-serialisation
+boundary moves. `<Heatmap>` is Canvas-backed and therefore client-only.
+
+## Agent Skill
+
+No model has PitchKit in its training data, so coding agents asked for a shot map tend to
+invent an mplsoccer-flavoured API. This package ships an Agent Skill — `skills/pitchkit/`
+inside the tarball — that documents the real one.
+
+```bash
+npx @pitchkit/react skills install          # -> .claude/skills/pitchkit/
+npx @pitchkit/react skills install --dir .cursor/skills
+npx @pitchkit/react skills path             # where it lives in node_modules
+```
+
+Install *symlinks* the target at the copy inside `node_modules`, so `npm update
+@pitchkit/react` moves the skill with it and an agent can't end up reading last version's
+API. On a filesystem that won't take a symlink it copies instead and says so — that copy is
+a snapshot, so re-run with `--force` after upgrading.
+
+The default directory suits Claude Code; for any other agent, point `--dir` at wherever it
+reads skills from, or hand it the `skills path` output to read directly. The layout follows
+the `skills/<name>/SKILL.md` convention, so generic installers like `skills-npm` find it in
+`node_modules` without needing this CLI at all.
+
+## Links
+
+- [Documentation & gallery](https://pitchkitjs.com)
+- [Repository](https://github.com/yribeiro/pitchkit)
+- [Issues](https://github.com/yribeiro/pitchkit/issues)
+- [`@pitchkit/core`](https://www.npmjs.com/package/@pitchkit/core) — the framework-agnostic engine
+
+## Licence
+
+MIT © Yohahn Ribeiro

package/bin/install-skill.mjs

@@ -0,0 +1,223 @@
+// The `npx @pitchkit/react skills install` implementation, kept separate from
+// bin/pitchkit.mjs so it can be unit-tested without spawning a process or
+// doing the "am I the main module?" dance (which npx's bin symlinks make
+// unreliable). Zero dependencies on purpose: this runs in a consumer's
+// project, via npx, before anything of ours is necessarily installed.
+import { cp, lstat, mkdir, readdir, rm, symlink } from "node:fs/promises";
+import { dirname, isAbsolute, join, relative, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+
+export const SKILL_NAME = "pitchkit";
+
+/**
+ * Claude Code's project-scoped skills directory. Chosen as the default
+ * because it's the one convention with a settled on-disk layout; every
+ * other agent gets pointed at `--dir` in the help text rather than us
+ * guessing at a location it may not read.
+ */
+export const DEFAULT_SKILLS_DIR = join(".claude", "skills");
+
+/** `bin/` -> the package root, so this resolves inside a consumer's node_modules too. */
+const packageRoot = dirname(dirname(fileURLToPath(import.meta.url)));
+
+export const skillSourceDir = join(packageRoot, "skills", SKILL_NAME);
+
+export class CliError extends Error {}
+
+export function formatHelp() {
+  return `pitchkit — ships the PitchKit Agent Skill with the package you installed
+
+Usage
+  npx @pitchkit/react skills install [options]   Link the skill into your project
+  npx @pitchkit/react skills path                Print the skill's location in node_modules
+  npx @pitchkit/react --help
+
+Options
+  --dir <path>   Skills directory to install into (default: ${DEFAULT_SKILLS_DIR})
+  --force        Replace an existing installation
+  -h, --help     Show this message
+
+<dir>/${SKILL_NAME}/ is symlinked to the copy inside node_modules, so the skill stays in
+step with the installed version; it falls back to a plain copy on filesystems that
+won't take a link. The default directory suits Claude Code; for another agent, point
+--dir at wherever it reads skills from, or use \`skills path\` and read SKILL.md
+directly.`;
+}
+
+export function parseArgs(argv) {
+  const options = { command: null, dir: DEFAULT_SKILLS_DIR, force: false, help: false };
+  const positional = [];
+
+  for (let i = 0; i < argv.length; i += 1) {
+    const arg = argv[i];
+    if (arg === "-h" || arg === "--help") {
+      options.help = true;
+    } else if (arg === "--force" || arg === "-f") {
+      options.force = true;
+    } else if (arg === "--dir") {
+      const value = argv[i + 1];
+      if (value === undefined || value.startsWith("-")) {
+        throw new CliError("--dir needs a path, e.g. --dir .claude/skills");
+      }
+      options.dir = value;
+      i += 1;
+    } else if (arg.startsWith("--dir=")) {
+      const value = arg.slice("--dir=".length);
+      if (value === "") throw new CliError("--dir needs a path, e.g. --dir .claude/skills");
+      options.dir = value;
+    } else if (arg.startsWith("-")) {
+      throw new CliError(`Unknown option: ${arg}`);
+    } else {
+      positional.push(arg);
+    }
+  }
+
+  // `skills install` and a bare `install` both work — the former is what the
+  // docs show, the latter is what people type.
+  const words = positional[0] === "skills" ? positional.slice(1) : positional;
+  options.command = words[0] ?? null;
+
+  if (words.length > 1) {
+    throw new CliError(`Unexpected argument: ${words[1]}`);
+  }
+
+  return options;
+}
+
+/**
+ * `lstat`, not `access`, so a dangling symlink left by an uninstalled
+ * dependency still counts as present and gets cleaned up by `--force`
+ * rather than colliding with EEXIST.
+ */
+async function entryExists(path) {
+  try {
+    await lstat(path);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+/**
+ * Links the destination at the skill inside node_modules, so `npm update
+ * @pitchkit/react` carries the skill with it — the property that makes a
+ * bundled skill worth more than scraped docs, and the one a plain copy
+ * silently loses. Falls back to copying where the filesystem won't take a
+ * link (Windows without Developer Mode, some network and container mounts).
+ *
+ * Returns "link" or "copy" so the caller can tell the user which they got;
+ * the update semantics differ, so this isn't an implementation detail.
+ */
+async function linkOrCopy(destination) {
+  try {
+    if (process.platform === "win32") {
+      // Junctions need an absolute target, but unlike real symlinks they
+      // don't need elevation or Developer Mode.
+      await symlink(skillSourceDir, destination, "junction");
+    } else {
+      // Relative, so the link survives the project being moved or checked
+      // out at a different path with node_modules already in place.
+      await symlink(relative(dirname(destination), skillSourceDir), destination, "dir");
+    }
+    return "link";
+  } catch {
+    await cp(skillSourceDir, destination, { recursive: true, force: true });
+    return "copy";
+  }
+}
+
+/**
+ * Installs `skills/pitchkit/` from the installed package into the consumer's
+ * project. Returns the destination, how it was installed, and what's now
+ * readable there.
+ */
+export async function installSkill({
+  cwd = process.cwd(),
+  dir = DEFAULT_SKILLS_DIR,
+  force = false,
+} = {}) {
+  if (!(await entryExists(skillSourceDir))) {
+    throw new CliError(
+      `Could not find the bundled skill at ${skillSourceDir}. ` +
+        "Is @pitchkit/react installed, and new enough to ship one?",
+    );
+  }
+
+  const skillsDir = isAbsolute(dir) ? dir : resolve(cwd, dir);
+  const destination = join(skillsDir, SKILL_NAME);
+
+  if (await entryExists(destination)) {
+    if (!force) {
+      throw new CliError(
+        `${relative(cwd, destination) || destination} already exists. Re-run with --force to replace it.`,
+      );
+    }
+    // `rm` unlinks a symlink rather than following it, so this can't reach
+    // through an existing link and delete the copy inside node_modules.
+    await rm(destination, { recursive: true, force: true });
+  }
+
+  await mkdir(skillsDir, { recursive: true });
+  const method = await linkOrCopy(destination);
+
+  // Plain codepoint sort, so SKILL.md leads and the references/ paths follow.
+  return { destination, method, files: (await listFiles(destination)).sort() };
+}
+
+async function listFiles(dir, prefix = "") {
+  const entries = await readdir(dir, { withFileTypes: true });
+  const files = [];
+  for (const entry of entries.sort((a, b) => a.name.localeCompare(b.name))) {
+    const name = prefix ? `${prefix}/${entry.name}` : entry.name;
+    if (entry.isDirectory()) {
+      files.push(...(await listFiles(join(dir, entry.name), name)));
+    } else {
+      files.push(name);
+    }
+  }
+  return files;
+}
+
+export async function run(argv, { cwd = process.cwd(), log = console.log } = {}) {
+  const options = parseArgs(argv);
+
+  if (options.help || options.command === null || options.command === "help") {
+    log(formatHelp());
+    return 0;
+  }
+
+  if (options.command === "path") {
+    log(skillSourceDir);
+    return 0;
+  }
+
+  if (options.command !== "install") {
+    throw new CliError(`Unknown command: ${options.command}\n\n${formatHelp()}`);
+  }
+
+  const { destination, method, files } = await installSkill({
+    cwd,
+    dir: options.dir,
+    force: options.force,
+  });
+  const shown = relative(cwd, destination) || destination;
+
+  if (method === "link") {
+    log(`Linked the PitchKit skill at ${shown}`);
+  } else {
+    log(`Copied the PitchKit skill to ${shown}`);
+  }
+  for (const file of files) log(`  ${shown}/${file}`);
+  log("");
+
+  if (method === "link") {
+    log("It points into node_modules, so `npm update @pitchkit/react` updates the");
+    log("skill too. Add it to .gitignore unless you want the link committed.");
+  } else {
+    log("This filesystem wouldn't take a symlink, so the skill was copied instead —");
+    log("it's a snapshot. Re-run with --force after upgrading @pitchkit/react.");
+  }
+  log("Start a new agent session so it picks the skill up.");
+
+  return 0;
+}

package/bin/pitchkit.mjs

@@ -0,0 +1,15 @@
+#!/usr/bin/env node
+// The package's only bin, so `npx @pitchkit/react skills install` resolves to
+// it despite the bin name not matching the (scoped) package name.
+import { CliError, run } from "./install-skill.mjs";
+
+try {
+  process.exitCode = await run(process.argv.slice(2));
+} catch (error) {
+  if (error instanceof CliError) {
+    console.error(error.message);
+    process.exitCode = 1;
+  } else {
+    throw error;
+  }
+}

package/dist/index.d.ts

@@ -1,6 +1,6 @@
 import * as react from 'react';
 import { CSSProperties, ReactNode } from 'react';
-import { PitchTypeId, Orientation, CropWindow, ViewportPadding, PitchAppearance, ScatterLayer, AnnotateLayer, ArrowsLayer, CometLayer, HeatmapLayer, PolygonLayer, ConvexHullLayer, VoronoiLayer, GoalAngleLayer, FlowLayer, FlowBin, PitchDimensions, Viewport, PixelTransform } from '@pitchkit/core';
+import { PitchTypeId, Orientation, CropWindow, ViewportPadding, PitchAppearance, ScatterLayer, AnnotateLayer, ArrowsLayer, CometLayer, HeatmapLayer, PositionalHeatmapLayer, HexbinLayer, KdeLayer, PolygonLayer, ConvexHullLayer, VoronoiLayer, GoalAngleLayer, FlowLayer, FlowBin, PitchDimensions, Viewport, PixelTransform } from '@pitchkit/core';
 
 interface PitchProps {
     type: PitchTypeId;
@@ -78,26 +78,59 @@ interface HeatmapProps<T> extends Omit<HeatmapLayer<T>, "type"> {
     style?: CSSProperties;
 }
 /**
- * Client-only `<canvas>` heatmap, painted imperatively via core's
- * `renderHeatmapLayersToCanvas` in an effect. Unlike the SVG layer
- * components, this can't be re-emitted as JSX — Canvas has no declarative
- * JSX equivalent, and dense raster data is exactly the case core's hybrid
- * SVG+Canvas architecture (PRD §8.1) reserves Canvas for. The `<canvas>`
- * itself renders server-side (empty), but its pixels only appear after the
- * client effect runs — a documented client-only boundary.
+ * Client-only `<canvas>` heatmap: bins `data` into a uniform
+ * `binsX` x `binsY` grid and colours each cell by count (or summed
+ * `weight`). See `DensityCanvas` for why every Canvas layer is painted
+ * imperatively rather than re-emitted as JSX.
+ */
+declare function Heatmap<T>({ className, style, ...layerProps }: HeatmapProps<T>): react.JSX.Element;
+
+interface PositionalHeatmapProps<T> extends Omit<PositionalHeatmapLayer<T>, "type"> {
+    className?: string;
+    style?: CSSProperties;
+}
+/**
+ * Client-only `<canvas>` heatmap binned into Juego de Posición zones —
+ * mplsoccer's `bin_statistic_positional` + `heatmap_positional`. Same
+ * aggregation as `<Heatmap>`, but the cells come from the pitch markings
+ * (penalty areas, six-yard boxes, halfway line) rather than a uniform
+ * grid, which is what makes zone-to-zone comparisons meaningful to an
+ * analyst reading positional play.
  *
- * Wrapped in `<foreignObject>` since a raw `<canvas>` can't be a direct
- * child of `<svg>` — this keeps the heatmap inside the same SVG tree as
- * the pitch and every other layer, rather than needing a second,
- * separately-positioned DOM element the way the vanilla-JS core example
- * demo has to (core has no JSX to lean on there).
+ * Pass `stroke` to outline the zones — off by default, since the
+ * boundaries compete with the pitch markings they're derived from.
+ */
+declare function PositionalHeatmap<T>({ className, style, ...layerProps }: PositionalHeatmapProps<T>): react.JSX.Element;
+
+interface HexbinProps<T> extends Omit<HexbinLayer<T>, "type"> {
+    className?: string;
+    style?: CSSProperties;
+}
+/**
+ * Client-only `<canvas>` hexagonal density — mplsoccer's `hexbin`.
+ * Hexagons pack more evenly than squares (every neighbour is equidistant),
+ * so dense touch/event data reads with less of the axis-aligned banding a
+ * rectangular `<Heatmap>` shows. Empty hexagons aren't drawn at all, so
+ * the pitch stays visible wherever there's no data.
+ */
+declare function Hexbin<T>({ className, style, ...layerProps }: HexbinProps<T>): react.JSX.Element;
+
+interface KDEProps<T> extends Omit<KdeLayer<T>, "type"> {
+    className?: string;
+    style?: CSSProperties;
+}
+/**
+ * Client-only `<canvas>` kernel density estimate — mplsoccer's `kdeplot`.
+ * Unlike the binned layers, each point spreads influence over its
+ * neighbourhood, so the result is a continuous surface rather than a grid
+ * of cells, and low-density areas fade out instead of being filled with
+ * `colorMin`.
  *
- * No effect dependency array (runs after every render) rather than
- * enumerating every spread `props` field plus `dimensions`/`viewport` —
- * repainting a canvas is cheap and idempotent, so this avoids a fragile,
- * easily-stale dependency list.
+ * `bandwidth` controls the smoothing radius in provider units; leave it
+ * unset to let Silverman's rule of thumb pick one per axis from the data's
+ * own spread.
  */
-declare function Heatmap<T>({ className, style, ...layerProps }: HeatmapProps<T>): react.JSX.Element;
+declare function KDE<T>({ className, style, ...layerProps }: KDEProps<T>): react.JSX.Element;
 
 interface PolygonProps<T> extends Omit<PolygonLayer<T>, "type"> {
     tooltip?: (d: T, i: number) => ReactNode;
@@ -175,4 +208,4 @@ interface PitchContextValue {
  */
 declare function usePitch(): Pick<PitchContextValue, "dimensions" | "viewport" | "transform">;
 
-export { Annotate, type AnnotateProps, Arrows, type ArrowsProps, Comet, type CometProps, ConvexHull, type ConvexHullProps, Flow, type FlowProps, GoalAngle, type GoalAngleProps, Heatmap, type HeatmapProps, Pitch, type PitchProps, Polygon, type PolygonProps, Scatter, type ScatterProps, type TooltipState, VerticalPitch, Voronoi, type VoronoiProps, usePitch };
+export { Annotate, type AnnotateProps, Arrows, type ArrowsProps, Comet, type CometProps, ConvexHull, type ConvexHullProps, Flow, type FlowProps, GoalAngle, type GoalAngleProps, Heatmap, type HeatmapProps, Hexbin, type HexbinProps, KDE, type KDEProps, Pitch, type PitchProps, Polygon, type PolygonProps, PositionalHeatmap, type PositionalHeatmapProps, Scatter, type ScatterProps, type TooltipState, VerticalPitch, Voronoi, type VoronoiProps, usePitch };