@johnmorrisdotca/kyogijo-stadiums 0.0.0-stage → 0.4.0

package/dist/react-entry.js

@@ -0,0 +1,2 @@
+// A helper for React that does not depend on it: props to spread onto a div, and a component made from the React you pass.
+export { createKyogijo, kyogijoHtml, kyogijoProps } from "./react.js";

package/dist/react.d.ts

@@ -0,0 +1,53 @@
+import type { ScoreOptions, SurfaceOptions } from "./types.ts";
+/** The drawing as the object React's `dangerouslySetInnerHTML` takes. */
+export declare function kyogijoHtml(options: SurfaceOptions | ScoreOptions): {
+    __html: string;
+};
+/**
+ * Props for a `div` (or any element) that holds a drawing, to spread onto it: no component, no dependency on React.
+ * With `orientation: "auto"` and no `aspect`, the drawing is wide; use `createKyogijo` for a container that is measured.
+ * @example
+ * ```ts
+ * import { kyogijoProps } from "@johnmorrisdotca/kyogijo-stadiums/react";
+ * const props = kyogijoProps({ sport: "nba", away: { name: "Harbour City Gulls", score: 108 }, home: { name: "Prairie Ridge Bison", score: 112 }, status: "final" });
+ * console.log(props["data-kyogijo"], props.dangerouslySetInnerHTML.__html.startsWith("<svg"));
+ * // nba true
+ * ```
+ */
+export declare function kyogijoProps(options: SurfaceOptions | ScoreOptions): {
+    dangerouslySetInnerHTML: {
+        __html: string;
+    };
+    "data-kyogijo": string;
+    "data-orientation": "landscape" | "portrait";
+};
+/** The part of React the component uses; pass the `React` you have, and nothing here imports it. */
+export interface ReactLike {
+    createElement(type: string, props: Record<string, unknown> | null, ...children: unknown[]): unknown;
+    useRef<T>(initial: T): {
+        current: T;
+    };
+    useState<S>(initial: S): [S, (next: S) => void];
+    useEffect(effect: () => void | (() => void), deps?: unknown[]): void;
+}
+/** The props of the component `createKyogijo` makes: the options, and the usual `className` and `style` of its `div`. */
+export type KyogijoProps = (SurfaceOptions | ScoreOptions) & {
+    containerClassName?: string;
+    containerStyle?: Record<string, unknown>;
+    breakpoint?: number;
+};
+/**
+ * A React component made from the `React` you give it. It draws the options, and with `orientation: "auto"` measures its
+ * own box and lays the drawing out tall or wide as the box changes.
+ * @example
+ * ```ts
+ * import { createKyogijo } from "@johnmorrisdotca/kyogijo-stadiums/react";
+ * // With React: `const Kyogijo = createKyogijo(React);` and then `<Kyogijo sport="nhl" orientation="auto" />`.
+ * // Here a stand-in for React, to show what comes out:
+ * const Kyogijo = createKyogijo({ createElement: (type, props) => ({ type, props }), useRef: (initial) => ({ current: initial }), useState: (initial) => [initial, () => {}], useEffect: () => {} });
+ * const element = Kyogijo({ sport: "nhl" }) as { type: string };
+ * console.log(element.type);
+ * // div
+ * ```
+ */
+export declare function createKyogijo(React: ReactLike): (props: KyogijoProps) => unknown;

package/dist/react.js

