@johnmorrisdotca/taisen-brackets 0.9.0 → 0.11.0

package/dist/rank-kit.d.ts

@@ -0,0 +1,90 @@
+/**
+ * What the ranking lists, the medal table and the results boards share: the sizes, the frame (size, theme, language, flags), the stylesheet with its light and dark palettes, the
+ * wrapper that makes the SVG, and the small shapes (a movement arrow, a pill, a rank badge). Every board is a static SVG for a given state, a pure function of its input.
+ */
+import type { DrawOptions, Locale, Words } from "./types.ts";
+import { bw, clampN, fitSize } from "./judo-board.ts";
+import { type Voice } from "./locales.ts";
+import { type MarkContext } from "./marks.ts";
+export { bw, clampN, fitSize };
+export type BoardSizeName = "tv" | "tablet" | "tablet-tall" | "phone" | "square" | "portrait";
+/** The sizes of a board: a TV's 1920 by 1080, a tablet on its side (1280 by 800) and upright (800 by 1280), a phone's 600 by 1300, and the social-card shapes, square (1080) and 4:5 (1080 by 1350). */
+export declare const BOARD_SIZES: Readonly<Record<BoardSizeName, {
+    width: number;
+    height: number;
+}>>;
+/** What every board takes. */
+export interface BoardOptions {
+    /** One of `BOARD_SIZES` (`tv` by default), or a size of your own, `{ width, height }`, at least 200 each way. */
+    size?: BoardSizeName | {
+        width: number;
+        height: number;
+    };
+    /** `auto` (the default) follows the page's light or dark, `light` and `dark` fix it. */
+    theme?: "auto" | "light" | "dark";
+    /** Draws a flag from its code, as for `drawBracket`: a synchronous function from a code (`CA-BC`, `JP`) and `{ shape, size, theme }` to an SVG string, such as one made from `@johnmorrisdotca/hata`. */
+    flags?: DrawOptions["flags"];
+    /** The address of a flag as a picture to load, tried where `flags` gives none. */
+    flagHref?: DrawOptions["flagHref"];
+    /** `round` (the default) or `square`: the shape a flag is asked for and drawn in. */
+    flagShape?: "round" | "square";
+    /** The language: `en`, `fr`, `ja`, `es`, `de` or a `Locale`. */
+    locale?: string | Locale;
+    words?: Partial<Words>;
+    /** The `<title>` of the drawing. Default: the board's own heading. */
+    title?: string;
+    /** Prefix for the drawing's ids. Default: a hash of the state and the options. */
+    id?: string;
+    className?: string;
+}
+export interface BoardFrame {
+    W: number;
+    H: number;
+    v: Voice;
+    scope: string;
+    theme: "auto" | "light" | "dark";
+    ctx: MarkContext;
+    options: BoardOptions;
+}
+export declare const rect: (x: number, y: number, w: number, h: number, cls: string, rx?: number, extra?: string) => string;
+export declare const label: (x: number, y: number, size: number, content: string, cls: string, anchor?: "start" | "middle" | "end", weight?: number, extra?: string) => string;
+/** The size, theme and language a board is drawn with, checked; `seed` is whatever the drawing depends on, for the hash of the ids. */
+export declare function boardFrame(options: BoardOptions, seed: unknown): BoardFrame;
+export interface BoardPalette {
+    bg: string;
+    ink: string;
+    sub: string;
+    accent: string;
+    accentInk: string;
+    row: string;
+    rowAlt: string;
+    edge: string;
+    head: string;
+    headInk: string;
+    up: string;
+    down: string;
+    upRow: string;
+    downRow: string;
+    pill: string;
+    pillInk: string;
+    /** Gold, silver, bronze: the two ends of the row's gradient, the edge and the numeral. */
+    gold: readonly [string, string, string, string];
+    silver: readonly [string, string, string, string];
+    bronze: readonly [string, string, string, string];
+}
+export declare const BOARD_LIGHT: BoardPalette;
+export declare const BOARD_DARK: BoardPalette;
+/** The rules for one palette, scoped, with `before` ahead of every selector (empty, or the dark-mode root selector). */
+export declare function boardRules(p: BoardPalette, scope: string, before: string, extra?: (sel: (s: string, body: string) => string, v: (name: string, value: string) => string) => string[]): string;
+/** The whole stylesheet: the light palette, the dark one under the page's dark mode (for `auto`) or on its own, and the fixed rules. */
+export declare function boardStyle(scope: string, theme: "auto" | "light" | "dark", extra?: Parameters<typeof boardRules>[3], fixed?: string): string;
+/** The medal gradients a board's rows use: one for gold, silver and bronze, by id. */
+export declare function medalDefs(scope: string): string;
+export declare function boardWrap(f: BoardFrame, title: string, desc: string, body: string[], kind: string, extra?: Parameters<typeof boardRules>[3], fixed?: string, defs?: string): string;
+/** A movement arrow, a triangle `s` high centred at (cx, cy), up or down. */
+export declare function arrow(cx: number, cy: number, s: number, up: boolean): string;
+/** A pill with centred text in it, as wide as the text needs (never wider than `maxW`). Returns the pieces and the width. */
+export declare function pill(x: number, cy: number, h: number, content: string, maxW: number, cls?: string, inkCls?: string, anchor?: "start" | "end"): {
+    svg: string;
+    w: number;
+};

