@johnmorrisdotca/kyogijo-stadiums 0.4.0 → 0.6.0

package/dist/charts.skating.js

@@ -0,0 +1,426 @@
+// The skating data: the pairs of a speed skating race on the lines of its start (an inner and an outer lane, the armbands the Rules give them), the starting positions of a short track race, the results
+// with their medals, times and splits, a replay of the race (every skater on his own way round the track, the lane changed once a lap), and the elements of a figure skating programme as marks on the ice.
+// Written for this package from the ISU's Special Regulations and Technical Rules for speed skating (Rules 203, 227, 253, 254 and 280) and short track speed skating (Rule 280); 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 { esc } from "./format.js";
+import { fill } from "./strings.js";
+import { ELEMENT_KINDS, ELEMENT_NAMES, raceById } from "./skating/events.js";
+import { ISU_SHORT_TRACK } from "./leagues/skating.js";
+import { disciplineOf, skatingPlan } from "./skating/plan.js";
+import { raceName } from "./skating/describe.js";
+import { markRace } from "./skating/long.js";
+import { shortPose, startingPositions, startsOnOppositeStraight } from "./skating/short.js";
+import { finishAt, laneRadius, pose, startOf } from "./skating/track.js";
+const isNum = (v) => typeof v === "number" && Number.isFinite(v);
+const WORDS = (language) => wordsOf(language).skating;
+/** A time in seconds as it is written: `34.32`, `1:40.91`, `6:01.03`. */
+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);
+}
+/** The discipline of the options' rink: a chart is for a track, the long one unless the league says the short one. */
+function trackOf(options) {
+    const d = disciplineOf({ sport: "skating", league: options.surface?.league });
+    if (d === "figure")
+        throw new RangeError('A race chart is for a speed skating track: use league "isu-long-track" or "isu-short-track"');
+    return d;
+}
+function raceOf(options) {
+    const id = options.race ?? "500m";
+    if (raceById(id) === undefined)
+        throw new Error(`Unknown race "${String(id)}"`);
+    return id;
+}
+/** The plan of the race's drawing, close up on its start or its finish (or whole), with the race marked. */
+function planOf(options, race, range, title, extraStyle = {}) {
+    const surface = options.surface ?? {};
+    const style = { races: [race], start: race, ...(surface.skating ?? {}), ...extraStyle };
+    const o = drawingOptions("skating", { ...options, surface: { ...(range === undefined ? {} : { range }), ...surface, skating: style } }, title, {});
+    const plan = skatingPlan({ sport: "skating", league: surface.league, skating: style, range: o.range });
+    return { o, plan };
+}
+const AT = { from: "skating", units: "m" };
+const ARMBAND = { inner: "#ffffff", outer: "#d6342a" };
+/** The point and the heading of a skater of a long track race who has skated `d` metres. */
+function longAt(oval, race, lane, d) {
+    const m = markRace(oval, race);
+    const nc = m.noChange;
+    const dist = raceById(race)?.distance ?? 0;
+    const start = startOf(oval, lane, dist, finishAt(oval, m.finish), nc);
+    const p = pose(oval, lane, start.v0 + d, nc);
+    return { x: p.x, y: p.y, heading: p.heading };
+}
+/** Where a skater of a short track race is when `d` metres have been skated from the starting position `position` (1 on the inner side). */
+function shortAt(oval, race, position, d) {
+    const laps = ISU_SHORT_TRACK.laps[race];
+    const total = laps * oval.lap;
+    // The finishing line is the middle of the bottom straight: S/2 along it. A half-lap race starts at the middle of the top one.
+    const finish = oval.straight / 2;
+    const v0 = (((finish - total) % oval.lap) + oval.lap) % oval.lap;
+    const offset = 0.5 + 1.3 * (position - 1) - 0.5;
+    const out = offset * Math.max(0, 1 - d / 25);
+    return shortPose(oval, v0 + d, out);
+}
+// ----- the pairs and the starting positions
+/**
+ * The pairs of a long track race on the start's close-up: the pair `pair` (the first by default) with each skater's name and flag behind the starting line of his lane, and an armband's colour (white
+ * for the inner lane, red for the outer: Rule 253.3.1); a table lists every pair. The starting lines are the ISU's: the 500 m on the finishing straight, the 1000 m, 1500 m, 3000 m and 5000 m on the
+ * crossing straight, where each lane's line stands a different distance from the finish.
+ * @example
+ * ```ts
+ * import { skatingPairs } from "@johnmorrisdotca/kyogijo-stadiums/skating";
+ * const chart = skatingPairs([{ pair: 1, inner: { name: "A. Skater" }, outer: { name: "B. Skater" } }], { race: "1000m" });
+ * console.log(chart.totals, chart.title);
+ * // { skaters: 2, pairs: 1 } Pairs, 1000 m
+ * ```
+ */
+export function skatingPairs(pairs, options = {}) {
+    if (!Array.isArray(pairs))
+        throw new TypeError("pairs is a list");
+    const track = trackOf(options);
+    if (track !== "long-track")
+        throw new RangeError("Pairs are for the long track: the short track has starting positions (skatingGrid)");
+    const seen = new Set();
+    for (const p of pairs) {
+        if (typeof p !== "object" || p === null || !Number.isInteger(p.pair) || p.pair < 1)
+            throw new TypeError("each pair has a number, a whole number from 1");
+        if (seen.has(p.pair))
+            throw new RangeError(`pair ${p.pair} is given twice`);
+        seen.add(p.pair);
+    }
+    const race = raceOf(options);
+    const language = languageOf(options);
+    const w = WORDS(language);
+    const title = fill(w.data.draw, { race: raceName(race, language) });
+    const { o, plan } = planOf(options, race, "start", title);
+    const oval = plan.oval;
+    const which = options.pair ?? [...pairs].sort((a, b) => a.pair - b.pair)[0]?.pair;
+    const shown = pairs.find((p) => p.pair === which);
+    const names = [];
+    const flags = [];
+    const bands = [];
+    const m = markRace(oval, race);
+    for (const [laneName, entry] of [["inner", shown?.inner], ["outer", shown?.outer]]) {
+        if (entry === undefined)
+            continue;
+        const lane = laneName === "inner" ? 0 : 1;
+        const start = m.starts.find((s) => s.lane === lane || s.lane === "both");
+        if (start === undefined)
+            continue;
+        const fx = Math.cos(start.heading);
+        const fy = Math.sin(start.heading);
+        // The skater stands in his lane, on the line of its measurement, behind the starting line.
+        const sign = start.y >= 0 ? 1 : -1;
+        const base = { x: start.x, y: sign * laneRadius(oval, lane) };
+        const back = (d) => [base.x - fx * d, base.y - fy * d];
+        const [bx, by] = back(1.6);
+        bands.push({ x: bx, y: by, shape: "circle", size: 1.2, color: ARMBAND[laneName], title: laneName === "inner" ? w.data.lanes.inner : w.data.lanes.outer });
+        if (entry.flag !== undefined) {
+            const [px, py] = back(3.6);
+            flags.push(clean({ x: px, y: py, shape: "logo", logo: entry.flag, size: 1.6, title: entry.country }));
+        }
+        const [nx, ny] = back(entry.flag !== undefined ? 5.4 : 3);
+        names.push(clean({ x: nx, y: ny, text: entry.name, anchor: fx < 0 ? "start" : "end", size: 1.9, title: entry.country === undefined ? undefined : `${entry.name}, ${entry.country}` }));
+    }
+    const layers = [];
+    layers.push({ kind: "points", id: "armbands", name: w.data.layers.names, ...AT, clip: "none", data: bands, style: { size: 1.2 } });
+    if (flags.length > 0)
+        layers.push({ kind: "points", id: "flags", name: w.data.layers.flags, ...AT, clip: "none", data: flags, style: { shape: "logo", size: 1.6 } });
+    layers.push({ kind: "text", id: "names", name: w.data.layers.names, ...AT, clip: "none", data: names, style: { size: 1.9, anchor: "end", weight: 800 } });
+    const skaters = pairs.reduce((n, p) => n + (p.inner === undefined ? 0 : 1) + (p.outer === undefined ? 0 : 1), 0);
+    const totals = { skaters, pairs: pairs.length };
+    const last = pairs.reduce((n, p) => Math.max(n, p.pair), 0);
+    const summary = pairs.length === 0 ? "" : fill(w.data.summaryDraw, { n: skaters, race: raceName(race, language), last });
+    const chart = assemble(o, layers, { title, summary, totals, tableLayers: ["names"] });
+    chart.table = () => pairsTable([...pairs].sort((a, b) => a.pair - b.pair), language);
+    return chart;
+}
+function pairsTable(pairs, language) {
+    const w = WORDS(language).data;
+    const c = w.columns;
+    const cell = (e) => (e === undefined ? "" : `${esc(e.name)}${e.country === undefined ? "" : ` (${esc(e.country)})`}`);
+    const rows = pairs.map((p) => `<tr><td>${p.pair}</td><td>${cell(p.inner)}</td><td>${cell(p.outer)}</td></tr>`).join("");
+    return `<table class="ky-table"><thead><tr><th>${c.pair}</th><th>${w.lanes.inner}</th><th>${w.lanes.outer}</th></tr></thead><tbody>${rows}</tbody></table>`;
+}
+/**
+ * The starting positions of a short track race on the start's close-up: the five dots of the 500 m and the 1000 m (every 1.3 m from 50 cm out from the inner side, Rule 280.2c), each with its starter's
+ * name and flag. The 500 m and the 1500 m start on the straight opposite the finishing line; the others at the finishing line.
+ * @example
+ * ```ts
+ * import { skatingGrid } from "@johnmorrisdotca/kyogijo-stadiums/skating";
+ * const chart = skatingGrid([{ position: 1, name: "A. Skater" }, { position: 2, name: "B. Skater" }], { race: "500m", surface: { league: "isu-short-track" } });
+ * console.log(chart.totals.skaters);
+ * // 2
+ * ```
+ */
+export function skatingGrid(starters, options = {}) {
+    if (!Array.isArray(starters))
+        throw new TypeError("starters is a list");
+    const surface = { ...(options.surface ?? {}), league: options.surface?.league ?? "isu-short-track" };
+    const opts = { ...options, surface };
+    if (trackOf(opts) !== "short-track")
+        throw new RangeError("Starting positions are for the short track: the long track has pairs (skatingPairs)");
+    const seen = new Set();
+    for (const s of starters) {
+        if (typeof s !== "object" || s === null || !Number.isInteger(s.position) || s.position < 1 || s.position > 5)
+            throw new RangeError("each starter has a position from 1 to 5 (Rule 280.2c)");
+        if (seen.has(s.position))
+            throw new RangeError(`position ${s.position} is given twice`);
+        seen.add(s.position);
+    }
+    const race = raceOf(opts);
+    const language = languageOf(opts);
+    const w = WORDS(language);
+    const title = fill(w.data.draw, { race: raceName(race, language) });
+    const { o, plan } = planOf(opts, race, "start", title);
+    const oval = plan.short;
+    const top = startsOnOppositeStraight(race);
+    const spots = startingPositions(oval, 0, top ? -1 : 1);
+    const names = [];
+    const flags = [];
+    for (const s of [...starters].sort((a, b) => a.position - b.position)) {
+        const spot = spots[s.position - 1];
+        // The skaters go left along the top straight and right along the bottom one: the names stand behind the line.
+        const dir = top ? -1 : 1;
+        names.push(clean({ x: spot.x - dir * (s.flag === undefined ? 1.2 : 2.6), y: spot.y, text: s.name, anchor: top ? "start" : "end", size: 0.9, title: s.country === undefined ? undefined : `${s.name}, ${s.country}` }));
+        if (s.flag !== undefined)
+            flags.push(clean({ x: spot.x - dir * 1.4, y: spot.y, shape: "logo", logo: s.flag, size: 0.8, title: s.country }));
+    }
+    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: 0.8 } });
+    layers.push({ kind: "text", id: "names", name: w.data.layers.names, ...AT, clip: "none", data: names, style: { size: 0.9, anchor: top ? "start" : "end", weight: 800 } });
+    const totals = { skaters: starters.length, pairs: starters.length === 0 ? 0 : 1 };
+    const summary = starters.length === 0 ? "" : fill(w.data.summaryGrid, { n: starters.length, race: raceName(race, language) });
+    const chart = assemble(o, layers, { title, summary, totals, tableLayers: ["names"] });
+    chart.table = () => `<table class="ky-table"><thead><tr><th>${w.data.columns.order}</th><th>${w.data.columns.skater}</th><th>${w.data.columns.country}</th></tr></thead><tbody>${[...starters].sort((a, b) => a.position - b.position).map((s) => `<tr><td>${s.position}</td><td>${esc(s.name)}</td><td>${esc(s.country ?? "")}</td></tr>`).join("")}</tbody></table>`;
+    return chart;
+}
+// ----- the results
+const MEDAL_COLOURS = { gold: "#d4a017", silver: "#b8bec6", bronze: "#b87333" };
+/**
+ * The results of a race as a leaderboard on the ice inside the track: for each skater with a place, a disc with the place (gold, silver and bronze for the first three), the name and the time; the splits
+ * as small marks along the skater's lane on the long track; and a table with the pair, the lane, the time, the splits and the lap times. Times are in seconds from the gun.
+ * @example
+ * ```ts
+ * import { skatingResults } from "@johnmorrisdotca/kyogijo-stadiums/skating";
+ * const chart = skatingResults([{ name: "A", place: 1, time: 34.3 }, { name: "B", place: 2, time: 34.5 }], { race: "500m" });
+ * console.log(chart.totals.winner?.name, chart.summary);
+ * // A A won the 500 m in 34.30.
+ * ```
+ */
+export function skatingResults(results, options = {}) {
+    if (!Array.isArray(results))
+        throw new TypeError("results is a list");
+    const track = trackOf(options);
+    const race = raceOf(options);
+    const language = languageOf(options);
+    const w = WORDS(language);
+    const title = fill(w.data.results, { race: raceName(race, language) });
+    const { o, plan } = planOf(options, race, undefined, title);
+    const sorted = [...results].sort((a, b) => (a.place ?? 999) - (b.place ?? 999));
+    const long = track === "long-track";
+    const unit = long ? 4.4 : 1.35;
+    const rows = Math.min(options.rows ?? (long ? 8 : 5), sorted.filter((r) => r.place !== undefined).length);
+    const discs = [];
+    const places = [];
+    const words = [];
+    const x0 = long ? -28 : -9;
+    const top = -((rows - 1) / 2) * unit * 1.25;
+    sorted.filter((r) => r.place !== undefined && isNum(r.time)).slice(0, rows).forEach((r, i) => {
+        const y = top + i * unit * 1.25;
+        const medal = r.place === 1 ? "gold" : r.place === 2 ? "silver" : r.place === 3 ? "bronze" : undefined;
+        discs.push(clean({ x: x0, y, shape: "circle", size: unit * 0.9, color: medal === undefined ? "#2f3a44" : MEDAL_COLOURS[medal], title: `${r.name}, ${medal === undefined ? "" : `${w.data.medals[medal]}, `}${formatTime(r.time)}` }));
+        places.push({ x: x0, y, text: r.place, size: unit * 0.55, color: medal === undefined ? "#ffffff" : "#1c1f1d" });
+        words.push({ x: x0 + unit * 0.9, y, text: `${r.name}  ${formatTime(r.time)}`, anchor: "start", size: unit * 0.55 });
+    });
+    const marks = [];
+    if (long && options.splits !== false) {
+        const oval = plan.oval;
+        for (const r of results) {
+            if (r.lane === undefined || r.splits === undefined)
+                continue;
+            const lane = r.lane === "inner" ? 0 : 1;
+            for (const sp of r.splits) {
+                if (!isNum(sp.distance) || !isNum(sp.time))
+                    continue;
+                const p = longAt(oval, race, lane, sp.distance);
+                marks.push({ x: round(p.x, 3), y: round(p.y, 3), shape: "circle", size: 1.1, title: fill(w.data.split, { d: round(sp.distance, 1), t: formatTime(sp.time) }), value: sp.time });
+            }
+        }
+    }
+    const layers = [];
+    if (marks.length > 0)
+        layers.push({ kind: "points", id: "splits", name: w.data.layers.splits, ...AT, clip: "none", data: marks, style: { size: 1.1, fill: "#f2c230" } });
+    layers.push({ kind: "points", id: "places", name: w.data.layers.medals, ...AT, clip: "none", data: discs, style: { size: unit * 0.9 } });
+    layers.push({ kind: "text", id: "place-numbers", name: w.data.layers.medals, ...AT, clip: "none", data: places, style: { size: unit * 0.55, weight: 800, halo: false } });
+    layers.push({ kind: "text", id: "skaters", name: w.data.layers.names, ...AT, clip: "none", data: words, style: { size: unit * 0.55, anchor: "start", weight: 800 } });
+    const winner = sorted.find((r) => r.place === 1 && isNum(r.time));
+    const totals = { skaters: results.length, finished: results.filter((r) => isNum(r.time) && r.place !== undefined).length, winner: winner === undefined ? null : { name: winner.name, time: winner.time } };
+    const summary = winner === undefined ? "" : fill(w.data.summaryResults, { winner: winner.name, race: raceName(race, language), time: formatTime(totals.winner?.time ?? 0) });
+    const chart = assemble(o, layers, { title, summary, totals, tableLayers: ["places"] });
+    chart.table = () => resultsTable(sorted, language);
+    return chart;
+}
+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("; ");
+        const laps = (r.laps ?? []).map((t, i) => fill(w.lap, { n: i + 1, t: formatTime(t) })).join("; ");
+        return `<tr><td>${r.place ?? ""}</td><td>${r.pair ?? ""}</td><td>${r.lane === undefined ? "" : r.lane === "inner" ? w.lanes.inner : w.lanes.outer}</td><td>${esc(r.name)}</td><td>${esc(r.country ?? "")}</td><td>${isNum(r.time) ? formatTime(r.time) : esc(r.note ?? "")}</td><td>${esc(splits)}</td><td>${esc(laps)}</td></tr>`;
+    })
+        .join("");
+    return `<table class="ky-table"><thead><tr><th>${c.place}</th><th>${c.pair}</th><th>${c.lane}</th><th>${c.skater}</th><th>${c.country}</th><th>${c.time}</th><th>${c.splits}</th><th>${c.laps}</th></tr></thead><tbody>${rows}</tbody></table>`;
+}
+/** The distance a skater has skated at a time, by the splits and the finish: straight lines between them, coasting for three seconds after the finish. */
+export function distanceSkated(runner, total, t) {
+    if (t <= 0)
+        return 0;
+    const pts = [[0, 0]];
+    for (const s of [...(runner.splits ?? [])].sort((a, b) => a.time - b.time))
+        if (s.time > 0 && 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);
+        }
+    }
+    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);
+}
+/**
+ * A replay of a race: every skater, from the gun, on his own way round the track (the long track's lane changed once a lap, on the crossing straight, and the first straight of the 1000 m and the 1500 m
+ * kept in the lane; the short track's oval of 111.12 m, the starters coming in from their positions), at the pace of the splits and the finish time. The positions are in the skating frame (metres
+ * from the middle of the rink). The team races, the mass start and the relays are not replayed.
+ * @example
+ * ```ts
+ * import { skatingReplay } from "@johnmorrisdotca/kyogijo-stadiums/skating";
+ * const replay = skatingReplay([{ name: "A", lane: "inner", time: 34.4 }, { name: "B", lane: "outer", time: 34.6 }], { race: "500m" });
+ * console.log(replay.timeline.frames.length > 40, replay.duration);
+ * // true 34.6
+ * ```
+ */
+export function skatingReplay(runners, options = {}) {
+    if (!Array.isArray(runners))
+        throw new TypeError("runners is a list");
+    trackOf(options);
+    const race = raceOf(options);
+    const info = raceById(race);
+    if (race === "mass-start" || race === "team-pursuit" || race === "team-sprint")
+        throw new RangeError(`The ${race} is not replayed: its skaters are not in lanes`);
+    const language = languageOf(options);
+    const w = WORDS(language);
+    const title = fill(w.data.replay, { race: raceName(race, language) });
+    const { o, plan } = planOf(options, race, undefined, title);
+    const step = isNum(options.step) && options.step > 0 ? options.step : 0.25;
+    for (const r of runners)
+        if (!isNum(r.time) || r.time <= 0)
+            throw new RangeError(`${String(r.name)}: the time is a number of seconds above zero`);
+    const total = info.distance;
+    const shortTotal = plan.short === undefined ? 0 : ISU_SHORT_TRACK.laps[race] * plan.short.lap;
+    const duration = Math.max(...runners.map((r) => r.time), 0);
+    const frames = [];
+    const at = (r, d) => {
+        if (plan.short !== undefined)
+            return shortAt(plan.short, race, r.position ?? 1, d);
+        return longAt(plan.oval, race, r.lane === "outer" ? 1 : 0, d);
+    };
+    const distance = plan.short === undefined ? total : shortTotal;
+    for (let k = 0; k * step <= duration + 3.2 + 1e-9; k += 1) {
+        const t = Math.round(k * step * 1000) / 1000;
+        const objects = [];
+        runners.forEach((r, i) => {
+            const p = at(r, distanceSkated(r, distance, t));
+            objects.push(clean({ id: `skater-${i + 1}`, team: r.lane === "outer" ? "away" : "home", x: round(p.x, 3), y: round(p.y, 3), label: r.name, number: plan.short === undefined ? (r.lane === "outer" ? 2 : 1) : (r.position ?? i + 1) }));
+        });
+        frames.push({ t, objects });
+    }
+    const events = [{ t: 0, kind: "gun", label: w.data.gun }];
+    runners.forEach((r, i) => {
+        const p = at(r, distance);
+        events.push({ t: r.time, kind: "finish", team: r.lane === "outer" ? "away" : "home", x: round(p.x, 3), y: round(p.y, 3), by: `skater-${i + 1}`, 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: "skating", units: "m" };
+    const summary = fill(w.data.summaryReplay, { n: runners.length, race: raceName(race, language) });
+    return { timeline, options: { ...o, title }, look: { trail: 0, scale: plan.short === undefined ? 0.8 : 0.7, numbers: true, hold: 2 }, title, summary, duration };
+}
+const KIND_SHAPE = { jump: "circle", spin: "star", "step-sequence": "diamond", "choreographic-sequence": "diamond", lift: "triangle", spiral: "square", twizzle: "x", "death-spiral": "star", throw: "cross" };
+/**
+ * The elements of a programme as marks on the rink: a mark for each element where it starts, its shape for its kind, the track of a step sequence or a spiral as a line to where it ends, and the order
+ * and the name beside it. Put them on the rink (`league: "isu-figure"`, the default for this chart).
+ * @example
+ * ```ts
+ * import { figureElements } from "@johnmorrisdotca/kyogijo-stadiums/skating";
+ * const chart = figureElements([{ kind: "jump", name: "3Lz", x: -12, y: 4, order: 1 }, { kind: "spin", name: "CCoSp4", x: 6, y: -3, order: 2 }]);
+ * console.log(chart.totals.elements, chart.totals.kinds.jump);
+ * // 2 1
+ * ```
+ */
+export function figureElements(elements, options = {}) {
+    if (!Array.isArray(elements))
+        throw new TypeError("elements is a list");
+    for (const e of elements) {
+        if (typeof e !== "object" || e === null || !ELEMENT_KINDS.includes(e.kind))
+            throw new Error(`Unknown kind of element "${String(e?.kind)}": use one of ${ELEMENT_KINDS.join(", ")}`);
+        if (!isNum(e.x) || !isNum(e.y))
+            throw new TypeError("each element has a place: x and y in metres from the middle of the rink");
+    }
+    const language = languageOf(options);
+    const w = WORDS(language);
+    const surface = { ...(options.surface ?? {}), league: options.surface?.league ?? "isu-figure" };
+    if (disciplineOf({ sport: "skating", league: surface.league }) !== "figure")
+        throw new RangeError('figureElements is for the figure skating rink: use league "isu-figure"');
+    const title = w.data.elements;
+    const o = drawingOptions("skating", { ...options, surface }, title, {});
+    const plan = skatingPlan({ sport: "skating", league: surface.league, skating: surface.skating });
+    const half = (plan.rink?.length ?? 60) / 2;
+    const wide = (plan.rink?.width ?? 30) / 2;
+    const sorted = [...elements].sort((a, b) => (a.order ?? 1e9) - (b.order ?? 1e9));
+    const points = [];
+    const lines = [];
+    const labels = [];
+    const kinds = {};
+    sorted.forEach((e, i) => {
+        kinds[e.kind] = (kinds[e.kind] ?? 0) + 1;
+        const x = Math.max(-half, Math.min(half, e.x));
+        const y = Math.max(-wide, Math.min(wide, e.y));
+        const kindName = ELEMENT_NAMES[e.kind][language];
+        points.push(clean({ x, y, shape: KIND_SHAPE[e.kind], team: e.team ?? "home", outcome: e.kind, title: e.title ?? `${e.order === undefined ? i + 1 : e.order}. ${e.name ?? kindName}` }));
+        if (isNum(e.x2) && isNum(e.y2))
+            lines.push(clean({ x, y, x2: Math.max(-half, Math.min(half, e.x2)), y2: Math.max(-wide, Math.min(wide, e.y2)), team: e.team }));
+        if (options.labels !== false)
+            labels.push({ x: x + 1.1, y: y - 1.1, text: `${e.order === undefined ? i + 1 : e.order}${e.name === undefined ? "" : ` ${e.name}`}`, size: 1.15, anchor: "start" });
+    });
+    const layers = [];
+    if (lines.length > 0)
+        layers.push({ kind: "lines", id: "paths", name: w.data.layers.paths, ...AT, clip: "none", data: lines.map((l) => clean({ x: l.x, y: l.y, x2: l.x2, y2: l.y2, team: l.team ?? "home" })), style: { width: 0.35, dash: "dashed" } });
+    layers.push({ kind: "points", id: "elements", name: w.data.layers.elements, ...AT, clip: "none", data: points, style: { size: 1.5 } });
+    if (labels.length > 0)
+        layers.push({ kind: "text", id: "labels", name: w.data.layers.elements, ...AT, clip: "none", data: labels, style: { size: 1.15, weight: 800 } });
+    const totals = { elements: elements.length, kinds };
+    const who = sorted.map((e) => e.name ?? ELEMENT_NAMES[e.kind][language]).slice(0, 6).join(language === "ja" ? "、" : ", ");
+    const summary = elements.length === 0 ? "" : fill(w.data.summaryElements, { n: elements.length, who });
+    const chart = assemble(o, layers, { title, summary, totals, tableLayers: ["elements"] });
+    chart.table = () => {
+        const c = w.data.columns;
+        const rows = sorted.map((e, i) => `<tr><td>${e.order ?? i + 1}</td><td>${esc(e.name ?? "")}</td><td>${esc(ELEMENT_NAMES[e.kind][language])}</td><td>${round(e.x, 1)}, ${round(e.y, 1)}</td></tr>`).join("");
+        return `<table class="ky-table"><thead><tr><th>${c.order}</th><th>${c.element}</th><th>${c.kind}</th><th>x, y (m)</th></tr></thead><tbody>${rows}</tbody></table>`;
+    };
+    return chart;
+}

package/dist/charts.soccer.js

@@ -65,7 +65,7 @@ export function soccerShotMap(shots, options = {}) {
     });
     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 data = shots.map((s) => clean({ id: s.id, 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;
@@ -140,7 +140,7 @@ export function soccerGoalMouth(shots, options = {}) {
     };
     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 rows = shots.map((s) => clean({ id: s.id, 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;
@@ -150,7 +150,7 @@ export function soccerGoalMouth(shots, options = {}) {
     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 rendered = renderLayers(surface, layers, false, undefined, undefined, () => undefined);
     const F = FEET_PER_METRE;
     const x0 = ((viewW - goalW) / 2) * F;
     const x1 = x0 + goalW * F;

package/dist/charts.types.d.ts

@@ -2,7 +2,7 @@ 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 { Language, SheetShow, 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>> {
@@ -48,6 +48,8 @@ export interface ChartOptions {
 }
 /** A shot as stats.nba.com's shot chart gives it: `LOC_X` and `LOC_Y` and whether it went in. */
 export interface NbaShot {
+    /** Your id for the shot, written on its mark as `data-mark-id`. */
+    id?: string | number;
     x: number | null;
     y: number | null;
     /** True for a shot that went in. Or give `outcome`. */
@@ -98,6 +100,8 @@ export interface NbaTotals {
 }
 /** A shot as the NHL's play-by-play gives it. */
 export interface NhlShot {
+    /** Your id for the shot, written on its mark as `data-mark-id`. */
+    id?: string | number;
     x: number | null;
     y: number | null;
     /** `goal`, `saved` (a shot on goal), `missed`, `blocked`, or `shot` for an attempt of no known result. */
@@ -152,6 +156,8 @@ export interface NhlTotals {
 }
 /** A ball in play. Give `x` and `y` in the frame, or for Retrosheet a `zone` (the location code, `8D`). */
 export interface Ball {
+    /** Your id for the shot, written on its mark as `data-mark-id`. */
+    id?: string | number;
     x?: number | null;
     y?: number | null;
     /** A Retrosheet hit-location code in place of `x` and `y`. */
@@ -197,6 +203,8 @@ export interface MlbTotals {
 }
 /** A pass. The destination is `x` and `y`; the passer's place is `fromX` and `fromY` when you have it. */
 export interface NflPass {
+    /** Your id for the shot, written on its mark as `data-mark-id`. */
+    id?: string | number;
     /** Where the ball came down or was caught, in the frame. */
     x: number | null;
     y: number | null;
@@ -246,6 +254,8 @@ export interface NflTotals {
 }
 /** A shot. The place is in the provider's frame; `goalY` and `goalZ` say where it crossed the goal line. */
 export interface SoccerShot {
+    /** Your id for the shot, written on its mark as `data-mark-id`. */
+    id?: string | number;
     x: number | null;
     y: number | null;
     /** `goal`, `saved`, `blocked`, `missed` or `post`. */
@@ -357,6 +367,58 @@ export interface CurlingOptions extends ChartOptions {
     units?: Unit;
     /** Write each stone's number on it. On by default, for the stones that have one. */
     numbers?: boolean;
+    /** How much of the sheet to draw: `half` (the default, the free guard zone and the house at `house`), `house`, `sheet` (the whole sheet), or `folded` (the whole sheet as a strip with both houses enlarged beside it). `surface.sheet.show` says the same and wins. */
+    show?: SheetShow;
+}
+/** What `curlingHeat` takes. */
+export interface CurlingHeatOptions extends ChartOptions {
+    /** 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;
+    /** Only this team's stones. Both by default. */
+    team?: "home" | "away";
+    /** Which stones: `all` of those in play (the default), `guards` (the free guards only: between the tee line and the hog line, outside the house) or `house` (those in or touching it). */
+    only?: "all" | "guards" | "house";
+    /** How the stones are drawn: `heatmap` (counts in square cells, the default), `hexbin`, `contour` (a density), `zones` (counted into the button, the rings and the free guard zone) or `discs` (each stone a translucent disc in its team's colour, so that stones that fall on each other build up colour). */
+    view?: "heatmap" | "hexbin" | "contour" | "zones" | "discs";
+    /** The width of a cell of the `heatmap`, or the radius of a hexagon of the `hexbin`, in feet. 1 foot by default. */
+    cell?: number;
+    /** How much of the sheet to draw, as for `curlingStones`: `half` by default. */
+    show?: SheetShow;
+    /** The teams' names, for the summary. */
+    names?: {
+        home?: string;
+        away?: string;
+    };
+    /** Write the number of stones in each cell, hexagon or zone. Off by default, except for the zones. */
+    labels?: boolean;
+}
+/** The numbers behind a heat chart of stones. */
+export interface CurlingHeatTotals {
+    /** Stones with a place, and the stones in play among them. */
+    stones: number;
+    inPlay: number;
+    /** The stones drawn: in play, and of the team and the kind asked for. */
+    drawn: number;
+    /** Of those in play, the free guards and the stones in the house, for each team. */
+    guards: {
+        home: number;
+        away: number;
+    };
+    house: {
+        home: number;
+        away: number;
+    };
+    /** Each zone of the house and the free guard zone, with the stones drawn that came to rest in it and their share of all drawn, as a percent. */
+    zones: {
+        id: string;
+        name: string;
+        stones: number;
+        share: number | null;
+    }[];
+    /** Rows left out for want of a place. */
+    skipped: number;
 }
 /** One stone as the chart judged it. */
 export interface CurlingStoneResult {

package/dist/colour.d.ts

@@ -17,13 +17,13 @@ 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
+ * A picture's address as it may be written into an image's `href`, or `undefined` (what `safeLogo` checks after it has looked for an emblem's id). 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)"));
+ * import { safePicture } from "@johnmorrisdotca/kyogijo-stadiums";
+ * console.log(safePicture("https://example.com/gulls.svg"), safePicture("javascript:alert(1)"));
  * // https://example.com/gulls.svg undefined
  * ```
  */
-export declare function safeLogo(value: unknown): string | undefined;
+export declare function safePicture(value: unknown): string | undefined;

package/dist/colour.js

@@ -64,16 +64,16 @@ export function inkOn(color) {
     return luminance(rgb) > 0.4 ? "#161a18" : "#ffffff";
 }
 /**
- * A logo's address as it may be written into an image's `href`, or `undefined`. An `https:` or `http:` address, a
+ * A picture's address as it may be written into an image's `href`, or `undefined` (what `safeLogo` checks after it has looked for an emblem's id). 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)"));
+ * import { safePicture } from "@johnmorrisdotca/kyogijo-stadiums";
+ * console.log(safePicture("https://example.com/gulls.svg"), safePicture("javascript:alert(1)"));
  * // https://example.com/gulls.svg undefined
  * ```
  */
-export function safeLogo(value) {
+export function safePicture(value) {
     if (typeof value !== "string")
         return undefined;
     const text = value.trim();