@johnmorrisdotca/kyogijo-stadiums 0.4.0 → 0.6.0

package/dist/pageant.js

@@ -0,0 +1,211 @@
+// The pageant: each team's flag or logo laid out large over its half of the surface, as a stadium lays giant flags and crests on the pitch for a final's ceremony
+// (a `carpet`: a rectangle at the flag's own ratio with a border; a `stage`: a crest on a large round disc with a ring), and an emblem or a trophy in the centre circle. This file
+// decides what is asked (`pageantOf`) and where each picture goes (`pageantLayout`); `pageant.draw.ts` draws them. Written for this package; the idea is a broadcast's, and no
+// flag, crest or emblem is drawn or supplied here.
+import { safeColour } from "./colour.js";
+import { renderedEmblem } from "./emblems-source.js";
+import { safeLogo } from "./logo.js";
+import { isNetSport } from "./court.js";
+/** The border band of a carpet, as a share of its shorter side: the least, the most and the usual. */
+export const PAGEANT_BORDER = { min: 0.02, max: 0.15, usual: 0.06 };
+/** The least and the most a carpet or a stage is scaled to, as a share of the room its half gives it. */
+export const PAGEANT_SCALE = { min: 0.4, max: 1 };
+/** The ratio of a carpet's width over its height: a flag of 3 to 2 unless the team or its SVG says otherwise, held between a square and 3 to 1. */
+export const PAGEANT_RATIO = { min: 1, max: 3, usual: 1.5 };
+/** How far a filled carpet's ratio may differ from its flag's, as a factor either way: the art is stretched and cropped by its square root. */
+export const PAGEANT_FILL_LIMIT = 1.75;
+/** What the plate is shrunk to when it stays in the middle of a pageant, so that the pictures have room. */
+const PLATE_SCALE = 0.85;
+const oneOf = (value, allowed) => allowed.includes(value) ? value : undefined;
+/** A colour or one of the words a choice also takes. */
+const colourOrWord = (value, words, fallback) => {
+    if (typeof value === "string" && words.includes(value))
+        return value;
+    return safeColour(value) ?? fallback;
+};
+const finite = (value, least, most, fallback) => (typeof value === "number" && Number.isFinite(value) ? Math.min(most, Math.max(least, value)) : fallback);
+/** The sports whose scoreboard covers the middle of the surface (a table of sets and games, an innings board): their score goes to the strip in a pageant. */
+const BOARDS = (sport) => isNetSport(sport) || sport === "cricket";
+/** The sports whose score is a plate that a pageant can shrink: a curling sheet's and a net court's boards are drawn to the room they are given and are not. */
+export const plateShrinks = (sport) => !BOARDS(sport) && sport !== "curling";
+/**
+ * What the options ask of a pageant, or `undefined` for none: `pageant` unset or `false`, a drawing with no score, one of the badge size, or a special game. A choice that is not one of
+ * the values is the default's; a colour must pass `safeColour`, the emblem `safeLogo`, a number is held to its range.
+ */
+export function pageantOf(o) {
+    const given = o.pageant;
+    if (given === undefined || given === false || given === null)
+        return undefined;
+    if (o.home === undefined || o.away === undefined || o.size === "badge" || o.host !== undefined)
+        return undefined;
+    const p = given === true ? {} : typeof given === "string" ? { style: given } : typeof given === "object" ? given : {};
+    const style = oneOf(p.style, ["carpet", "stage"]) ?? "carpet";
+    const href = safeLogo(p.emblem, { theme: o.theme === "light" || o.theme === "dark" ? o.theme : undefined });
+    const asked = oneOf(p.score, ["auto", "centre", "strip"]) ?? "auto";
+    // The emblem takes the middle, and a board is as wide as the middle: both send the score to the strip, unless the options say otherwise.
+    const score = asked === "auto" && (href !== undefined || BOARDS(o.sport)) ? "strip" : asked;
+    return {
+        style,
+        border: colourOrWord(p.border, ["dark", "team"], "dark"),
+        borderWidth: finite(p.borderWidth, PAGEANT_BORDER.min, PAGEANT_BORDER.max, PAGEANT_BORDER.usual),
+        fabric: p.fabric !== false,
+        lines: oneOf(p.lines, ["over", "under", "through"]) ?? "over",
+        ring: colourOrWord(p.ring, ["gold", "team"], "gold"),
+        ...(href === undefined ? {} : { emblem: { href, shape: oneOf(p.emblemShape, ["round", "plain"]) ?? "round", fit: oneOf(p.emblemFit, ["contain", "cover"]) ?? "contain", name: typeof p.emblemName === "string" && p.emblemName.trim() !== "" ? p.emblemName.trim().slice(0, 60) : undefined } }),
+        score,
+        scale: finite(p.scale, PAGEANT_SCALE.min, PAGEANT_SCALE.max, PAGEANT_SCALE.max),
+        fit: oneOf(p.fit, ["fill", "ratio"]) ?? "fill",
+        names: typeof p.names === "boolean" ? p.names : undefined,
+        animate: oneOf(p.animate, ["none", "unfurl", "fade"]) ?? "none",
+    };
+}
+/** The ratio of an SVG document's picture: its `viewBox`, else its `width` and `height`. */
+function svgRatio(text) {
+    const head = text.slice(0, 2000);
+    const open = /<svg\b[^>]*>/i.exec(head)?.[0] ?? head;
+    const box = /viewBox\s*=\s*["']\s*[-\d.e]+[\s,]+[-\d.e]+[\s,]+([\d.e]+)[\s,]+([\d.e]+)/i.exec(open);
+    if (box !== null && Number(box[1]) > 0 && Number(box[2]) > 0)
+        return Number(box[1]) / Number(box[2]);
+    const w = /\swidth\s*=\s*["']\s*([\d.]+)/i.exec(open);
+    const h = /\sheight\s*=\s*["']\s*([\d.]+)/i.exec(open);
+    return w !== null && h !== null && Number(w[1]) > 0 && Number(h[1]) > 0 ? Number(w[1]) / Number(h[1]) : undefined;
+}
+/** How wide a team's carpet is for its height: the team's `logoRatio`, else its SVG logo's own, else 3 to 2; held between a square and 3 to 1. */
+export function ratioOf(team) {
+    const clamp = (value) => Math.min(PAGEANT_RATIO.max, Math.max(PAGEANT_RATIO.min, value));
+    if (typeof team.logoRatio === "number" && Number.isFinite(team.logoRatio) && team.logoRatio > 0)
+        return clamp(team.logoRatio);
+    const logo = typeof team.logo === "string" ? team.logo.trim() : "";
+    let found;
+    if (renderedEmblem(logo) !== undefined)
+        found = 1;
+    else if (/^(?:<\?xml|<svg)\b/i.test(logo))
+        found = svgRatio(logo);
+    else if (/^data:image\/svg\+xml/i.test(logo)) {
+        const comma = logo.indexOf(",");
+        try {
+            const body = /;base64/i.test(logo.slice(0, comma)) ? atob(logo.slice(comma + 1)) : decodeURIComponent(logo.slice(comma + 1));
+            found = svgRatio(body);
+        }
+        catch {
+            found = undefined;
+        }
+    }
+    return clamp(found ?? PAGEANT_RATIO.usual);
+}
+/** A rectangle's outline, as points the outline's `contains` is asked about: corners, then more along each side. */
+function ring(cx, cy, w, h, grow, to) {
+    const out = [];
+    const hw = w / 2 + grow;
+    const hh = h / 2 + grow;
+    const steps = 6;
+    for (let i = 0; i <= steps; i += 1) {
+        const t = -1 + (2 * i) / steps;
+        for (const [ex, ey] of [[t * hw, -hh], [t * hw, hh], [-hw, t * hh], [hw, t * hh]]) {
+            const [dx, dy] = to(ex, ey);
+            out.push([cx + dx, cy + dy]);
+        }
+    }
+    return out;
+}
+const around = (cx, cy, r, grow) => Array.from({ length: 16 }, (_, i) => [cx + (r + grow) * Math.cos((i * Math.PI) / 8), cy + (r + grow) * Math.sin((i * Math.PI) / 8)]);
+/**
+ * Where each team's picture and the emblem go. A picture is sized to the room its half gives it (less a margin) at its own ratio, and is moved in until it lies inside the surface's outline
+ * (a rink's rounded corners, a ballpark's fence, an oval's curve). The middle is kept clear of the emblem and of the plate: the pictures are narrower where they must be.
+ * @returns `undefined` when the surface has no playing area to lay a picture on.
+ */
+export function pageantLayout(input) {
+    const { pageant: p, surface, outline, turned } = input;
+    const box = surface.whole ?? surface.box ?? outline.box;
+    if (!(box.w > 0 && box.h > 0))
+        return undefined;
+    const minDim = Math.min(box.w, box.h);
+    const margin = (p.fit === "fill" ? 0.05 : 0.03) * minDim;
+    const mid = box.x + box.w / 2;
+    const plan = surface.pageant;
+    const centre = plan?.centre ?? { cx: mid, cy: box.y + box.h / 2, r: surface.centreRadius ?? 0.14 * minDim };
+    const emblemR = p.emblem === undefined ? 0 : centre.r * 0.92;
+    const scale = plateShrinks(input.sport) ? PLATE_SCALE : 1;
+    // What the middle holds: the emblem's disc, the plate's length along the surface, the cricket pitch.
+    const plateAlong = input.plate && plateShrinks(input.sport) && plan?.left === undefined ? ((turned ? surface.plate.h : surface.plate.w) * scale) / 2 : 0;
+    const clear = Math.max(emblemR, plateAlong, plan?.clear ?? 0);
+    const eye = (ex, ey) => (turned ? [ey, -ex] : [ex, ey]);
+    const place = (team, which, spot) => {
+        const along = spot.x1 - spot.x0;
+        const across = spot.y1 - spot.y0;
+        const cx = (spot.x0 + spot.x1) / 2;
+        const cy = (spot.y0 + spot.y1) / 2;
+        // The room as the eye sees it: a tall drawing's halves lie one above the other.
+        const roomW = turned ? across : along;
+        const roomH = turned ? along : across;
+        if (p.style === "stage") {
+            let r = (spot.disc === undefined ? Math.min(roomW, roomH) : Math.min(spot.disc, roomW, roomH)) / 2 * p.scale;
+            for (let i = 0; i < 50 && !around(cx, cy, r, margin * 0.5).every(([x, y]) => outline.contains(x, y)); i += 1)
+                r *= 0.96;
+            return { team, spot: which, cx, cy, w: 2 * r, h: 2 * r, r };
+        }
+        const ratio = team.ratio;
+        let ratioOfCarpet = ratio;
+        let filled = false;
+        let w;
+        // In a round room (a curling house) the rectangle's corners lie on the circle; in a box it is the box's own shape that limits it.
+        if (spot.disc !== undefined)
+            w = Math.min(((spot.disc * ratio) / Math.sqrt(1 + ratio * ratio)) * 0.94, roomW, roomH * ratio) * p.scale;
+        else if (p.fit === "fill") {
+            // The carpet is the room's own shape, as far as its flag's ratio allows: not more than PAGEANT_FILL_LIMIT either way.
+            const shape = Math.min(Math.max(roomW / roomH, ratio / PAGEANT_FILL_LIMIT), ratio * PAGEANT_FILL_LIMIT);
+            w = Math.min(roomW, roomH * shape) * p.scale;
+            filled = true;
+            ratioOfCarpet = shape;
+        }
+        else
+            w = Math.min(roomW, roomH * ratio) * p.scale;
+        let h = w / ratioOfCarpet;
+        let px = cx;
+        for (let i = 0; i < 60 && !ring(px, cy, w, h, margin * 0.5, eye).every(([x, y]) => outline.contains(x, y)); i += 1) {
+            if (filled) {
+                // Pull in the outer edge, along the surface, so that a rink's rounded corner or a fence is cleared and the carpet keeps its full breadth across.
+                const cut = (turned ? h : w) * 0.03;
+                if (turned)
+                    h -= cut;
+                else
+                    w -= cut;
+                px += ((which === "left" ? 1 : -1) * cut) / 2;
+            }
+            else {
+                w *= 0.96;
+                h *= 0.96;
+            }
+        }
+        return { team, spot: which, cx: px, cy, w, h, ...(filled ? { filled } : {}) };
+    };
+    const spotOf = (side) => {
+        const given = side === "left" ? plan?.left : plan?.right;
+        if (given !== undefined)
+            return { x0: given.cx - given.w / 2, x1: given.cx + given.w / 2, y0: given.cy - given.h / 2, y1: given.cy + given.h / 2, ...(given.disc === undefined ? {} : { disc: given.disc }) };
+        const y0 = box.y + margin;
+        const y1 = box.y + box.h - margin;
+        return side === "left" ? { x0: box.x + margin, x1: mid - clear - margin, y0, y1 } : { x0: mid + clear + margin, x1: box.x + box.w - margin, y0, y1 };
+    };
+    const pictures = [place(input.left, "left", spotOf("left")), place(input.right, "right", spotOf("right"))];
+    if (!pictures.every((picture) => picture.w > 0 && picture.h > 0 && Number.isFinite(picture.cx + picture.cy)))
+        return undefined;
+    const layout = { pictures, plateScale: scale };
+    if (p.emblem !== undefined && emblemR > 0)
+        layout.emblem = { cx: centre.cx, cy: centre.cy, r: emblemR };
+    return layout;
+}
+/** How much of their width the pictures must keep with the plate in the middle, against without it, before the plate in the middle gives way to the strip. */
+export const PLATE_COST = 0.7;
+/**
+ * Where the score goes when the options say `auto` and there is no emblem or board: the plate stays in the middle if the pictures lose little of their size to it, otherwise the score
+ * goes to the strip under the drawing and the pictures take the room.
+ */
+export function autoScore(input) {
+    const withPlate = pageantLayout({ ...input, plate: true });
+    const without = pageantLayout({ ...input, plate: false });
+    if (withPlate === undefined || without === undefined)
+        return "centre";
+    const size = (layout) => Math.min(...layout.pictures.map((picture) => picture.w));
+    return size(withPlate) >= PLATE_COST * size(without) ? "centre" : "strip";
+}

package/dist/pageant.style.d.ts

@@ -0,0 +1,8 @@
+/** The pageant's colours, light and dark. */
+export declare const KYOGIJO_PAGEANT_STYLE: string;
+/**
+ * The entrance (`animate: "unfurl"` or `"fade"`), in CSS only, and only for a reader who has not asked for less motion: a carpet rolls out from its own end, a stage and the emblem
+ * grow, and `fade` brings each in. The end state is the drawing's own, so a reader who has asked for less sees it at once, and a renderer that reads no CSS animation (the canvas,
+ * the PNG) draws it finished. The second team's picture and then the emblem come a little later.
+ */
+export declare const KYOGIJO_PAGEANT_MOTION: string;

package/dist/pageant.style.js

@@ -0,0 +1,42 @@
+// The pageant's rules: the colours of a carpet's border and fabric, of a stage's disc and ring, and the entrance. The colours are custom properties with fallbacks (`--ky-pg-border`,
+// `--ky-pg-edge`, `--ky-pg-seam`, `--ky-pg-shadow`, `--ky-pg-disc`, `--ky-pg-groove`, `--ky-pg-light`), so a page can set them; the dark ones are the dark theme's. A drawing with a
+// pageant writes these in; `KYOGIJO_STYLE` has them for a page that draws with `style: "none"`.
+/** The pageant's colours, light and dark. */
+export const KYOGIJO_PAGEANT_STYLE = `
+.kyogijo .ky-pg-border{fill:var(--ky-pg-border,#14181a)}
+.kyogijo .ky-pg-edge{fill:none;stroke:var(--ky-pg-edge,rgba(255,255,255,.55))}
+.kyogijo .ky-pg-seam{fill:none;stroke:var(--ky-pg-seam,rgba(0,0,0,.4))}
+.kyogijo .ky-pg-shadow{fill:var(--ky-pg-shadow,rgba(0,0,0,.26))}
+.kyogijo .ky-pg-ground{fill:var(--c,#d9dde0)}
+.kyogijo .ky-pg-plain{fill:var(--c,var(--ky-mark-plain,#f4f5f6))}
+.kyogijo .ky-pg-band{fill:var(--ci,#fff)}
+.kyogijo .ky-pg-name{fill:var(--c,#14181a);text-anchor:middle}
+.kyogijo .ky-pg-disc{fill:var(--ky-pg-disc,#101417)}
+.kyogijo .ky-pg-groove{fill:none;stroke:var(--ky-pg-groove,rgba(0,0,0,.5))}
+.kyogijo .ky-pg-light{fill:var(--ky-pg-light,#f7f4ea)}
+.kyogijo .ky-pg-pill{fill:var(--ky-plate,rgba(18,24,21,.9))}
+.kyogijo .ky-pg-pilltext{fill:var(--ky-plate-ink,#fff);text-anchor:middle}
+@media (prefers-color-scheme:dark){:where(html:not([data-theme=light]) .kyogijo:not([data-theme=light])){--ky-pg-border:#050709;--ky-pg-edge:rgba(255,255,255,.42);--ky-pg-seam:rgba(0,0,0,.6);--ky-pg-shadow:rgba(0,0,0,.45);--ky-pg-disc:#07090b;--ky-pg-light:#e9e5d6}}
+:where(html[data-theme=dark] .kyogijo,.kyogijo[data-theme=dark]){--ky-pg-border:#050709;--ky-pg-edge:rgba(255,255,255,.42);--ky-pg-seam:rgba(0,0,0,.6);--ky-pg-shadow:rgba(0,0,0,.45);--ky-pg-disc:#07090b;--ky-pg-light:#e9e5d6}`.trim();
+/**
+ * The entrance (`animate: "unfurl"` or `"fade"`), in CSS only, and only for a reader who has not asked for less motion: a carpet rolls out from its own end, a stage and the emblem
+ * grow, and `fade` brings each in. The end state is the drawing's own, so a reader who has asked for less sees it at once, and a renderer that reads no CSS animation (the canvas,
+ * the PNG) draws it finished. The second team's picture and then the emblem come a little later.
+ */
+export const KYOGIJO_PAGEANT_MOTION = `
+@media (prefers-reduced-motion:no-preference){
+.kyogijo .ky-pg-fade .ky-pg-art{animation:ky-pg-fade .8s ease-out both}
+.kyogijo .ky-pg-unfurl .ky-pg-art{transform-box:fill-box;animation:ky-pg-unfurl-x .95s cubic-bezier(.22,.8,.28,1) both}
+.kyogijo .ky-pg-unfurl.ky-pg-left .ky-pg-art{transform-origin:0 50%}
+.kyogijo .ky-pg-unfurl.ky-pg-right .ky-pg-art{transform-origin:100% 50%}
+.kyogijo .ky-pg-unfurl.ky-pg-tall .ky-pg-art{animation-name:ky-pg-unfurl-y}
+.kyogijo .ky-pg-unfurl.ky-pg-tall.ky-pg-left .ky-pg-art{transform-origin:50% 0}
+.kyogijo .ky-pg-unfurl.ky-pg-tall.ky-pg-right .ky-pg-art{transform-origin:50% 100%}
+.kyogijo .ky-pg-unfurl.ky-pg-stage .ky-pg-art,.kyogijo .ky-pg-unfurl.ky-pg-emblem .ky-pg-art{animation-name:ky-pg-grow;transform-origin:50% 50%}
+.kyogijo .ky-pg-right .ky-pg-art{animation-delay:.16s}
+.kyogijo .ky-pg-emblem .ky-pg-art{animation-delay:.34s}
+@keyframes ky-pg-fade{from{opacity:0}to{opacity:1}}
+@keyframes ky-pg-unfurl-x{from{transform:scaleX(.02);opacity:.3}to{transform:none;opacity:1}}
+@keyframes ky-pg-unfurl-y{from{transform:scaleY(.02);opacity:.3}to{transform:none;opacity:1}}
+@keyframes ky-pg-grow{from{transform:scale(.55);opacity:0}to{transform:none;opacity:1}}
+}`.trim();

package/dist/png.d.ts

@@ -1,4 +1,4 @@
-import type { SceneOptions, SceneSource } from "./scene.types.ts";
+import type { Scene, SceneItem, SceneOptions, SceneSource } from "./scene.types.ts";
 /** What `toPNG` takes besides the drawing. */
 export interface PngOptions extends SceneOptions {
     /** The width of the picture in pixels. 1200 when neither a width nor a height is given. */
@@ -9,6 +9,13 @@ export interface PngOptions extends SceneOptions {
     /** Options for resvg's font handling, passed as its `font` option (`{ fontFiles: [...], loadSystemFonts: false }`). */
     font?: Record<string, unknown>;
 }
+/**
+ * A shape wholly outside the drawing's frame, stroke included. resvg (the PNG renderer) stops the whole process, with a panic in its geometry code, on a shape with an opacity below 1 that lies wholly outside the
+ * viewBox (a goal's net beyond a soccer pitch's penalty area, seen through a range), and such a shape paints nothing, so it is left out of the picture. Text and images are kept.
+ */
+export declare function isOutside(item: SceneItem, view: Scene["viewBox"]): boolean;
+/** The scene without the shapes that lie wholly outside its frame. */
+export declare function cullOutside(scene: Scene): Scene;
 /** The message of the error thrown when the peer is not there. */
 export declare const PNG_PEER_MISSING = "toPNG needs the optional package @resvg/resvg-js: install it with `npm install @resvg/resvg-js`. It runs in Node only; in a browser draw to a canvas with drawToCanvas and call canvas.toBlob.";
 /**

package/dist/png.js

@@ -9,6 +9,26 @@ var __rewriteRelativeImportExtension = (this && this.__rewriteRelativeImportExte
 // A drawing as a PNG, in Node, through resvg (the optional peer `@resvg/resvg-js`). The SVG is first written without a stylesheet (see `sceneToSvg`),
 // because resvg does not read CSS variables. In a browser, draw to a canvas (`drawToCanvas`) and ask it for a PNG instead.
 import { sceneToSvg } from "./scene.flat.js";
+import { boundsOf } from "./scene.path.js";
+import { sceneOf } from "./scene.js";
+/**
+ * A shape wholly outside the drawing's frame, stroke included. resvg (the PNG renderer) stops the whole process, with a panic in its geometry code, on a shape with an opacity below 1 that lies wholly outside the
+ * viewBox (a goal's net beyond a soccer pitch's penalty area, seen through a range), and such a shape paints nothing, so it is left out of the picture. Text and images are kept.
+ */
+export function isOutside(item, view) {
+    if (item.kind === "text" || item.kind === "image")
+        return false;
+    const box = boundsOf(item, item.matrix);
+    if (box === undefined)
+        return false;
+    const [a, b, c, d] = item.matrix;
+    const pad = (item.style.stroke === "none" ? 0 : item.style.strokeWidth * Math.sqrt(Math.abs(a * d - b * c)) * 1.5) + 0.5;
+    return box.x + box.w + pad < view.x || box.x - pad > view.x + view.w || box.y + box.h + pad < view.y || box.y - pad > view.y + view.h;
+}
+/** The scene without the shapes that lie wholly outside its frame. */
+export function cullOutside(scene) {
+    return { ...scene, items: scene.items.filter((item) => !isOutside(item, scene.viewBox)) };
+}
 /** The message of the error thrown when the peer is not there. */
 export const PNG_PEER_MISSING = "toPNG needs the optional package @resvg/resvg-js: install it with `npm install @resvg/resvg-js`. It runs in Node only; in a browser draw to a canvas with drawToCanvas and call canvas.toBlob.";
 /**
@@ -36,7 +56,7 @@ export async function toPNG(source, options = {}) {
         throw new Error(PNG_PEER_MISSING);
     }
     const wide = options.width === undefined && options.height === undefined ? 1200 : options.width;
-    const svg = sceneToSvg(source, { theme: options.theme, css: options.css });
+    const svg = sceneToSvg(cullOutside(sceneOf(source, { theme: options.theme, css: options.css })), { theme: options.theme, css: options.css });
     const resvg = new mod.Resvg(svg, {
         fitTo: wide !== undefined ? { mode: "width", value: wide } : { mode: "height", value: options.height },
         ...(options.background === undefined ? {} : { background: options.background }),

package/dist/pointer-entry.d.ts

@@ -0,0 +1,2 @@
+export { clientPointToField, clientPointToFrames, fieldPointToClient } from "./pointer.ts";
+export type { ElementLike, FieldPoint, MatrixLike, PointerOptions, SvgLike } from "./pointer.ts";

package/dist/pointer-entry.js

@@ -0,0 +1,2 @@
+// A click on a drawing as a place on the field: the pointer in a provider's numbers with the zone, and the way back.
+export { clientPointToField, clientPointToFrames, fieldPointToClient } from "./pointer.js";

package/dist/pointer.d.ts

@@ -0,0 +1,113 @@
+import { type Attacking, type Frame } from "./frames.ts";
+import { type PlaceLike, type ZoneOptions } from "./rules.ts";
+import { type Unit } from "./units.ts";
+import type { Language } from "./types.ts";
+/** The six numbers of a matrix, as an SVG's `DOMMatrix` has them. */
+export interface MatrixLike {
+    a: number;
+    b: number;
+    c: number;
+    d: number;
+    e: number;
+    f: number;
+}
+/** What the functions need of an element of the drawing: its attributes, and for the surface group its matrix to the page. */
+export interface ElementLike {
+    getAttribute(name: string): string | null;
+    getScreenCTM?(): MatrixLike | null;
+}
+/** What the functions need of the drawing's `<svg>`: to find the surface group in it. A real `SVGSVGElement` is one. */
+export interface SvgLike extends ElementLike {
+    querySelector(selectors: string): unknown;
+    closest?(selectors: string): unknown;
+}
+/** What the pointer functions take besides the position. */
+export interface PointerOptions {
+    /** The frame the answer is written in: the name of a frame of the drawing's sport (`nhl-api`, `opta`, `statsbomb`, `mlbam`), a frame, or `"surface"` for the drawing's own numbers (feet, or `units`). `"surface"` when missing. */
+    provider?: Frame | string;
+    /** The unit of the `"surface"` numbers: feet when missing. */
+    units?: Unit;
+    /** The end the provider's team attacks, as in `toSurface`: `left` says the provider's numbers are of a team that attacks the left end of the surface as it is drawn wide. */
+    attacking?: Attacking;
+    /** The language of the zone names. */
+    language?: Language;
+    /** The size of the surface when the frame is a variable one, in place of the drawing's own. */
+    size?: ZoneOptions["size"];
+}
+/** Where the pointer is on the field. */
+export interface FieldPoint {
+    /** The place in the provider's frame (feet in the drawing's wide frame for `"surface"`). */
+    x: number;
+    y: number;
+    /** The frame's name. */
+    provider: string;
+    /** The place on the surface: feet in the drawing's wide frame (x along the surface from the left, y across it from the top). */
+    surface: {
+        x: number;
+        y: number;
+    };
+    /** True when the pointer is on the surface, or on its edge: not on the apron, the stands or the page round it. */
+    inBounds: boolean;
+    /** The zone and the finer area, by id (`zoneAt` in the zones entry): `undefined` off the surface. */
+    zone: string | undefined;
+    subzone: string | undefined;
+    /** Every id that holds, with its name. */
+    zones: string[];
+    names: Record<string, string>;
+}
+/**
+ * Where a page position is on the field of a drawing, in a provider's numbers, with the zone the rules put it in. `svg` is the drawing's `<svg>` element, and
+ * the position is a pointer event's `clientX` and `clientY`. It holds whatever the drawing is: wide or tall, any size or padding, a range, a cropped viewBox. It answers `null` for
+ * a drawing with no surface to ask (a badge, a special game, or the 3D view, whose floor is laid in CSS 3D). `provider` names a frame of the drawing's sport (`nhl-api`,
+ * `opta`, `statsbomb`, `mlbam`...) and a frame of another sport is an error; without one, the numbers are the surface's own in feet.
+ * @example
+ * ```ts no-run
+ * import { clientPointToField } from "@johnmorrisdotca/kyogijo-stadiums/pointer";
+ * const svg = document.querySelector<SVGSVGElement>("svg.kyogijo")!;
+ * svg.addEventListener("click", (event) => {
+ *   const at = clientPointToField(svg, event.clientX, event.clientY, { provider: "nhl-api" });
+ *   if (at !== null) console.log(at.x, at.y, at.zone, at.inBounds);
+ * });
+ * ```
+ */
+export declare function clientPointToField(svg: SvgLike | Element, clientX: number, clientY: number, options?: PointerOptions): FieldPoint | null;
+/**
+ * The page position of a place on the field: the undoing of `clientPointToField`. The place is in a provider's numbers (or the surface's own, in feet or `units`); the answer is
+ * `clientX` and `clientY`, to put a marker over the drawing with. `null` for a drawing with no surface to ask.
+ * @example
+ * ```ts no-run
+ * import { fieldPointToClient } from "@johnmorrisdotca/kyogijo-stadiums/pointer";
+ * const svg = document.querySelector<SVGSVGElement>("svg.kyogijo")!;
+ * const at = fieldPointToClient(svg, [69, 22], { provider: "nhl-api" });
+ * declare const marker: HTMLElement;
+ * if (at !== null) marker.style.transform = `translate(${at.x}px, ${at.y}px)`;
+ * ```
+ */
+export declare function fieldPointToClient(svg: SvgLike | Element, point: PlaceLike, options?: PointerOptions): {
+    x: number;
+    y: number;
+} | null;
+/**
+ * The same page position in each of several frames at once, with the zone: what a readout that shows a place in every provider asks (the demo's). `providers` defaults to every
+ * frame of the drawing's sport.
+ * @example
+ * ```ts no-run
+ * import { clientPointToFrames } from "@johnmorrisdotca/kyogijo-stadiums/pointer";
+ * const svg = document.querySelector<SVGSVGElement>("svg.kyogijo")!;
+ * svg.addEventListener("pointermove", (event) => {
+ *   const all = clientPointToFrames(svg, event.clientX, event.clientY);
+ *   console.log(all?.points.map((p) => `${p.provider}: ${p.x}, ${p.y}`), all?.zone);
+ * });
+ * ```
+ */
+export declare function clientPointToFrames(svg: SvgLike | Element, clientX: number, clientY: number, options?: Omit<PointerOptions, "provider"> & {
+    providers?: readonly (Frame | string)[];
+}): (Omit<FieldPoint, "x" | "y" | "provider"> & {
+    points: {
+        provider: string;
+        title: string;
+        unit: string;
+        x: number;
+        y: number;
+    }[];
+}) | null;

package/dist/pointer.js

@@ -0,0 +1,151 @@
+// A click on a drawing, as a place on the field. `clientPointToField(svg, clientX, clientY, { provider })` asks the drawing where the pointer is: the browser's own
+// matrix for the surface group (`getScreenCTM`) carries a page coordinate back through the CSS size, the viewBox and its padding, the preserved aspect ratio, a
+// tall drawing's quarter turn and a range's crop, to the surface's wide frame in feet; the frame of the provider (frames.ts) turns that into the provider's numbers,
+// and the rules engine (rules.ts) names the zone. `fieldPointToClient` is the way back. A drawing writes the box of its surface and the options that decide its rules
+// on its surface group (field.data.ts), so the answer needs nothing but the SVG.
+import { FRAMES, frameByName, fromSurface, toSurface } from "./frames.js";
+import { frameSizeOf } from "./outline.js";
+import { readField } from "./field.data.js";
+import { zoneAtSurface } from "./rules.js";
+import { FEET_PER, isUnit } from "./units.js";
+const invert = (m) => {
+    const det = m.a * m.d - m.b * m.c;
+    if (!Number.isFinite(det) || Math.abs(det) < 1e-12)
+        return undefined;
+    return { a: m.d / det, b: -m.b / det, c: -m.c / det, d: m.a / det, e: (m.c * m.f - m.d * m.e) / det, f: (m.b * m.e - m.a * m.f) / det };
+};
+const apply = (m, x, y) => [m.a * x + m.c * y + m.e, m.b * x + m.d * y + m.f];
+/** The surface group of a drawing and what it says of its surface, or `undefined` for one the question does not apply to: a badge, a special game, a 3D view. */
+function find(svg) {
+    const root = svg;
+    // The 3D view lays the floor in CSS 3D, where the browser's matrix for an SVG element is the flat drawing's: it would answer for a place that is not under the pointer.
+    if (typeof root.closest === "function" && root.closest(".ky-turn") !== null)
+        return undefined;
+    const group = root.querySelector(".ky-surface-group");
+    if (group === null || typeof group.getAttribute !== "function")
+        return undefined;
+    const field = readField((name) => group.getAttribute(name));
+    const sport = root.getAttribute("data-sport");
+    if (field === undefined || sport === null)
+        return undefined;
+    return { sport: sport, league: root.getAttribute("data-league") ?? undefined, box: field.box, rules: field.rules, group };
+}
+const unitOf = (units) => (units !== undefined && isUnit(units) ? units : "ft");
+function frameOf(found, provider) {
+    if (provider === undefined || provider === "surface")
+        return undefined;
+    const frame = typeof provider === "string" ? frameByName(provider) : provider;
+    if (frame.sport !== found.sport)
+        throw new RangeError(`The frame "${frame.name}" is for ${frame.sport}, and this drawing is of ${found.sport}: use one of ${Object.values(FRAMES).filter((f) => f.sport === found.sport).map((f) => f.name).join(", ") || "surface"}`);
+    return frame;
+}
+const sizeOf = (found, options) => {
+    if (options.size !== undefined)
+        return options.size;
+    return frameSizeOf({ sport: found.sport, league: found.league }, { w: found.box.w, h: found.box.h });
+};
+/** The place on the surface, in feet, under a page position; `undefined` where the drawing has no matrix to ask (not in the page, or hidden). */
+function toLocal(found, clientX, clientY) {
+    const matrix = found.group.getScreenCTM?.();
+    if (matrix === null || matrix === undefined)
+        return undefined;
+    const back = invert(matrix);
+    return back === undefined ? undefined : apply(back, clientX, clientY);
+}
+/**
+ * Where a page position is on the field of a drawing, in a provider's numbers, with the zone the rules put it in. `svg` is the drawing's `<svg>` element, and
+ * the position is a pointer event's `clientX` and `clientY`. It holds whatever the drawing is: wide or tall, any size or padding, a range, a cropped viewBox. It answers `null` for
+ * a drawing with no surface to ask (a badge, a special game, or the 3D view, whose floor is laid in CSS 3D). `provider` names a frame of the drawing's sport (`nhl-api`,
+ * `opta`, `statsbomb`, `mlbam`...) and a frame of another sport is an error; without one, the numbers are the surface's own in feet.
+ * @example
+ * ```ts no-run
+ * import { clientPointToField } from "@johnmorrisdotca/kyogijo-stadiums/pointer";
+ * const svg = document.querySelector<SVGSVGElement>("svg.kyogijo")!;
+ * svg.addEventListener("click", (event) => {
+ *   const at = clientPointToField(svg, event.clientX, event.clientY, { provider: "nhl-api" });
+ *   if (at !== null) console.log(at.x, at.y, at.zone, at.inBounds);
+ * });
+ * ```
+ */
+export function clientPointToField(svg, clientX, clientY, options = {}) {
+    if (!Number.isFinite(clientX) || !Number.isFinite(clientY))
+        throw new TypeError("clientX and clientY are numbers");
+    const found = find(svg);
+    if (found === undefined)
+        return null;
+    const local = toLocal(found, clientX, clientY);
+    if (local === undefined)
+        return null;
+    const frame = frameOf(found, options.provider);
+    const unit = unitOf(options.units);
+    let x;
+    let y;
+    if (frame === undefined)
+        [x, y] = [local[0] / FEET_PER[unit], local[1] / FEET_PER[unit]];
+    else
+        [x, y] = fromSurface([local], { to: frame, size: sizeOf(found, options), attacking: options.attacking })[0];
+    const rules = { ...found.rules, league: found.league ?? found.rules.league, language: options.language };
+    const zone = zoneAtSurface(found.sport, local, rules);
+    return { x, y, provider: frame?.name ?? "surface", surface: { x: local[0], y: local[1] }, inBounds: zone.inBounds, zone: zone.zone, subzone: zone.subzone, zones: zone.zones, names: zone.names };
+}
+/**
+ * The page position of a place on the field: the undoing of `clientPointToField`. The place is in a provider's numbers (or the surface's own, in feet or `units`); the answer is
+ * `clientX` and `clientY`, to put a marker over the drawing with. `null` for a drawing with no surface to ask.
+ * @example
+ * ```ts no-run
+ * import { fieldPointToClient } from "@johnmorrisdotca/kyogijo-stadiums/pointer";
+ * const svg = document.querySelector<SVGSVGElement>("svg.kyogijo")!;
+ * const at = fieldPointToClient(svg, [69, 22], { provider: "nhl-api" });
+ * declare const marker: HTMLElement;
+ * if (at !== null) marker.style.transform = `translate(${at.x}px, ${at.y}px)`;
+ * ```
+ */
+export function fieldPointToClient(svg, point, options = {}) {
+    const found = find(svg);
+    if (found === undefined)
+        return null;
+    const matrix = found.group.getScreenCTM?.();
+    if (matrix === null || matrix === undefined)
+        return null;
+    const xy = Array.isArray(point) ? point : [point.x, point.y];
+    const [px, py] = xy;
+    if (typeof px !== "number" || typeof py !== "number" || !Number.isFinite(px) || !Number.isFinite(py))
+        throw new TypeError("a point is [x, y] or { x, y }, two finite numbers");
+    const frame = frameOf(found, options.provider);
+    const unit = unitOf(options.units);
+    const local = frame === undefined ? [px * FEET_PER[unit], py * FEET_PER[unit]] : toSurface([[px, py]], { from: frame, size: sizeOf(found, options), attacking: options.attacking })[0];
+    const [x, y] = apply(matrix, local[0], local[1]);
+    return { x, y };
+}
+/**
+ * The same page position in each of several frames at once, with the zone: what a readout that shows a place in every provider asks (the demo's). `providers` defaults to every
+ * frame of the drawing's sport.
+ * @example
+ * ```ts no-run
+ * import { clientPointToFrames } from "@johnmorrisdotca/kyogijo-stadiums/pointer";
+ * const svg = document.querySelector<SVGSVGElement>("svg.kyogijo")!;
+ * svg.addEventListener("pointermove", (event) => {
+ *   const all = clientPointToFrames(svg, event.clientX, event.clientY);
+ *   console.log(all?.points.map((p) => `${p.provider}: ${p.x}, ${p.y}`), all?.zone);
+ * });
+ * ```
+ */
+export function clientPointToFrames(svg, clientX, clientY, options = {}) {
+    const found = find(svg);
+    if (found === undefined)
+        return null;
+    const first = clientPointToField(svg, clientX, clientY, { ...options, provider: "surface" });
+    if (first === null)
+        return null;
+    const list = options.providers ?? Object.values(FRAMES).filter((frame) => frame.sport === found.sport);
+    const points = list.map((entry) => {
+        const frame = typeof entry === "string" ? frameByName(entry) : entry;
+        const [x, y] = fromSurface([[first.surface.x, first.surface.y]], { to: frame, size: sizeOf(found, options), attacking: options.attacking })[0];
+        return { provider: frame.name, title: frame.title, unit: frame.unit, x, y };
+    });
+    const { x: _x, y: _y, provider: _provider, ...rest } = first;
+    void _x;
+    void _y;
+    void _provider;
+    return { ...rest, points };
+}