@johnmorrisdotca/dougu-sports 0.4.0 → 0.4.1

package/CHANGELOG.md

@@ -6,6 +6,14 @@ All notable changes to this project are written here. The format follows
 
 ## [Unreleased]
 
+## [0.4.1] - 2026-10-14
+
+The printed pucks take the same flag renderer as taisen-brackets.
+
+### Changed
+
+- **The puck's flag renderer is the one taisen-brackets takes.** `flags` is now an option of the call (`renderEmblem`, `emblemFrame`, `ballFrame`), beside `face`, and no longer a field of `face`; it is called `flags(code, { shape: "round" | "square" | "rect", size, theme: "inherit" | "light" | "dark" })` (the puck asks for `"rect"`), may return `null` or `undefined` for a code it has no flag for, and is synchronous, so one adapter over hata serves every package. New types `FlagRequest` and `FlagShape`. `FlagRenderer` changed accordingly; the 0.4.0 form (`face.flags`, shapes `4:3`/`1:1`/`round`) is gone.
+
 ## [0.4.0] - 2026-10-14
 
 Printed pucks: eight souvenir pucks with a print on the top face that turns with the puck, and a `face` option that takes any picture, emblem or flag code. 194 emblems.
@@ -132,7 +140,8 @@ First preview: the name, the API and two sample emblems. The full set of trophie
 - Tests for the drawing, the ids, the turns and the bundle size of one item; a package check that installs the packed tarball and bundles one item from it.
 - The demo (a playground with a turn slider, and a gallery page), `docs/layout.md`, `docs/turning.md`, `docs/gallery.md`, the family header and footer, the CI, Pages and Release workflows, and `LICENSES/` and `NOTICE.md` ready for third-party art.
 
-[Unreleased]: https://github.com/johnmorrisdotca/dougu-sports/compare/v0.4.0...HEAD
+[Unreleased]: https://github.com/johnmorrisdotca/dougu-sports/compare/v0.4.1...HEAD
+[0.4.1]: https://github.com/johnmorrisdotca/dougu-sports/compare/v0.4.0...v0.4.1
 [0.4.0]: https://github.com/johnmorrisdotca/dougu-sports/compare/v0.3.2...v0.4.0
 [0.3.2]: https://github.com/johnmorrisdotca/dougu-sports/compare/v0.3.1...v0.3.2
 [0.3.1]: https://github.com/johnmorrisdotca/dougu-sports/compare/v0.3.0...v0.3.1

package/dist/emblems/ball/ball.core.d.ts

@@ -1,4 +1,4 @@
-import type { PuckFace } from "./ball.face.ts";
+import type { FlagRenderer, PuckFace } from "./ball.face.ts";
 /** `metal` (also written `colour`): full colour, with shading. `line`: one outline in `currentColor`. */
 export type PieceStyle = "metal" | "colour" | "color" | "line";
 /** `inherit` (the default): the page's text colour. `auto`: dark ink on a light device and pale ink on a dark one. `light` and `dark` force one. */