@@ -0,0 +1,58 @@
+import { drawKyogijo, isPortrait } from "./draw.js";
+import { containerAspect } from "./mount.js";
+/** The drawing as the object React's `dangerouslySetInnerHTML` takes. */
+export function kyogijoHtml(options) {
+    return { __html: drawKyogijo(options) };
+}
+/**
+ * Props for a `div` (or any element) that holds a drawing, to spread onto it: no component, no dependency on React.
+ * With `orientation: "auto"` and no `aspect`, the drawing is wide; use `createKyogijo` for a container that is measured.
+ * @example
+ * ```ts
+ * import { kyogijoProps } from "@johnmorrisdotca/kyogijo-stadiums/react";
+ * const props = kyogijoProps({ sport: "nba", away: { name: "Harbour City Gulls", score: 108 }, home: { name: "Prairie Ridge Bison", score: 112 }, status: "final" });
+ * console.log(props["data-kyogijo"], props.dangerouslySetInnerHTML.__html.startsWith("<svg"));
+ * // nba true
+ * ```
+ */
+export function kyogijoProps(options) {
+    return { dangerouslySetInnerHTML: kyogijoHtml(options), "data-kyogijo": options.sport, "data-orientation": isPortrait(options) ? "portrait" : "landscape" };
+}
+/**
+ * A React component made from the `React` you give it. It draws the options, and with `orientation: "auto"` measures its
+ * own box and lays the drawing out tall or wide as the box changes.
+ * @example
+ * ```ts
+ * import { createKyogijo } from "@johnmorrisdotca/kyogijo-stadiums/react";
+ * // With React: `const Kyogijo = createKyogijo(React);` and then `<Kyogijo sport="nhl" orientation="auto" />`.
+ * // Here a stand-in for React, to show what comes out:
+ * const Kyogijo = createKyogijo({ createElement: (type, props) => ({ type, props }), useRef: (initial) => ({ current: initial }), useState: (initial) => [initial, () => {}], useEffect: () => {} });
+ * const element = Kyogijo({ sport: "nhl" }) as { type: string };
+ * console.log(element.type);
+ * // div
+ * ```
+ */
+export function createKyogijo(React) {
+    return function Kyogijo(props) {
+        const { containerClassName, containerStyle, breakpoint, ...options } = props;
+        const ref = React.useRef(null);
+        const [aspect, setAspect] = React.useState(undefined);
+        const auto = options.orientation === "auto" && options.aspect === undefined;
+        React.useEffect(() => {
+            if (!auto || ref.current === null || typeof ResizeObserver === "undefined")
+                return undefined;
+            const host = ref.current;
+            const measure = () => {
+                const next = containerAspect(host, breakpoint);
+                if (next !== undefined)
+                    setAspect(next < 1 ? 0.75 : 1.5);
+            };
+            measure();
+            const observer = new ResizeObserver(measure);
+            observer.observe(host);
+            return () => observer.disconnect();
+        }, [auto, breakpoint]);
+        const drawn = { ...options, aspect: options.aspect ?? aspect };
+        return React.createElement("div", { ref, className: containerClassName, style: containerStyle, ...kyogijoProps(drawn) });
+    };
+}

package/dist/replay-entry.d.ts

@@ -0,0 +1,5 @@
+export { activeEvents, describeEvent, drawFrame, eventsBetween, interpolate, possession, replayClock, replayEvents, replayInfo, replayLayers, replaySnapshot, replaySummary, replayTable, replayTimes, trails } from "./replay.ts";
+export type { ReplaySnapshot } from "./replay.ts";
+export { REPLAY_SPEEDS, REPLAY_SPEED_RANGE, createReplay } from "./replay.control.ts";
+export type { ReplayController } from "./replay.control.ts";
+export type { ActiveEvent, Possession, ReplayChange, ReplayEvent, ReplayEventKind, ReplayFrame, ReplayLook, ReplayObject, ReplayReason, ReplaySettings, ReplayState, ReplayTeam, ReplayTimeline, ReplayTrail, } from "./replay.types.ts";

package/dist/replay-entry.js

@@ -0,0 +1,4 @@
+// Replay: tracking data over time on a surface. The frame, the clock and the pure functions between them; the controls and the animation
+// are in the mount (`mountKyogijo(...).replay(...)`) and in `<kyogijo-field>`.
+export { activeEvents, describeEvent, drawFrame, eventsBetween, interpolate, possession, replayClock, replayEvents, replayInfo, replayLayers, replaySnapshot, replaySummary, replayTable, replayTimes, trails } from "./replay.js";
+export { REPLAY_SPEEDS, REPLAY_SPEED_RANGE, createReplay } from "./replay.control.js";

package/dist/replay.control.d.ts

