@johnmorrisdotca/kyogijo-stadiums 0.4.0 → 0.6.0

package/dist/charts.athletics.js

@@ -0,0 +1,455 @@
+// The athletics data: the lane draw of a race (names and flags on the lanes of its start), its results (places, medals, times, reaction times and splits at the finish and along the lanes), a replay of the
+// race (every runner on the curve of the lane, the stagger as the rules put it), and the attempts of a field event as marks in the sector or the pit with the best mark picked out. Written for this
+// package from the Track and Field Facilities Manual (2019, 2.2.1.6) and Book C2.1's Technical Rules (14, 17, 25 to 38); nothing of any other package is used. The flags are the caller's: an SVG
+// document as text, or an address, as a team's logo is.
+import { assemble, clean, drawingOptions, languageOf, round, wordsOf } from "./charts.js";
+import { athleticsPlan } from "./athletics/plan.js";
+import { raceById, fieldEventById } from "./athletics/events.js";
+import { fieldEventName } from "./athletics/describe.js";
+import { curveAcross } from "./athletics/races.js";
+import { distanceOn, laneRadius, lap, pose } from "./athletics/track.js";
+import { esc } from "./format.js";
+import { fill } from "./strings.js";
+const isNum = (v) => typeof v === "number" && Number.isFinite(v);
+const K = 1 / 0.3048;
+const WORDS = (language) => wordsOf(language).athletics;
+/** A time in seconds as it is written: `9.58`, `1:40.91`, `2:03:59.40`. */
+export function formatTime(seconds, places = 2) {
+    if (!isNum(seconds) || seconds < 0)
+        return "";
+    const r = Math.round(seconds * 10 ** places) / 10 ** places;
+    const h = Math.floor(r / 3600);
+    const m = Math.floor((r - h * 3600) / 60);
+    const s = r - h * 3600 - m * 60;
+    const sec = s.toFixed(places).padStart(places > 0 ? places + 3 : 2, "0");
+    return h > 0 ? `${h}:${String(m).padStart(2, "0")}:${sec}` : m > 0 ? `${m}:${sec}` : s.toFixed(places);
+}
+function raceOf(options) {
+    const id = options.race ?? "400m";
+    if (raceById(id) === undefined)
+        throw new Error(`Unknown race "${String(id)}"`);
+    return id;
+}
+/** The plan of the race's drawing, with its marks, and the marks of the race. */
+function planOf(options, race, surface) {
+    const style = { ...(surface?.athletics ?? {}), races: [race], start: race };
+    const plan = athleticsPlan({ sport: "athletics", league: surface?.league, athletics: style, units: surface?.units, pitch: surface?.pitch, detail: surface?.detail, range: surface?.range });
+    void options;
+    const marks = plan.races.find((r) => r.race.id === race);
+    return { plan, marks };
+}
+const isPortraitSurface = (surface) => surface?.orientation === "portrait";
+function checkEntries(entries, label) {
+    if (!Array.isArray(entries))
+        throw new TypeError(`${label} is a list`);
+    const seen = new Set();
+    for (const e of entries) {
+        if (typeof e !== "object" || e === null || !Number.isInteger(e.lane) || e.lane < 1)
+            throw new TypeError(`${label}: each athlete has a lane, a whole number from 1`);
+        if (seen.has(e.lane))
+            throw new RangeError(`${label}: lane ${e.lane} is given twice`);
+        seen.add(e.lane);
+    }
+}
+/** The drawing's options for an athletics chart: the stadium close up on the start (or the finish), the race marked, whatever the caller laid over it. */
+function surfaceFor(options, title, race, range) {
+    const surface = options.surface ?? {};
+    const style = { races: [race], start: race, ...(surface.athletics ?? {}) };
+    return drawingOptions("athletics", { ...options, surface: { ...(range === undefined ? {} : { range }), ...surface, athletics: style } }, title, {});
+}
+/**
+ * The lane draw of a race: each athlete's name and flag on the lane of the start, behind the lane's number, for the close-up of the start (`range: "start"`, the drawing's default). The positions are the
+ * start lines' as the Manual marks them: the stagger of the 200, 400 and 800 m and the 4 x 400 m, the straight line of the sprints, the curved line of a race run without lanes.
+ * @example
+ * ```ts
+ * import { laneDraw } from "@johnmorrisdotca/kyogijo-stadiums/athletics";
+ * const chart = laneDraw([{ lane: 4, name: "M. Jacobs", country: "ITA" }, { lane: 5, name: "F. Kerley", country: "USA" }], { race: "100m" });
+ * console.log(chart.totals.athletes, chart.title);
+ * // 2 Lane draw, 100 m
+ * ```
+ */
+export function laneDraw(entries, options = {}) {
+    checkEntries(entries, "entries");
+    const race = raceOf(options);
+    const language = languageOf(options);
+    const w = WORDS(language);
+    const info = raceById(race);
+    const raceName = (info?.name[language] ?? race);
+    const title = fill(w.data.draw, { race: raceName });
+    const o = surfaceFor(options, title, race, "start");
+    const { plan, marks } = planOf(options, race, o);
+    const portrait = isPortraitSurface(o);
+    const names = [];
+    const flags = [];
+    const sorted = [...entries].sort((a, b) => a.lane - b.lane);
+    // The number behind each line is a tag, sized to the view, on a bend; on a straight it is painted, 0.85 m tall. The flag and the name follow it back along the lane.
+    const number = plan.digits.find((d) => d.id === "start-number");
+    const tag = number?.tag === true;
+    const unit = number === undefined ? 0.85 : number.h;
+    const numberBack = tag ? unit * 0.78 + 0.35 : unit * 1.2;
+    const numberHalf = tag ? unit * 0.78 : unit * 0.45;
+    const flagSide = 0.9 * (unit / 0.85);
+    const flagAt = numberBack + numberHalf + flagSide / 2 + 0.2;
+    const nameAt = flagAt + flagSide / 2 + 0.3;
+    const nameSize = Math.max(0.45, unit * (tag ? 0.42 : 0.6));
+    for (const e of sorted) {
+        const start = marks.starts.find((s) => s.lane === e.lane);
+        if (start === undefined)
+            continue;
+        const fx = Math.cos(start.heading);
+        const fy = Math.sin(start.heading);
+        const back = (d) => [start.x - fx * d, start.y - fy * d];
+        const [nx, ny] = back(nameAt);
+        names.push(clean({ x: nx, y: ny, text: e.name, anchor: "end", size: nameSize, rotate: portrait ? -90 : 0, title: e.country === undefined ? undefined : `${e.name}, ${e.country}` }));
+        if (e.flag !== undefined) {
+            const [px, py] = back(flagAt);
+            flags.push(clean({ x: px, y: py, shape: "logo", logo: e.flag, size: flagSide / 1.8, title: e.country }));
+        }
+    }
+    const at = { from: "athletics", units: "m" };
+    const layers = [];
+    if (flags.length > 0)
+        layers.push({ kind: "points", id: "flags", name: w.data.layers.flags, ...at, clip: "none", data: flags, style: { shape: "logo", size: flagSide / 1.8 } });
+    layers.push({ kind: "text", id: "names", name: w.data.layers.names, ...at, clip: "none", data: names, style: { size: nameSize, anchor: "end", weight: 800 } });
+    const lanes = sorted.map((e) => e.lane);
+    const totals = { athletes: sorted.length, firstLane: lanes[0] ?? 0, lastLane: lanes[lanes.length - 1] ?? 0 };
+    const summary = sorted.length === 0 ? "" : fill(w.data.summaryDraw, { n: totals.athletes, race: raceName, first: totals.firstLane, last: totals.lastLane });
+    const chart = assemble(o, layers, { title, summary, totals, tableLayers: ["names"] });
+    chart.table = () => entriesTable(sorted, language);
+    return chart;
+}
+/** The lane draw as an HTML table: lane, athlete, country. Every cell is escaped. */
+function entriesTable(entries, language) {
+    const c = WORDS(language).data.columns;
+    const rows = entries.map((e) => `<tr><td>${e.lane}</td><td>${esc(e.name)}</td><td>${esc(e.country ?? "")}</td></tr>`).join("");
+    return `<table class="ky-table"><thead><tr><th>${c.lane}</th><th>${c.athlete}</th><th>${c.country}</th></tr></thead><tbody>${rows}</tbody></table>`;
+}
+const MEDAL_COLOURS = { gold: "#d4a017", silver: "#b8bec6", bronze: "#b87333" };
+/**
+ * The results of a race on the finish line's close-up: after the line, in each lane, a disc with the place (gold, silver and bronze for the first three), the athlete's name and time; the reaction time
+ * behind the start line and the splits along the lane as small marks with their times; and a table of all of it. Times are in seconds from the gun.
+ * @example
+ * ```ts
+ * import { raceResults } from "@johnmorrisdotca/kyogijo-stadiums/athletics";
+ * const chart = raceResults([{ lane: 4, name: "M. Jacobs", place: 1, time: 9.8 }, { lane: 5, name: "F. Kerley", place: 2, time: 9.84 }], { race: "100m" });
+ * console.log(chart.totals.winner?.name, chart.summary);
+ * // M. Jacobs M. Jacobs won the 100 m in 9.80.
+ * ```
+ */
+export function raceResults(results, options = {}) {
+    checkEntries(results, "results");
+    const race = raceOf(options);
+    const language = languageOf(options);
+    const w = WORDS(language);
+    const info = raceById(race);
+    const raceName = (info?.name[language] ?? race);
+    const title = fill(w.data.results, { race: raceName });
+    const o = surfaceFor(options, title, race, "finish");
+    const { plan, marks } = planOf(options, race, o);
+    const oval = plan.oval;
+    const S = oval.straight;
+    const finishX = S / 2;
+    const sorted = [...results].sort((a, b) => (a.place ?? 99) - (b.place ?? 99) || a.lane - b.lane);
+    const lanes = plan.straight?.lane ?? oval.lane;
+    const top = plan.straight?.y0 ?? oval.radius;
+    const at = { from: "athletics", units: "m" };
+    const discs = [];
+    const places = [];
+    const words = [];
+    const reactions = [];
+    const splits = [];
+    for (const r of sorted) {
+        const y = top + (r.lane - 0.5) * lanes;
+        const medal = r.place === 1 ? "gold" : r.place === 2 ? "silver" : r.place === 3 ? "bronze" : undefined;
+        const done = isNum(r.time) && r.place !== undefined;
+        if (done) {
+            discs.push(clean({ x: finishX + 1.15, y, shape: "circle", size: 0.95, color: medal === undefined ? "#2f3a44" : MEDAL_COLOURS[medal], title: `${r.name}, ${medal === undefined ? "" : `${w.data.medals[medal]}, `}${formatTime(r.time)}` }));
+            places.push({ x: finishX + 1.15, y, text: r.place, size: 0.55, color: medal === undefined ? "#ffffff" : "#1c1f1d" });
+            words.push({ x: finishX + 2.05, y, text: `${r.name}  ${formatTime(r.time)}`, anchor: "start", size: 0.5 });
+        }
+        else if (r.note !== undefined) {
+            words.push({ x: finishX + 2.05, y, text: `${r.name}  ${r.note}`, anchor: "start", size: 0.5 });
+        }
+        if (options.reactions !== false && isNum(r.reaction)) {
+            const start = marks.starts.find((s) => s.lane === r.lane);
+            if (start !== undefined)
+                reactions.push({ x: start.x + Math.cos(start.heading) * 2.1 - Math.cos(start.heading + Math.PI / 2) * 0, y: start.y + Math.sin(start.heading) * 2.1, text: `${r.reaction.toFixed(3)}`, size: 0.4, anchor: "middle", title: fill(w.data.reaction, { t: r.reaction.toFixed(3) }) });
+        }
+        if (options.splits !== false && r.splits !== undefined) {
+            const start = marks.starts.find((s) => s.lane === r.lane);
+            if (start !== undefined) {
+                for (const sp of r.splits) {
+                    if (!isNum(sp.distance) || !isNum(sp.time))
+                        continue;
+                    const p = alongLane(plan, marks, start.lane, sp.distance);
+                    splits.push({ x: p[0], y: p[1], shape: "circle", size: 0.5, title: fill(w.data.split, { d: round(sp.distance, 1), t: formatTime(sp.time) }), value: sp.time });
+                }
+            }
+        }
+    }
+    const layers = [];
+    if (splits.length > 0)
+        layers.push({ kind: "points", id: "splits", name: w.data.layers.splits, ...at, clip: "none", data: splits, style: { size: 0.5, fill: "#f2c230" } });
+    layers.push({ kind: "points", id: "places", name: w.data.layers.medals, ...at, clip: "none", data: discs, style: { size: 0.95 } });
+    layers.push({ kind: "text", id: "place-numbers", name: w.data.layers.medals, ...at, clip: "none", data: places, style: { size: 0.55, weight: 800, halo: false } });
+    layers.push({ kind: "text", id: "athletes", name: w.data.layers.names, ...at, clip: "none", data: words, style: { size: 0.5, anchor: "start", weight: 800 } });
+    if (reactions.length > 0)
+        layers.push({ kind: "text", id: "reactions", name: w.data.layers.reactions, ...at, clip: "none", data: reactions, style: { size: 0.4 } });
+    const winner = sorted.find((r) => r.place === 1 && isNum(r.time));
+    const react = results.filter((r) => isNum(r.reaction)).map((r) => r.reaction);
+    const totals = {
+        athletes: results.length,
+        finished: results.filter((r) => isNum(r.time) && r.place !== undefined).length,
+        winner: winner === undefined ? null : { name: winner.name, time: winner.time },
+        quickestReaction: react.length === 0 ? null : Math.min(...react),
+    };
+    const summary = winner === undefined ? "" : fill(w.data.summaryResults, { winner: winner.name, race: raceName, time: formatTime(totals.winner?.time ?? 0) });
+    const chart = assemble(o, layers, { title, summary, totals, tableLayers: ["places"] });
+    chart.table = () => resultsTable(sorted, language);
+    const entries = [];
+    chart.key = [];
+    void entries;
+    return chart;
+}
+/** The point `distance` metres along the lane of a race from its start line, for a splits mark: on the lane's own line, and in a race that leaves its lanes, drawn in towards the inside. */
+function alongLane(plan, marks, lane, distance) {
+    const start = marks.starts.find((s) => s.lane === lane);
+    if (start === undefined)
+        return [0, 0];
+    return runnerAt(plan, marks, lane, distance);
+}
+/** The results as an HTML table: place, lane, athlete, country, time, reaction, the splits. Every cell is escaped. */
+function resultsTable(results, language) {
+    const w = WORDS(language).data;
+    const c = w.columns;
+    const rows = results
+        .map((r) => {
+        const splits = (r.splits ?? []).map((s) => `${round(s.distance, 1)} ${w.metres}: ${formatTime(s.time)}`).join("; ");
+        return `<tr><td>${r.place ?? ""}</td><td>${r.lane}</td><td>${esc(r.name)}</td><td>${esc(r.country ?? "")}</td><td>${isNum(r.time) ? formatTime(r.time) : esc(r.note ?? "")}</td><td>${isNum(r.reaction) ? r.reaction.toFixed(3) : ""}</td><td>${esc(splits)}</td></tr>`;
+    })
+        .join("");
+    return `<table class="ky-table"><thead><tr><th>${c.place}</th><th>${c.lane}</th><th>${c.athlete}</th><th>${c.country}</th><th>${c.time}</th><th>${c.reaction}</th><th>${c.splits}</th></tr></thead><tbody>${rows}</tbody></table>`;
+}
+const smooth = (t) => (t <= 0 ? 0 : t >= 1 ? 1 : t * t * (3 - 2 * t));
+/** The distance a runner has run at a time, by the reaction time, the splits and the finish: straight lines between them, standing until the reaction. */
+export function distanceRun(runner, total, t) {
+    const rt = isNum(runner.reaction) ? runner.reaction : 0.15;
+    if (t <= rt)
+        return 0;
+    const pts = [[rt, 0]];
+    for (const s of [...(runner.splits ?? [])].sort((a, b) => a.time - b.time))
+        if (s.time > rt && s.time < runner.time && s.distance > 0 && s.distance < total)
+            pts.push([s.time, s.distance]);
+    pts.push([runner.time, total]);
+    for (let i = 1; i < pts.length; i += 1) {
+        if (t <= pts[i][0]) {
+            const [t0, d0] = pts[i - 1];
+            const [t1, d1] = pts[i];
+            return d0 + ((t - t0) / (t1 - t0)) * (d1 - d0);
+        }
+    }
+    // After the finish: carry on at the pace of the last stretch, slowing to a stop over three seconds.
+    const [t0, d0] = pts[pts.length - 2];
+    const [t1, d1] = pts[pts.length - 1];
+    const v = (d1 - d0) / (t1 - t0);
+    const u = Math.min(t - t1, 3);
+    return d1 + v * (u - (u * u) / 6);
+}
+/** The running line's distance mapped from one radius to another by the part of the track it is on (its bend's angle, its straight's length): where a runner who has cut in to another lane is. */
+function mapDistance(plan, from, to, s) {
+    const S = plan.oval.straight;
+    const L = 2 * S + 2 * Math.PI * from;
+    const d = ((s % L) + L) % L;
+    const turns = Math.floor(s / L);
+    const bend = Math.PI * from;
+    const Lto = 2 * S + 2 * Math.PI * to;
+    let out;
+    if (d <= bend)
+        out = (d / from) * to;
+    else if (d <= bend + S)
+        out = Math.PI * to + (d - bend);
+    else if (d <= 2 * bend + S)
+        out = Math.PI * to + S + ((d - bend - S) / from) * to;
+    else
+        out = 2 * Math.PI * to + S + (d - 2 * bend - S);
+    return out + turns * Lto;
+}
+/**
+ * Where a runner is when `d` metres have been run from the start line of the lane: in the lane, on the lane's own curve, for a race run in lanes; and, for a race that leaves them, in the lane as far as
+ * the breakline (or, with none, the start) and then moving in to lane 1's line over the next 40 m, as a runner does once free.
+ */
+function runnerAt(plan, marks, lane, d) {
+    const o = plan.oval;
+    const start = marks.starts.find((s) => s.lane === lane);
+    if (start === undefined)
+        return [0, 0];
+    const race = marks.race;
+    const total = race.distance;
+    if (race.kind === "straight") {
+        const x = Math.min(start.x + d, start.x + total + 100);
+        return [x, start.y];
+    }
+    const r = laneRadius(o, lane);
+    const r1 = laneRadius(o, 1);
+    const s = start.s + d;
+    // Where the runner leaves the lane: the breakline's crossing of the lane, or the start for a race run without lanes.
+    let free = Infinity;
+    if (race.kind === "curved" || race.kind === "steeplechase")
+        free = 0;
+    else if (race.breakline === true && marks.breakline !== undefined) {
+        const a = r1;
+        const [px, py] = curveAcross(o, { side: plan.indoor ? "right" : "left", f0: 0, wire: o.straight }, a, r, r, 1)[0];
+        const sBreak = distanceOn(o, r, px, py);
+        const L = lap(o, lane);
+        free = (((sBreak - start.s) % L) + L) % L;
+    }
+    const w = free === Infinity ? 0 : smooth((d - free) / 40);
+    const p = pose(o, r, s);
+    if (w === 0)
+        return [p.x, p.y];
+    const q = pose(o, r1, mapDistance(plan, r, r1, s));
+    return [p.x + (q.x - p.x) * w, p.y + (q.y - p.y) * w];
+}
+/**
+ * A replay of a race: every runner, from the gun, on the curve of the lane (the stagger of the start as the Manual's table has it), in the pace of the reaction time, the splits and the finish time,
+ * to the line and on to a stop. A race that leaves its lanes (the 800 m after its breakline, the long races from the start) is drawn with the runners moving in to the inside. The positions are in
+ * the athletics frame (metres from the middle of the track), so the timeline is for the stadium drawn whole or close up. The relays are not replayed.
+ * @example
+ * ```ts
+ * import { raceReplay } from "@johnmorrisdotca/kyogijo-stadiums/athletics";
+ * const replay = raceReplay([{ lane: 1, name: "A", time: 10.1 }, { lane: 2, name: "B", time: 10.3 }], { race: "100m" });
+ * console.log(replay.timeline.frames.length > 40, replay.duration);
+ * // true 10.3
+ * ```
+ */
+export function raceReplay(runners, options = {}) {
+    checkEntries(runners, "runners");
+    const race = raceOf(options);
+    const info = raceById(race);
+    if (info?.legs !== undefined)
+        throw new RangeError(`The ${race} is a relay: a replay of a relay is not made`);
+    const language = languageOf(options);
+    const w = WORDS(language);
+    const raceName = (info?.name[language] ?? race);
+    const title = fill(w.data.replay, { race: raceName });
+    const o = surfaceFor(options, title, race, undefined);
+    const { plan, marks } = planOf(options, race, o);
+    const step = isNum(options.step) && options.step > 0 ? options.step : 0.2;
+    const runOut = isNum(options.runOut) && options.runOut >= 0 ? options.runOut : 8;
+    for (const r of runners)
+        if (!isNum(r.time) || r.time <= 0)
+            throw new RangeError(`runner in lane ${r.lane}: the time is a number of seconds above zero`);
+    const total = info.distance;
+    const duration = Math.max(...runners.map((r) => r.time), 0);
+    const end = duration + 3.2;
+    const frames = [];
+    const finishX = plan.oval.straight / 2;
+    for (let k = 0; k * step <= end + 1e-9; k += 1) {
+        const t = Math.round(k * step * 1000) / 1000;
+        const objects = [];
+        for (const r of [...runners].sort((a, b) => a.lane - b.lane)) {
+            const d = distanceRun(r, total, t);
+            const run = Math.min(d, total + runOut);
+            // The runner reaches the line at `total`; beyond it the run-out is straight along the finish straight.
+            const [x, y] = d <= total ? runnerAt(plan, marks, r.lane, d) : (() => { const [fx, fy] = runnerAt(plan, marks, r.lane, total); return [Math.max(fx, finishX) + (run - total), fy]; })();
+            objects.push(clean({ id: `lane-${r.lane}`, team: "home", x: round(x, 3), y: round(y, 3), label: r.name, number: r.lane }));
+        }
+        frames.push({ t, objects });
+    }
+    const events = [{ t: 0, kind: "gun", label: w.data.gun }];
+    for (const r of runners) {
+        const [x, y] = runnerAt(plan, marks, r.lane, total);
+        events.push({ t: r.time, kind: "finish", team: "home", x: round(x, 3), y: round(y, 3), by: `lane-${r.lane}`, label: fill(w.data.finish, { name: r.name, time: formatTime(r.time) }) });
+    }
+    events.sort((a, b) => a.t - b.t);
+    const timeline = { frames, events, from: "athletics", units: "m" };
+    const summary = fill(w.data.summaryReplay, { n: runners.length, race: raceName });
+    return { timeline, options: { ...o, title }, look: { trail: 0, scale: 0.5, numbers: true, hold: 2 }, title, summary, duration };
+}
+// ----- field events
+/** The distance from the facility's centre to where a mark is measured from: the circle's inside edge (Rule 32), or the javelin's arc (8 m, Rule 32, javelin throw runway). */
+const MEASURED_FROM = { "shot-put": 1.0675, "discus-throw": 1.25, "hammer-throw": 1.0675, "javelin-throw": 8 };
+/**
+ * The attempts of a field event as marks: each valid throw in its sector at its distance and direction, each jump in its pit at its distance from the take-off line, the best of them picked out with
+ * a ring and its distance written beside it. A foul has no mark and is in the table. Put them on the stadium (`athletics: { events: [event] }`) or on the event alone (`athletics: { layout: event }`).
+ * @example
+ * ```ts
+ * import { fieldMarks } from "@johnmorrisdotca/kyogijo-stadiums/athletics";
+ * const chart = fieldMarks("javelin-throw", [{ athlete: "A", distance: 84.2 }, { athlete: "A", distance: 88.1, across: -3 }, { athlete: "A", valid: false }]);
+ * console.log(chart.totals.best?.distance, chart.totals.fouls);
+ * // 88.1 1
+ * ```
+ */
+export function fieldMarks(event, attempts, options = {}) {
+    if (fieldEventById(event) === undefined)
+        throw new Error(`Unknown field event "${String(event)}"`);
+    if (!Array.isArray(attempts))
+        throw new TypeError("attempts is a list of attempts");
+    const language = languageOf(options);
+    const w = WORDS(language);
+    const surface = options.surface ?? {};
+    const layout = surface.athletics?.layout === event;
+    const title = fill(w.data.marks, { event: fieldEventName(event, language) });
+    const style = { events: [event], ...(surface.athletics ?? {}) };
+    const o = drawingOptions("athletics", { ...options, surface: { ...surface, athletics: style } }, title, {});
+    const plan = athleticsPlan({ sport: "athletics", league: surface.league, athletics: style, pitch: surface.pitch });
+    const facility = plan.facilities.find((f) => f.event === event && (options.facility === undefined || f.id === options.facility));
+    if (facility === undefined)
+        throw new Error(options.facility === undefined ? `The stadium has no ${event} facility: put the event in athletics.events` : `The ${event} has no facility "${options.facility}": use one of ${plan.facilities.filter((f) => f.event === event).map((f) => f.id).join(", ")}`);
+    const jump = event === "long-jump" || event === "triple-jump";
+    const heading = facility.heading;
+    const from = (x, y) => (layout ? [(x - plan.box.x0) * K, (y - plan.box.y0) * K] : [x, y]);
+    const at = layout ? { units: "ft" } : { from: "athletics", units: "m" };
+    // A layer's sizes are in its own units: feet for the event alone, metres in the athletics frame.
+    const u = layout ? K : 1;
+    const takeoff = event === "long-jump" ? 3 : options.women === true ? 11 : 13;
+    const place = (a) => {
+        const d = a.distance;
+        const across = isNum(a.across) ? a.across : 0;
+        if (jump) {
+            // The pit's near end is the facility; the take-off line is `takeoff` m before it, and the mark is `d` m from the line.
+            const along = d - takeoff;
+            return [facility.x + Math.cos(heading) * along - Math.sin(heading) * across, facility.y + Math.sin(heading) * along + Math.cos(heading) * across];
+        }
+        const th = heading + (across * Math.PI) / 180;
+        const r = d + (MEASURED_FROM[event] ?? 0);
+        return [facility.x + r * Math.cos(th), facility.y + r * Math.sin(th)];
+    };
+    const valid = attempts.filter((a) => isNum(a.distance) && a.valid !== false);
+    const fouls = attempts.length - valid.length;
+    const bestOne = valid.reduce((b, a) => (b === undefined || a.distance > b.distance ? a : b), undefined);
+    const marks = [];
+    const labels = [];
+    valid.forEach((a, i) => {
+        const [x, y] = from(...place(a));
+        const isBest = a === bestOne;
+        const text = `${a.distance.toFixed(2)}`;
+        marks.push(clean({ x, y, team: a.team ?? "home", outcome: isBest ? "best" : "attempt", value: a.distance, title: a.title ?? `${a.athlete === undefined ? "" : `${a.athlete}, `}${text} ${w.data.metres}${isBest ? `, ${w.data.best}` : ""}` }));
+        if (isBest || options.labels === true)
+            labels.push({ x: x + 1.4 * u, y: y - 1.4 * u, text, size: (isBest ? 0.9 : 0.6) * u, anchor: "start" });
+        void i;
+    });
+    const layers = [];
+    const size = 1.1 * u;
+    layers.push({ kind: "points", id: "attempts", name: w.data.layers.attempts, ...at, clip: "none", data: marks, style: { size, outcomes: { best: { shape: "star", scale: 1.7 }, attempt: {} } } });
+    if (labels.length > 0)
+        layers.push({ kind: "text", id: "marks", name: w.data.layers.best, ...at, clip: "none", data: labels, style: { size: 0.8 * u, weight: 800 } });
+    const totals = { attempts: attempts.length, valid: valid.length, fouls, best: bestOne === undefined ? null : { distance: bestOne.distance, athlete: bestOne.athlete } };
+    const summary = bestOne === undefined ? "" : fill(w.data.summaryMarks, { n: attempts.length, best: `${bestOne.distance.toFixed(2)} ${w.data.metres}`, who: bestOne.athlete ?? "" });
+    const chart = assemble(o, layers, { title, summary, totals, tableLayers: ["attempts"] });
+    chart.table = () => attemptsTable(attempts, bestOne, language);
+    return chart;
+}
+/** The attempts as an HTML table: the round, the athlete, the mark, whether it was valid. The best is in bold. Every cell is escaped. */
+function attemptsTable(attempts, best, language) {
+    const w = WORDS(language).data;
+    const c = w.columns;
+    const rows = attempts
+        .map((a, i) => {
+        const mark = isNum(a.distance) && a.valid !== false ? `${(a.distance).toFixed(2)}` : w.foul;
+        const cell = a === best ? `<strong>${mark}</strong>` : mark;
+        return `<tr><td>${a.round ?? i + 1}</td><td>${esc(a.athlete ?? "")}</td><td>${cell}</td><td>${isNum(a.distance) && a.valid !== false ? w.yes : w.no}</td></tr>`;
+    })
+        .join("");
+    return `<table class="ky-table"><thead><tr><th>${c.round}</th><th>${c.athlete}</th><th>${c.distance}</th><th>${c.valid}</th></tr></thead><tbody>${rows}</tbody></table>`;
+}

