@johnmorrisdotca/dougu-sports 0.0.1 → 0.2.0

package/dist/emblems/emblem.api.js

@@ -1,7 +1,8 @@
 import { EMBLEM_STYLES } from "./emblem.core.js";
-import { BALL_IDS, EMBLEM_IDS } from "./emblem.ids.js";
+import { BALL_IDS, CREST_SHAPES, EMBLEM_ALIASES, EMBLEM_IDS } from "./emblem.ids.js";
+import { EMBLEM_DESCRIPTIONS } from "./emblem.descriptions.js";
 import { EMBLEM_TABLE } from "./emblem.registry.js";
-/** The id and style a string names, or `undefined` when it is not an emblem. An id may end in `/metal`, `/line` or `/color`. */
+/** The id and style a string names, or `undefined` when it is not an emblem. An id may end in `/metal`, `/line` or `/color`, and a trophy or an award may be written without its group (`cup`, `crown`). */
 export function parseEmblem(value) {
     if (typeof value !== "string")
         return undefined;
@@ -17,9 +18,10 @@ export function parseEmblem(value) {
         style = tail;
         text = text.slice(0, slash);
     }
-    return Object.hasOwn(EMBLEM_TABLE, text) ? { id: text, style } : undefined;
+    const id = Object.hasOwn(EMBLEM_ALIASES, text) ? EMBLEM_ALIASES[text] : text;
+    return Object.hasOwn(EMBLEM_TABLE, id) ? { id: id, style } : undefined;
 }
-/** True when the value is the id of an emblem (with no style). */
+/** True when the value is the id of an emblem (not a short name, and with no style). */
 export function isEmblemId(value) {
     return typeof value === "string" && Object.hasOwn(EMBLEM_TABLE, value);
 }
@@ -29,7 +31,7 @@ export function emblemOf(ref) {
         return { emblem: ref, style: undefined };
     const parsed = parseEmblem(ref);
     if (parsed === undefined)
-        throw new Error(`Unknown emblem "${ref.slice(0, 60)}". Ids look like "award:medal" or "ball:soccer"; see EMBLEM_IDS.`);
+        throw new Error(`Unknown emblem "${ref.slice(0, 60)}". Ids look like "trophy:cup", "medal:gold", "sport:nhl" or "crest:shield"; see EMBLEM_IDS.`);
     return { emblem: EMBLEM_TABLE[parsed.id], style: parsed.style };
 }
 const withStyle = (style, options) => (style === undefined || options?.style !== undefined ? options : { ...options, style });