package/dist/rank-kit.js

@@ -0,0 +1,124 @@
+import { bw, clampN, fitSize, FONT } from "./judo-board.js";
+import { voiceOf } from "./locales.js";
+import { markDefs } from "./marks.js";
+import { esc, fit, hash, num } from "./text.js";
+export { bw, clampN, fitSize };
+/** The sizes of a board: a TV's 1920 by 1080, a tablet on its side (1280 by 800) and upright (800 by 1280), a phone's 600 by 1300, and the social-card shapes, square (1080) and 4:5 (1080 by 1350). */
+export const BOARD_SIZES = Object.freeze({
+    tv: { width: 1920, height: 1080 },
+    tablet: { width: 1280, height: 800 },
+    "tablet-tall": { width: 800, height: 1280 },
+    phone: { width: 600, height: 1300 },
+    square: { width: 1080, height: 1080 },
+    portrait: { width: 1080, height: 1350 },
+});
+export const rect = (x, y, w, h, cls, rx = 0, extra = "") => `<rect class="${cls}" x="${num(x)}" y="${num(y)}" width="${num(w)}" height="${num(h)}"${rx ? ` rx="${num(rx)}"` : ""}${extra}/>`;
+export const label = (x, y, size, content, cls, anchor = "start", weight = 800, extra = "") => `<text class="${cls}" x="${num(x)}" y="${num(y)}" font-size="${num(size)}" font-weight="${weight}" text-anchor="${anchor}"${extra}>${esc(content)}</text>`;
+/** An id for the drawing's classes and ids, made safe: letters, digits, `_` and `-` only (anything else becomes `-`), and a letter first. `undefined` stays `undefined`. */
+const safeId = (id) => (id === undefined ? undefined : /^[A-Za-z]/.test(id) ? id.replace(/[^\w-]/g, "-") : `rk-${id.replace(/[^\w-]/g, "-")}`);
+/** The size, theme and language a board is drawn with, checked; `seed` is whatever the drawing depends on, for the hash of the ids. */
+export function boardFrame(options, seed) {
+    const v = voiceOf(options);
+    const size = typeof options.size === "string" ? BOARD_SIZES[options.size] : options.size ?? BOARD_SIZES.tv;
+    if (!size || !(size.width >= 200) || !(size.height >= 200))
+        throw new RangeError(`taisen-brackets: a size is ${Object.keys(BOARD_SIZES).map((k) => `"${k}"`).join(", ")} or { width, height } of 200 or more, not ${JSON.stringify(options.size)}`);
+    const theme = options.theme ?? "auto";
+    if (theme !== "auto" && theme !== "light" && theme !== "dark")
+        throw new RangeError(`taisen-brackets: a theme is "auto", "light" or "dark", not ${JSON.stringify(theme)}`);
+    const shape = options.flagShape ?? "round";
+    if (shape !== "round" && shape !== "square")
+        throw new RangeError(`taisen-brackets: a flag shape is "round" or "square", not ${JSON.stringify(options.flagShape)}`);
+    const scope = safeId(options.id) ?? `rk-${hash(JSON.stringify([seed, options.size, theme, shape, v.locale.code, options.flags ? 1 : 0, options.flagHref ? 1 : 0, options.title]))}`;
+    const ctx = { radii: new Set(), symbols: new Map(), prefix: scope, shape, theme: "inherit", flagCache: new Map(), ...(options.flags ? { flags: options.flags } : {}), ...(options.flagHref ? { flagHref: options.flagHref } : {}) };
+    return { W: size.width, H: size.height, v, scope, theme, ctx, options };
+}
+export const BOARD_LIGHT = {
+    bg: "#eceff4", ink: "#131822", sub: "#566071", accent: "#2457c5", accentInk: "#ffffff",
+    row: "#ffffff", rowAlt: "#f6f8fb", edge: "#d3d9e3", head: "#16233f", headInk: "#ffffff",
+    up: "#0f8a46", down: "#c3302a", upRow: "#e0f4e8", downRow: "#fbe3e1",
+    pill: "#e3e8f1", pillInk: "#2a3345",
+    gold: ["#f8e9b5", "#fdf6dc", "#d4a929", "#7d5d00"], silver: ["#e4e8ee", "#f3f5f8", "#a9b2c0", "#4f586a"], bronze: ["#f2d5ba", "#faeadb", "#c98650", "#82451a"],
+};
+export const BOARD_DARK = {
+    bg: "#0b0f17", ink: "#f0f3f9", sub: "#98a3b8", accent: "#6ea2ff", accentInk: "#0b0f17",
+    row: "#161d2b", rowAlt: "#121826", edge: "#27324a", head: "#1b2742", headInk: "#f0f3f9",
+    up: "#4fdc8b", down: "#ff7b72", upRow: "#123724", downRow: "#451d1d",
+    pill: "#25304a", pillInk: "#dfe6f5",
+    gold: ["#5a4813", "#2c2512", "#d0aa3a", "#f5d263"], silver: ["#434c60", "#232a38", "#9ba6bb", "#e3e8f2"], bronze: ["#58341b", "#2b1d14", "#c4854f", "#f3a96f"],
+};
+const MEDALS = ["gold", "silver", "bronze"];
+/** The rules for one palette, scoped, with `before` ahead of every selector (empty, or the dark-mode root selector). */
+export function boardRules(p, scope, before, extra) {
+    const sel = (s, body) => `${before}.${scope} ${s}{${body}}`;
+    const v = (name, value) => `var(--rk-${name}, ${value})`;
+    const out = [
+        sel(".rk-bg", `fill:${v("bg", p.bg)}`),
+        sel(".rk-ink", `fill:${v("ink", p.ink)}`),
+        sel(".rk-sub", `fill:${v("sub", p.sub)}`),
+        sel(".rk-accent", `fill:${v("accent", p.accent)}`),
+        sel(".rk-accentink", `fill:${v("accent-ink", p.accentInk)}`),
+        sel(".rk-head", `fill:${v("head", p.head)}`),
+        sel(".rk-headink", `fill:${v("head-ink", p.headInk)}`),
+        sel(".rk-row", `fill:${v("row", p.row)};stroke:${v("edge", p.edge)};stroke-width:1.5`),
+        sel(".rk-row.rk-alt", `fill:${v("row-alt", p.rowAlt)}`),
+        sel(".rk-sep", `stroke:${v("edge", p.edge)};stroke-width:1.5`),
+        sel(".rk-up", `fill:${v("up", p.up)}`),
+        sel(".rk-down", `fill:${v("down", p.down)}`),
+        sel(".rk-row.rk-mup", `fill:${v("up-row", p.upRow)}`),
+        sel(".rk-row.rk-mdown", `fill:${v("down-row", p.downRow)}`),
+        sel(".rk-pill", `fill:${v("pill", p.pill)}`),
+        sel(".rk-pillink", `fill:${v("pill-ink", p.pillInk)}`),
+        sel(".rk-nr", `fill:${v("accent", p.accent)}`),
+        sel(".rk-nrink", `fill:${v("accent-ink", p.accentInk)}`),
+        sel(".tb-ring", `fill:none;stroke:rgba(0,0,0,.28);stroke-width:1.5`),
+        sel(".tb-plain", `fill:${v("pill", p.pill)}`),
+        sel(".tb-initials", `fill:${v("pill-ink", p.pillInk)}`),
+    ];
+    MEDALS.forEach((m, i) => {
+        const c = p[m];
+        out.push(sel(`.rk-ga${i + 1}`, `stop-color:${c[0]}`), sel(`.rk-gb${i + 1}`, `stop-color:${c[1]}`), sel(`.rk-medal${i + 1}`, `stroke:${c[2]};stroke-width:2`), sel(`.rk-num${i + 1}`, `fill:${c[3]}`), sel(`.rk-bar${i + 1}`, `fill:${c[2]}`));
+    });
+    if (extra)
+        out.push(...extra(sel, v));
+    return out.join("\n");
+}
+/** The whole stylesheet: the light palette, the dark one under the page's dark mode (for `auto`) or on its own, and the fixed rules. */
+export function boardStyle(scope, theme, extra, fixed = "") {
+    const tail = [`.${scope} text{font-family:var(--rk-font, ${FONT});font-variant-numeric:tabular-nums}`, fixed.replaceAll("$S", `.${scope}`)].filter(Boolean).join("\n");
+    if (theme === "light")
+        return `${boardRules(BOARD_LIGHT, scope, "", extra)}\n${tail}`;
+    if (theme === "dark")
+        return `${boardRules(BOARD_DARK, scope, "", extra)}\n${tail}`;
+    return `${boardRules(BOARD_LIGHT, scope, "", extra)}\n@media (prefers-color-scheme: dark){\n${boardRules(BOARD_DARK, scope, ':root:not([data-theme="light"]) ', extra)}\n}\n${boardRules(BOARD_DARK, scope, ':root[data-theme="dark"] ', extra)}\n${tail}`;
+}
+/** The medal gradients a board's rows use: one for gold, silver and bronze, by id. */
+export function medalDefs(scope) {
+    return MEDALS.map((_, i) => `<linearGradient id="${esc(scope)}-g${i + 1}" x1="0" x2="1" y1="0" y2="0"><stop class="rk-ga${i + 1}" offset="0"/><stop class="rk-gb${i + 1}" offset="1"/></linearGradient>`).join("");
+}
+export function boardWrap(f, title, desc, body, kind, extra, fixed = "", defs = "") {
+    const marks = markDefs(f.ctx);
+    return [
+        `<svg xmlns="http://www.w3.org/2000/svg" lang="${esc(f.v.locale.code)}" class="taisen taisen-board ${esc(f.scope)}${f.options.className ? ` ${esc(f.options.className)}` : ""}" viewBox="0 0 ${num(f.W)} ${num(f.H)}" width="${num(f.W)}" height="${num(f.H)}" style="max-width:100%;height:auto" role="img" aria-labelledby="${esc(f.scope)}-t ${esc(f.scope)}-d" data-board="${kind}">`,
+        `<title id="${esc(f.scope)}-t">${esc(title)}</title><desc id="${esc(f.scope)}-d">${esc(desc)}</desc>`,
+        `<style>${boardStyle(f.scope, f.theme, extra, fixed)}</style>`,
+        `<defs>${medalDefs(f.scope)}${defs}${marks}</defs>`,
+        `<rect class="rk-bg" width="${num(f.W)}" height="${num(f.H)}"/>`,
+        ...body,
+        "</svg>",
+    ].join("\n");
+}
+// ------------------------------------------------------------------------------------------------ small shapes
+/** A movement arrow, a triangle `s` high centred at (cx, cy), up or down. */
+export function arrow(cx, cy, s, up) {
+    const w = s * 1.1, h = s * 0.9;
+    const pts = up ? [[cx, cy - h / 2], [cx + w / 2, cy + h / 2], [cx - w / 2, cy + h / 2]] : [[cx - w / 2, cy - h / 2], [cx + w / 2, cy - h / 2], [cx, cy + h / 2]];
+    return `<polygon class="${up ? "rk-up" : "rk-down"}" points="${pts.map(([x, y]) => `${num(x)},${num(y)}`).join(" ")}"/>`;
+}
+/** A pill with centred text in it, as wide as the text needs (never wider than `maxW`). Returns the pieces and the width. */
+export function pill(x, cy, h, content, maxW, cls = "rk-pill", inkCls = "rk-pillink", anchor = "start") {
+    const size = h * 0.56;
+    const fs = fitSize(content, size, maxW - h * 0.7, 0.6);
+    const w = Math.min(maxW, bw(content, fs) + h * 0.7);
+    const x0 = anchor === "start" ? x : x - w;
+    return { svg: `${rect(x0, cy - h / 2, w, h, cls, h / 2)}${label(x0 + w / 2, cy + fs * 0.36, fs, fit(content, fs, w, bw), inkCls, "middle", 800, ' letter-spacing=".03em"')}`, w };
+}

