@johnmorrisdotca/dougu-sports 0.1.0 → 0.2.1

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

@@ -6,6 +6,8 @@ export declare const EMBLEM_STYLES: readonly ["metal", "line", "color"];
  * one, for an image (an `<img>`, a data address) that cannot inherit. `light` and `dark` force one.
  */
 export type EmblemTheme = "inherit" | "auto" | "light" | "dark";
+/** The languages an emblem's `<title>` can be written in. */
+export type EmblemLocale = "en" | "ja";
 export interface EmblemOptions {
     /** `metal` (the default), `line` or `color`. */
     style?: EmblemStyle;
@@ -21,6 +23,27 @@ export interface EmblemOptions {
     initials?: string;
     /** A ball: force the grain of its surface on or off. By default it is on for a ball of 48 pixels or more that is not turning. */
     grain?: boolean;
+    /** The language of the `<title>`: `"en"` (the default) or `"ja"`, from the emblem's English or Japanese name. */
+    locale?: EmblemLocale;
+    /** The `<title>`: a string writes that title (escaped); `false` drops it and marks the drawing `aria-hidden="true"`, for an emblem that sits beside text that says the same. */
+    title?: string | false;
+    /**
+     * Text cut into the face of a medal or place badge, the plaque, the belt, and the plinth of a cup: any text, Japanese included, up to three lines (a line break, or a space between a word and a year, makes lines).
+     * It wins over `label`, `year` and `rank`.
+     */
+    engrave?: string;
+    /** The words to engrave ("MVP"), with `year` and `rank` as lines of their own. Ignored when `engrave` is given. */
+    label?: string;
+    /** A year, engraved small under the label (on a plaque, on its nameplate). A number or a string. */
+    year?: number | string;
+    /** A place or a number, engraved large ("1"). On a place badge it is the badge's own place unless given. */
+    rank?: number | string;
+    /** The engraving of a medal's back, shown when it is turned over. Without it the back is plain. */
+    engraveBack?: string;
+    /** The colour of a pennant's lettering when it is not the second colour. A hex colour or `rgb()`. */
+    numberColor?: string;
+    /** Which side of a pennant is drawn at rest: `"front"` (the default) or `"back"`. */
+    view?: "front" | "back";
 }
 /** 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 {
@@ -46,8 +69,8 @@ export declare const METALS: {
 };
 /** A metal by name, or `flat` for a colour that is no metal (a crest's blue, a sport's plain ink). */
 export type Metal = keyof typeof METALS | "flat";
-/** Where an emblem's art comes from: drawn for this package (`ours`) or taken from a source listed in NOTICE.md. */
-export type EmblemSource = "ours" | "material" | "generated" | "drawn" | "noto" | "mdi" | "commons" | "gameicons";
+/** Where an emblem's art comes from: drawn for this package (`ours`, `drawn`) or made by this package's own code (`generated`). Nothing is copied from another project. */
+export type EmblemSource = "ours" | "generated" | "drawn";
 /** What an emblem is: a flat object (a front and a back, to flip), a ball (a sphere or a solid, turned in 3D), a body of revolution (`lathe`), an icon (one drawing, not turned) or a piece of gear (a flat drawing, not turned). */
 export type EmblemKind = "flat" | "ball" | "lathe" | "icon" | "gear";
 export type Rgb = readonly [number, number, number];
@@ -58,6 +81,19 @@ export declare const hexOf: (rgb: Rgb) => string;
 export declare function mix(rgb: Rgb, amount: number): string;
 /** Text made safe to write between tags and inside a double-quoted attribute. */
 export declare const escape: (text: string) => string;
+/**
+ * The `<title>` of a finished drawing, as the options ask: a string is the title (escaped), `false` drops it and hides the drawing from a screen reader, and `locale: "ja"` writes the Japanese name. With none
+ * of the three the drawing is returned as it is.
+ */
+export declare function relabel(svg: string, en: string, ja: string, o: {
+    locale?: unknown;
+    title?: unknown;
+} | undefined): string;
+/** A drawing function whose result carries the title the options ask for. */
+export declare const labelled: <O extends {
+    locale?: unknown;
+    title?: unknown;
+}>(en: string, ja: string, draw: (options?: O) => string) => (options?: O) => string;
 /** A number written for a path: two decimals at most, and never `-0`. */
 export declare const n2: (value: number) => string;
 /** The options as the renderers use them. */
@@ -70,6 +106,16 @@ export interface Resolved {
     initials: string;
 }
 export declare function resolve(o: EmblemOptions | undefined): Resolved;
+/** What is to be cut into a face: the free text, or the label, year and rank, and the text of the back. A line is at most 24 letters and has no control character. */
+export interface Engraving {
+    free?: string;
+    label?: string;
+    year?: string;
+    rank?: string;
+    back?: string;
+}
+/** A text from outside made safe: control characters removed, at most 24 letters a line and `lines` lines, or `undefined` when nothing is left. */
+export declare const clean: (value: unknown, lines?: number) => string | undefined;
 /** The main colour of a metal, or the tint when there is one. */
 export declare const mainOf: (metal: Metal, tint: Rgb | undefined) => Rgb;
 /** The relative luminance of a colour, 0 to 1. */

package/dist/emblems/emblem.core.js

@@ -29,6 +29,24 @@ export function mix(rgb, amount) {
 }
 /** Text made safe to write between tags and inside a double-quoted attribute. */
 export const escape = (text) => text.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;").replace(/"/g, "&quot;");
