@johnmorrisdotca/kyogijo-stadiums 0.0.0-stage → 0.4.0

package/dist/charts.soccer.d.ts

@@ -0,0 +1,43 @@
+import type { GoalMouth, GoalMouthOptions, SoccerChart, SoccerShot, SoccerShotOptions } from "./charts.types.ts";
+import { keyItems } from "./charts.ts";
+/**
+ * A shot map for soccer: each shot on the pitch (all of it, or the half the shots attack) in a data provider's own numbers, sized by its expected
+ * goals, a goal a filled star and the rest open marks (a save a circle, a miss an x, a block a triangle, the post a diamond), with the expected-goals
+ * total, a key and a table. `goalMouth()` of the result is the goal-mouth view of the same shots.
+ * @example
+ * ```ts
+ * import { soccerShotMap } from "@johnmorrisdotca/kyogijo-stadiums/charts";
+ * const chart = soccerShotMap(
+ *   [
+ *     { x: 104, y: 36, outcome: "goal", xg: 0.31, goalY: -1.2, goalZ: 0.6 },
+ *     { x: 98, y: 50, outcome: "saved", xg: 0.08, goalY: 2.4, goalZ: 1.1 },
+ *     { x: 90, y: 30, outcome: "missed", xg: 0.04, goalY: 5, goalZ: 0.5 },
+ *   ],
+ *   { provider: "statsbomb", half: true, goalUnit: "yd" },
+ * );
+ * console.log(chart.totals.shots, chart.totals.goals, chart.totals.xg, chart.options.half);
+ * console.log(chart.goalMouth().svg.startsWith("<svg"), chart.goalMouth().placed);
+ * // 3 1 0.43 right
+ * // true 3
+ * ```
+ */
+export declare function soccerShotMap(shots: readonly SoccerShot[], options?: SoccerShotOptions): SoccerChart & {
+    key: ReturnType<typeof keyItems>;
+};
+/**
+ * The goal-mouth view of soccer shots: a small drawing of the goal frame seen from the front (the shooter's left on the left), with where each shot
+ * crossed the goal line, across from the centre of the goal (`goalY`, positive to the shooter's right) and up from the ground (`goalZ`). A shot wide
+ * or high of the frame is drawn beside or above it; a block has no place across the goal and is left out, and the count says how many were.
+ * @example
+ * ```ts
+ * import { soccerGoalMouth } from "@johnmorrisdotca/kyogijo-stadiums/charts";
+ * const view = soccerGoalMouth([
+ *   { x: 100, y: 40, outcome: "goal", goalY: 0.8, goalZ: 1.9, xg: 0.2 },
+ *   { x: 90, y: 40, outcome: "missed", goalY: -4.6, goalZ: 1.2 },
+ *   { x: 85, y: 30, outcome: "blocked" },
+ * ]);
+ * console.log(view.placed, view.skipped, view.svg.includes("Goal mouth"));
+ * // 2 1 true
+ * ```
+ */
+export declare function soccerGoalMouth(shots: readonly SoccerShot[], options?: GoalMouthOptions): GoalMouth;

package/dist/charts.soccer.js