@@ -0,0 +1,47 @@
+import type { ReplayChange, ReplaySettings, ReplayState, ReplayTimeline } from "./replay.types.ts";
+/** The speeds the controls offer. Any speed from the least to the greatest is allowed. */
+export declare const REPLAY_SPEEDS: readonly number[];
+/** The slowest and the fastest speed of play. */
+export declare const REPLAY_SPEED_RANGE: readonly [number, number];
+/** What `createReplay` gives back. */
+export interface ReplayController {
+    /** A copy of the state now. */
+    state(): Readonly<ReplayState>;
+    /** Start playing, from the start if it stopped at the end. In step mode, play moves one step and never plays by itself. */
+    play(): void;
+    pause(): void;
+    toggle(): void;
+    /** Go to a time, in seconds on the timeline's clock; held to the first and last moments. */
+    seek(t: number): void;
+    /** Pause and go to the next frame (1) or the one before (-1). In step mode, move `stepSeconds`. */
+    step(direction: 1 | -1): void;
+    /** Move by seconds, backward or forward. */
+    jump(seconds: number): void;
+    /** 0.25 to 4. */
+    setSpeed(speed: number): void;
+    setLoop(loop: boolean): void;
+    /** `step` for a reader who prefers reduced motion: playing stops, and play steps. */
+    setMotion(motion: "smooth" | "step"): void;
+    /** Tell the clock that seconds went by: while playing, the time moves by that many seconds times the speed. */
+    advance(seconds: number): void;
+    /** Be told of every change. Returns a function that stops it. */
+    subscribe(listener: (change: ReplayChange) => void): () => void;
+}
+/**
+ * The controller of a replay: a state machine over a timeline's clock. It plays, pauses, seeks, steps by a frame, changes speed, loops, and says which
+ * events went by in each move so that they can be announced. It never reads a clock or the page: `advance(seconds)` is how time passes.
+ * @example
+ * ```ts
+ * import { createReplay } from "@johnmorrisdotca/kyogijo-stadiums/replay";
+ * const frames = [0, 1, 2, 3, 4].map((t) => ({ t, objects: [{ id: "ball", team: "ball" as const, x: t * 10, y: 0 }] }));
+ * const replay = createReplay({ frames, events: [{ t: 2, kind: "goal" }] }, { speed: 2 });
+ * replay.play();
+ * replay.advance(1.5);
+ * console.log(replay.state().t, replay.state().playing);
+ * replay.advance(5);
+ * console.log(replay.state().t, replay.state().playing, replay.state().ended);
+ * // 3 true
+ * // 4 false true
+ * ```
+ */
+export declare function createReplay(timeline: ReplayTimeline, settings?: ReplaySettings): ReplayController;

package/dist/replay.control.js

