@johnmorrisdotca/dougu-sports 0.0.1 → 0.2.0

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

@@ -0,0 +1,75 @@
+import { type EmblemLocale, type EmblemStyle, type EmblemTheme } from "./emblem.core.ts";
+import { type EmblemRef } from "./emblem.api.ts";
+/** The options both displays share. */
+export interface DisplayOptions {
+    /** The width in pixels; the height follows the drawing's proportions. A podium is 320 by default, an award case as wide as its cells. */
+    width?: number;
+    /** `metal` (the default), `line` or `color`: the style of the emblems and of the steps and the shelf. */
+    style?: EmblemStyle;
+    /** `inherit` (the default), `auto`, `light` or `dark`, as for an emblem. */
+    theme?: EmblemTheme;
+    /** `"en"` (the default) or `"ja"`: the language of the default title and description, and of the emblems' names in the description. */
+    locale?: EmblemLocale;
+    /** A string is the `<title>`; `false` drops the title and the description and marks the drawing `aria-hidden="true"`. By default it is "Podium" or "Award case". */
+    title?: string | false;
+    /** The `<desc>`: by default it lists what is drawn, in words. */
+    desc?: string;
+}
+/** One place of a podium. */
+export interface PodiumPlace {
+    /** The medal or trophy for the place: any emblem. By default the gold, silver and bronze medals. */
+    emblem?: EmblemRef;
+    /** The name of the winner, written under the step's top. Long names are cut short with an ellipsis. */
+    name?: string;
+    /** A flag for the winner: SVG markup (`<svg …>`), which is drawn as an image and so cannot run or load anything, or a URL (`https:`, a path on your site, or a `data:image/…` address). Anything else is left out. */
+    flag?: string;
+    /** A line on the step: a time, a score, a number of points. */
+    label?: string;
+}
+/** What `podium` takes. */
+export type PodiumOptions = DisplayOptions;
+/** One kind of trophy in an award case. */
+export interface AwardItem {
+    /** The trophy, medal or crest: any emblem. */
+    emblem: EmblemRef;
+    /** How many the team has won; a badge `×N` shows when it is more than one. 1 by default; less than 1 leaves the item out, and the badge stops at 999. */
+    count?: number;
+    /** A line under the shelf: the years, or a name. */
+    label?: string;
+}
+/** What `awardCase` takes. */
+export interface AwardCaseOptions extends DisplayOptions {
+    /** Items in a row before the case wraps into another (5 by default, 1 to 12). */
+    perRow?: number;
+    /** The width of an emblem in the drawing's own units (56 by default, 24 to 128): the pixel size at the default width. */
+    size?: number;
+    /** `shelf` (the default) stands the emblems on a plank under each row; `row` draws them with no plank. */
+    layout?: "shelf" | "row";
+}
+/** An image address that is safe to put in an `<image>`: SVG markup becomes a data address (an image cannot run script or load anything), a URL must be `https:`, a path of your own site, or an image data address. */
+export declare function safeImage(source: unknown): string | undefined;
+/**
+ * A podium: first, second and third on tiered steps (second on the left, first in the middle, third on the right), each with a medal or a trophy, and optionally a name, a flag and a line of text. `places[0]` is first;
+ * a place left out is an empty step. The drawing is the page's text colour on tinted steps, so it reads on light and dark; it has a title and a description that says who stands where. A flag is SVG markup or a URL
+ * and is drawn as an `<image>`, so it cannot run script or reach anything it was not given; anything that is neither is left out.
+ * @example
+ * ```ts
+ * import { podium } from "@johnmorrisdotca/dougu-sports/emblems";
+ * const svg = podium([{ name: "Aoki", label: "9.80" }, { name: "Brown" }, { name: "Chen" }]);
+ * console.log(svg.includes("<desc>1st: Aoki (9.80); 2nd: Brown; 3rd: Chen</desc>"));
+ * // true
+ * ```
+ */
+export declare function podium(places: readonly (PodiumPlace | null | undefined)[], options?: PodiumOptions): string;
+/**
+ * An award case: a team's trophies on a shelf (or in a row), each drawn once with a `×N` badge when the team has won it more than once, wrapping into more rows after `perRow` items. Each item can carry a line of
+ * text, such as its years. The drawing follows the page's text colour, has a title and a description that lists what is in the case, and holds at most 60 items.
+ * @example
+ * ```ts
+ * import { awardCase } from "@johnmorrisdotca/dougu-sports/emblems";
+ * const svg = awardCase([{ emblem: "trophy:hockey-cup", count: 3 }, { emblem: "medal:gold" }]);
+ * console.log(svg.includes("×3"));
+ * // true
+ * ```
+ */
+export declare function awardCase(items: readonly AwardItem[], options?: AwardCaseOptions): string;

package/dist/emblems/emblem.display.js