@@ -0,0 +1,191 @@
+// The soccer shot map and the goal-mouth view. The map is shots on a pitch (all of it, or the half the shots attack) in a data provider's own
+// numbers, sized by expected goals; the goal mouth is a small drawing of the goal frame seen from the front, with where each shot crossed the goal line.
+// The ideas are those of mplsoccer's shot maps and goal-mouth plots (MIT); no code of it, nor of sportypy or sportyR (GPL), is used.
+import { drawingId } from "./common.js";
+import { esc, el, num } from "./format.js";
+import { layerTable, renderLayers } from "./layers.js";
+import { outlineOf } from "./outline.js";
+import { KYOGIJO_BASE_STYLE } from "./style.js";
+import { fill } from "./strings.js";
+import { FEET_PER_METRE } from "./geometry.js";
+import { SOCCER } from "./surfaces/soccer-spec.js";
+import { VERSION } from "./version.js";
+import { assemble, clean, countOutcomes, describeCounts, drawingOptions, frameOf, fromOf, hasPlace, isNum, keyItems, keyLayers, languageOf, round, teamTotals, wordsOf } from "./charts.js";
+const LOOKS = {
+    goal: { shape: "star", scale: 1.35 },
+    saved: { hollow: true },
+    missed: { shape: "x", hollow: true },
+    blocked: { shape: "triangle", hollow: true },
+    post: { shape: "diamond", hollow: true },
+};
+const ORDER = ["goal", "saved", "post", "missed", "blocked"];
+const METRES = { m: 1, yd: 0.9144, ft: 0.3048 };
+/** A shot's outcome word: its own, `goal` for a goal, else `shot`. */
+const outcomeOf = (s) => (s.goal === true ? "goal" : typeof s.outcome === "string" && s.outcome !== "" ? s.outcome.toLowerCase() : "shot");
+/** The key's entries for the outcomes present, goals first. */
+function entriesOf(counts, labels) {
+    const present = [...counts.keys()].filter((k) => k !== "");
+    return [...ORDER.filter((k) => present.includes(k)), ...present.filter((k) => !ORDER.includes(k))].map((k) => ({ label: labels[k] ?? k, outcome: k }));
+}
+/**
+ * A shot map for soccer: each shot on the pitch (all of it, or the half the shots attack) in a data provider's own numbers, sized by its expected
+ * goals, a goal a filled star and the rest open marks (a save a circle, a miss an x, a block a triangle, the post a diamond), with the expected-goals
+ * total, a key and a table. `goalMouth()` of the result is the goal-mouth view of the same shots.
+ * @example
+ * ```ts
+ * import { soccerShotMap } from "@johnmorrisdotca/kyogijo-stadiums/charts";
+ * const chart = soccerShotMap(
+ *   [
+ *     { x: 104, y: 36, outcome: "goal", xg: 0.31, goalY: -1.2, goalZ: 0.6 },
+ *     { x: 98, y: 50, outcome: "saved", xg: 0.08, goalY: 2.4, goalZ: 1.1 },
+ *     { x: 90, y: 30, outcome: "missed", xg: 0.04, goalY: 5, goalZ: 0.5 },
+ *   ],
+ *   { provider: "statsbomb", half: true, goalUnit: "yd" },
+ * );
+ * console.log(chart.totals.shots, chart.totals.goals, chart.totals.xg, chart.options.half);
+ * console.log(chart.goalMouth().svg.startsWith("<svg"), chart.goalMouth().placed);
+ * // 3 1 0.43 right
+ * // true 3
+ * ```
+ */
+export function soccerShotMap(shots, options = {}) {
+    if (!Array.isArray(shots))
+        throw new TypeError("shots is a list of shots");
+    const language = languageOf(options);
+    const all = wordsOf(language);
+    const w = all.charts;
+    const provider = options.provider ?? "international";
+    const frame = frameOf(provider, "international");
+    const half = options.half === true ? "right" : options.half === "left" || options.half === "right" ? options.half : undefined;
+    const o = drawingOptions("soccer", options, w.titleSoccer, {
+        ...(typeof provider === "string" ? { pitchType: provider } : {}),
+        ...(half === undefined ? {} : { half }),
+        ...(options.pitch === undefined ? {} : { pitch: options.pitch }),
+        ...(options.ground === undefined ? {} : { ground: options.ground }),
+    });
+    const attacking = options.attacking === "left" ? "left" : undefined;
+    const where = clean({ from: fromOf(typeof provider === "object" ? provider : undefined, frame), attacking });
+    const data = shots.map((s) => clean({ x: s.x, y: s.y, outcome: outcomeOf(s), value: s.xg, team: s.team, title: s.title }));
+    const { counts, placed: count, skipped } = countOutcomes(data);
+    const hasXg = data.some((d) => isNum(d.value));
+    const sized = options.xg === false ? false : hasXg;
+    const xgMax = isNum(options.xgMax) && options.xgMax > 0 ? options.xgMax : 0.8;
+    const labels = { goal: w.goal, saved: w.saved, missed: w.missedNet, blocked: w.blocked, shot: w.shot, post: w.post };
+    const entries = entriesOf(counts, labels);
+    const style = { outcomes: LOOKS, opacity: 0.92, ...(sized ? { size: { domain: [0, xgMax], range: [3.2, 13] } } : { scale: 1.5 }) };
+    const xg = hasXg ? round(data.reduce((sum, d) => sum + (hasPlace(d) && isNum(d.value) ? d.value : 0), 0), 2) : null;
+    const layers = [];
+    const description = [describeCounts(entries, counts, all), sized ? w.sizeNote : ""].filter(Boolean).join(all.said.gap);
+    layers.push(clean({ kind: "points", id: "shots", name: w.shots, description: description === "" ? undefined : description, ...where, data, style }));
+    const extras = [...(sized ? [w.sizeXg] : []), ...(xg === null ? [] : [fill(w.xgTotal, { n: xg })])];
+    if (options.key !== false) {
+        const { box } = outlineOf(o);
+        const place = half === undefined ? {} : { x: half === "right" ? box.x + box.w / 2 : box.x, w: box.w / 2 };
+        layers.push(...keyLayers(o, entries, LOOKS, all, extras, place));
+    }
+    const goals = counts.get("goal") ?? 0;
+    const totals = { shots: count, goals, xg, skipped, teams: teamTotals(data) };
+    const summary = xg === null ? fill(w.sumShots, { shots: count, goals }) : fill(w.sumShotsXg, { shots: count, goals, xg });
+    const base = assemble(o, layers, { title: w.titleSoccer, summary, totals });
+    const chart = {
+        ...base,
+        key: keyItems(entries, LOOKS),
+        goalMouth: (mouth = {}) => soccerGoalMouth(shots, { language, unit: options.goalUnit, xg: sized, xgMax, theme: options.surface?.theme, style: options.surface?.style, id: options.id === undefined ? undefined : `${options.id}-goal`, ...mouth }),
+    };
+    return chart;
+}
+/**
+ * The goal-mouth view of soccer shots: a small drawing of the goal frame seen from the front (the shooter's left on the left), with where each shot
+ * crossed the goal line, across from the centre of the goal (`goalY`, positive to the shooter's right) and up from the ground (`goalZ`). A shot wide
+ * or high of the frame is drawn beside or above it; a block has no place across the goal and is left out, and the count says how many were.
+ * @example
+ * ```ts
+ * import { soccerGoalMouth } from "@johnmorrisdotca/kyogijo-stadiums/charts";
+ * const view = soccerGoalMouth([
+ *   { x: 100, y: 40, outcome: "goal", goalY: 0.8, goalZ: 1.9, xg: 0.2 },
+ *   { x: 90, y: 40, outcome: "missed", goalY: -4.6, goalZ: 1.2 },
+ *   { x: 85, y: 30, outcome: "blocked" },
+ * ]);
+ * console.log(view.placed, view.skipped, view.svg.includes("Goal mouth"));
+ * // 2 1 true
+ * ```
+ */
+export function soccerGoalMouth(shots, options = {}) {
+    if (!Array.isArray(shots))
+        throw new TypeError("shots is a list of shots");
+    const language = languageOf(options);
+    const all = wordsOf(language);
+    const w = all.charts;
+    const unit = options.unit === "yd" || options.unit === "ft" ? options.unit : "m";
+    const k = METRES[unit];
+    const goalW = options.goal !== undefined && options.goal.width > 0 ? options.goal.width : SOCCER.goalWidth;
+    const goalH = options.goal !== undefined && options.goal.height > 0 ? options.goal.height : SOCCER.goalHeight;
+    // The view, in metres: the goal frame with room beside it, above it and a strip of ground beneath.
+    const viewW = goalW * 1.7;
+    const ground = goalH * 0.22;
+    const viewH = goalH * 2.1;
+    const frame = {
+        name: "goal-mouth",
+        title: "Goal mouth, seen from the front: across from the centre (positive to the shooter's right) and the height",
+        sport: "soccer",
+        unit: "m",
+        x: [-viewW / 2, viewW / 2],
+        y: [0, viewH - ground],
+        origin: "the centre of the goal on the ground",
+        yDirection: "up",
+        size: "variable",
+        ends: "none",
+        landmarks: ({ length, width }) => ({ x: [[-viewW / 2, 0], [viewW / 2, length]], y: [[0, width - ground * FEET_PER_METRE], [viewH - ground, 0]] }),
+        source: "Kyogijo",
+    };
+    const id = options.id === undefined ? undefined : options.id;
+    const surface = { sport: "soccer", pitch: { length: viewW, width: viewH, unit: "m" }, units: "m", language, ...(id === undefined ? {} : { id }), margin: 0 };
+    const rows = shots.map((s) => clean({ x: isNum(s.goalY) ? round(s.goalY * k, 3) : null, y: isNum(s.goalZ) ? round(s.goalZ * k, 3) : null, outcome: outcomeOf(s), value: s.xg, team: s.team, title: s.title }));
+    const { counts, placed: placedCount, skipped } = countOutcomes(rows);
+    const hasXg = rows.some((r) => isNum(r.value));
+    const sized = options.xg === false ? false : options.xg === true || hasXg;
+    const xgMax = isNum(options.xgMax) && options.xgMax > 0 ? options.xgMax : 0.8;
+    const labels = { goal: w.goal, saved: w.saved, missed: w.missedNet, blocked: w.blocked, shot: w.shot, post: w.post };
+    const entries = entriesOf(counts, labels);
+    const style = { outcomes: LOOKS, opacity: 0.92, ...(sized ? { size: { domain: [0, xgMax], range: [0.25, 0.8] } } : { size: 0.45 }) };
+    const layer = clean({ kind: "points", id: "goal-shots", name: w.shots, description: describeCounts(entries, counts, all), from: frame, units: "m", data: rows, style, clip: "none" });
+    const layers = [layer];
+    const rendered = renderLayers(surface, layers, false);
+    const F = FEET_PER_METRE;
+    const x0 = ((viewW - goalW) / 2) * F;
+    const x1 = x0 + goalW * F;
+    const yb = (viewH - ground) * F;
+    const yt = yb - goalH * F;
+    const net = [];
+    const step = 0.45 * F;
+    for (let x = x0 + step; x < x1 - 0.01; x += step)
+        net.push(`M${num(x)} ${num(yt)}V${num(yb)}`);
+    for (let y = yt + step; y < yb - 0.01; y += step)
+        net.push(`M${num(x0)} ${num(y)}H${num(x1)}`);
+    const art = el("rect", { class: "ky-surface", x: 0, y: 0, width: viewW * F, height: viewH * F }) +
+        el("rect", { class: "ky-zone", x: x0, y: yt, width: goalW * F, height: goalH * F }) +
+        el("path", { class: "ky-goal-net", d: net.join(""), "stroke-width": 0.12 }) +
+        el("path", { class: "ky-line", d: `M0 ${num(yb)}H${num(viewW * F)}`, "stroke-width": 0.5 }) +
+        el("path", { class: "ky-goal", d: `M${num(x0)} ${num(yb)}V${num(yt)}H${num(x1)}V${num(yb)}`, "stroke-width": 0.75, "stroke-linejoin": "round" });
+    const gid = drawingId(surface);
+    const title = options.title ?? w.titleGoal;
+    const description = [fill(w.goalDesc, { w: round(goalW, 2), h: round(goalH, 2) }), rendered.summaries.length === 0 ? "" : `${all.layers.data}${all.said.colon}${rendered.summaries.join(all.said.gap)}`].filter(Boolean).join(all.said.gap);
+    const theme = options.theme === "light" || options.theme === "dark" ? options.theme : undefined;
+    const svg = el("svg", {
+        xmlns: "http://www.w3.org/2000/svg",
+        class: `kyogijo ky-soccer ky-goal-mouth${options.className === undefined || options.className.replace(/[^\w -]/g, "").trim() === "" ? "" : ` ${options.className.replace(/[^\w -]/g, "").trim()}`}`,
+        viewBox: `0 0 ${num(viewW * F)} ${num(viewH * F)}`,
+        role: "img",
+        "aria-labelledby": `${gid}-t ${gid}-d`,
+        "data-sport": "soccer",
+        "data-theme": theme,
+        "data-version": VERSION,
+    }, `<title id="${gid}-t">${esc(title)}</title><desc id="${gid}-d">${esc(description)}</desc>${options.style === "none" ? "" : `<style>${KYOGIJO_BASE_STYLE}</style>`}${art}${rendered.svg}`);
+    return {
+        svg,
+        layers,
+        placed: placedCount,
+        skipped,
+        table: (tableOptions = {}) => layerTable(layers, { ...tableOptions, language, surface }),
+    };
+}