package/dist/charts.baseball.js

@@ -76,7 +76,7 @@ export function mlbSprayChart(balls, options = {}) {
             if (at !== undefined)
                 [x, y] = toFrame === undefined ? at : toFrame([at])[0];
         }
-        return clean({ x: x ?? null, y: y ?? null, outcome: ballType(b.type), value: b.value, team: b.team, title: b.title });
+        return clean({ id: b.id, x: x ?? null, y: y ?? null, outcome: ballType(b.type), value: b.value, team: b.team, title: b.title });
     });
     const { counts, placed: count, skipped } = countOutcomes(rows);
     // The fence of the park in that season, and the balls that came down beyond it: each ball's distance and its angle from dead centre, from the surface's own feet.

package/dist/charts.curling.heat.d.ts

@@ -0,0 +1,24 @@
+import type { Chart, CurlingHeatOptions, CurlingHeatTotals, CurlingStone, KeyItem } from "./charts.types.ts";
+/**
+ * A heat chart of the stones of many ends on a house: where they came to rest, counted into cells (`heatmap`, `hexbin`), a density (`contour`), the zones of the house (`zones`) or
+ * drawn as translucent discs in their team's colours (`discs`). Only stones in play are drawn, as `curlingScore` judges them. `team` keeps one team's stones, and `only` the free
+ * guards or the stones in the house, so that "where do the guards of the team with the hammer end up" is one call. Places are feet from the button, as for `curlingStones`; give
+ * the stones of every end together. The totals say how many stones were drawn, the free guards and the stones in the house for each team, and the share in each zone.
+ * @example
+ * ```ts
+ * import { curlingHeat } from "@johnmorrisdotca/kyogijo-stadiums/charts";
+ * const stones = [
+ *   { x: 0.3, y: 0.2, team: "home" },
+ *   { x: -1.1, y: 0.9, team: "away" },
+ *   { x: 0.1, y: -14, team: "away" },
+ *   { x: 2.4, y: -17, team: "home" },
+ *   { x: 0, y: -10, team: "home" },
+ * ];
+ * const chart = curlingHeat(stones, { only: "guards", view: "discs" });
+ * console.log(chart.totals.drawn, chart.totals.guards, chart.totals.house);
+ * // 3 { home: 2, away: 1 } { home: 1, away: 1 }
+ * ```
+ */
+export declare function curlingHeat(stones: readonly CurlingStone[], options?: CurlingHeatOptions): Chart<CurlingHeatTotals> & {
+    key: KeyItem[];
+};