@@ -0,0 +1,184 @@
+// The clock of a replay as a state machine: play, pause, seek, step, speed, loop, and what went by in each move. It knows nothing of the
+// browser: the caller feeds it the seconds that passed (`advance`), which a test does with numbers and the page does from
+// `requestAnimationFrame`. replay.dom.ts is the page's side.
+import { eventsBetween, replayInfo, replayTimes } from "./replay.js";
+/** The speeds the controls offer. Any speed from the least to the greatest is allowed. */
+export const REPLAY_SPEEDS = [0.25, 0.5, 1, 2, 4];
+/** The slowest and the fastest speed of play. */
+export const REPLAY_SPEED_RANGE = [0.25, 4];
+const EPS = 1e-9;
+const clamp = (value, least, greatest) => Math.min(greatest, Math.max(least, value));
+const isNum = (value) => typeof value === "number" && Number.isFinite(value);
+/**
+ * The controller of a replay: a state machine over a timeline's clock. It plays, pauses, seeks, steps by a frame, changes speed, loops, and says which
+ * events went by in each move so that they can be announced. It never reads a clock or the page: `advance(seconds)` is how time passes.
+ * @example
+ * ```ts
+ * import { createReplay } from "@johnmorrisdotca/kyogijo-stadiums/replay";
+ * const frames = [0, 1, 2, 3, 4].map((t) => ({ t, objects: [{ id: "ball", team: "ball" as const, x: t * 10, y: 0 }] }));
+ * const replay = createReplay({ frames, events: [{ t: 2, kind: "goal" }] }, { speed: 2 });
+ * replay.play();
+ * replay.advance(1.5);
+ * console.log(replay.state().t, replay.state().playing);
+ * replay.advance(5);
+ * console.log(replay.state().t, replay.state().playing, replay.state().ended);
+ * // 3 true
+ * // 4 false true
+ * ```
+ */
+export function createReplay(timeline, settings = {}) {
+    const info = replayInfo(timeline);
+    const times = replayTimes(timeline);
+    const stepSeconds = isNum(settings.stepSeconds) && settings.stepSeconds > 0 ? settings.stepSeconds : 1;
+    const state = {
+        t: clamp(info.start + (isNum(settings.start) ? settings.start : 0), info.start, info.end),
+        start: info.start,
+        end: info.end,
+        playing: false,
+        ended: false,
+        speed: isNum(settings.speed) ? clamp(settings.speed, REPLAY_SPEED_RANGE[0], REPLAY_SPEED_RANGE[1]) : 1,
+        loop: settings.loop === true,
+        motion: settings.motion === "step" ? "step" : "smooth",
+    };
+    const listeners = new Set();
+    const tell = (reason, crossed = []) => {
+        const change = { state: { ...state }, reason, crossed };
+        for (const listener of [...listeners])
+            listener(change);
+    };
+    const over = (from, to) => (to > from ? eventsBetween(timeline, from, to) : []);
+    /** The first frame time after `t`, or the end. */
+    const after = (t) => {
+        let lo = 0;
+        let hi = times.length;
+        while (lo < hi) {
+            const mid = (lo + hi) >> 1;
+            if (times[mid] <= t + EPS)
+                lo = mid + 1;
+            else
+                hi = mid;
+        }
+        return lo < times.length ? times[lo] : state.end;
+    };
+    /** The last frame time before `t`, or the start. */
+    const before = (t) => {
+        let lo = 0;
+        let hi = times.length;
+        while (lo < hi) {
+            const mid = (lo + hi) >> 1;
+            if (times[mid] < t - EPS)
+                lo = mid + 1;
+            else
+                hi = mid;
+        }
+        return lo > 0 ? times[lo - 1] : state.start;
+    };
+    const controller = {
+        state: () => ({ ...state }),
+        play() {
+            if (state.motion === "step") {
+                controller.step(1);
+                return;
+            }
+            if (state.playing)
+                return;
+            if (state.t >= state.end - EPS && state.end > state.start)
+                state.t = state.start;
+            state.playing = true;
+            state.ended = false;
+            tell("play");
+        },
+        pause() {
+            if (!state.playing)
+                return;
+            state.playing = false;
+            tell("pause");
+        },
+        toggle() {
+            if (state.playing)
+                controller.pause();
+            else
+                controller.play();
+        },
+        seek(t) {
+            if (!isNum(t))
+                return;
+            state.t = clamp(t, state.start, state.end);
+            state.ended = false;
+            tell("seek");
+        },
+        step(direction) {
+            const was = state.playing;
+            state.playing = false;
+            const from = state.t;
+            let to;
+            if (state.motion === "step")
+                to = clamp(from + direction * stepSeconds, state.start, state.end);
+            else
+                to = direction > 0 ? after(from) : before(from);
+            if (to === from && !was)
+                return;
+            state.t = to;
+            state.ended = false;
+            tell("step", direction > 0 ? over(from, to) : []);
+        },
+        jump(seconds) {
+            if (isNum(seconds))
+                controller.seek(state.t + seconds);
+        },
+        setSpeed(speed) {
+            if (!isNum(speed))
+                return;
+            const next = clamp(speed, REPLAY_SPEED_RANGE[0], REPLAY_SPEED_RANGE[1]);
+            if (next === state.speed)
+                return;
+            state.speed = next;
+            tell("speed");
+        },
+        setLoop(loop) {
+            if (state.loop === loop)
+                return;
+            state.loop = loop;
+            tell("loop");
+        },
+        setMotion(motion) {
+            if (state.motion === motion)
+                return;
+            state.motion = motion;
+            state.playing = false;
+            tell("motion");
+        },
+        advance(seconds) {
+            if (!state.playing || state.motion === "step" || !isNum(seconds) || seconds <= 0)
+                return;
+            const from = state.t;
+            const to = from + seconds * state.speed;
+            if (to < state.end - EPS || (state.loop && state.end > state.start && to < state.end + EPS)) {
+                state.t = to;
+                tell("tick", over(from, to));
+                return;
+            }
+            if (state.loop && state.end > state.start) {
+                // Past the end: the rest of the clock goes round from the start, however many times it fits.
+                const length = state.end - state.start;
+                const wrapped = (to - state.start) % length;
+                state.t = state.start + wrapped;
+                // Everything from `from` to the end went by, and then everything from the start to where the clock is now.
+                const crossed = [...over(from, state.end), ...eventsBetween(timeline, state.start - 1, state.start + wrapped)];
+                tell("tick", crossed);
+                return;
+            }
+            state.t = state.end;
+            state.playing = false;
+            state.ended = true;
+            tell("tick", over(from, state.end));
+        },
+        subscribe(listener) {
+            listeners.add(listener);
+            return () => {
+                listeners.delete(listener);
+            };
+        },
+    };
+    return controller;
+}