package/dist/charts.types.d.ts

@@ -0,0 +1,396 @@
+import type { Frame } from "./frames.ts";
+import type { HeatRamp } from "./heat.types.ts";
+import type { Layer, LayerTeam, MarkShape, TableOptions } from "./layers.types.ts";
+import type { SoccerProviderId } from "./surfaces/soccer-providers.ts";
+import type { Language, SurfaceOptions } from "./types.ts";
+import type { Unit } from "./units.ts";
+/** What every chart gives back: the layers and the drawing options to put them on, a sentence, the totals, and the ways to draw them. */
+export interface Chart<Totals = Record<string, never>> {
+    /** The drawing's options: the sport, the layers, the language, a title and what the chart needs of the surface (the park and the season of a spray chart, the half of a pitch). Pass them to `drawKyogijo`, `drawSurface`, `mountKyogijo` or `kyogijoProps`; change any of them first if you like. */
+    options: SurfaceOptions;
+    /** The layers, the same list as `options.layers`: the zones under the marks, the marks, and a key. They are plain data, so a layer can be changed, taken out or followed by layers of your own. */
+    layers: Layer[];
+    /** The chart's accessible name, in the chart's language. */
+    title: string;
+    /** What the chart shows, in a sentence or two, for a caption. */
+    summary: string;
+    /** The numbers behind it: counts, percentages and expected goals, and the zones with theirs. */
+    totals: Totals;
+    /** The drawing as an SVG string: `drawKyogijo({ ...options, ...extra })`. */
+    draw(extra?: Partial<SurfaceOptions>): string;
+    /** One HTML table for each layer that holds data (not the key), with the zones as rows. The table that stands for the drawing for a screen reader. */
+    table(options?: Omit<TableOptions, "surface" | "language">): string;
+}
+/** One entry of a chart's key: a mark and what it means. A chart lists its own in `key`. */
+export interface KeyItem {
+    /** The outcome the mark stands for (`made`, `goal`). */
+    outcome: string;
+    /** What the mark is called, in the chart's language. */
+    label: string;
+    shape: MarkShape;
+    /** Drawn open (a miss, a save) and not filled. */
+    hollow: boolean;
+}
+/** The options every chart takes. */
+export interface ChartOptions {
+    /** The language of the chart's words: its title, its key, the labels of its zones and its table. English by default. */
+    language?: Language;
+    /** A prefix for the ids inside the drawing. Made from the chart when missing, so that two charts on a page do not share ids. */
+    id?: string;
+    /** Draw the key (what each mark is) in the margin above the surface. On by default. */
+    key?: boolean;
+    /** Draw the colour bar of the zones, hexagons or cells. On by default. */
+    legend?: boolean;
+    /** The colour ramp of the zones, hexagons or cells: a built-in name, a list of stops or `{ light, dark }`. */
+    ramp?: HeatRamp;
+    /** Options of the drawing laid over the chart's own: the theme, the orientation, `colors`, `style: "none"`, `className`. */
+    surface?: Partial<SurfaceOptions>;
+}
+/** A shot as stats.nba.com's shot chart gives it: `LOC_X` and `LOC_Y` and whether it went in. */
+export interface NbaShot {
+    x: number | null;
+    y: number | null;
+    /** True for a shot that went in. Or give `outcome`. */
+    made?: boolean;
+    /** `made` or `missed`, in place of `made`. */
+    outcome?: "made" | "missed" | (string & {});
+    /** A number to carry with the shot (a distance, a value over average). */
+    value?: number | null;
+    team?: LayerTeam;
+    /** The tooltip of the mark and its line in the table. */
+    title?: string;
+}
+/** What `nbaShotChart` takes. */
+export interface NbaShotOptions extends ChartOptions {
+    /** The frame the shots are in: `nba-stats` (the default), or another frame of the court. */
+    from?: Frame | string;
+    /** The basket the shots were taken at: `right` (the default; the shot chart puts every shot at the right basket) or `left`. */
+    end?: "left" | "right";
+    /** Count the shots into the six shot zones (restricted area, in the paint, mid-range, both corner threes, above the break) and colour each by its field-goal percentage. On by default. */
+    zones?: boolean;
+    /** Draw each shot as a mark: filled when made, an open x when missed. On by default. */
+    marks?: boolean;
+    /** The league's field-goal percentage (46 for 46 percent). With it the zones are coloured by how far they are above or below it, on a diverging ramp; without it, by the percentage alone. */
+    league?: number;
+    /** A zone with fewer shots than this is left uncoloured (a percentage from two shots says little). 3 by default. */
+    minShots?: number;
+    /** Write each zone's percentage and its made over taken (`13/31`). On by default. */
+    labels?: boolean;
+}
+/** One zone of a chart: its name, the shots in it and the share that went in. */
+export interface ZoneTotal {
+    id: string;
+    name: string;
+    taken: number;
+    made: number;
+    /** The percent that went in, one decimal, or null for a zone with no shots. */
+    percent: number | null;
+}
+/** The numbers behind an NBA shot chart. */
+export interface NbaTotals {
+    shots: number;
+    made: number;
+    /** The percent that went in, one decimal, or null with no shots. */
+    percent: number | null;
+    /** Rows left out for want of a place. */
+    skipped: number;
+    zones: ZoneTotal[];
+}
+/** A shot as the NHL's play-by-play gives it. */
+export interface NhlShot {
+    x: number | null;
+    y: number | null;
+    /** `goal`, `saved` (a shot on goal), `missed`, `blocked`, or `shot` for an attempt of no known result. */
+    outcome?: "goal" | "saved" | "missed" | "blocked" | "shot" | (string & {});
+    /** True for a goal, in place of `outcome`. */
+    goal?: boolean;
+    /** The chance the shot had of scoring, 0 to 1. */
+    xg?: number | null;
+    team?: LayerTeam;
+    title?: string;
+}
+/** What `nhlShotMap` takes. */
+export interface NhlShotOptions extends ChartOptions {
+    /** The frame the shots are in: `nhl-api` (the default), `hockeytech`, or another frame of the rink. */
+    from?: Frame | string;
+    /** Turn the shots at the left end a half turn so that all of them are at the right end: one half of the rink, every shot. Off by default. */
+    fold?: boolean;
+    /** `xg` sizes each mark by its chance of scoring (the area of the mark follows `xg`); `none` draws them all alike. `xg` by default when any shot has an `xg`. */
+    sizeBy?: "xg" | "none";
+    /** The `xg` that is the largest mark. 0.5 by default; a larger one is drawn as large. */
+    xgMax?: number;
+    /** Count the shots into the rink's slot zones (`nhl-slot`), or into home plate (`nhl-home-plate`). `true` is the slot. Off by default. */
+    zones?: boolean | "nhl-slot" | "nhl-home-plate";
+    /** Count the shots into hexagons (`true`, or their size in feet). Off by default; with `zones` as well, the zones win. */
+    hexbin?: boolean | {
+        size?: number;
+    };
+    /** What the zones or hexagons show: `shots` (the count, the default), `xg` (the sum of the chances) or `goals` (the percent that were goals). */
+    statistic?: "shots" | "xg" | "goals";
+    /** The end the shots attack, in the frame's numbers, when they are not folded: leave out for shots at both ends. */
+    attacking?: "left" | "right";
+    /** Draw the marks. On by default. */
+    marks?: boolean;
+    /** Write the numbers on the zones. On by default for zones. */
+    labels?: boolean;
+}
+/** The numbers behind a hockey shot map. */
+export interface NhlTotals {
+    shots: number;
+    goals: number;
+    /** The sum of the shots' chances, two decimals, or null when no shot has one. */
+    xg: number | null;
+    skipped: number;
+    /** The zones, when the chart has them. */
+    zones: ZoneTotal[];
+    /** Shots and goals by team, when the shots name one. */
+    teams: Record<string, {
+        shots: number;
+        goals: number;
+        xg: number | null;
+    }>;
+}
+/** A ball in play. Give `x` and `y` in the frame, or for Retrosheet a `zone` (the location code, `8D`). */
+export interface Ball {
+    x?: number | null;
+    y?: number | null;
+    /** A Retrosheet hit-location code in place of `x` and `y`. */
+    zone?: string;
+    /** What happened: `single`, `double`, `triple`, `home run`, `out`, or the words of Statcast's `events` (`home_run`, `field_out`) or the usual short forms (`1B`, `HR`). Any other word is drawn as it is. */
+    type?: string;
+    /** A number to carry with the ball (exit velocity, distance). */
+    value?: number | null;
+    team?: LayerTeam;
+    title?: string;
+}
+/** What `mlbSprayChart` takes. */
+export interface MlbSprayOptions extends ChartOptions {
+    /** The frame the balls are in: `mlbam` (the default; Statcast's `hc_x` and `hc_y`), `retrosheet` (feet from home plate, or zone codes), or another frame of the field. */
+    from?: Frame | string;
+    /** The ballpark: a key of `PARKS`, past parks included. The generic field when missing. */
+    park?: string;
+    /** The season: a past park is drawn with the fence it had in it (`polo-grounds` in 1915). */
+    year?: number;
+    /** The side the batter bats from, `R` (the default) or `L`: it says which side of the field is pull. `none` names the thirds left, centre and right field. */
+    bats?: "L" | "R" | "none";
+    /** Count the balls into the spray zones (`baseball-spray`, pull, centre and opposite by infield and outfield; `true` is this) or Retrosheet's sectors (`baseball-retrosheet`). Off by default. */
+    zones?: boolean | "baseball-spray" | "baseball-retrosheet";
+    /** What the zones show: `share` of all the balls (the default), `count`, or the `hit-rate` (the percent that were hits). */
+    statistic?: "share" | "count" | "hit-rate";
+    /** The ground round the fence, in feet. A ball beyond the fence is drawn there, over the ground round it; 40 by default so that there is room. A ball farther than the margin is drawn at its edge. */
+    margin?: number;
+    /** Draw the marks. On by default. */
+    marks?: boolean;
+    /** Write the numbers on the zones. On by default for zones. */
+    labels?: boolean;
+}
+/** The numbers behind a spray chart. */
+export interface MlbTotals {
+    balls: number;
+    /** Balls by type: `single`, `double`, `triple`, `home run`, `out`, and any other word given. */
+    types: Record<string, number>;
+    /** Balls that came down beyond the fence of the park in that season. */
+    beyondFence: number;
+    skipped: number;
+    /** The zones, when the chart has them: the balls in each and, for a hit rate, the hits. */
+    zones: ZoneTotal[];
+}
+/** A pass. The destination is `x` and `y`; the passer's place is `fromX` and `fromY` when you have it. */
+export interface NflPass {
+    /** Where the ball came down or was caught, in the frame. */
+    x: number | null;
+    y: number | null;
+    /** Where it was thrown from. With it a pass can be drawn as an arrow. */
+    fromX?: number | null;
+    fromY?: number | null;
+    /** `complete`, `incomplete`, `touchdown` or `interception`. */
+    outcome?: "complete" | "incomplete" | "touchdown" | "interception" | (string & {});
+    /** The yards the ball travelled past the line of scrimmage. Worked out from the destination and `los` when missing. */
+    airYards?: number | null;
+    team?: LayerTeam;
+    title?: string;
+}
+/** What `nflPassChart` takes. */
+export interface NflPassOptions extends ChartOptions {
+    /** The frame the passes are in: `nfl-tracking` (the default; yards, the end zones counted) or another frame of the field. */
+    from?: Frame | string;
+    /** The line of scrimmage, in the frame's numbers along the field (60 for midfield in `nfl-tracking`). Midfield by default. */
+    los?: number;
+    /** The way the offence goes in the frame's numbers: `right` (the default) or `left`. The chart is drawn with the offence going right. */
+    direction?: "left" | "right";
+    /** Count the passes into the pass grid (short and deep by left, middle and right) and colour each by its completion percentage. On by default. */
+    zones?: boolean;
+    /** Draw each pass from its passer to its destination as an arrow (dashed when incomplete), for passes that have `fromX` and `fromY`. Off by default. */
+    arrows?: boolean;
+    /** Draw the destinations as marks. On by default. */
+    marks?: boolean;
+    /** Draw the line of scrimmage. On by default. */
+    line?: boolean;
+    /** Write each zone's percentage and its completions over attempts. On by default. */
+    labels?: boolean;
+    /** A zone with fewer passes than this is left uncoloured. 3 by default. */
+    minPasses?: number;
+}
+/** The numbers behind a pass chart. */
+export interface NflTotals {
+    passes: number;
+    complete: number;
+    touchdowns: number;
+    interceptions: number;
+    /** The percent that were caught (touchdowns included), one decimal, or null with no passes. */
+    percent: number | null;
+    /** The mean air yards of the passes that have a place, or null. */
+    airYards: number | null;
+    skipped: number;
+    zones: ZoneTotal[];
+}
+/** A shot. The place is in the provider's frame; `goalY` and `goalZ` say where it crossed the goal line. */
+export interface SoccerShot {
+    x: number | null;
+    y: number | null;
+    /** `goal`, `saved`, `blocked`, `missed` or `post`. */
+    outcome?: "goal" | "saved" | "blocked" | "missed" | "post" | (string & {});
+    /** True for a goal, in place of `outcome`. */
+    goal?: boolean;
+    /** Expected goals, 0 to 1. */
+    xg?: number | null;
+    /** Where the shot crossed the goal line, for the goal-mouth view: across the goal from its centre, positive to the shooter's right, in `goalUnit` (metres by default). */
+    goalY?: number | null;
+    /** How high above the ground it crossed the goal line, in `goalUnit`. */
+    goalZ?: number | null;
+    team?: LayerTeam;
+    title?: string;
+}
+/** What `soccerShotMap` takes. */
+export interface SoccerShotOptions extends ChartOptions {
+    /** The provider the shots are in (`opta`, `statsbomb`, `wyscout`, ...): the pitch is drawn in its numbers and the marks use them. Or a `Frame` of your own, for a pitch drawn as usual. `international` (metres) by default. */
+    provider?: SoccerProviderId | Frame;
+    /** Show only the half the shots attack: `true` for the right half (the default for `attacking: "right"`), `"left"` or `"right"` to choose. All of the pitch when false or missing. */
+    half?: boolean | "left" | "right";
+    /** The end the shots attack, in the provider's numbers: `right` (the default; each team attacks left to right) or `left`. */
+    attacking?: "left" | "right";
+    /** Size each mark by its expected goals (`xg`). On by default when any shot has one. */
+    xg?: boolean;
+    /** The `xg` that is the largest mark. 0.8 by default. */
+    xgMax?: number;
+    /** The pitch: a preset or a size, as `pitch` of a drawing. */
+    pitch?: SurfaceOptions["pitch"];
+    /** The ground, as `ground` of a drawing. */
+    ground?: string;
+    /** The unit of `goalY` and `goalZ`: `m` (the default), `yd` or `ft`. */
+    goalUnit?: "m" | "yd" | "ft";
+}
+/** The numbers behind a soccer shot map. */
+export interface SoccerTotals {
+    shots: number;
+    goals: number;
+    /** The sum of the shots' expected goals, two decimals, or null when none has one. */
+    xg: number | null;
+    skipped: number;
+    teams: Record<string, {
+        shots: number;
+        goals: number;
+        xg: number | null;
+    }>;
+}
+/** The options of the goal-mouth view. */
+export interface GoalMouthOptions {
+    language?: Language;
+    id?: string;
+    /** The unit of `goalY` and `goalZ`: `m` (the default), `yd` or `ft`. */
+    unit?: "m" | "yd" | "ft";
+    /** The size of the goal in metres: the Laws' 7.32 by 2.44 by default. */
+    goal?: {
+        width: number;
+        height: number;
+    };
+    /** Size the marks by expected goals. On when any shot has one. */
+    xg?: boolean;
+    xgMax?: number;
+    theme?: SurfaceOptions["theme"];
+    style?: SurfaceOptions["style"];
+    className?: string;
+    title?: string;
+}
+/** The goal-mouth view: a small drawing of the goal frame seen from the front, with where each shot crossed the goal line. */
+export interface GoalMouth {
+    /** The drawing as an SVG string. */
+    svg: string;
+    /** The layers of the marks, in the frame of the goal (`x` across from the centre, `y` the height, in metres), if you want to draw them another way. */
+    layers: Layer[];
+    /** The shots that had a place across the goal and the ones that did not. */
+    placed: number;
+    skipped: number;
+    /** The table of the shots with their place across the goal (`x` across from the centre, `y` the height, in metres). */
+    table(options?: Omit<TableOptions, "surface" | "language">): string;
+}
+/** A soccer shot map: the chart, and the goal-mouth view of the same shots. */
+export interface SoccerChart extends Chart<SoccerTotals> {
+    /** The goal-mouth view of the shots that have `goalY` and `goalZ`: a small drawing of the goal frame, seen from the front, with where each shot crossed the goal line. */
+    goalMouth(options?: GoalMouthOptions): GoalMouth;
+}
+/** A stone at rest, as its place on the sheet: feet from the button of the house it was played to (the `curling` frame), x across the sheet (positive to the thrower's right) and y along it (positive towards the back line). */
+export interface CurlingStone {
+    x: number | null;
+    y: number | null;
+    /** The team that threw it: `home` or `away` take the two stone colours (red and yellow by default). */
+    team?: LayerTeam;
+    /** Its number among its team's eight, 1 to 8, written on the stone. */
+    number?: number;
+    /** The tooltip of the stone and its line in the table. Made from the team, the number and the distance when missing. */
+    title?: string;
+}
+/** What `curlingStones` takes. */
+export interface CurlingOptions extends ChartOptions {
+    /** The number of the end, for the title: `6` gives "End 6". */
+    end?: number;
+    /** The team that has the hammer, the last stone of the end. It is named in the summary. */
+    hammer?: "home" | "away";
+    /** The teams' names, for the summary and the stones' tooltips. */
+    names?: {
+        home?: string;
+        away?: string;
+    };
+    /** The house the stones are at: the `left` one (the top house of a tall drawing, the default) or the `right`. */
+    house?: "left" | "right";
+    /** The unit of the stones' places: feet by default. */
+    units?: Unit;
+    /** Write each stone's number on it. On by default, for the stones that have one. */
+    numbers?: boolean;
+}
+/** One stone as the chart judged it. */
+export interface CurlingStoneResult {
+    /** The place of the stone in the list given. */
+    index: number;
+    /** Its centre's distance from the button, in feet. */
+    distance: number;
+    /** In play: it did not touch a sideline, and it stands wholly beyond the hog line and not wholly beyond the back line. */
+    inPlay: boolean;
+    /** Any part of it is within 6 feet of the button (in or touching the house), so that it can score. */
+    inHouse: boolean;
+    /** It scores. */
+    counting: boolean;
+    /** It is the stone nearest the button of those that can score. */
+    shot: boolean;
+}
+/** The numbers behind a curling chart. */
+export interface CurlingTotals {
+    /** Stones with a place. */
+    stones: number;
+    /** In play, and out of play (removed, so not drawn). */
+    inPlay: number;
+    out: number;
+    /** The stones that score, and the points. */
+    counting: number;
+    points: number;
+    /** The team that scores, or `null` for a blank end. */
+    scoring: string | null;
+    /** The shot rock's place in the list given, or `null`. */
+    shot: number | null;
+    /** No one scores: no stone in the house, or the two nearest are as near. */
+    blank: boolean;
+    /** Rows left out for want of a place. */
+    skipped: number;
+    /** Every stone, as judged. */
+    results: CurlingStoneResult[];
+}