package/dist/charts.curling.heat.js

@@ -0,0 +1,116 @@
+// The curling heat chart: where the stones of many ends came to rest, counted into square cells, hexagons, a density or the zones of the house (the button, the rings and the
+// free guard zone), or drawn as translucent discs in each team's colour so that stones that fall on each other build up colour. The idea of the chart is the heat map of the
+// stones' resting places and the map of the free guards that the analyses of curlovision (BSD) and Jordan Myslik's curling analytics show; the code is written for this package on
+// the heat layers, with the rules of `curlingScore` for which stones are in play and in the house and `curlingFreeGuards` for the guards.
+import { curlingFreeGuards } from "./curling.stats.js";
+import { curlingScore, CURLING_COLORS } from "./charts.curling.js";
+import { assemble, clean, drawingOptions, languageOf, percentOf, wordsOf } from "./charts.js";
+import { STONE_DIAMETER } from "./geometry.js";
+import { sheetFor } from "./sheet.js";
+import { shownIce, teesOf } from "./surfaces/curling.js";
+import { foldCrop } from "./surfaces/curling.fold.js";
+import { zoneCounts } from "./heat.js";
+import { envFor } from "./layers.env.js";
+import { fill } from "./strings.js";
+import { convertLength, isUnit } from "./units.js";
+const isNum = (value) => typeof value === "number" && Number.isFinite(value);
+/**
+ * A heat chart of the stones of many ends on a house: where they came to rest, counted into cells (`heatmap`, `hexbin`), a density (`contour`), the zones of the house (`zones`) or
+ * drawn as translucent discs in their team's colours (`discs`). Only stones in play are drawn, as `curlingScore` judges them. `team` keeps one team's stones, and `only` the free
+ * guards or the stones in the house, so that "where do the guards of the team with the hammer end up" is one call. Places are feet from the button, as for `curlingStones`; give
+ * the stones of every end together. The totals say how many stones were drawn, the free guards and the stones in the house for each team, and the share in each zone.
+ * @example
+ * ```ts
+ * import { curlingHeat } from "@johnmorrisdotca/kyogijo-stadiums/charts";
+ * const stones = [
+ *   { x: 0.3, y: 0.2, team: "home" },
+ *   { x: -1.1, y: 0.9, team: "away" },
+ *   { x: 0.1, y: -14, team: "away" },
+ *   { x: 2.4, y: -17, team: "home" },
+ *   { x: 0, y: -10, team: "home" },
+ * ];
+ * const chart = curlingHeat(stones, { only: "guards", view: "discs" });
+ * console.log(chart.totals.drawn, chart.totals.guards, chart.totals.house);
+ * // 3 { home: 2, away: 1 } { home: 1, away: 1 }
+ * ```
+ */
+export function curlingHeat(stones, options = {}) {
+    if (!Array.isArray(stones))
+        throw new TypeError("stones is a list of stones");
+    const view = options.view ?? "heatmap";
+    if (!["heatmap", "hexbin", "contour", "zones", "discs"].includes(view))
+        throw new RangeError(`Unknown view "${String(view)}": use heatmap, hexbin, contour, zones or discs`);
+    const only = options.only ?? "all";
+    if (!["all", "guards", "house"].includes(only))
+        throw new RangeError(`Unknown only "${String(only)}": use all, guards or house`);
+    const unit = options.units ?? "ft";
+    if (!isUnit(unit))
+        throw new RangeError(`Unknown units "${String(unit)}": use one of ft, in, yd, m, cm, mm`);
+    const language = languageOf(options);
+    const all = wordsOf(language);
+    const w = all.charts;
+    const house = options.house === "right" ? "right" : "left";
+    const surface = options.surface ?? {};
+    const sheet = { show: options.show ?? "half", end: house, guardZone: true, ...(surface.sheet ?? {}) };
+    const o = drawingOptions("curling", { ...options, surface: { ...surface, sheet, colors: { layerHome: CURLING_COLORS.home, layerAway: CURLING_COLORS.away, ...(surface.colors ?? {}) } } }, w.titleCurlingHeat, { margin: 4.5 });
+    const feet = (value) => convertLength(value, unit, "ft");
+    const judged = curlingScore(stones, { units: unit });
+    const guards = curlingFreeGuards(stones, { units: unit });
+    const guardSet = new Set(guards.indices);
+    const teamOf = (s) => (typeof s.team === "string" && s.team !== "" ? s.team : "home");
+    const count = { guards: { home: 0, away: 0 }, house: { home: 0, away: 0 } };
+    const kept = [];
+    let inPlay = 0;
+    for (const r of judged.results) {
+        if (!r.inPlay)
+            continue;
+        inPlay += 1;
+        const s = stones[r.index];
+        const team = teamOf(s);
+        if (guardSet.has(r.index) && (team === "home" || team === "away"))
+            count.guards[team] += 1;
+        if (r.inHouse && (team === "home" || team === "away"))
+            count.house[team] += 1;
+        if (options.team !== undefined && team !== options.team)
+            continue;
+        if (only === "guards" && !guardSet.has(r.index))
+            continue;
+        if (only === "house" && !r.inHouse)
+            continue;
+        kept.push(clean({ x: feet(s.x), y: feet(s.y), team, title: s.title }));
+    }
+    const at = { from: "curling", units: "ft", ...(house === "left" ? { attacking: "left" } : {}) };
+    // The cells are a foot square by default: the bins are counted across the sheet's length, and a cell that holds no stone is not drawn.
+    const cell = isNum(options.cell) && options.cell > 0 ? options.cell : 1;
+    const plan = sheetFor(o);
+    const bins = Math.min(400, Math.max(1, Math.round(plan.spec.length / cell)));
+    // The colour bar is sized and placed against the part of the sheet that is drawn: the half or the house, or on a folded sheet the house end the stones are at, where its panel shows it large.
+    const region = plan.show === "folded" ? ((crop) => ({ x: crop.x, y: 0, w: crop.w, h: plan.spec.width }))(foldCrop(plan.spec, teesOf(plan.spec)[house === "left" ? 0 : 1], house, plan.panels)) : shownIce(plan.spec, plan.show, plan.end);
+    const heat = { name: w.curlingHeatStat, statistic: "count", statisticName: w.curlingHeatStat, ramp: options.ramp, legend: options.legend === false ? undefined : { position: "bottom", region }, labels: options.labels === true ? true : undefined, ground: "none", minCount: 1 };
+    const layers = [];
+    if (view === "heatmap")
+        layers.push(clean({ kind: "heatmap", id: "heat", ...at, data: kept, bins, ...heat }));
+    else if (view === "hexbin")
+        layers.push(clean({ kind: "hexbin", id: "heat", ...at, data: kept, size: cell, ...heat }));
+    else if (view === "contour")
+        layers.push(clean({ kind: "contour", id: "heat", ...at, data: kept, ...heat }));
+    else if (view === "zones")
+        layers.push(clean({ kind: "zones", id: "heat", ...at, zones: "curling-house", end: house, data: kept, ...heat, labels: options.labels === false ? undefined : true }));
+    else
+        layers.push({ kind: "points", id: "discs", name: w.curlingStone, ...at, data: kept, style: { size: STONE_DIAMETER, opacity: 0.35 } });
+    // The zones of the house, counted for the totals whichever way the stones are drawn.
+    const counter = { kind: "zones", id: "zones", ...at, zones: "curling-house", end: house, data: kept };
+    const zones = zoneCounts(counter, envFor(o, false)).map((z) => ({ id: z.id, name: z.name, stones: z.n, share: percentOf(z.n, kept.length) }));
+    const kinds = [];
+    if (options.team !== undefined)
+        kinds.push(fill(w.curlingHeatTeam, { name: options.team === "away" ? options.names?.away ?? all.said.away : options.names?.home ?? all.said.home }));
+    if (only === "guards")
+        kinds.push(w.curlingHeatGuards);
+    if (only === "house")
+        kinds.push(w.curlingHeatHouse);
+    const parts = [fill(w.sumCurlingHeat, { n: inPlay, house: count.house.home + count.house.away, guards: count.guards.home + count.guards.away }), ...kinds];
+    const totals = { stones: judged.stones, inPlay, drawn: kept.length, guards: count.guards, house: count.house, zones, skipped: judged.skipped };
+    const chart = assemble(o, layers, { title: w.titleCurlingHeat, summary: parts.join(all.said.gap), totals });
+    chart.key = [];
+    return chart;
+}