@@ -0,0 +1,214 @@
+// Two displays made from emblems: a podium (first, second and third on tiered steps) and an award case (a team's trophies on a shelf, with a count for each). Both are one SVG string, pure functions of their
+// arguments, in the page's text colour so they follow light and dark, with a title and a description for a screen reader. The emblems inside are the registry's, drawn without their own titles.
+import { EMBLEM_INK, METALS, escape, mix, n2, readColour } from "./emblem.core.js";
+import { emblemOf, renderEmblem } from "./emblem.api.js";
+import { IdSpace, nest, partsOf } from "./emblem.compose.js";
+import { encodeSvg } from "./emblem.uri.js";
+const WORDS = {
+    en: { podium: "Podium", case: "Award case", places: ["1st", "2nd", "3rd"] },
+    ja: { podium: "表彰台", case: "トロフィーケース", places: ["1位", "2位", "3位"] },
+};
+const FONT = 'font-family="system-ui,sans-serif"';
+/** Text cut to a number of character widths, with an ellipsis where it was cut. */
+function fit(text, max) {
+    const chars = [...text.replace(/\s+/g, " ").trim()];
+    let width = 0;
+    const out = [];
+    for (const c of chars) {
+        const w = (c.codePointAt(0) ?? 0) > 0x2e7f ? 2 : 1;
+        if (width + w > max)
+            return `${out.join("").trimEnd()}…`;
+        width += w;
+        out.push(c);
+    }
+    return out.join("");
+}
+/** An image address that is safe to put in an `<image>`: SVG markup becomes a data address (an image cannot run script or load anything), a URL must be `https:`, a path of your own site, or an image data address. */
+export function safeImage(source) {
+    if (typeof source !== "string")
+        return undefined;
+    const text = source.trim();
+    if (text === "" || text.length > 100_000)
+        return undefined;
+    if (/^<svg[\s>]/i.test(text)) {
+        const root = /^<svg[^>]*>/i.exec(text);
+        if (root === null)
+            return undefined;
+        const withNamespace = /\sxmlns\s*=/.test(root[0]) ? text : text.replace(/^<svg/i, '<svg xmlns="http://www.w3.org/2000/svg"');
+        // An `=` is encoded as well, so that nothing in the address reads as an attribute to a scanner that looks for one.
+        return `data:image/svg+xml;utf8,${encodeSvg(withNamespace).replace(/=/g, "%3D")}`;
+    }
+    if (/^https:\/\/[^\s"'<>\\@]+$/i.test(text))
+        return text;
+    if (/^data:image\/(png|jpeg|gif|webp|avif|svg\+xml)[;,][^\s"'<>\\]*$/i.test(text))
+        return text;
+    if (/^(?:\/(?!\/)|\.{1,2}\/)[\w\-./~%+@]*$/.test(text))
+        return text;
+    return undefined;
+}
+/** The emblem as a part of another drawing: its body and its definitions, with no title. */
+function inner(ref, style, space) {
+    const parts = partsOf(renderEmblem(ref, { style, theme: "inherit", title: false, grain: false }));
+    return { box: parts.box, body: space.add(parts) };
+}
+/** The document that holds a display: size, theme, title and description. */
+function document(o, kind, box, defs, body, desc, defaultWidth) {
+    const [x, y, w, h] = box;
+    const width = typeof o.width === "number" && Number.isFinite(o.width) && o.width > 0 ? Math.min(Math.round(o.width * 100) / 100, 4096) : defaultWidth;
+    const locale = o.locale === "ja" ? "ja" : "en";
+    const theme = o.theme === "auto" || o.theme === "light" || o.theme === "dark" ? o.theme : "inherit";
+    const colour = theme === "dark" ? EMBLEM_INK.dark : theme === "inherit" ? "" : EMBLEM_INK.light;
+    const auto = theme === "auto" ? `<style>@media(prefers-color-scheme:dark){svg{color:${EMBLEM_INK.dark}}}</style>` : "";
+    const hidden = o.title === false;
+    const title = typeof o.title === "string" && o.title.trim() !== "" ? o.title.trim().slice(0, 300) : WORDS[locale][kind === "case" ? "case" : "podium"];
+    const text = typeof o.desc === "string" && o.desc.trim() !== "" ? o.desc.trim().slice(0, 1000) : desc;
+    const lang = locale === "ja" && typeof o.title !== "string" && !hidden ? ' lang="ja"' : "";
+    return (`<svg xmlns="http://www.w3.org/2000/svg" viewBox="${n2(x)} ${n2(y)} ${n2(w)} ${n2(h)}" width="${n2(width)}" height="${n2((width * h) / w)}"${hidden ? ' aria-hidden="true"' : ` role="img"${lang}`}${colour === "" ? "" : ` color="${colour}"`}>` +
+        `${hidden ? "" : `<title>${escape(title)}</title><desc>${escape(text)}</desc>`}${auto}${defs.length === 0 ? "" : `<defs>${defs.join("")}</defs>`}` +
+        `<g ${FONT} fill="none" stroke="none">${body}</g></svg>`);
+}
+const NAME_OF = (ref, locale) => (locale === "ja" ? emblemOf(ref).emblem.ja : emblemOf(ref).emblem.en);
+/** A step: the three metals tint the steps in the metal and colour styles; in the line style they are outlines. */
+function step(style, place, x, y, w, h, defs) {
+    const metal = readColour([METALS.gold, METALS.silver, METALS.bronze][place] ?? METALS.gold);
+    const edge = mix(metal, -0.3);
+    if (style === "line")
+        return `<rect x="${x}" y="${y}" width="${w}" height="${h}" rx="3" stroke="currentColor" stroke-width="2"/>`;
+    if (style === "color")
+        return `<rect x="${x}" y="${y}" width="${w}" height="${h}" rx="3" fill="${mix(metal, 0)}" fill-opacity=".34" stroke="${edge}" stroke-width="1.5"/>`;
+    const id = `dgpd${place + 1}`;
+    const hex = mix(metal, 0);
+    const def = `<linearGradient id="${id}" x2="0" y2="1"><stop offset="0" stop-color="${mix(metal, 0.35)}" stop-opacity=".78"/><stop offset="1" stop-color="${hex}" stop-opacity=".22"/></linearGradient>`;
+    if (!defs.includes(def))
+        defs.push(def);
+    return `<rect x="${x}" y="${y}" width="${w}" height="${h}" rx="3" fill="url(#${id})" stroke="${edge}" stroke-width="1.5"/>`;
+}
+/**
+ * A podium: first, second and third on tiered steps (second on the left, first in the middle, third on the right), each with a medal or a trophy, and optionally a name, a flag and a line of text. `places[0]` is first;
+ * a place left out is an empty step. The drawing is the page's text colour on tinted steps, so it reads on light and dark; it has a title and a description that says who stands where. A flag is SVG markup or a URL
+ * and is drawn as an `<image>`, so it cannot run script or reach anything it was not given; anything that is neither is left out.
+ * @example
+ * ```ts
+ * import { podium } from "@johnmorrisdotca/dougu-sports/emblems";
+ * const svg = podium([{ name: "Aoki", label: "9.80" }, { name: "Brown" }, { name: "Chen" }]);
+ * console.log(svg.includes("<desc>1st: Aoki (9.80); 2nd: Brown; 3rd: Chen</desc>"));
+ * // true
+ * ```
+ */
+export function podium(places, options = {}) {
+    const style = options.style === "line" || options.style === "color" ? options.style : "metal";
+    const locale = options.locale === "ja" ? "ja" : "en";
+    const space = new IdSpace();
+    const stepDefs = [];
+    const base = 206;
+    const heights = [100, 78, 60];
+    const centres = [160, 56, 264];
+    const defaults = ["medal:gold", "medal:silver", "medal:bronze"];
+    let top = base;
+    let body = "";
+    const said = [];
+    for (const place of [1, 0, 2]) {
+        const entry = places[place] ?? undefined;
+        const c = centres[place];
+        const h = heights[place];
+        const t = base - h;
+        body += step(style, place, c - 48, t, 96, h, stepDefs);
+        body += `<text x="${c}" y="${t + 31}" text-anchor="middle" font-size="26" font-weight="800" fill="currentColor" fill-opacity=".85">${place + 1}</text>`;
+        if (entry === undefined)
+            continue;
+        const label = typeof entry.label === "string" ? fit(entry.label, 18) : "";
+        if (label !== "")
+            body += `<text x="${c}" y="${t + 50}" text-anchor="middle" font-size="11" fill="currentColor">${escape(label)}</text>`;
+        const ref = entry.emblem ?? defaults[place];
+        const emblem = inner(ref, style, space);
+        const emblemTop = t - 62;
+        body += nest(emblem.box, emblem.body, c - 30, emblemTop, 60, 60);
+        let cursor = emblemTop;
+        const flag = safeImage(entry.flag);
+        if (flag !== undefined) {
+            cursor -= 20;
+            body += `<image href="${escape(flag)}" x="${c - 12}" y="${cursor}" width="24" height="16" preserveAspectRatio="xMidYMid meet"/><rect x="${c - 12}" y="${cursor}" width="24" height="16" stroke="currentColor" stroke-opacity=".4" stroke-width=".75"/>`;
+        }
+        const name = typeof entry.name === "string" ? fit(entry.name, 16) : "";
+        if (name !== "") {
+            cursor -= 6;
+            body += `<text x="${c}" y="${cursor}" text-anchor="middle" font-size="12" font-weight="600" fill="currentColor">${escape(name)}</text>`;
+            cursor -= 11;
+        }
+        top = Math.min(top, cursor);
+        const who = name !== "" ? (typeof entry.name === "string" ? entry.name.replace(/\s+/g, " ").trim() : name) : NAME_OF(ref, locale);
+        const line = typeof entry.label === "string" ? entry.label.replace(/\s+/g, " ").trim() : "";
+        // Japanese writes its description with full-width punctuation and 、 between the places.
+        said[place] = locale === "ja" ? `${WORDS.ja.places[place]}：${who}${line !== "" ? `（${line}）` : ""}` : `${WORDS.en.places[place]}: ${who}${line !== "" ? ` (${line})` : ""}`;
+    }
+    top = Math.max(0, Math.min(top, base - 100 - 62) - 6);
+    const desc = said.filter(Boolean).join(locale === "ja" ? "、" : "; ");
+    return document(options, "podium", [0, top, 320, base + 6 - top], [...space.defs, ...stepDefs], body, desc, 320);
+}
+/**
+ * An award case: a team's trophies on a shelf (or in a row), each drawn once with a `×N` badge when the team has won it more than once, wrapping into more rows after `perRow` items. Each item can carry a line of
+ * text, such as its years. The drawing follows the page's text colour, has a title and a description that lists what is in the case, and holds at most 60 items.
+ * @example
+ * ```ts
+ * import { awardCase } from "@johnmorrisdotca/dougu-sports/emblems";
+ * const svg = awardCase([{ emblem: "trophy:hockey-cup", count: 3 }, { emblem: "medal:gold" }]);
+ * console.log(svg.includes("×3"));
+ * // true
+ * ```
+ */
+export function awardCase(items, options = {}) {
+    const style = options.style === "line" || options.style === "color" ? options.style : "metal";
+    const locale = options.locale === "ja" ? "ja" : "en";
+    const perRow = typeof options.perRow === "number" && Number.isFinite(options.perRow) ? Math.max(1, Math.min(12, Math.floor(options.perRow))) : 5;
+    const size = typeof options.size === "number" && Number.isFinite(options.size) ? Math.max(24, Math.min(128, options.size)) : 56;
+    const shelf = options.layout !== "row";
+    const list = items
+        .filter((item) => item !== null && typeof item === "object")
+        .map((item) => ({ item, count: item.count === undefined ? 1 : Math.min(999, Math.floor(Number(item.count))) }))
+        .filter(({ count }) => count >= 1)
+        .slice(0, 60);
+    const space = new IdSpace();
+    const gap = shelf ? 24 : 16;
+    const cell = size + gap;
+    const columns = Math.max(1, Math.min(perRow, list.length));
+    const labelled = list.some(({ item }) => typeof item.label === "string" && item.label.trim() !== "");
+    const rowHeight = 10 + size + (shelf ? 8 : 0) + (labelled ? 18 : 0) + 8;
+    const rows = Math.max(1, Math.ceil(list.length / perRow));
+    const pad = 8;
+    const width = columns * cell + 2 * pad;
+    const wide = Math.max(4, Math.floor(cell / 5.4));
+    let body = "";
+    const said = [];
+    for (let r = 0; r < rows; r++) {
+        const y0 = pad + r * rowHeight;
+        const emblemY = y0 + 10;
+        const plank = emblemY + size;
+        if (shelf)
+            body += `<rect x="${pad}" y="${plank}" width="${columns * cell}" height="6" rx="2" fill="currentColor" fill-opacity=".16" stroke="currentColor" stroke-opacity=".5" stroke-width="1"/>`;
+        for (let c = 0; c < columns; c++) {
+            const entry = list[r * perRow + c];
+            if (entry === undefined)
+                break;
+            const x = pad + c * cell + gap / 2;
+            const emblem = inner(entry.item.emblem, style, space);
+            body += nest(emblem.box, emblem.body, x, emblemY, size, size);
+            const label = typeof entry.item.label === "string" ? fit(entry.item.label, wide) : "";
+            if (label !== "")
+                body += `<text x="${n2(x + size / 2)}" y="${plank + (shelf ? 20 : 14)}" text-anchor="middle" font-size="10" fill="currentColor">${escape(label)}</text>`;
+            if (entry.count > 1) {
+                const text = `×${entry.count}`;
+                const w = 10 + text.length * 6.4;
+                const right = x + size + 4;
+                body += `<rect x="${n2(right - w)}" y="${n2(emblemY - 4)}" width="${n2(w)}" height="16" rx="8" fill="${EMBLEM_INK.light}" stroke="${EMBLEM_INK.dark}" stroke-width="1"/><text x="${n2(right - w / 2)}" y="${n2(emblemY + 7.5)}" text-anchor="middle" font-size="11" font-weight="700" fill="#ffffff">${text}</text>`;
+            }
+            const name = NAME_OF(entry.item.emblem, locale);
+            const note = typeof entry.item.label === "string" ? entry.item.label.replace(/\s+/g, " ").trim() : "";
+            // The badge is drawn ×N; spoken in Japanese the count is N回, because a screen reader reads × unevenly.
+            if (locale === "ja")
+                said.push(`${name}${entry.count > 1 ? ` ${entry.count}回` : ""}${note === "" ? "" : `（${note}）`}`);
+            else
+                said.push(`${name}${entry.count > 1 ? ` ×${entry.count}` : ""}${note === "" ? "" : ` (${note})`}`);
+        }
+    }
+    return document(options, "case", [0, 0, width, pad * 2 + rows * rowHeight - 8], space.defs, body, said.join(locale === "ja" ? "、" : ", "), width);
+}

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

@@ -0,0 +1,50 @@
+import { type EmblemOptions, type Engraving, type Rgb } from "./emblem.core.ts";
+/** A box on a flat face: its centre and its size (`w` along the text), and for a plate that runs up or down a side, the turn of the text in degrees about the centre. */
+export interface Plate {
+    x: number;
+    y: number;
+    w: number;
+    h: number;
+    rot?: number;
+}
+/** A line of text and how big it is next to the others (1 is the biggest). */
+export interface Line {
+    text: string;
+    weight: number;
+}
+/** The width of one character in em: a guess that holds for the usual sans-serif fonts, whole for Japanese and the wide forms. */
+export declare function advance(ch: string): number;
+/** The width of a text in em. */
+export declare const widthOf: (text: string) => number;
+/** The contrast ratio of two colours, 1 to 21. */
+export declare const contrastOf: (a: Rgb, b: Rgb) => number;
+/** Black or white, or a deep or pale tone of the colour itself, whichever reads at 4.5 to 1 on the colour (the best of them when none does). */
+export declare function inkFor(main: Rgb): string;
+/** The lines to cut, as candidates (the layout takes the one that gives the biggest letters), and the year when a plate of its own holds it. */
+export declare function linesOf(e: Engraving, place?: {
+    rank?: string;
+    yearApart?: boolean;
+}): {
+    main: Line[][];
+    year: string | undefined;
+};
+/** The ink of an engraving: the page's ink in the line style, else the colour that reads on the metal. */
+export declare const engravingInk: (style: string, main: Rgb) => string;
+/** Lines cut into a plate, as markup: the ink, and in the metal style a faint light under each line where the cut catches it. `candidates` are alternative line breaks, and the best fit is used. */
+export declare function plateMarkup(candidates: readonly (readonly Line[])[], plate: Plate, main: Rgb, style: string): string;
+/** A band round a body of revolution that holds text: the heights it spans, the tone it is cut into, the angle it is centred on and, for a body with flat sides, the side. */
+export interface Band {
+    y0: number;
+    y1: number;
+    tone?: string;
+    at?: number;
+    face?: number;
+}
+/** The letters of a text set round a body at a radius: `angle` is the turn of the body now, `place` puts a point of the surface on the screen. A letter on the far side is left out. */
+export declare function cylinderText(text: string, radius: number, height: number, ink: string, angle: number, centre: number, place: (deg: number) => readonly [x: number, y: number, depth: number]): string;
+/** The letters of a text set on one flat side of a body, from one edge of the side to the other, as that side faces the eye. `a` and `b` are the two edges on the screen, `depth` how squarely the side faces. */
+export declare function sideText(text: string, chord: number, height: number, ink: string, a: readonly [number, number], b: readonly [number, number], depth: number): string;
+/** The text of an engraving as one line, for a band that holds one: the free text with its lines joined, or the rank, label and year. */
+export declare const flatText: (e: Engraving) => string;
+/** What is to be cut into a face, from the options: the free text, or the label, year and rank, and the text of the back. */
+export declare function engravingOf(o: EmblemOptions | undefined): Engraving;

package/dist/emblems/emblem.engrave.js

@@ -0,0 +1,145 @@
+// Engraving: text cut into a face. A plate is a box on a flat face; its lines are fitted to it (the biggest size at which the longest line and the stack of lines both fit), and the ink is chosen
+// to read at 4.5 to 1 on the metal under it, the same way a crest's letters are. A plinth is a band round a body of revolution: its letters are set one by one at their angle round it, so the
+// text foreshortens, goes behind the edge and comes round as the body turns. Imports only the core.
+import { clean, escape, lum, mix, n2, readColour } from "./emblem.core.js";
+const FONT = "system-ui,-apple-system,'Segoe UI','Hiragino Sans','Noto Sans JP','Yu Gothic',sans-serif";
+/** The width of one character in em: a guess that holds for the usual sans-serif fonts, whole for Japanese and the wide forms. */
+export function advance(ch) {
+    const c = ch.codePointAt(0);
+    if (c >= 0x2e80 && c <= 0xffef && !(c >= 0xff61 && c <= 0xff9f))
+        return 1.02;
+    if (ch === " ")
+        return 0.3;
+    if (/[iljI.,:;'!|]/.test(ch))
+        return 0.34;
+    if (/[mwMW]/.test(ch))
+        return 0.92;
+    if (/[A-Z]/.test(ch))
+        return 0.72;
+    if (/[0-9]/.test(ch))
+        return 0.62;
+    return 0.58;
+}
+/** The width of a text in em. */
+export const widthOf = (text) => [...text].reduce((sum, ch) => sum + advance(ch), 0);
+/** The contrast ratio of two colours, 1 to 21. */
+export const contrastOf = (a, b) => (Math.max(lum(a), lum(b)) + 0.05) / (Math.min(lum(a), lum(b)) + 0.05);
+/** Black or white, or a deep or pale tone of the colour itself, whichever reads at 4.5 to 1 on the colour (the best of them when none does). */
+export function inkFor(main) {
+    const dark = lum(main) > 0.18;
+    const list = dark ? [mix(main, -0.72), "#000000", mix(main, 0.9), "#ffffff"] : [mix(main, 0.9), "#ffffff", mix(main, -0.72), "#000000"];
+    const scored = list.map((c) => [c, contrastOf(readColour(c), main)]);
+    return (scored.find((s) => s[1] >= 4.5) ?? scored.reduce((a, b) => (b[1] > a[1] ? b : a)))[0];
+}
+/** The lines to cut, as candidates (the layout takes the one that gives the biggest letters), and the year when a plate of its own holds it. */
+export function linesOf(e, place) {
+    const yearApart = place?.yearApart === true;
+    if (e.free !== undefined) {
+        const rows = e.free.split("\n");
+        if (rows.length > 1)
+            return { main: [rows.map((text, i) => ({ text, weight: i === 0 ? 1 : i === 1 ? 0.62 : 0.5 }))], year: undefined };
+        const words = (e.free.match(/\S+/g) ?? [e.free]);
+        const cut = words.slice(1).map((_, i) => [words.slice(0, i + 1).join(" "), words.slice(i + 1).join(" ")]);
+        const one = [{ text: e.free, weight: 1 }];
+        return { main: [one, ...cut.map((pair) => pair.map((text, i) => ({ text, weight: i === 0 ? 1 : 0.62 })))], year: undefined };
+    }
+    const rank = e.rank ?? place?.rank;
+    const lines = [];
+    const big = rank !== undefined;
+    if (rank !== undefined)
+        lines.push({ text: rank, weight: 1 });
+    if (e.label !== undefined)
+        lines.push({ text: e.label, weight: big ? 0.5 : 1 });
+    if (e.year !== undefined && !yearApart)
+        lines.push({ text: e.year, weight: big ? 0.42 : 0.6 });
+    return { main: lines.length === 0 ? [] : [lines], year: yearApart ? e.year : undefined };
+}
+/** Lines fitted to a plate: each line's size and baseline, and the smallest size (the score of the fit). */
+function fit(lines, p) {
+    const lh = 1.14;
+    const unit = p.h / lines.reduce((sum, l) => sum + l.weight * lh, 0);
+    const sizes = lines.map((l) => Math.min(unit * l.weight, (p.w * 0.96) / Math.max(widthOf(l.text), 0.4)));
+    const total = sizes.reduce((sum, s) => sum + s * lh, 0);
+    let top = p.y - total / 2;
+    const rows = lines.map((l, i) => {
+        const size = sizes[i];
+        const y = top + (size * lh) / 2 + size * 0.36;
+        top += size * lh;
+        return { text: l.text, size, y, width: widthOf(l.text) * size };
+    });
+    return { rows, score: Math.min(...sizes) };
+}
+/** The ink of an engraving: the page's ink in the line style, else the colour that reads on the metal. */
+export const engravingInk = (style, main) => (style === "line" ? "currentColor" : inkFor(main));
+/** Lines cut into a plate, as markup: the ink, and in the metal style a faint light under each line where the cut catches it. `candidates` are alternative line breaks, and the best fit is used. */
+export function plateMarkup(candidates, plate, main, style) {
+    const fits = candidates.filter((c) => c.length > 0).map((c) => fit(c, plate));
+    if (fits.length === 0)
+        return "";
+    const best = fits.reduce((a, b) => (b.score > a.score + 0.01 ? b : a));
+    const text = (dx) => best.rows
+        .map((r) => `<text x="${n2(plate.x + dx)}" y="${n2(r.y + dx)}" font-size="${n2(r.size)}" textLength="${n2(r.width)}" lengthAdjust="spacingAndGlyphs">${escape(r.text)}</text>`)
+        .join("");
+    const head = `font-family="${FONT}" font-weight="800" text-anchor="middle" stroke="none"`;
+    const glint = style === "metal" ? `<g ${head} fill="${mix(main, 0.7)}" fill-opacity=".7">${text(0.3)}</g>` : "";
+    const marks = `${glint}<g ${head} fill="${engravingInk(style, main)}">${text(0)}</g>`;
+    return plate.rot === undefined ? marks : `<g transform="rotate(${plate.rot} ${n2(plate.x)} ${n2(plate.y)})">${marks}</g>`;
+}
+/** The letters of a text set round a body at a radius: `angle` is the turn of the body now, `place` puts a point of the surface on the screen. A letter on the far side is left out. */
+export function cylinderText(text, radius, height, ink, angle, centre, place) {
+    const em = Math.max(widthOf(text), 0.4);
+    const size = Math.min(height * 0.8, (radius * 1.9) / em);
+    const letters = [...text];
+    let run = -(em * size) / 2;
+    let out = "";
+    for (const ch of letters) {
+        const w = advance(ch) * size;
+        const deg = centre + angle + ((run + w / 2) / radius) * (180 / Math.PI);
+        run += w;
+        if (ch === " ")
+            continue;
+        const [x, y, depth] = place(deg);
+        if (depth < 0.14)
+            continue;
+        out += `<text transform="translate(${n2(x)} ${n2(y + size * 0.36)}) scale(${n2(depth)} 1)">${escape(ch)}</text>`;
+    }
+    return out === "" ? "" : `<g font-family="${FONT}" font-weight="800" text-anchor="middle" font-size="${n2(size)}" fill="${ink}" fill-opacity=".92" stroke="none">${out}</g>`;
+}
+/** The letters of a text set on one flat side of a body, from one edge of the side to the other, as that side faces the eye. `a` and `b` are the two edges on the screen, `depth` how squarely the side faces. */
+export function sideText(text, chord, height, ink, a, b, depth) {
+    if (depth < 0.14)
+        return "";
+    const em = Math.max(widthOf(text), 0.4);
+    const size = Math.min(height * 0.8, (chord * 0.8) / em);
+    const slope = (b[1] - a[1]) / (b[0] - a[0] || 1);
+    let run = -(em * size) / 2;
+    let out = "";
+    for (const ch of text) {
+        const w = advance(ch) * size;
+        const u = 0.5 + (run + w / 2) / chord;
+        run += w;
+        if (ch === " ")
+            continue;
+        out += `<text transform="matrix(${n2(depth)} ${n2(slope * depth)} 0 1 ${n2(a[0] + (b[0] - a[0]) * u)} ${n2(a[1] + (b[1] - a[1]) * u + size * 0.36)})">${escape(ch)}</text>`;
+    }
+    return `<g font-family="${FONT}" font-weight="800" text-anchor="middle" font-size="${n2(size)}" fill="${ink}" fill-opacity=".92" stroke="none">${out}</g>`;
+}
+/** The text of an engraving as one line, for a band that holds one: the free text with its lines joined, or the rank, label and year. */
+export const flatText = (e) => (e.free ?? [e.rank, e.label, e.year].filter((part) => part !== undefined).join(" ")).replace(/\n/g, " ");
+/** What is to be cut into a face, from the options: the free text, or the label, year and rank, and the text of the back. */
+export function engravingOf(o) {
+    const e = {};
+    const free = clean(o?.engrave, 3);
+    const [label, year, rank, back] = [clean(o?.label), clean(o?.year), clean(o?.rank), clean(o?.engraveBack, 3)];
+    if (free !== undefined)
+        e.free = free;
+    if (label !== undefined)
+        e.label = label;
+    if (year !== undefined)
+        e.year = year;
+    if (rank !== undefined)
+        e.rank = rank;
+    if (back !== undefined)
+        e.back = back;
+    return e;
+}

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

@@ -0,0 +1,24 @@
+import type { BallId, GearId, MedalId, SportName, TrophyId } from "./emblem.ids.ts";
+/** The equipment of one sport. */
+export interface SportEquipment {
+    sport: SportName;
+    /** The ball, or the implement that stands for one (the puck, the shuttlecock, the shot). Swimming, diving, artistic swimming, skating and the Japanese sports (sumo, kendo, judo, kyudo, karate) have none. */
+    ball?: BallId;
+    /** The gear the sport has an emblem for, most telling first. Empty where the package has none yet. */
+    gear: GearId[];
+    /** The trophy that stands for the sport's cup: its own where the package draws one, otherwise a plain cup, bowl or globe. */
+    trophy: TrophyId;
+    /** The medal of the sport's champion, for a sport in the Games. */
+    medal?: MedalId;
+}
+/**
+ * What a sport is played and won with, as ids of the registry: `sportEquipment("nhl")` is the puck, a stick, a skate, a goalie's mask and a net, and the hockey cup. The arrays are new each call. An unknown sport is an error.
+ * @example
+ * ```ts
+ * import { sportEquipment } from "@johnmorrisdotca/dougu-sports/emblems";
+ * const nhl = sportEquipment("nhl");
+ * console.log(nhl.ball, nhl.trophy);
+ * // ball:puck trophy:hockey-cup
+ * ```
+ */
+export declare function sportEquipment(sport: SportName): SportEquipment;

package/dist/emblems/emblem.equipment.js

@@ -0,0 +1,57 @@
+const GOLD = "medal:gold";
+const TABLE = {
+    nfl: ["ball:football", ["gear:football-helmet", "gear:goalposts"], "trophy:football"],
+    cfl: ["ball:football-cfl", ["gear:football-helmet", "gear:goalposts"], "trophy:canadian-bowl"],
+    ifaf: ["ball:football-ifaf", ["gear:football-helmet", "gear:goalposts"], "trophy:cup"],
+    nhl: ["ball:puck", ["gear:hockey-stick", "gear:hockey-skate", "gear:goalie-mask", "gear:goal-net"], "trophy:hockey-cup"],
+    nba: ["ball:basketball", ["gear:basketball-hoop"], "trophy:basketball"],
+    mlb: ["ball:baseball", ["gear:baseball-bat", "gear:baseball-glove"], "trophy:baseball"],
+    soccer: ["ball:soccer", ["gear:goal-net"], "trophy:soccer-globe", GOLD],
+    curling: ["ball:curling-stone", ["gear:curling-broom"], "trophy:bowl", GOLD],
+    tennis: ["ball:tennis", ["gear:tennis-racket"], "trophy:tennis-cup", GOLD],
+    volleyball: ["ball:volleyball", ["gear:volleyball-net"], "trophy:cup", GOLD],
+    badminton: ["ball:shuttlecock-feather", ["gear:badminton-racket"], "trophy:cup", GOLD],
+    pickleball: ["ball:pickleball-outdoor", ["gear:pickleball-paddle"], "trophy:cup"],
+    tabletennis: ["ball:table-tennis", ["gear:table-tennis-paddle"], "trophy:cup", GOLD],
+    padel: ["ball:padel", ["gear:padel-racket"], "trophy:cup"],
+    squash: ["ball:squash", ["gear:squash-racket"], "trophy:cup", GOLD],
+    racquetball: ["ball:racquetball", ["gear:racquetball-racket"], "trophy:cup"],
+    sepaktakraw: ["ball:sepak-takraw", [], "trophy:cup"],
+    teqball: ["ball:teqball", [], "trophy:cup"],
+    roundnet: ["ball:roundnet", ["gear:roundnet-set"], "trophy:cup"],
+    netball: ["ball:netball", [], "trophy:cup"],
+    swimming: [undefined, ["gear:swim-goggles"], "trophy:cup", GOLD],
+    waterpolo: ["ball:water-polo", ["gear:swim-goggles"], "trophy:cup", GOLD],
+    diving: [undefined, ["gear:diving-board"], "trophy:cup", GOLD],
+    artisticswimming: [undefined, ["gear:swim-goggles"], "trophy:cup", GOLD],
+    lacrosse: ["ball:lacrosse", ["gear:lacrosse-stick"], "trophy:cup", GOLD],
+    rugby: ["ball:rugby", ["gear:goalposts"], "trophy:rugby-cup", GOLD],
+    afl: ["ball:afl", ["gear:goalposts"], "trophy:cup"],
+    gaelic: ["ball:sliotar", ["gear:hurley", "gear:goalposts"], "trophy:cup"],
+    cricket: ["ball:cricket-red", ["gear:cricket-bat", "gear:wicket"], "trophy:cricket-urn", GOLD],
+    fieldhockey: ["ball:field-hockey", ["gear:field-hockey-stick", "gear:goal-net"], "trophy:cup", GOLD],
+    handball: ["ball:handball", ["gear:goal-net"], "trophy:cup", GOLD],
+    athletics: ["ball:shot", ["gear:starting-blocks", "gear:relay-baton", "gear:javelin", "gear:hurdles"], "trophy:laurel", GOLD],
+    skating: [undefined, ["gear:figure-skate", "gear:speed-skate"], "trophy:cup", GOLD],
+    sumo: [undefined, ["gear:gunbai", "gear:mawashi"], "trophy:sumo-cup"],
+    kendo: [undefined, ["gear:shinai", "gear:kendo-men"], "trophy:cup"],
+    judo: [undefined, ["gear:judogi", "gear:obi"], "trophy:cup", GOLD],
+    kyudo: [undefined, ["gear:yumi", "gear:ya"], "trophy:cup"],
+    karate: [undefined, ["gear:karate-gi"], "trophy:cup", GOLD],
+};
+/**
+ * What a sport is played and won with, as ids of the registry: `sportEquipment("nhl")` is the puck, a stick, a skate, a goalie's mask and a net, and the hockey cup. The arrays are new each call. An unknown sport is an error.
+ * @example
+ * ```ts
+ * import { sportEquipment } from "@johnmorrisdotca/dougu-sports/emblems";
+ * const nhl = sportEquipment("nhl");
+ * console.log(nhl.ball, nhl.trophy);
+ * // ball:puck trophy:hockey-cup
+ * ```
+ */
+export function sportEquipment(sport) {
+    if (!Object.hasOwn(TABLE, sport))
+        throw new Error(`Unknown sport "${String(sport).slice(0, 40)}": the equipment is for the names in SPORT_NAMES.`);
+    const [ball, gear, trophy, medal] = TABLE[sport];
+    return { sport, ...(ball === undefined ? {} : { ball }), gear: [...gear], trophy, ...(medal === undefined ? {} : { medal }) };
+}

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

@@ -0,0 +1,10 @@
+/** What a turn needs. `line` is the line style (the rim is drawn in the page's ink), `back` is the document of the back view, and `thick` is the thickness as a fraction of the width. */
+export interface FlipOptions {
+    yaw: number;
+    pitch: number;
+    line?: boolean;
+    back?: string;
+    thick?: number;
+}
+/** A document turned by `yaw` and `pitch` degrees from its still drawing. With no turn it is the document itself. */
+export declare function flipSvg(svg: string, o: FlipOptions): string;

package/dist/emblems/emblem.flip.js

@@ -0,0 +1,45 @@
+// The coin-flip turn for any flat drawing: it takes a finished document and returns it turned. The face is squeezed by the cosine of the yaw and shows its back past a quarter turn, and the rim
+// (the thickness of the sheet) shows as a dark edge on the side that is turning away, widest when the drawing is edge on. A piece with no drawing of its own for the back (a bat, a racket, a pictogram)
+// shows its front mirrored and a little darker, as the other side of a cut-out; a pennant passes the drawing of its back. A pure function of strings and numbers; it imports nothing.
+const RAD = Math.PI / 180;
+const n2 = (value) => String(Math.round(value * 100) / 100 + 0);
+/** The parts of a document of SVG: its opening tag, its titles, and the rest. */
+function split(svg) {
+    const open = /^<svg[^>]*>/.exec(svg)?.[0] ?? "";
+    const after = svg.slice(open.length, svg.length - "</svg>".length);
+    const head = /^<title>[\s\S]*?<\/title>(?:<desc>[\s\S]*?<\/desc>)?/.exec(after)?.[0] ?? "";
+    const box = (/viewBox="([^"]*)"/.exec(open)?.[1] ?? "0 0 64 64").split(/\s+/).map(Number);
+    return { open, head, rest: after.slice(head.length), box: [box[0] ?? 0, box[1] ?? 0, box[2] || 64, box[3] || 64] };
+}
+/** A document turned by `yaw` and `pitch` degrees from its still drawing. With no turn it is the document itself. */
+export function flipSvg(svg, o) {
+    if (o.yaw === 0 && o.pitch === 0)
+        return svg;
+    const across = Math.cos(o.yaw * RAD);
+    const tilt = Math.cos(o.pitch * RAD);
+    const front = split(svg);
+    const showBack = across < 0;
+    const own = showBack && o.back !== undefined ? split(o.back) : undefined;
+    const face = own ?? front;
+    const [x0, y0, w, h] = front.box;
+    const sx = Math.max(Math.abs(across), 0.02);
+    const sy = Math.max(Math.abs(tilt), 0.02);
+    const thick = w * (o.thick ?? 0.035);
+    const dx = thick * Math.sin(o.yaw * RAD);
+    const dy = -thick * Math.sin(o.pitch * RAD) * 0.6;
+    const mirror = showBack && own === undefined;
+    const cx = x0 + w / 2;
+    const cy = y0 + h / 2;
+    // The turned face, then the filter that adds the rim behind it (and dims a mirrored back).
+    // The id names everything the definition depends on (its region comes from the box), so two drawings in one page that share an id share one filter.
+    const id = `dgf${o.line === true ? "l" : "c"}${mirror ? "b" : "f"}${Math.round(dx * 100)}_${Math.round(dy * 100)}_${[x0, y0, w, h].map((v) => Math.round(v)).join("_")}`;
+    const flood = o.line === true ? '<feFlood flood-color="currentColor" flood-opacity=".5"/>' : '<feFlood flood-color="#000" flood-opacity=".42"/>';
+    const steps = [1, 2, 3].map((k) => (Math.abs(dx) + Math.abs(dy) < 0.05 ? "" : `<feOffset in="s" dx="${n2((dx * k) / 3)}" dy="${n2((dy * k) / 3)}" result="o${k}"/>`)).join("");
+    const nodes = Math.abs(dx) + Math.abs(dy) < 0.05 ? "" : '<feMergeNode in="o3"/><feMergeNode in="o2"/><feMergeNode in="o1"/>';
+    const dim = mirror && o.line !== true ? '<feColorMatrix in="SourceGraphic" values=".8 0 0 0 0 0 .8 0 0 0 0 0 .8 0 0 0 0 0 1 0" result="d"/>' : "";
+    const filter = `<filter id="${id}" x="${n2(x0 - w * 0.15)}" y="${n2(y0 - h * 0.15)}" width="${n2(w * 1.3)}" height="${n2(h * 1.3)}" filterUnits="userSpaceOnUse" color-interpolation-filters="sRGB">` +
+        `${flood}<feComposite in2="SourceAlpha" operator="in" result="s"/>${steps}${dim}<feMerge>${nodes}<feMergeNode in="${dim === "" ? "SourceGraphic" : "d"}"/></feMerge></filter>`;
+    const flip = mirror ? -1 : 1;
+    const group = `<g filter="url(#${id})"><g transform="translate(${n2(cx)} ${n2(cy)}) scale(${n2(sx * flip)} ${n2(sy)}) translate(${n2(-cx)} ${n2(-cy)})">${face.rest}</g></g>`;
+    return `${front.open}${front.head}<defs>${filter}</defs>${group}</svg>`;
+}