package/dist/replay.d.ts

@@ -0,0 +1,170 @@
+import type { Layer } from "./layers.types.ts";
+import type { ActiveEvent, Possession, ReplayEvent, ReplayLook, ReplayObject, ReplayTeam, ReplayTimeline, ReplayTrail } from "./replay.types.ts";
+import { type KyogijoWords } from "./strings.ts";
+import type { Language, ScoreOptions, SurfaceOptions } from "./types.ts";
+type P = [number, number];
+/** Seconds as a clock, `0:12` or `1:05:09`. */
+export declare function replayClock(seconds: number): string;
+/** Seconds as it is said aloud, in the words of the language: `0:12` in English and `12秒` in Japanese, where a clock would be read as a time of day. */
+export declare function replaySpoken(seconds: number, w: KyogijoWords["replay"]): string;
+/** The first and last moments of a timeline, how long it is, how many frames and objects it has, and the usual gap between frames, all in seconds. */
+export declare function replayInfo(timeline: ReplayTimeline): {
+    start: number;
+    end: number;
+    duration: number;
+    frames: number;
+    objects: number;
+    events: number;
+    step: number;
+};
+/** The times of the frames, and of the events, in order: the moments a step can land on. */
+export declare function replayTimes(timeline: ReplayTimeline): readonly number[];
+/** The events of a timeline, in time order. */
+export declare function replayEvents(timeline: ReplayTimeline): readonly ReplayEvent[];
+/**
+ * Where everything is at a time: each object of the frame at or before `t` placed between that frame and the next, in a straight line or, with
+ * `smooth`, along a curve through the frames. An object in both frames moves; one only in the earlier frame stays put until the next; one only in
+ * the later frame appears when its frame comes. `t` is held to the first and last moments. The objects keep the order of their first appearance.
+ * @example
+ * ```ts
+ * import { interpolate } from "@johnmorrisdotca/kyogijo-stadiums/replay";
+ * import type { ReplayTimeline } from "@johnmorrisdotca/kyogijo-stadiums/replay";
+ * const timeline: ReplayTimeline = { frames: [
+ *   { t: 0, objects: [{ id: "ball", team: "ball", x: 100, y: 40 }] },
+ *   { t: 2, objects: [{ id: "ball", team: "ball", x: 140, y: 20 }] },
+ * ] };
+ * console.log(interpolate(timeline, 0.5).map((o) => `${o.id} ${o.x} ${o.y}`).join());
+ * // ball 110 35
+ * ```
+ */
+export declare function interpolate(timeline: ReplayTimeline, t: number, options?: {
+    smooth?: boolean | number;
+}): ReplayObject[];
+/**
+ * The path each object took over the last `seconds` before `t`, oldest place first and ending at its place at `t`: the frames in between, and the places at the two ends.
+ * Only objects that are there at `t` have a trail. `teams` and `ids` choose whose; all by default.
+ * @example
+ * ```ts
+ * import { trails } from "@johnmorrisdotca/kyogijo-stadiums/replay";
+ * import type { ReplayTimeline } from "@johnmorrisdotca/kyogijo-stadiums/replay";
+ * const timeline: ReplayTimeline = { frames: [0, 1, 2, 3].map((t) => ({ t, objects: [{ id: "puck", team: "puck", x: t * 10, y: 0 }] })) };
+ * console.log(trails(timeline, 3, 2)[0].points.map((point) => point[0]).join());
+ * // 10,20,30
+ * ```
+ */
+export declare function trails(timeline: ReplayTimeline, t: number, seconds: number, options?: {
+    teams?: readonly ReplayTeam[];
+    ids?: readonly string[];
+    smooth?: boolean | number;
+}): ReplayTrail[];
+/**
+ * Who has the ball at a time, when the data says: the `possession` of the latest frame at or before `t` that has one. `undefined` when no frame
+ * says, or when the latest says nobody does (`null`).
+ * @example
+ * ```ts
+ * import { possession } from "@johnmorrisdotca/kyogijo-stadiums/replay";
+ * import type { ReplayTimeline } from "@johnmorrisdotca/kyogijo-stadiums/replay";
+ * const timeline: ReplayTimeline = { frames: [
+ *   { t: 0, possession: "h7", objects: [{ id: "h7", team: "home", x: 1, y: 1 }, { id: "ball", team: "ball", x: 1, y: 1 }] },
+ *   { t: 1, possession: null, objects: [{ id: "h7", team: "home", x: 2, y: 1 }, { id: "ball", team: "ball", x: 5, y: 1 }] },
+ * ] };
+ * console.log(possession(timeline, 0.5), possession(timeline, 1));
+ * // { holder: 'h7', team: 'home' } undefined
+ * ```
+ */
+export declare function possession(timeline: ReplayTimeline, t: number): Possession | undefined;
+/**
+ * The events that are on the surface at a time: from the moment of each until `hold` seconds after it ends (3 by default), with their places worked out.
+ * @example
+ * ```ts
+ * import { activeEvents } from "@johnmorrisdotca/kyogijo-stadiums/replay";
+ * const ball = { id: "ball", team: "ball" as const, x: 10, y: 10 };
+ * const timeline = { frames: [{ t: 0, objects: [ball] }, { t: 10, objects: [ball] }], events: [{ t: 4, kind: "goal", team: "home" as const }] };
+ * console.log(activeEvents(timeline, 3).length, activeEvents(timeline, 5).map((a) => a.event.kind).join(), activeEvents(timeline, 9).length);
+ * // 0 goal 0
+ * ```
+ */
+export declare function activeEvents(timeline: ReplayTimeline, t: number, hold?: number, smooth?: boolean | number): ActiveEvent[];
+/** The events with a time in `(from, to]`, for the live region: what went by while the clock moved from `from` to `to`. */
+export declare function eventsBetween(timeline: ReplayTimeline, from: number, to: number): ReplayEvent[];
+/**
+ * What is said of an event, for a live region and a tooltip: its `label`, else the word for its kind and its team, then the time.
+ * @example
+ * ```ts
+ * import { describeEvent } from "@johnmorrisdotca/kyogijo-stadiums/replay";
+ * console.log(describeEvent({ t: 72, kind: "goal", team: "home" }));
+ * console.log(describeEvent({ t: 72, kind: "goal", team: "home" }, "ja"));
+ * // Goal, home, 1:12
+ * // ホームのゴール、1分12秒
+ * ```
+ */
+export declare function describeEvent(event: ReplayEvent, language?: Language, start?: number): string;
+/** The same frame of a timeline always draws the same layers: this is what a frame is, before it is drawn. */
+export interface ReplaySnapshot {
+    t: number;
+    objects: ReplayObject[];
+    trails: ReplayTrail[];
+    events: ActiveEvent[];
+}
+/** What is on the surface at a time: the objects, the trails behind the ones `look.trailOf` names, and the events. */
+export declare function replaySnapshot(timeline: ReplayTimeline, t: number, look?: ReplayLook): ReplaySnapshot;
+/** What a layer of the frame holds: for each mark its key, and where it is in the timeline's frame, so that the browser can move it without drawing again. */
+export interface ReplayGroup {
+    /** The layer's id, `replay-players`. */
+    id: string;
+    layer: Layer;
+    /** Whether the marks move with the clock (the objects, their numbers and trails); an event's marks stay where they are put. */
+    moving: boolean;
+    kind: "points" | "text" | "lines";
+    keys: string[];
+    /** Where each mark is, in the timeline's frame: a place for a point or a text, the places of a path for a line. */
+    coords: (P | P[])[];
+}
+/** The groups of a frame, in the order they are drawn: trails, event lines, event marks, officials, players, their numbers, then the ball and the puck on top. */
+export declare function replayGroups(timeline: ReplayTimeline, snap: ReplaySnapshot, look?: ReplayLook, language?: Language): ReplayGroup[];
+/** The data layers of one frame, to put in a drawing's `layers` (after your own): the trails, the events' marks, the players with their numbers, the ball. */
+export declare function replayLayers(timeline: ReplayTimeline, t: number, look?: ReplayLook, language?: Language): Layer[];
+/** The sentence a replay adds to the drawing's description: its length, what it tracks and how many events it holds. It does not change with the time. */
+export declare function replaySummary(timeline: ReplayTimeline, language?: Language): string;
+/** A function that puts places in a timeline's frame on the surface of a drawing, in feet. */
+export declare function replayPlacer(options: SurfaceOptions | ScoreOptions, timeline: ReplayTimeline): (points: readonly P[]) => P[];
+/**
+ * One frame of a replay as an SVG string: the drawing `drawKyogijo` makes of `options`, with the players, their numbers, the ball and its trail, and
+ * the events that are on the surface at `t`, laid on it as data layers. The same options, timeline and time always give the same string. Without
+ * an `id` the drawing's ids come from the options and the timeline, not from the time, so that every frame of a replay has the same ids.
+ * @example
+ * ```ts
+ * import { drawFrame } from "@johnmorrisdotca/kyogijo-stadiums/replay";
+ * import type { ReplayTimeline } from "@johnmorrisdotca/kyogijo-stadiums/replay";
+ * const timeline: ReplayTimeline = {
+ *   from: "nhl-api",
+ *   frames: [0, 1, 2].map((t) => ({ t, objects: [
+ *     { id: "h1", team: "home", number: 9, x: 10 + t * 12, y: 5 },
+ *     { id: "a1", team: "away", number: 4, x: 40 - t * 5, y: -8 },
+ *     { id: "puck", team: "puck", x: 10 + t * 12, y: 5 },
+ *   ] })),
+ *   events: [{ t: 2, kind: "goal", team: "home", x: 34, y: 5 }],
+ * };
+ * const svg = drawFrame({ sport: "nhl" }, timeline, 1.5);
+ * console.log(svg.startsWith("<svg"), svg === drawFrame({ sport: "nhl" }, timeline, 1.5), svg.includes("Shirt numbers"));
+ * // true true true
+ * ```
+ */
+export declare function drawFrame(options: SurfaceOptions | ScoreOptions, timeline: ReplayTimeline, t: number, look?: ReplayLook): string;
+/** The prefix of the ids in a replay's drawing when the options give none: a hash of the options and of the timeline's size, not of the time. */
+export declare const replayId: (options: SurfaceOptions | ScoreOptions, timeline: ReplayTimeline) => string;
+/**
+ * The events of a timeline as an HTML table, for a reader who cannot see the drawing: the time, the kind, the team and what is said of it. Every cell is escaped.
+ * @example
+ * ```ts
+ * import { replayTable } from "@johnmorrisdotca/kyogijo-stadiums/replay";
+ * const html = replayTable({ frames: [{ t: 0, objects: [] }], events: [{ t: 12, kind: "goal", team: "home", label: "Goal, Rivera" }] });
+ * console.log(html.includes("<td>0:12</td>"), html.includes("Goal, Rivera"));
+ * // true true
+ * ```
+ */
+export declare function replayTable(timeline: ReplayTimeline, options?: {
+    language?: Language;
+    className?: string;
+}): string;
+export {};