package/dist/ranking.d.ts

@@ -0,0 +1,95 @@
+/**
+ * Ranking lists for any ranked sport, drawn from the caller's data (a provincial or club feed, a federation's list): a title and a category, then the entries as a podium (the top
+ * three in gold, silver and bronze rows) above a compact list, as one featured row above two columns, or as a plain list. Text first: rank, flag, name, club, points and the
+ * movement since the last list, with no photo slot to leave empty. A champion row ("C"), an interim champion, newly ranked athletes ("NR"), tied ranks and paging are in.
+ * Static SVG for a given state, like every drawing here.
+ */
+import { type BoardOptions } from "./rank-kit.ts";
+/** A name in two parts: the family name is written in capitals and first by default (`SURNAME Given`, as judo and the IJF write it). */
+export interface RankingName {
+    given?: string;
+    surname: string;
+}
+/** One line of a ranking. Only `name` is needed. */
+export interface RankingEntry {
+    /** The name as it is to be written, or its two parts (set by `nameStyle`). */
+    name: string | RankingName;
+    /** The rank. Left out, the position in the list, with equal points sharing a rank (`ties`). A champion has none. */
+    rank?: number;
+    /** A number (shown to `precision` decimals) or text (shown as it is). */
+    points?: number | string;
+    club?: string;
+    /** The country's or region's name, written under the name in a podium row. */
+    country?: string;
+    /** The country's three letters (`CAN`), written in the compact rows. */
+    code?: string;
+    /** A code for the `flags` renderer: a country (`JP`) or a Canadian province or territory (`CA-BC`). */
+    flag?: string;
+    /** A mark of your own (an image address or inline SVG) in place of a flag: a club's emblem. */
+    mark?: string;
+    /** This athlete's category ("U18 · -60 kg"), written in the second line when `categories` is on: for a list that mixes categories. */
+    category?: string;
+    /** The movement since the last list: whole places up (positive) or down (negative), `0` for none, `"new"` for newly ranked ("NR"). */
+    change?: number | "new";
+    /** The champion of the division: a row marked "C" above the ranks (`"interim"` for an interim champion). */
+    champion?: boolean | "interim";
+}
+export interface RankingSource {
+    /** The heading. Default: the language's word for ranking. */
+    title?: string;
+    /** The category as a line under the heading ("U18 · Men -60 kg"; `rankingCategoryLabel` writes one). */
+    category?: string;
+    /** The date or period of the list, at the right of the heading ("October 2026"). */
+    date?: string;
+    /** Where the list comes from, small at the foot ("Source: BC Judo"). */
+    source?: string;
+    entries: readonly RankingEntry[];
+}
+export interface RankingOptions extends BoardOptions {
+    /** `podium` (the default): the top three as big rows, tinted gold, silver and bronze, above the compact rest. `featured`: one big row above two columns. `list`: every row compact. */
+    style?: "podium" | "list" | "featured";
+    /** How many rows, from the top, are big (0 to 3). Default by `style`. Only on the first page. */
+    big?: number;
+    /** One column or two for the compact rows (the first column runs down before the second starts). Default 1, and 2 for `featured`. */
+    columns?: 1 | 2;
+    /** The most entries drawn, from the first of the page. Default: as many as fit at a readable size. */
+    rows?: number;
+    /** Which page of `rows` entries (0 is the first). The header says which entries are shown. */
+    page?: number;
+    /** On a wide board (at least 3:2) the big rows go in a panel on the left and the compact ones beside them, in place of one above the other. Default true; `false` stacks them. */
+    split?: boolean;
+    /** Tint the rows of ranks 1 to 3 gold, silver and bronze. Default: on for `podium` and `featured` (off when the list has a champion row), off for `list`. */
+    medals?: boolean;
+    /** How movement is shown: `arrow` (an arrow and the number of places, the default), `row` (the row tinted green or red), `both`, or `none`. */
+    movement?: "arrow" | "row" | "both" | "none";
+    /** `surname-first` (the default: `SURNAME Given`), `given-first` (`Given SURNAME`) or `as-is`, for a `name` given in two parts. */
+    nameStyle?: "surname-first" | "given-first" | "as-is";
+    /** `plain` (`10`, the default) or `hash` (`#10`). */
+    rankStyle?: "plain" | "hash";
+    /** Decimals for numeric points (`2` writes `91.60` and `50.00`). Default: as many as the number has, up to three. */
+    precision?: number;
+    /** Equal points share a rank where an entry names none (`1, 2, 2, 4`). Default true. */
+    ties?: boolean;
+    /** `given` (the default) keeps the order of the entries; `points` puts the most points first. */
+    sort?: "given" | "points";
+    /** Write each entry's own `category` in the second line. */
+    categories?: boolean;
+    /** Draw a club's (or the athlete's) initials on a badge for an entry with no flag or mark, even where no entry has one. Default: only where some entry has a flag or mark. */
+    badge?: boolean;
+}
+/** The ranks of a list, in order: an entry's own `rank`, else its position, with equal points sharing a rank; `null` for a champion row. Pure; takes the list as it is ordered. */
+export declare function rankingRanks(entries: readonly RankingEntry[], options?: {
+    ties?: boolean;
+}): (number | null)[];
+/** A category as a heading ("U18 · Men -60 kg"): an age group, a sex and a weight, any of them, joined by a dot. A weight is `-60` or `+100` (kg) or any text. */
+export declare function rankingCategoryLabel(category: {
+    age?: string;
+    sex?: "men" | "women" | "open";
+    weight?: string;
+}, locale?: string): string;
+/** The ranking as a sentence, the drawing's description. */
+export declare function describeRanking(source: RankingSource, options?: Pick<RankingOptions, "locale" | "words" | "nameStyle" | "precision" | "ties" | "sort" | "rankStyle" | "rows" | "page">): string;
+/**
+ * The ranking list as an SVG. Throws a `RangeError` for an entry with no name, a rank or change that is not a whole number, an option that is not one of its values, or a bad size or theme.
+ */
+export declare function rankingList(source: RankingSource, options?: RankingOptions): string;