package/dist/charts.types.js

@@ -0,0 +1 @@
+export {};

package/dist/colour.d.ts

@@ -0,0 +1,29 @@
+/**
+ * The colour as it may be written into a style attribute, or `undefined`. A hex colour, `rgb()`, `rgba()`, `hsl()`,
+ * `hsla()`, a colour name or `var(--name)` is drawn; anything else is ignored, so nothing from a form or an address
+ * can end the attribute or add a rule.
+ * @example
+ * ```ts
+ * import { safeColour } from "@johnmorrisdotca/kyogijo-stadiums";
+ * console.log(safeColour("#1f5fa8"), safeColour("red;fill:url(x)"));
+ * // #1f5fa8 undefined
+ * ```
+ */
+export declare function safeColour(value: unknown): string | undefined;
+/** The red, green and blue of a colour, when it can be read without a browser (a hex colour, `rgb()` or a common name). */
+export declare function rgbOf(value: string | undefined): [number, number, number] | undefined;
+/** The relative luminance of a colour, 0 (black) to 1 (white). */
+export declare function luminance(rgb: [number, number, number]): number;
+/** White or near-black, whichever reads better on the colour. White when the colour cannot be read. */
+export declare function inkOn(color: string | undefined): string;
+/**
+ * A logo's address as it may be written into an image's `href`, or `undefined`. An `https:` or `http:` address, a
+ * relative path, an image `data:` address, or an SVG document as text (written as an image, which cannot run scripts).
+ * @example
+ * ```ts
+ * import { safeLogo } from "@johnmorrisdotca/kyogijo-stadiums";
+ * console.log(safeLogo("https://example.com/gulls.svg"), safeLogo("javascript:alert(1)"));
+ * // https://example.com/gulls.svg undefined
+ * ```
+ */
+export declare function safeLogo(value: unknown): string | undefined;