+/**
+ * The `<title>` of a finished drawing, as the options ask: a string is the title (escaped), `false` drops it and hides the drawing from a screen reader, and `locale: "ja"` writes the Japanese name. With none
+ * of the three the drawing is returned as it is.
+ */
+export function relabel(svg, en, ja, o) {
+    const title = o?.title;
+    const japanese = o?.locale === "ja";
+    if (title === false)
+        return svg.replace(/<title>[^<]*<\/title>/, "").replace(' role="img"', ' aria-hidden="true"');
+    const custom = typeof title === "string" && title.trim() !== "";
+    if (!custom && !japanese)
+        return svg;
+    const text = custom ? title.trim().slice(0, 300) : ja;
+    const titled = svg.replace(/<title>[^<]*<\/title>/, () => `<title>${escape(text)}</title>`);
+    return custom ? titled : titled.replace(' role="img"', ' role="img" lang="ja"');
+}
+/** A drawing function whose result carries the title the options ask for. */
+export const labelled = (en, ja, draw) => (options) => relabel(draw(options), en, ja, options);
 /** A number written for a path: two decimals at most, and never `-0`. */
 export const n2 = (value) => String(Math.round(value * 100) / 100 + 0);
 export function resolve(o) {
@@ -39,6 +57,18 @@ export function resolve(o) {
     const initials = typeof o?.initials === "string" ? [...o.initials.trim()].slice(0, 3).join("").toUpperCase() : "";
     return { style, size, theme, tint: readColour(o?.tint), accent: accent === undefined ? undefined : hexOf(accent), initials };
 }
+/** A text from outside made safe: control characters removed, at most 24 letters a line and `lines` lines, or `undefined` when nothing is left. */
+export const clean = (value, lines = 1) => {
+    if (typeof value !== "string" && typeof value !== "number")
+        return undefined;
+    const text = String(value)
+        .split(/\r?\n/)
+        .slice(0, lines)
+        .map((line) => [...line.replace(/\p{Cc}/gu, "").trim()].slice(0, 24).join(""))
+        .filter((line) => line !== "")
+        .join("\n");
+    return text === "" ? undefined : text;
+};
 /** The main colour of a metal, or the tint when there is one. */
 export const mainOf = (metal, tint) => tint ?? readColour(metal === "flat" ? "#8a949e" : METALS[metal]);
 /** The relative luminance of a colour, 0 to 1. */

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;