@@ -21,6 +21,8 @@ export interface PieceOptions {
     title?: string | false;
     /** A puck: the print on its top face (see `PuckFace`). The printed pucks (`puck:*`) take it, and so does `ball:puck` through `renderEmblem`, `emblemFrame` and `ballFrame`. Anything else ignores it. */
     face?: PuckFace;
+    /** A puck: a renderer for the flag codes this package does not draw (`face.flag`), `(code, { shape, size, theme }) => svg`, the one taisen-brackets takes. Synchronous. */
+    flags?: FlagRenderer;
 }
 /** A turn: `yaw` degrees about the vertical axis (0 is the default view), `pitch` the tilt toward you, `roll` the turn about the line of sight. */
 export interface BallFrameOptions extends PieceOptions {
@@ -89,6 +91,7 @@ export interface ResolvedOptions {
     accent: string | undefined;
     grain: boolean | undefined;
     face: PuckFace | undefined;
+    flags: FlagRenderer | undefined;
     /** A string that tells two faces apart, for the ids of a drawing. */
     faceKey: string;
 }

package/dist/emblems/ball/ball.core.js

@@ -58,7 +58,7 @@ export function resolveOptions(o) {
     const theme = o?.theme === "auto" || o?.theme === "light" || o?.theme === "dark" ? o.theme : "inherit";
     const tint = readColour(o?.tint);
     const accent = readColour(o?.accent);
-    return { style: o?.style === "line" ? "line" : "colour", size, theme, tint: tint === undefined ? undefined : hexOf(tint), accent: accent === undefined ? undefined : hexOf(accent), grain: typeof o?.grain === "boolean" ? o.grain : undefined, face: typeof o?.face === "object" && o.face !== null ? o.face : undefined, faceKey: faceKeyOf(o?.face) };
+    return { style: o?.style === "line" ? "line" : "colour", size, theme, tint: tint === undefined ? undefined : hexOf(tint), accent: accent === undefined ? undefined : hexOf(accent), grain: typeof o?.grain === "boolean" ? o.grain : undefined, face: typeof o?.face === "object" && o.face !== null ? o.face : undefined, flags: typeof o?.flags === "function" ? o.flags : undefined, faceKey: faceKeyOf(o?.face) + (typeof o?.flags === "function" ? `|fn:${o.flags.name}` : "") };
 }
 /** The ink of a drawing when a theme sets it, and the page it is made to read on. */
 export const PIECE_INK = { light: "#20262d", dark: "#eef1f3" };

package/dist/emblems/ball/ball.face.d.ts

@@ -1,11 +1,18 @@
 /** The designs a face starts from. */
 export type PuckDesign = "canada" | "canada-red" | "canada-white" | "usa" | "usa-navy" | "player" | "souvenir";
-/** What the renderer a caller supplies for a flag is asked: the code, the shape (`"4:3"`, `"1:1"` or `"round"`, the shapes hata draws), a size in pixels and the theme. It returns an SVG document. */
-export type FlagRenderer = (code: string, options: {
-    shape: "4:3" | "1:1" | "round";
+/** How a flag is framed: `round` in a circle, `square`, or `rect` in its own proportions (the puck asks for `rect`). */
+export type FlagShape = "round" | "square" | "rect";
+/** What a drawing asks a `flags` renderer for: the shape, a width and height in pixels, and the look (`inherit` for a page whose ink is its own). */
+export interface FlagRequest {
+    shape: FlagShape;
     size: number;
-    theme: "light" | "dark" | "auto" | "inherit";
-}) => string;
+    theme: "inherit" | "light" | "dark";
+}
+/**
+ * A function from a country code and a request to an SVG string, or `null` or `undefined` for a code it has no flag for: the same renderer taisen-brackets and kyogijo take, so one adapter over hata serves them
+ * all. It must be synchronous (a drawing is a pure function of its options): hata's `flag()` is asynchronous, so load the flags first and pass `(code) => loaded[code]`. Pass it as the `flags` option of the call.
+ */
+export type FlagRenderer = (code: string, request: FlagRequest) => string | null | undefined;
 /** The colours of a face, by name. The array form is the same list in this order: field, ring, ink, accent, signature. */
 export interface FaceColors {
     /** The disc's own colour. */
@@ -28,10 +35,8 @@ export interface PuckFace {
     design?: PuckDesign;
     /** Any SVG: a logo, a crest, a drawing. Made safe first (see `safeImage`): shapes, gradients and clip paths only. It is fitted into the middle of the face and replaces the design's own picture. */
     image?: string;
-    /** A country code (`"ca"` and `"us"` are drawn by this package; another needs `flags`). It replaces the design's own picture. */
+    /** A country code (`"ca"` and `"us"` are drawn by this package; another needs the `flags` option of the call). It replaces the design's own picture. */
     flag?: string;
-    /** A renderer for the flag codes this package does not draw: `(code, { shape, size, theme }) => svg`, the shape of the function hata exports. */
-    flags?: FlagRenderer;
     /** The id of a dougu emblem (`"trophy:cup"`, `"sport:nhl"`), drawn small in the middle. Resolved by `renderEmblem`, `emblemFrame` and `ballFrame`. */
     emblem?: string;
     /** The words under the picture (`"CANADA"`), one line. */
@@ -48,7 +53,7 @@ export interface PuckFace {
     colors?: FaceColors | readonly (string | undefined)[];
 }
 /** The face of a design, in the face's units (a disc of radius 1, up is up): its definitions and its drawing. `prefix` makes every id unique to this puck. */
-export declare function faceMarkup(face: PuckFace | undefined, design: PuckDesign, own: PuckFace | undefined, prefix: string): {
+export declare function faceMarkup(face: PuckFace | undefined, design: PuckDesign, own: PuckFace | undefined, prefix: string, flags?: FlagRenderer, theme?: FlagRequest["theme"]): {
     defs: string;
     body: string;
 };

package/dist/emblems/ball/ball.face.js

@@ -38,7 +38,7 @@ const colourOf = (value) => {
 };
 const DESIGNS = Object.keys(LOOKS);
 /** The face, ready to draw: the design's words and colours under the caller's. `base` is the design a puck's own id starts from. */
-function resolve(face, base, own) {
+function resolve(face, base, own, flags, theme) {
     const f = typeof face === "object" && face !== null ? face : {};
     const design = (typeof f.design === "string" && DESIGNS.includes(f.design) ? f.design : own?.design ?? base);
     const words = { ...WORDS[design], ...own, ...definedOnly(f) };
@@ -60,7 +60,8 @@ function resolve(face, base, own) {
         look,
         image: typeof words.image === "string" ? words.image : undefined,
         flag: typeof words.flag === "string" ? words.flag.trim().toLowerCase().slice(0, 12) : undefined,
-        flags: typeof words.flags === "function" ? words.flags : undefined,
+        flags,
+        theme,
         text: cleanText(words.text),
         ring,
         number: number === "" ? undefined : number,
@@ -112,7 +113,7 @@ function picture(f, prefix, cx, cy, w, h) {
         if (f.flags !== undefined) {
             let svg;
             try {
-                svg = f.flags(code, { shape: "4:3", size: 120, theme: "light" });
+                svg = f.flags(code, { shape: "rect", size: 120, theme: f.theme });
             }
             catch {
                 svg = undefined;
@@ -182,8 +183,8 @@ function leaf(cx, cy, w, fill) {
     return `<path d="${LEAF_PATH}" transform="translate(${num(cx, 3)} ${num(cy, 3)}) scale(${num(w / 2, 4)})" fill="${fill}"/>`;
 }
 /** The face of a design, in the face's units (a disc of radius 1, up is up): its definitions and its drawing. `prefix` makes every id unique to this puck. */
-export function faceMarkup(face, design, own, prefix) {
-    const f = resolve(face, design, own);
+export function faceMarkup(face, design, own, prefix, flags, theme = "inherit") {
+    const f = resolve(face, design, own, typeof flags === "function" ? flags : undefined, theme);
     const look = f.look;
     const clip = `${prefix}clip`;
     let defs = `<clipPath id="${clip}"><circle r=".965"/></clipPath>`;

package/dist/emblems/ball/ball.puck.print.js

@@ -24,7 +24,7 @@ function definePuck(def) {
                 // The top face's plane in the box: its centre, and where a step of 1 along the puck's x and z axes goes (the face's right, and its down).
                 const o = cx.at([0, PUCK_H, 0]), ex = cx.at([1, PUCK_H, 0]), ez = cx.at([0, PUCK_H, 1]);
                 const m = [ex[0] - o[0], ex[1] - o[1], ez[0] - o[0], ez[1] - o[1], o[0], o[1]].map((v) => num(v, 4)).join(" ");
-                const face = faceMarkup(cx.opts.face, def.design, def.own, `${cx.id}p`);
+                const face = faceMarkup(cx.opts.face, def.design, def.own, `${cx.id}p`, cx.opts.flags, cx.opts.theme === "light" || cx.opts.theme === "dark" ? cx.opts.theme : "inherit");
                 // A light from the upper left and a falling-off at the far edge, over the print, in the box's own space so the light stays put while the puck turns.
                 const gid = `${cx.id}fl`;
                 const defs = `${face.defs}<radialGradient id="${gid}" cx=".36" cy=".3" r=".85"><stop offset="0" stop-color="#fff" stop-opacity=".34"/><stop offset=".4" stop-color="#fff" stop-opacity="0"/><stop offset="1" stop-color="#000" stop-opacity=".42"/></radialGradient>`;

package/dist/emblems/emblem.core.d.ts

@@ -1,4 +1,4 @@
-import type { PuckFace } from "./ball/ball.face.ts";
+import type { FlagRenderer, PuckFace } from "./ball/ball.face.ts";
 /** `metal`: full colour with a gradient. `line`: one outline in `currentColor`. `color`: flat fills of the main colour, with no gradient. */
 export type EmblemStyle = "metal" | "line" | "color";
 export declare const EMBLEM_STYLES: readonly ["metal", "line", "color"];
@@ -53,9 +53,11 @@ export interface EmblemOptions {
     turnBox?: boolean;
     /**
      * The print on the top face of a puck: the printed pucks (`puck:*`) start from a face of their own and this replaces any part of it, and `ball:puck` given a face is drawn as `puck:souvenir` with it. `image` takes any SVG
-     * (made safe first), `emblem` a dougu id, `flag` a country code (`ca` and `us` are drawn here; another needs `flags`, a renderer like hata's). See `PuckFace`. Anything that is not a puck ignores it.
+     * (made safe first), `emblem` a dougu id, `flag` a country code (`ca` and `us` are drawn here; another needs the `flags` option, a renderer like hata's). See `PuckFace`. Anything that is not a puck ignores it.
      */
     face?: PuckFace;
+    /** A puck: a renderer for the flag codes this package does not draw (`face.flag`): `(code, { shape: "round" | "square" | "rect", size, theme }) => svg`, synchronous, the same as taisen-brackets takes (hata's `flag()` is asynchronous, so load the flags first). */
+    flags?: FlagRenderer;
 }
 /** A turn, in degrees from the resting view (0 and 0 is the still drawing): `yaw` about the vertical axis, `pitch` the tilt toward the eye. */
 export interface FrameOptions extends EmblemOptions {

package/dist/emblems-entry.d.ts

@@ -19,4 +19,4 @@ export { sportEquipment } from "./emblems/emblem.equipment.ts";
 export type { SportEquipment } from "./emblems/emblem.equipment.ts";
 export { awardCase, podium } from "./emblems/emblem.display.ts";
 export type { AwardCaseOptions, AwardItem, DisplayOptions, PodiumOptions, PodiumPlace } from "./emblems/emblem.display.ts";
-export type { FaceColors, FlagRenderer, PuckDesign, PuckFace } from "./emblems/ball/ball.face.ts";
+export type { FaceColors, FlagRenderer, FlagRequest, FlagShape, PuckDesign, PuckFace } from "./emblems/ball/ball.face.ts";

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const VERSION = "0.4.0";
+export declare const VERSION = "0.4.1";

package/dist/version.js

@@ -1 +1 @@
-export const VERSION = "0.4.0";
+export const VERSION = "0.4.1";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@johnmorrisdotca/dougu-sports",
-  "version": "0.4.0",
+  "version": "0.4.1",
   "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",