@johnmorrisdotca/dougu-sports 0.7.2 → 0.9.0

package/dist/turn-control.d.ts

@@ -1,5 +1,13 @@
-import { type EmblemRef } from "./emblems/emblem.api.ts";
-import type { FrameOptions } from "./emblems/emblem.core.ts";
+import type { EmblemRef } from "./emblems/emblem.api.ts";
+import type { Emblem, FrameOptions } from "./emblems/emblem.core.ts";
+/** What reading an id needs of the registry: `emblemOf`, `renderEmblem` and `emblemFrame` of `emblem.api`. The main entry hands them to `bindTurn` itself; `./turn` loads them when an id is bound. */
+export interface TurnRegistry {
+    emblemOf(ref: EmblemRef): {
+        emblem: Emblem;
+    };
+    renderEmblem(ref: EmblemRef, options?: FrameOptions): string;
+    emblemFrame(ref: EmblemRef, options?: FrameOptions): string;
+}
 /** The three angles of a turn, in degrees. */
 export interface TurnAngles {
     /** About the vertical axis, from -180 (excluded) to 180. */
@@ -37,8 +45,13 @@ export interface TurnController {
     readonly angles: TurnAngles;
     /** Whether the auto-turn is running. */
     readonly playing: boolean;
-    /** Whether the emblem now drawn can be turned at all (read from the registry, so an emblem that gains a turn is turnable here without a change). */
+    /** Whether the emblem now drawn can be turned at all (read from the emblem's own frames, so an emblem that gains a turn is turnable here without a change). `false` until an id has loaded; see `ready`. */
     readonly turnable: boolean;
+    /**
+     * Resolves when the emblem is drawn and bound. At once (already resolved) for an emblem object, and for an id from the main entry or once the registry has loaded; otherwise after the registry's chunk has loaded.
+     * Rejects for an id that names no emblem.
+     */
+    readonly ready: Promise<void>;
     /** Sets some of the angles (wrapped or clamped as a drag would) and draws. Pauses the auto-turn when `pauseOnInteract` is on. */
     setAngles(angles: Partial<TurnAngles>): void;
     /** Draws another emblem, or the same one with other options, and keeps the angles (unless the options carry some). */
@@ -86,16 +99,22 @@ export interface TurnContainer {
 /** An angle wrapped into -180 (excluded) to 180, as the demo's slider is. */
 export declare function wrapAngle(value: number): number;
 /**
- * Binds an emblem to an element so that it can be turned: it draws `emblemFrame` into `container`, and a drag turns it (left and right are yaw, up and down are pitch, and Shift on a ball is roll), the arrow keys turn
+ * Binds an emblem to an element so that it can be turned: it draws the emblem's `frame` into `container`, and a drag turns it (left and right are yaw, up and down are pitch, and Shift on a ball is roll), the arrow keys turn
  * it, Home or 0 puts it back, and Space starts and stops an auto-turn. An emblem that cannot turn is drawn as it is, and nothing is listened to. Nothing moves by itself: `autoPlay` is off by default and, under
  * `prefers-reduced-motion`, only starts when it is `"force"`. The element gets `touch-action: none`, `user-select: none`, a grab cursor, a tab stop, a role description and a hint; `destroy()` takes them away.
+ *
+ * Pass the emblem itself (`TROPHY_HOCKEY_CUP`, from its own module) and nothing but the turning and that one emblem is in the bundle. Pass an id (`"trophy:hockey-cup"`) and the registry is loaded on
+ * demand: the element is drawn when `ready` resolves, not before. The main entry's `bindTurn` has the registry already and draws an id at once.
  * @example
  * ```ts
  * import { bindTurn } from "@johnmorrisdotca/dougu-sports/turn";
- * const turner = bindTurn(document.getElementById("cup")!, "trophy:tennis-cup", { size: 160 });
+ * import { TROPHY_TENNIS_CUP } from "@johnmorrisdotca/dougu-sports/trophy/tennis-cup";
+ * const turner = bindTurn(document.getElementById("cup")!, TROPHY_TENNIS_CUP, { size: 160 });
  * turner.setAngles({ yaw: 40 });
  * console.log(turner.angles.yaw);
  * // 40
  * ```
  */
 export declare function bindTurn(container: TurnContainer, ref: EmblemRef, options?: TurnControlOptions): TurnController;
+/** `bindTurn` with the registry in hand (or none, to load it when an id is bound): the main entry gives it, so that an id is drawn at once. An emblem object needs neither. */
+export declare function bindTurnWith(registry: TurnRegistry | undefined, container: TurnContainer, ref: EmblemRef, options?: TurnControlOptions): TurnController;

package/dist/turn-control.js

@@ -1,6 +1,3 @@
-// `bindTurn`: an emblem that a pointer, the arrow keys, the Space bar or a clock can turn. It draws `emblemFrame` into an element and listens to that element, and it is a module of its own, so importing an
-// emblem never pulls it in. Nothing here moves by itself: an auto-turn starts only when the caller asks for it, and not at all under `prefers-reduced-motion` unless the caller forces it.
-import { emblemFrame, emblemOf, renderEmblem } from "./emblems/emblem.api.js";
 const WORDS = {
     en: { role: "turnable emblem", hint: "Drag, or use the arrow keys, to turn it. Space starts and stops the turning." },
     ja: { role: "回せるエンブレム", hint: "ドラッグするか矢印キーで回せます。スペースキーで自動回転を始めたり止めたりできます。" },
@@ -13,7 +10,7 @@ export function wrapAngle(value) {
 const finite = (value, fallback) => (typeof value === "number" && Number.isFinite(value) ? value : fallback);
 const clamp = (value, low, high) => Math.max(low, Math.min(high, value));
 const globals = globalThis;
-/** Whether an emblem turns at all, read from the registry's own frames: a turned view that differs from the resting one. An emblem may say so itself with a `turnable` flag. */
+/** Whether an emblem turns at all, read from the emblem's own frames: a turned view that differs from the resting one. An emblem may say so itself with a `turnable` flag. */
 const turns = new WeakMap();
 function canTurn(emblem) {
     const flag = emblem.turnable;
@@ -26,22 +23,41 @@ function canTurn(emblem) {
     }
     return known;
 }
+const fromEmblem = (emblem) => ({ emblem, still: (o) => emblem.svg(o), frame: (o) => emblem.frame(o) });
+const fromId = (registry, ref) => ({ emblem: registry.emblemOf(ref).emblem, still: (o) => registry.renderEmblem(ref, o), frame: (o) => registry.emblemFrame(ref, o) });
+/** The registry, once something has loaded it: later ids are bound at once. */
+let loaded;
+let loading;
+const load = () => {
+    loading ??= import("./turn-registry.js").then((api) => (loaded = api));
+    return loading;
+};
 /**
- * Binds an emblem to an element so that it can be turned: it draws `emblemFrame` into `container`, and a drag turns it (left and right are yaw, up and down are pitch, and Shift on a ball is roll), the arrow keys turn
+ * Binds an emblem to an element so that it can be turned: it draws the emblem's `frame` into `container`, and a drag turns it (left and right are yaw, up and down are pitch, and Shift on a ball is roll), the arrow keys turn
  * it, Home or 0 puts it back, and Space starts and stops an auto-turn. An emblem that cannot turn is drawn as it is, and nothing is listened to. Nothing moves by itself: `autoPlay` is off by default and, under
  * `prefers-reduced-motion`, only starts when it is `"force"`. The element gets `touch-action: none`, `user-select: none`, a grab cursor, a tab stop, a role description and a hint; `destroy()` takes them away.
+ *
+ * Pass the emblem itself (`TROPHY_HOCKEY_CUP`, from its own module) and nothing but the turning and that one emblem is in the bundle. Pass an id (`"trophy:hockey-cup"`) and the registry is loaded on
+ * demand: the element is drawn when `ready` resolves, not before. The main entry's `bindTurn` has the registry already and draws an id at once.
  * @example
  * ```ts
  * import { bindTurn } from "@johnmorrisdotca/dougu-sports/turn";
- * const turner = bindTurn(document.getElementById("cup")!, "trophy:tennis-cup", { size: 160 });
+ * import { TROPHY_TENNIS_CUP } from "@johnmorrisdotca/dougu-sports/trophy/tennis-cup";
+ * const turner = bindTurn(document.getElementById("cup")!, TROPHY_TENNIS_CUP, { size: 160 });
  * turner.setAngles({ yaw: 40 });
  * console.log(turner.angles.yaw);
  * // 40
  * ```
  */
 export function bindTurn(container, ref, options = {}) {
+    return bindTurnWith(undefined, container, ref, options);
+}
+/** `bindTurn` with the registry in hand (or none, to load it when an id is bound): the main entry gives it, so that an id is drawn at once. An emblem object needs neither. */
+export function bindTurnWith(registry, container, ref, options = {}) {
     let current = ref;
-    let emblem = emblemOf(ref).emblem;
+    let drawer;
+    let version = 0;
+    let pending;
     let turnable = false;
     let sensitivity = 1.5;
     let range = [-60, 60];
@@ -95,7 +111,9 @@ export function bindTurn(container, ref, options = {}) {
         }
         const at = angles.yaw === 0 && angles.pitch === 0 && angles.roll === 0;
         // The resting view of an emblem that turns is drawn in the box of the turn too, so that the element is the same size at every angle and a drag does not make the emblem jump or zoom at its first step.
-        container.innerHTML = !turnable ? renderEmblem(current, frame) : at ? renderEmblem(current, { turnBox: true, ...frame }) : emblemFrame(current, { ...frame, ...angles });
+        if (drawer === undefined)
+            return;
+        container.innerHTML = !turnable ? drawer.still(frame) : at ? drawer.still({ turnBox: true, ...frame }) : drawer.frame({ ...frame, ...angles });
     };
     /** One drawing for any number of changes within a frame. */
     const schedule = () => {
@@ -178,7 +196,7 @@ export function bindTurn(container, ref, options = {}) {
         drag.y = y;
         if (dx === 0 && dy === 0)
             return;
-        if (event.shiftKey === true && emblem.kind === "ball")
+        if (event.shiftKey === true && drawer?.emblem.kind === "ball")
             place({ roll: angles.roll + dx, pitch: angles.pitch - dy });
         else
             place({ yaw: angles.yaw + dx, pitch: angles.pitch - dy });
@@ -287,24 +305,46 @@ export function bindTurn(container, ref, options = {}) {
         drag = undefined;
         held = false;
     };
-    const settle = () => {
-        emblem = emblemOf(current).emblem;
-        turnable = canTurn(emblem);
+    const adopt = (next) => {
+        drawer = next;
+        turnable = canTurn(next.emblem);
+        detach();
         if (turnable)
             attach();
-        else {
-            detach();
+        else
             setPlaying(false);
-        }
     };
-    configure(options);
-    place({ yaw: options.yaw, pitch: options.pitch, roll: options.roll });
-    settle();
-    draw();
-    if (turnable && options.autoPlay !== undefined && options.autoPlay !== false) {
+    /** Binds what `current` names: at once for an emblem, or for an id when the registry is in hand; otherwise when it has loaded. Gives the wait, if there is one. */
+    const settle = (first) => {
+        const mine = ++version;
+        const now = current;
+        if (typeof now !== "string")
+            return void adopt(fromEmblem(now));
+        const known = registry ?? loaded;
+        if (known !== undefined)
+            return void adopt(fromId(known, now));
+        return load().then((api) => {
+            if (mine !== version || destroyed)
+                return;
+            adopt(fromId(api, now));
+            draw();
+            if (first)
+                autoStart();
+        });
+    };
+    const autoStart = () => {
+        if (!turnable || options.autoPlay === undefined || options.autoPlay === false)
+            return;
         const reduced = globals.matchMedia?.("(prefers-reduced-motion: reduce)").matches === true;
         if (options.autoPlay === "force" || !reduced)
             setPlaying(true);
+    };
+    configure(options);
+    place({ yaw: options.yaw, pitch: options.pitch, roll: options.roll });
+    pending = settle(true);
+    if (pending === undefined) {
+        draw();
+        autoStart();
     }
     return {
         get angles() {
@@ -316,6 +356,9 @@ export function bindTurn(container, ref, options = {}) {
         get turnable() {
             return turnable;
         },
+        get ready() {
+            return pending ?? Promise.resolve();
+        },
         setAngles(partial) {
             if (destroyed)
                 return;
@@ -331,9 +374,9 @@ export function bindTurn(container, ref, options = {}) {
             place({ yaw: o.yaw, pitch: o.pitch, roll: o.roll });
             // The pitch the new range allows.
             place({ pitch: angles.pitch });
-            detach();
-            settle();
-            draw();
+            pending = settle(false);
+            if (pending === undefined)
+                draw();
         },
         play() {
             if (!turnable || destroyed)
@@ -355,6 +398,7 @@ export function bindTurn(container, ref, options = {}) {
                 return;
             setPlaying(false);
             destroyed = true;
+            version++;
             if (renderId !== undefined)
                 globals.cancelAnimationFrame?.(renderId);
             renderId = undefined;

package/dist/turn-full.d.ts

@@ -0,0 +1,15 @@
+import { type EmblemRef } from "./emblems/emblem.api.ts";
+import { type TurnContainer, type TurnControlOptions, type TurnController } from "./turn-control.ts";
+/**
+ * Binds an emblem to an element so that a drag, the arrow keys, Space or a clock turn it; see `bindTurn` of `@johnmorrisdotca/dougu-sports/turn`, which takes an emblem object and loads nothing else. This one is
+ * from the main entry: an id is read from the registry and drawn at once, with no `await`.
+ * @example
+ * ```ts
+ * import { bindTurn } from "@johnmorrisdotca/dougu-sports";
+ * const turner = bindTurn(document.getElementById("cup")!, "trophy:tennis-cup", { size: 160 });
+ * turner.setAngles({ yaw: 40 });
+ * console.log(turner.angles.yaw);
+ * // 40
+ * ```
+ */
+export declare function bindTurn(container: TurnContainer, ref: EmblemRef, options?: TurnControlOptions): TurnController;

package/dist/turn-full.js

@@ -0,0 +1,19 @@
+// `bindTurn` of the main entry: the same as the light one of `./turn`, with the registry already in hand, so an id is drawn at once (as it always was) and an emblem object works too. It is a function of its own, so
+// a page that imports only emblems from the main entry does not pull it in; one that imports `bindTurn` from here has the registry in the bundle anyway.
+import { emblemFrame, emblemOf, renderEmblem } from "./emblems/emblem.api.js";
+import { bindTurnWith } from "./turn-control.js";
+/**
+ * Binds an emblem to an element so that a drag, the arrow keys, Space or a clock turn it; see `bindTurn` of `@johnmorrisdotca/dougu-sports/turn`, which takes an emblem object and loads nothing else. This one is
+ * from the main entry: an id is read from the registry and drawn at once, with no `await`.
+ * @example
+ * ```ts
+ * import { bindTurn } from "@johnmorrisdotca/dougu-sports";
+ * const turner = bindTurn(document.getElementById("cup")!, "trophy:tennis-cup", { size: 160 });
+ * turner.setAngles({ yaw: 40 });
+ * console.log(turner.angles.yaw);
+ * // 40
+ * ```
+ */
+export function bindTurn(container, ref, options = {}) {
+    return bindTurnWith({ emblemOf, renderEmblem, emblemFrame }, container, ref, options);
+}

package/dist/turn-registry.d.ts

@@ -0,0 +1 @@
+export { emblemFrame, emblemOf, renderEmblem } from "./emblems/emblem.api.ts";

package/dist/turn-registry.js

@@ -0,0 +1,3 @@
+// What `bindTurn` loads when it is given an id: the three functions that read the registry. A module of its own, so that the dynamic import has a target no static import of `./turn` shares, and a bundler
+// makes it a chunk of its own.
+export { emblemFrame, emblemOf, renderEmblem } from "./emblems/emblem.api.js";

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "0.7.2";
+export declare const VERSION = "0.9.0";

package/dist/version.js

@@ -1 +1 @@
-export const VERSION = "0.7.2";
+export const VERSION = "0.9.0";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@johnmorrisdotca/dougu-sports",
-  "version": "0.7.2",
+  "version": "0.9.0",
   "description": "Dougu Sports 道具, sports emblems as SVG strings: trophies, medals, crests, sport icons, and the ball and gear of every sport, in metal, line or flat colour, with optional 3D turning. Light and dark, accessible, tree-shakeable. Zero dependencies.",
   "keywords": [
     "sports",
@@ -113,18 +113,18 @@
   "scripts": {
     "build": "node -e \"require('node:fs').rmSync('dist', { recursive: true, force: true })\" && tsc -p tsconfig.json",
     "lint": "eslint .",
-    "typecheck": "tsc -p tsconfig.check.json",
-    "test": "node --test test/*.test.ts test/*.test.js",
-    "test:package": "pnpm build && node scripts/check-package.mjs",
-    "test:readme": "pnpm build && node scripts/make-gallery.mjs --check && node scripts/check-readme-examples.mjs",
-    "check": "pnpm lint && pnpm typecheck && pnpm test && pnpm build && node scripts/check-package.mjs",
+    "typecheck": "tsc -p tsconfig.check.json && tsc -p tsconfig.tools.json && tsc -p tsconfig.demo.json",
+    "test": "node --test test/*.test.ts",
+    "test:package": "pnpm build && node scripts/check-package.ts",
+    "test:readme": "pnpm build && node scripts/make-gallery.ts --check && node scripts/check-readme-examples.ts",
+    "check": "pnpm lint && pnpm typecheck && pnpm test && pnpm build && node scripts/check-package.ts",
     "prepublishOnly": "pnpm check",
     "family:readme": "node scripts/family-readme.mjs",
-    "dev": "pnpm build && node scripts/dev.mjs",
-    "gallery": "pnpm build && node scripts/make-gallery.mjs",
-    "site": "pnpm build && node scripts/site.mjs",
+    "dev": "pnpm build && node scripts/dev.ts",
+    "gallery": "pnpm build && node scripts/make-gallery.ts",
+    "site": "pnpm build && node scripts/site.ts",
     "test:demo": "pnpm site && playwright test",
-    "screenshots": "pnpm site && node scripts/screenshots.mjs"
+    "screenshots": "pnpm site && node scripts/screenshots.ts"
   },
   "devDependencies": {
     "@eslint/js": "^9.0.0",