package/dist/charts.curling.js

@@ -9,6 +9,9 @@ import { assemble, clean, drawingOptions, keyItems, keyLayers, languageOf, round
 import { fill } from "./strings.js";
 import { outlineOf } from "./outline.js";
 import { isUnit } from "./units.js";
+import { isPortrait } from "./common.js";
+import { foldPlan } from "./surfaces/curling.fold.js";
+import { teesOf } from "./surfaces/curling.js";
 const R = STONE_DIAMETER / 2;
 const EPS = 1e-6;
 /** The colours of the two teams' stones, the handles' colours of a game: red and yellow. */
@@ -122,7 +125,7 @@ export function curlingStones(stones, options = {}) {
     const title = options.end === undefined ? w.titleCurling : `${w.titleCurling}${all.said.sep}${fill(w.curlingEnd, { n: options.end })}`;
     const surface = options.surface ?? {};
     // The two stone colours and the half of the sheet with the free guard zone, under whatever the caller laid over them.
-    const sheet = { show: "half", end: house, guardZone: true, ...(surface.sheet ?? {}) };
+    const sheet = { show: options.show ?? "half", end: house, guardZone: true, ...(surface.sheet ?? {}) };
     const o = drawingOptions("curling", { ...options, surface: { ...surface, sheet, colors: { layerHome: CURLING_COLORS.home, layerAway: CURLING_COLORS.away, ...(surface.colors ?? {}) } } }, title, { margin: 4.5 });
     const plan = sheetFor(o);
     const totals = curlingScore(stones, { units: options.units, width: plan.spec.width });
@@ -181,8 +184,16 @@ export function curlingStones(stones, options = {}) {
     if (options.key !== false) {
         const { box } = outlineOf(o);
         const tee = house === "left" ? box.w / 2 - CURLING.teeFromMiddle : box.w / 2 + CURLING.teeFromMiddle;
-        const shown = { x: house === "left" ? tee - CURLING.backLine : tee - CURLING.hogLine - 1, w: CURLING.backLine + CURLING.hogLine + 1 };
-        layers.push(...keyLayers(o, entries, LOOKS, all, [], shown));
+        if (plan.show === "folded") {
+            // A folded sheet's key runs along the top of the whole drawing, above the enlarged house that is there.
+            const margin = typeof o.margin === "number" ? convertLength(o.margin, o.units ?? "ft", "ft") : 3;
+            const fold = foldPlan(plan.spec, teesOf(plan.spec), { panels: plan.panels, fit: plan.fit, margin, turned: isPortrait(o), id: "k" });
+            layers.push(...keyLayers(o, entries, LOOKS, all, [], { x: box.x, w: box.w, y: fold.view.y + margin * 0.5 }));
+        }
+        else {
+            const shown = { x: house === "left" ? tee - CURLING.backLine : tee - CURLING.hogLine - 1, w: CURLING.backLine + CURLING.hogLine + 1 };
+            layers.push(...keyLayers(o, entries, LOOKS, all, [], shown));
+        }
     }
     const teamName = totals.scoring === null ? "" : name(totals.scoring);
     const parts = [