package/dist/replay.dom.d.ts

@@ -0,0 +1,21 @@
+import { type ReplayController } from "./replay.control.ts";
+import type { ReplaySettings, ReplayTimeline } from "./replay.types.ts";
+import type { ScoreOptions, SurfaceOptions } from "./types.ts";
+/** The controls' stylesheet: written once beside the controls, scoped to them, in the page's own colours. */
+export declare const REPLAY_STYLE: string;
+/** A replay attached to a container: the controller, the stage the drawing goes in, and how to draw it again. */
+export interface ReplayView {
+    controller: ReplayController;
+    /** The element the drawing is written into. */
+    stage: HTMLElement;
+    /** Draw the surface and the frame the clock is at, with new options (a theme that changed, a score that moved). */
+    draw(options: SurfaceOptions | ScoreOptions): void;
+    /** Stop the clock and the listeners, and empty the container. */
+    destroy(): void;
+}
+/**
+ * Attach a replay to a container: the stage with the drawing, the controls under it, the keyboard and the live region. The drawing is written once
+ * and then only the marks that move are moved, on `requestAnimationFrame`; a mark that comes or goes (an object that enters, an event that
+ * begins) redraws the replay's own layers, never the surface. With `prefers-reduced-motion` nothing plays by itself and play steps instead.
+ */
+export declare function createReplayView(host: HTMLElement, timeline: ReplayTimeline, settings: ReplaySettings, initial: SurfaceOptions | ScoreOptions): ReplayView;