@johnmorrisdotca/dougu-sports 0.1.0 → 0.2.0

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

@@ -0,0 +1,7 @@
+import type { EmblemId } from "./emblem.ids.ts";
+/** An emblem's description in the two languages. */
+export interface EmblemDescription {
+    readonly en: string;
+    readonly ja: string;
+}
+export declare const EMBLEM_DESCRIPTIONS: Readonly<Partial<Record<EmblemId, EmblemDescription>>>;

package/dist/emblems/emblem.descriptions.js

@@ -0,0 +1,60 @@
+export const EMBLEM_DESCRIPTIONS = {
+    "trophy:hockey-cup": { en: "Tall banded silver cup", ja: "帯を何段も重ねた背の高い銀のカップ" },
+    "trophy:basketball": { en: "Basketball trophy", ja: "バスケットボールのトロフィー" },
+    "trophy:football": { en: "Football trophy", ja: "アメリカンフットボールのトロフィー" },
+    "trophy:soccer-ball": { en: "Soccer ball trophy", ja: "サッカーボールのトロフィー" },
+    "trophy:tennis-cup": { en: "Two-handled cup with a pineapple", ja: "取っ手が二つあり、ふたにパイナップルの飾りが付いたカップ" },
+    "sport:ifaf": { en: "American football, international rules", ja: "国際ルールのアメリカンフットボール" },
+    "sport:pickleball": { en: "Pickleball paddle and ball", ja: "ピックルボールのパドルとボール" },
+    "sport:tabletennis": { en: "Table tennis paddle and ball", ja: "卓球のラケットとボール" },
+    "sport:squash": { en: "Squash racket and ball", ja: "スカッシュのラケットとボール" },
+    "sport:racquetball": { en: "Racquetball racket and ball", ja: "ラケットボールのラケットとボール" },
+    "sport:sepaktakraw": { en: "Woven ball", ja: "セパタクローの編み目のボール" },
+    "sport:teqball": { en: "Curved table and ball", ja: "テックボールの湾曲した台とボール" },
+    "sport:roundnet": { en: "Round net", ja: "ラウンドネットの円形ネット" },
+    "sport:netball": { en: "Ball and hoop", ja: "ネットボールのボールとゴールリング" },
+    "sport:artisticswimming": { en: "Raised legs", ja: "水面に上げた脚（アーティスティックスイミング）" },
+    "sport:afl": { en: "Oval ball", ja: "オーストラリアンフットボールのボール" },
+    "sport:gaelic": { en: "Round ball with seams", ja: "ゲーリックフットボールのボール" },
+    "sport:fieldhockey": { en: "Hooked stick and ball", ja: "フィールドホッケーのスティックとボール" },
+    "ball:basketball-6": { en: "Basketball, size 6", ja: "バスケットボール（6号球）" },
+    "ball:cricket-pink": { en: "Cricket ball, pink", ja: "クリケットボール（ピンク）" },
+    "ball:football": { en: "Football (NFL)", ja: "アメリカンフットボールのボール（NFL）" },
+    "ball:football-cfl": { en: "Football (CFL)", ja: "カナディアンフットボールのボール（CFL）" },
+    "ball:football-ifaf": { en: "Football (IFAF)", ja: "アメリカンフットボールのボール（IFAF）" },
+    "ball:afl": { en: "Australian football", ja: "オーストラリアンフットボールのボール" },
+    "ball:gaelic-football": { en: "Gaelic football", ja: "ゲーリックフットボールのボール" },
+    "ball:squash": { en: "Squash ball, double yellow dot", ja: "スカッシュボール（ダブルイエロードット）" },
+    "ball:squash-yellow": { en: "Squash ball, yellow dot", ja: "スカッシュボール（イエロードット）" },
+    "ball:squash-green": { en: "Squash ball, green dot", ja: "スカッシュボール（グリーンドット）" },
+    "ball:squash-red": { en: "Squash ball, red dot", ja: "スカッシュボール（レッドドット）" },
+    "ball:squash-blue": { en: "Squash ball, blue dot", ja: "スカッシュボール（ブルードット）" },
+    "ball:shuttlecock-feather": { en: "Shuttlecock, feather", ja: "シャトルコック（水鳥の羽根）" },
+    "ball:shuttlecock-nylon": { en: "Shuttlecock, nylon", ja: "シャトルコック（ナイロン）" },
+    "gear:hockey-stick": { en: "Hockey stick and puck", ja: "アイスホッケーのスティックとパック" },
+    "gear:goalie-stick": { en: "Ice hockey goalie stick", ja: "アイスホッケーのゴーリーのスティック" },
+    "gear:hockey-skate": { en: "Hockey skate", ja: "アイスホッケーのスケート靴" },
+    "gear:field-hockey-stick": { en: "Field hockey stick and ball", ja: "フィールドホッケーのスティックとボール" },
+    "gear:cricket-bat": { en: "Cricket bat and ball", ja: "クリケットのバットとボール" },
+    "gear:table-tennis-paddle": { en: "Table-tennis paddle and ball", ja: "卓球のラケットとボール" },
+    "gear:badminton-racket": { en: "Badminton racket and shuttlecock", ja: "バドミントンのラケットとシャトルコック" },
+    "gear:football-helmet": { en: "Football helmet", ja: "アメリカンフットボールのヘルメット" },
+    "gear:hurley": { en: "Hurley", ja: "ハーリー（ハーリングのスティック）" },
+    "trophy:sumo-cup": { en: "A tall silver cup on a tall stepped stand, with an ornate phoenix-crested handle on each side", ja: "段のある高い台に載った、背の高い銀の杯。両側の取っ手に鳳凰の飾りが付く" },
+    "trophy:championship-banner": { en: "A fringed banner on a pole with a gilt finial and an embroidered border, with no lettering unless some is given", ja: "金の先端飾りの付いた竿に掛けた、刺繍の縁と房の付いた旗。文字は指定したときだけ入る" },
+    "sport:sumo": { en: "Two wrestlers in the crouch they face each other in at the start of a bout, with their belts", ja: "仕切りの姿勢で向かい合う、廻しを締めた二人の力士" },
+    "sport:handball": { en: "A hand throwing the ball, with lines of speed", ja: "ボールを投げる手と、速さを表す線" },
+    "sport:kendo": { en: "The kendo helmet", ja: "剣道の面" },
+    "sport:judo": { en: "The judo suit and belt", ja: "柔道衣と帯" },
+    "sport:kyudo": { en: "A long bow, its string and an arrow", ja: "弦を張った長弓と矢" },
+    "sport:karate": { en: "A clenched fist", ja: "握りしめた拳" },
+    "gear:gunbai": { en: "The sumo referee's war fan, with its tassel", ja: "行司が持つ軍配と、その房" },
+    "gear:mawashi": { en: "The wrestler's belt, with the stiff cords that hang from its front", ja: "力士の廻しと、前に垂らした下がり" },
+    "gear:shinai": { en: "The kendo practice sword: four bamboo staves with a leather tip, a tie and a hilt", ja: "剣道の竹刀。四つ割りの竹に先革、中結、柄が付く" },
+    "gear:kendo-men": { en: "The kendo helmet: a steel grille, cloth flaps and a throat guard", ja: "剣道の面。面金、面布団、突き垂れが付く" },
+    "gear:judogi": { en: "The judo suit: a jacket with crossed lapels, trousers and a belt", ja: "柔道衣。上衣、ズボン、帯" },
+    "gear:obi": { en: "A tied belt in the colour of a rank, white to black", ja: "段級に応じた色の、結んだ帯（白から黒まで）" },
+    "gear:yumi": { en: "The long asymmetric bow, held a third of the way up, with its string and wrapped grip", ja: "上が長い非対称の長弓。弦を張り、握り革と籐巻きが付く" },
+    "gear:ya": { en: "A kyudo arrow with feather fletching, a nock and a steel point", ja: "弓道の矢。矢羽根、筈、矢尻が付く" },
+    "gear:karate-gi": { en: "The karate suit: a jacket with crossed lapels, trousers and a belt", ja: "空手衣。上衣、ズボン、帯" },
+};

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;