@@ -39,8 +41,8 @@ const withStyle = (style, options) => (style === undefined || options?.style !==
  * @example
  * ```ts
  * import { renderEmblem } from "@johnmorrisdotca/dougu-sports/emblems";
- * const svg = renderEmblem("award:medal", { style: "line", size: 32 });
- * console.log(svg.startsWith("<svg"), svg.includes("<title>Medal</title>"));
+ * const svg = renderEmblem("trophy:cup", { style: "line", size: 32 });
+ * console.log(svg.startsWith("<svg"), svg.includes("<title>Cup</title>"));
  * // true true
  * ```
  */
@@ -51,11 +53,11 @@ export function renderEmblem(ref, options) {
 /** The same as `renderEmblem`. */
 export const emblemSvg = renderEmblem;
 /**
- * An emblem turned: `yaw` degrees about its vertical axis and `pitch` degrees of tilt, from its resting view, in plain SVG. A flat emblem (a medal) flips like a coin and shows its back; a ball rolls.
+ * An emblem turned: `yaw` degrees about its vertical axis and `pitch` degrees of tilt, from its resting view, in plain SVG. A cup, bowl or urn keeps its outline and moves its light, handles and seams; a medal flips like a coin and shows its back; a ball rolls; an icon is not turned.
  * @example
  * ```ts
  * import { emblemFrame, renderEmblem } from "@johnmorrisdotca/dougu-sports/turn";
- * console.log(emblemFrame("award:medal", { yaw: 0 }) === renderEmblem("award:medal"));
+ * console.log(emblemFrame("medal:gold", { yaw: 0 }) === renderEmblem("medal:gold"));
  * // true
  * ```
  */
@@ -76,7 +78,9 @@ export const EMBLEMS = Object.freeze(Object.fromEntries(EMBLEM_IDS.map((id) => [
 /** The names, source and kind of an emblem. */
 export function emblemInfo(id) {
     const e = EMBLEM_TABLE[id];
-    return { id, en: e.en, ja: e.ja, source: e.source, kind: e.kind };
+    const size = e.size;
+    const description = EMBLEM_DESCRIPTIONS[id];
+    return { id, en: e.en, ja: e.ja, source: e.source, kind: e.kind, ...(size === undefined ? {} : { size }), ...(description === undefined ? {} : { description }) };
 }
 /** An emblem's name in a language. */
 export function emblemName(id, language = "en") {
@@ -86,3 +90,45 @@ export function emblemName(id, language = "en") {
 export function emblemModel(id) {
     return EMBLEM_TABLE[id].model;
 }
+/**
+ * A generic crest tinted by a team's colours, with its letters if it has any: what a team with no logo gets. The letters are in the ink that reads on the colour.
+ * @example
+ * ```ts
+ * import { crest } from "@johnmorrisdotca/dougu-sports/emblems";
+ * const svg = crest({ shape: "shield", colors: ["#c8102e", "#f4f0e4"], initials: "NO" });
+ * console.log(svg.includes(">NO<"));
+ * // true
+ * ```
+ */
+export function crest(options = {}) {
+    const colors = typeof options.colors === "string" ? [options.colors] : (options.colors ?? []);
+    const shape = CREST_SHAPES.includes(options.shape) ? options.shape : "shield";
+    return EMBLEM_TABLE[`crest:${shape}`].svg({ tint: colors[0], accent: colors[1], initials: options.initials, size: options.size, style: options.style, theme: options.theme, locale: options.locale, title: options.title });
+}
+/** A medal on a ribbon: `medal("gold")`, `"silver"` or `"bronze"`; any other kind is the gold one. */
+export function medal(kind, options) {
+    return (EMBLEM_TABLE[`medal:${kind}`] ?? EMBLEM_TABLE["medal:gold"]).svg(options);
+}
+/** The icon of a sport, by the names of `SPORT_NAMES`: `sportIcon("nhl")`. An unknown sport is an error. */
+export function sportIcon(sport, options) {
+    const e = Object.hasOwn(EMBLEM_TABLE, `sport:${sport}`) ? EMBLEM_TABLE[`sport:${sport}`] : undefined;
+    if (e === undefined)
+        throw new Error(`Unknown sport "${String(sport).slice(0, 40)}": the icons are for the names in SPORT_NAMES.`);
+    return e.svg(options);
+}
+/**
+ * A felt championship pennant with a stitched edge, lettered with its words and its year.
+ * @example
+ * ```ts
+ * import { pennant } from "@johnmorrisdotca/dougu-sports/emblems";
+ * const svg = pennant({ colors: ["#1f4e8c", "#f2c230"], text: "Champions", year: 2026 });
+ * console.log(svg.includes(">CHAMPIONS<"), svg.includes(">2026<"));
+ * // true true
+ * ```
+ */
+export function pennant(options = {}) {
+    const colors = typeof options.colors === "string" ? [options.colors] : (options.colors ?? []);
+    const o = { tint: colors[0], accent: colors[1], numberColor: colors[2], engrave: options.text, label: options.label, rank: options.rank, year: options.year, view: options.view, size: options.size, style: options.style, theme: options.theme, yaw: options.yaw, pitch: options.pitch };
+    const e = EMBLEM_TABLE["pennant:championship"];
+    return options.yaw === undefined && options.pitch === undefined ? e.svg(o) : e.frame(o);
+}

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

@@ -0,0 +1,31 @@
+/** An emblem's document taken apart. */
+export interface Parts {
+    /** The view box, `0 0 64 64` unless the drawing came from elsewhere. */
+    box: string;
+    /** The definitions, one string for each top-level element of the `<defs>` (a gradient, a clip path, a filter), with the id it carries. */
+    defs: readonly {
+        id: string;
+        text: string;
+    }[];
+    /** Everything that draws: the body, with the `<title>`, `<style>` and `<defs>` taken out. A `<desc>` stays, because it carries the credit of copied art. */
+    body: string;
+}
+/** Takes an emblem's document apart. */
+export declare function partsOf(svg: string): Parts;
+/**
+ * Documents put together: the definitions of all of them in one list with none twice, and every id renamed so that two different definitions never share one. With a `prefix` the ids are the prefix and a short
+ * counter, so a sheet's ids cannot meet the page's own; with none an id keeps its name until a different definition wants it.
+ */
+export declare class IdSpace {
+    private readonly named;
+    private readonly taken;
+    private readonly prefix;
+    private count;
+    readonly defs: string[];
+    constructor(prefix?: string);
+    private fresh;
+    /** Takes one document's parts in: its definitions join the list, and its body comes back with the ids it uses. */
+    add(parts: Parts): string;
+}
+/** A document nested inside another: its box becomes the place the parent gives it. */
+export declare function nest(box: string, body: string, x: number, y: number, width: number, height: number): string;

package/dist/emblems/emblem.compose.js

@@ -0,0 +1,91 @@
+// The pieces that the sprite, the podium and the award case share: an emblem's document taken apart (its view box, its definitions, its body), and put together again inside another document with
+// every id unique. The emblems are written by this package, so the parts are found by their shape, not by a general XML parser.
+/** The top-level elements of a run of markup, each with its `id` attribute (an empty string when it has none). */
+function topLevel(markup) {
+    const out = [];
+    const tag = /<(\/?)[A-Za-z][\w:-]*[^>]*?(\/?)>/g;
+    let depth = 0;
+    let start = 0;
+    for (let m = tag.exec(markup); m !== null; m = tag.exec(markup)) {
+        if (m[1] === "/") {
+            depth--;
+            if (depth === 0)
+                out.push({ id: "", text: markup.slice(start, m.index + m[0].length) });
+        }
+        else if (m[2] === "/") {
+            if (depth === 0)
+                out.push({ id: "", text: m[0] });
+        }
+        else {
+            if (depth === 0)
+                start = m.index;
+            depth++;
+        }
+    }
+    return out.map((e) => ({ id: /\sid="([^"]*)"/.exec(e.text)?.[1] ?? "", text: e.text }));
+}
+/** Takes an emblem's document apart. */
+export function partsOf(svg) {
+    const open = /^<svg\s[^>]*>/.exec(svg);
+    const box = (open === null ? undefined : /\sviewBox="([^"]+)"/.exec(open[0])?.[1]) ?? "0 0 64 64";
+    let inner = open === null ? svg : svg.slice(open[0].length, svg.lastIndexOf("</svg>"));
+    inner = inner.replace(/<title>[^<]*<\/title>/, "").replace(/<style>[^<]*<\/style>/, "");
+    const defs = [];
+    inner = inner.replace(/<defs>([\s\S]*?)<\/defs>/g, (_, content) => {
+        defs.push(...topLevel(content));
+        return "";
+    });
+    return { box, defs, body: inner };
+}
+/** The ids a document of ours refers to: `id="x"`, `url(#x)` and `href="#x"`. */
+const REFERENCE = /(\sid="|url\(#|href="#)([^")]+)/g;
+/**
+ * Documents put together: the definitions of all of them in one list with none twice, and every id renamed so that two different definitions never share one. With a `prefix` the ids are the prefix and a short
+ * counter, so a sheet's ids cannot meet the page's own; with none an id keeps its name until a different definition wants it.
+ */
+export class IdSpace {
+    named = new Map();
+    taken = new Set();
+    prefix;
+    count = 0;
+    defs = [];
+    constructor(prefix = "") {
+        this.prefix = prefix;
+    }
+    fresh(id) {
+        if (this.prefix === "") {
+            let candidate = id;
+            while (this.taken.has(candidate))
+                candidate = `${id}-${(++this.count).toString(36)}`;
+            return candidate;
+        }
+        return `${this.prefix}_${(this.count++).toString(36)}`;
+    }
+    /** Takes one document's parts in: its definitions join the list, and its body comes back with the ids it uses. */
+    add(parts) {
+        const rename = new Map();
+        const added = [];
+        for (const def of parts.defs) {
+            if (def.id === "")
+                continue;
+            const key = `${def.id}\u0000${def.text}`;
+            let name = this.named.get(key);
+            if (name === undefined) {
+                name = this.fresh(def.id);
+                this.taken.add(name);
+                this.named.set(key, name);
+                added.push(def.text);
+            }
+            rename.set(def.id, name);
+        }
+        const apply = (text) => text.replace(REFERENCE, (all, lead, id) => (rename.has(id) ? `${lead}${rename.get(id)}` : all));
+        for (const text of added)
+            this.defs.push(apply(text));
+        return apply(parts.body);
+    }
+}
+/** A document nested inside another: its box becomes the place the parent gives it. */
+export function nest(box, body, x, y, width, height) {
+    const n = (v) => String(Math.round(v * 100) / 100 + 0);
+    return `<svg x="${n(x)}" y="${n(y)}" width="${n(width)}" height="${n(height)}" viewBox="${box}">${body}</svg>`;
+}

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;
@@ -15,11 +17,40 @@ export interface EmblemOptions {
     tint?: string;
     /** `inherit` (the default), `auto`, `light` or `dark`. */
     theme?: EmblemTheme;
+    /** A second colour: a medal's ribbon, a crest's band, the flags of a trophy. A hex colour or `rgb()`; anything else is ignored. */
+    accent?: string;
+    /** The letters of a crest, up to three. */
+    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 {
     yaw?: number;
     pitch?: number;
+    /** A ball: the turn about the line of sight. */
+    roll?: number;
 }
 /** The ink of a drawing when a theme sets it, and the page it is made to read on. */
 export declare const EMBLEM_INK: {
@@ -36,11 +67,12 @@ export declare const METALS: {
     readonly silver: "#aeb6c0";
     readonly bronze: "#b8733a";
 };
-export type Metal = keyof typeof METALS;
-/** 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" | "noto" | "mdi" | "game-icons";
-/** What an emblem is: a flat object (a front and a back, to flip), a ball (marks on a sphere, to roll), a body of revolution (`lathe`) or an icon (one path, not turned). */
-export type EmblemKind = "flat" | "ball" | "lathe" | "icon";
+/** 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`, `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];
 /** A colour from `#rgb`, `#rrggbb` or `rgb(r, g, b)`, or `undefined` for anything else. */
 export declare function readColour(value: string | undefined): Rgb | undefined;
@@ -49,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. */
@@ -57,10 +102,26 @@ export interface Resolved {
     size: number;
     theme: EmblemTheme;
     tint: Rgb | undefined;
+    accent: string | undefined;
+    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. */
+export declare function lum(rgb: Rgb): number;
+/** Black or white, whichever reads better on a colour. */
+export declare const onColour: (rgb: Rgb) => string;
 /** A turn in degrees, as a finite number (0 for anything else). */
 export declare const degrees: (value: number | undefined) => number;
 /** The colours a drawing is painted with. In the `line` style every fill is `none`. */
@@ -74,8 +135,27 @@ export interface Paint {
     /** The definitions the fills refer to. */
     defs: string;
 }
-/** The paint for a main colour in a style. The gradient's id names the colour, so two of one colour in a page agree. */
-export declare function paintFor(style: EmblemStyle, main: Rgb, kind?: "linear" | "radial"): Paint;
+/** The paint of a ball: a radial gradient in the metal style. The gradient's id names the colour, so two of one colour in a page agree. */
+export declare function paintFor(style: EmblemStyle, main: Rgb): Paint;
+/** A gradient: its id, its definition (a fragment for a `<defs>`) and the fill that names it. */
+export interface Gradient {
+    id: string;
+    def: string;
+    fill: string;
+}
+/**
+ * The shading of a round metal body: a dark edge, a bright band left of the middle, the metal, a darker side, and a faint light from the rim on the far edge, as polished metal throws it. `shift` slides the bright
+ * band (a turn). The id names the colour and the shift, so two bodies of one colour in a page share one definition.
+ */
+export declare function cylinderGradient(main: Rgb, shift?: number): Gradient;
+/** The shading of a round flat or a ball: light from the top left, the metal, then dark at the far edge. */
+export declare function orbGradient(main: Rgb): Gradient;
+/** The shading of a flat sheet of metal, from a bright corner to a dark one. */
+export declare function sheetGradient(main: Rgb): Gradient;
+/** The shading of a raised rim: bright on the top left, dark on the bottom right, as a bevel catches the light (or the other way round, for a groove). */
+export declare function bevelGradient(main: Rgb, groove?: boolean): Gradient;
+/** The gradients' definitions as one `<defs>`, with none twice. */
+export declare const defsOf: (gradients: readonly Gradient[]) => string;
 /** A drawing wrapped into a document: the title, the outline's colour for the theme, and the group that strokes it. */
 export declare function wrap(o: {
     title: string;
@@ -85,6 +165,8 @@ export declare function wrap(o: {
     defs?: string;
     body: string;
     box?: string;
+    edge?: string;
+    width?: number;
 }): string;
 /** One emblem: its id and names, where its art comes from, and the functions that draw it. Importing one of these pulls in its own module and the small renderer it needs, not the other emblems. */
 export interface Emblem<Model = unknown> {

package/dist/emblems/emblem.core.js

@@ -29,20 +29,62 @@ 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) {
     const size = typeof o?.size === "number" && Number.isFinite(o.size) && o.size > 0 ? Math.min(Math.round(o.size * 100) / 100, 4096) : 64;
     const theme = o?.theme === "auto" || o?.theme === "light" || o?.theme === "dark" ? o.theme : "inherit";
     const style = o?.style === "line" || o?.style === "color" ? o.style : "metal";
-    return { style, size, theme, tint: readColour(o?.tint) };
+    const accent = readColour(o?.accent);
+    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(METALS[metal]);
+export const mainOf = (metal, tint) => tint ?? readColour(metal === "flat" ? "#8a949e" : METALS[metal]);
+/** The relative luminance of a colour, 0 to 1. */
+export function lum(rgb) {
+    const [r, g, b] = rgb.map((c) => {
+        const k = c / 255;
+        return k <= 0.03928 ? k / 12.92 : ((k + 0.055) / 1.055) ** 2.4;
+    });
+    return 0.2126 * r + 0.7152 * g + 0.0722 * b;
+}
+/** Black or white, whichever reads better on a colour. */
+export const onColour = (rgb) => ((lum(rgb) + 0.05) / 0.05 > 1.05 / (lum(rgb) + 0.05) ? "#000000" : "#ffffff");
 /** A turn in degrees, as a finite number (0 for anything else). */
 export const degrees = (value) => (typeof value === "number" && Number.isFinite(value) ? value % 360 : 0);
-/** The paint for a main colour in a style. The gradient's id names the colour, so two of one colour in a page agree. */
-export function paintFor(style, main, kind = "linear") {
+/** The paint of a ball: a radial gradient in the metal style. The gradient's id names the colour, so two of one colour in a page agree. */
+export function paintFor(style, main) {
     if (style === "line")
         return { main: "none", shade: "none", light: "none", ribbon: "none", defs: "" };
     const shade = mix(main, -0.28);
@@ -50,18 +92,50 @@ export function paintFor(style, main, kind = "linear") {
     const ribbon = "#b3362b";
     if (style === "color")
         return { main: hexOf(main), shade, light, ribbon, defs: "" };
-    const id = `dgs${kind === "radial" ? "r" : "l"}${hexOf(main).slice(1)}`;
-    const stops = `<stop offset="0" stop-color="${mix(main, -0.3)}"/><stop offset="0.3" stop-color="${light}"/><stop offset="0.55" stop-color="${hexOf(main)}"/><stop offset="1" stop-color="${mix(main, -0.38)}"/>`;
-    const defs = kind === "linear"
-        ? `<defs><linearGradient id="${id}" x2="1" y2="0.2">${stops}</linearGradient></defs>`
-        : `<defs><radialGradient id="${id}" cx="0.36" cy="0.3" r="0.8"><stop offset="0" stop-color="${light}"/><stop offset="0.55" stop-color="${hexOf(main)}"/><stop offset="1" stop-color="${mix(main, -0.38)}"/></radialGradient></defs>`;
+    const id = `dgsr${hexOf(main).slice(1)}`;
+    const defs = `<defs><radialGradient id="${id}" cx="0.36" cy="0.3" r="0.8"><stop offset="0" stop-color="${light}"/><stop offset="0.55" stop-color="${hexOf(main)}"/><stop offset="1" stop-color="${mix(main, -0.38)}"/></radialGradient></defs>`;
     return { main: `url(#${id})`, shade, light, ribbon, defs };
 }
+const stops = (list) => list.map(([at, colour]) => `<stop offset="${n2(at).replace(/^0\./, ".")}" stop-color="${colour}"/>`).join("");
+/**
+ * The shading of a round metal body: a dark edge, a bright band left of the middle, the metal, a darker side, and a faint light from the rim on the far edge, as polished metal throws it. `shift` slides the bright
+ * band (a turn). The id names the colour and the shift, so two bodies of one colour in a page share one definition.
+ */
+export function cylinderGradient(main, shift = 0) {
+    const h = Math.max(0.14, Math.min(0.5, 0.3 + shift));
+    const id = `dgsc${hexOf(main).slice(1)}${shift === 0 ? "" : `s${Math.round(shift * 100) + 100}`}`;
+    const list = [[0, mix(main, -0.5)], [0.1, mix(main, -0.16)], [h, mix(main, 0.62)], [h + 0.26, mix(main, 0.08)], [0.84, mix(main, -0.36)], [0.95, mix(main, -0.1)], [1, mix(main, -0.52)]];
+    return { id, def: `<linearGradient id="${id}">${stops(list)}</linearGradient>`, fill: `url(#${id})` };
+}
+/** The shading of a round flat or a ball: light from the top left, the metal, then dark at the far edge. */
+export function orbGradient(main) {
+    const id = `dgso${hexOf(main).slice(1)}`;
+    return { id, def: `<radialGradient id="${id}" cx="0.36" cy="0.3" r="0.82">${stops([[0, mix(main, 0.7)], [0.3, mix(main, 0.2)], [0.62, hexOf(main)], [1, mix(main, -0.42)]])}</radialGradient>`, fill: `url(#${id})` };
+}
+/** The shading of a flat sheet of metal, from a bright corner to a dark one. */
+export function sheetGradient(main) {
+    const id = `dgsd${hexOf(main).slice(1)}`;
+    return { id, def: `<linearGradient id="${id}" x2="1" y2="1">${stops([[0, mix(main, 0.55)], [0.35, mix(main, 0.12)], [0.6, hexOf(main)], [1, mix(main, -0.4)]])}</linearGradient>`, fill: `url(#${id})` };
+}
+/** The shading of a raised rim: bright on the top left, dark on the bottom right, as a bevel catches the light (or the other way round, for a groove). */
+export function bevelGradient(main, groove = false) {
+    const id = `dgse${hexOf(main).slice(1)}${groove ? "g" : ""}`;
+    const [a, b] = groove ? [mix(main, -0.45), mix(main, 0.6)] : [mix(main, 0.65), mix(main, -0.5)];
+    return { id, def: `<linearGradient id="${id}" x2="1" y2="1">${stops([[0, a], [0.5, hexOf(main)], [1, b]])}</linearGradient>`, fill: `url(#${id})` };
+}
+/** The gradients' definitions as one `<defs>`, with none twice. */
+export const defsOf = (gradients) => {
+    const seen = new Set();
+    const list = gradients.filter((g) => !seen.has(g.id) && seen.add(g.id));
+    return list.length === 0 ? "" : `<defs>${list.map((g) => g.def).join("")}</defs>`;
+};
 /** A drawing wrapped into a document: the title, the outline's colour for the theme, and the group that strokes it. */
 export function wrap(o) {
     const colour = o.theme === "dark" ? EMBLEM_INK.dark : o.theme === "inherit" ? "" : EMBLEM_INK.light;
     const auto = o.theme === "auto" ? `<style>@media(prefers-color-scheme:dark){svg{color:${EMBLEM_INK.dark}}}</style>` : "";
-    const stroke = o.style === "line" ? 2.6 : 2.2;
+    // `edge` is a colour of the drawing's own for the outline (a metal's darker tone); without it the outline is the page's ink. The `line` style is always the page's ink.
+    const ink = o.edge !== undefined && o.style !== "line" ? o.edge : "currentColor";
+    const stroke = o.width ?? (o.style === "line" ? 2.6 : 2.2);
     return (`<svg xmlns="http://www.w3.org/2000/svg" viewBox="${o.box ?? "0 0 64 64"}" width="${o.size}" height="${o.size}" role="img"${colour === "" ? "" : ` color="${colour}"`}>` +
-        `<title>${escape(o.title)}</title>${auto}${o.defs ?? ""}<g fill="none" stroke="currentColor" stroke-width="${stroke}" stroke-linejoin="round" stroke-linecap="round">${o.body}</g></svg>`);
+        `<title>${escape(o.title)}</title>${auto}${o.defs ?? ""}<g fill="none" stroke="${ink}" stroke-width="${n2(stroke)}" stroke-linejoin="round" stroke-linecap="round">${o.body}</g></svg>`);
 }

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: "空手衣。上衣、ズボン、帯" },
+};