@johnmorrisdotca/taisen-brackets 0.0.0-stage → 0.1.1

package/dist/layout.js

@@ -0,0 +1,261 @@
+import { collectTeams, resolveMatchup } from "./matchup.js";
+/**
+ * The shape of a knockout, worked out from its ties: which tie feeds which (a winner goes on to the next tie its team
+ * plays, or the tie that `feeds` names), the rounds, which half each tie sits in, and which side has a bye. A tie is
+ * a game, a series, two legs or a replayed game, so one layout draws a hockey playoff and a World Cup. Pure and
+ * sport-agnostic: no DOM, no drawing.
+ */
+export function layoutBracket(input, options = {}) {
+    const matchups = Array.isArray(input) ? input : input.matchups;
+    const given = Array.isArray(input) ? [] : input.teams ?? [];
+    const teamMap = collectTeams(matchups, given);
+    const ties = matchups.map((m, i) => resolveMatchup(m, i, teamMap));
+    const n = ties.length;
+    const byId = new Map();
+    for (const t of ties) {
+        if (byId.has(t.id))
+            throw new Error(`taisen-brackets: two matchups have the id ${JSON.stringify(t.id)}`);
+        byId.set(t.id, t.index);
+    }
+    const thirds = ties.filter((t) => t.third).map((t) => t.index);
+    const robin = ties.filter((t) => !t.third && matchups[t.index].round === 0).map((t) => t.index);
+    const inTree = ties.filter((t) => !t.third && matchups[t.index].round !== 0).map((t) => t.index);
+    const isTree = new Set(inTree);
+    const winnerId = (i) => (ties[i].winner === null ? null : ties[i].sides[ties[i].winner]?.id ?? null);
+    const sideIdOf = (i, k) => ties[i].sides[k]?.id ?? null;
+    // Explicit feeds: the tie named for side k is a child of this one.
+    const children = new Map();
+    const parent = new Array(n).fill(-1);
+    const feedSide = new Map();
+    const explicit = new Set();
+    for (const j of inTree) {
+        const feeds = matchups[j].feeds;
+        if (!feeds)
+            continue;
+        explicit.add(j);
+        const list = [];
+        feeds.forEach((id, k) => {
+            if (id == null)
+                return;
+            const c = byId.get(id);
+            if (c === undefined)
+                throw new Error(`taisen-brackets: matchup ${JSON.stringify(ties[j].id)} is fed by ${JSON.stringify(id)}, which is not a matchup`);
+            if (!isTree.has(c))
+                throw new Error(`taisen-brackets: matchup ${JSON.stringify(ties[j].id)} is fed by ${JSON.stringify(id)}, which is not part of the tree`);
+            if (c === j || parent[c] !== -1)
+                throw new Error(`taisen-brackets: ${JSON.stringify(id)} feeds more than one matchup, or itself`);
+            parent[c] = j;
+            feedSide.set(c, k);
+            list.push(c);
+        });
+        children.set(j, list);
+    }
+    // Rounds: given, or one more than the latest tie that feeds this one.
+    const key = (i) => ties[i].date;
+    const earlier = (a, b) => (key(a) < key(b) ? true : key(a) > key(b) ? false : a < b);
+    const round = new Array(n).fill(-1);
+    for (const i of inTree)
+        if (matchups[i].round !== undefined && matchups[i].round > 0)
+            round[i] = matchups[i].round;
+    const memo = new Map();
+    const rounding = (j) => {
+        if (round[j] > 0)
+            return round[j];
+        const hit = memo.get(j);
+        if (hit !== undefined)
+            return hit;
+        let feeders;
+        if (explicit.has(j))
+            feeders = children.get(j) ?? [];
+        else {
+            const here = [sideIdOf(j, 0), sideIdOf(j, 1)];
+            feeders = inTree.filter((i) => i !== j && winnerId(i) !== null && here.includes(winnerId(i)) && earlier(i, j) && !(parent[i] !== -1 && parent[i] !== j));
+        }
+        const r = 1 + Math.max(0, ...feeders.map(rounding));
+        memo.set(j, r);
+        return r;
+    };
+    const raw = new Map();
+    for (const i of inTree)
+        raw.set(i, rounding(i));
+    const distinct = [...new Set(raw.values())].sort((a, b) => a - b);
+    for (const i of inTree)
+        round[i] = distinct.indexOf(raw.get(i)) + 1;
+    const rounds = distinct.length;
+    // Derived feeding: a winner goes on to the nearest later tie its team plays, when no `feeds` names the tree.
+    for (const i of inTree) {
+        if (parent[i] !== -1 || winnerId(i) === null)
+            continue;
+        let best = -1;
+        for (const j of inTree) {
+            if (explicit.has(j) || round[j] <= round[i])
+                continue;
+            if (sideIdOf(j, 0) !== winnerId(i) && sideIdOf(j, 1) !== winnerId(i))
+                continue;
+            if (best < 0 || round[j] < round[best])
+                best = j;
+        }
+        if (best >= 0) {
+            parent[i] = best;
+            children.set(best, [...(children.get(best) ?? []), i]);
+            feedSide.set(i, sideIdOf(best, 0) === winnerId(i) ? 0 : 1);
+        }
+    }
+    const cmpId = (a, b) => (String(a) < String(b) ? -1 : String(a) > String(b) ? 1 : 0);
+    const first = (a, b) => {
+        const na = ties[a].no ?? Infinity, nb = ties[b].no ?? Infinity;
+        if (na !== nb)
+            return na < nb ? -1 : 1;
+        if (ties[a].date !== ties[b].date)
+            return ties[a].date < ties[b].date ? -1 : 1;
+        return cmpId(sideIdOf(a, 0), sideIdOf(b, 0));
+    };
+    for (const [p, list] of children)
+        if (!explicit.has(p))
+            children.set(p, [...list].sort(first));
+    const tops = inTree.filter((i) => round[i] === rounds);
+    const fin = tops.length === 1 ? tops[0] : null;
+    for (const i of thirds)
+        ties[i] = { ...ties[i], round: rounds };
+    for (const i of inTree)
+        ties[i] = { ...ties[i], round: round[i] };
+    for (const i of robin)
+        ties[i] = { ...ties[i], round: 0 };
+    const place = new Array(n).fill("o");
+    const subtree = (i) => [i, ...(children.get(i) ?? []).flatMap(subtree)];
+    const groupOf = (t) => t?.group ?? null;
+    const orderOf = (i) => {
+        const ch = children.get(i) ?? [];
+        if (ch.length === 2 && feedSide.get(ch[0]) === 1)
+            return [1, 0];
+        return [0, 1];
+    };
+    const byeOf = (i) => {
+        const ch = children.get(i) ?? [];
+        if (round[i] <= 1 || ch.length !== 1)
+            return null;
+        const fed = feedSide.get(ch[0]);
+        if (fed === undefined)
+            return null;
+        const other = (1 - fed);
+        return ties[i].sides[other] ? other : null;
+    };
+    /** Lays one tree out: leaves take the next rows, a tie sits at the middle of the ones that feed it. */
+    const lay = (root, mark) => {
+        const boxes = [];
+        let next = 0;
+        const go = (i) => {
+            const ch = children.get(i) ?? [];
+            const ys = ch.map(go);
+            const y = ys.length ? ys.reduce((a, b) => a + b, 0) / ys.length : next++;
+            boxes.push({ i, round: round[i], y, to: null, fed: ch.length > 0, order: orderOf(i), bye: byeOf(i) });
+            place[i] = mark;
+            return y;
+        };
+        go(root);
+        return { boxes, rows: Math.max(next, 1) };
+    };
+    const wantLtr = options.shape === "ltr";
+    let sides = [];
+    let final = null;
+    let shape = "forest";
+    if (fin !== null && !wantLtr && (children.get(fin) ?? []).length > 0) {
+        shape = "halves";
+        place[fin] = "f";
+        const ch = children.get(fin);
+        let feeders;
+        if (explicit.has(fin))
+            feeders = [ch[0] ?? null, ch[1] ?? null];
+        else
+            feeders = [0, 1].map((k) => ch.find((c) => winnerId(c) === sideIdOf(fin, k)) ?? null);
+        const spare = ch.filter((c) => !feeders.includes(c));
+        feeders = feeders.map((f) => f ?? spare.shift() ?? null);
+        if (feeders[0] === null && feeders[1] !== null)
+            feeders = [feeders[1], null];
+        // A half is a group when at most one team of it comes from another group and fewer than half do.
+        const lead = feeders.map((c) => {
+            if (c === null)
+                return { name: null, clean: false };
+            const ts = [...new Set(subtree(c).flatMap((i) => ties[i].sides.map((t) => t?.id).filter((id) => id !== undefined && id !== null)))];
+            const counts = new Map();
+            for (const id of ts) {
+                const g = groupOf(teamMap.get(id) ?? null);
+                if (g)
+                    counts.set(g, (counts.get(g) ?? 0) + 1);
+            }
+            const top = [...counts].sort((a, b) => b[1] - a[1] || cmpId(a[0], b[0]))[0];
+            if (!top)
+                return { name: null, clean: false };
+            const out = ts.length - top[1];
+            return { name: top[0], clean: out <= 1 && out * 2 < ts.length };
+        });
+        const differ = lead[0].name !== null && lead[1].name !== null && lead[0].name !== lead[1].name;
+        const clean = differ && lead[0].clean && lead[1].clean;
+        let order = [0, 1];
+        if (differ) {
+            const preset = options.groupOrder;
+            const rank = (g) => {
+                if (preset) {
+                    const at = preset.indexOf(g);
+                    return at < 0 ? preset.length : at;
+                }
+                return /west/i.test(g) ? 0 : /east/i.test(g) ? 2 : 1;
+            };
+            const ra = rank(lead[0].name), rb = rank(lead[1].name);
+            if (ra > rb || (ra === rb && lead[0].name > lead[1].name))
+                order = [1, 0];
+        }
+        const built = order
+            .map((k) => (feeders[k] === null ? null : { ...lay(feeders[k], "l"), root: feeders[k], label: clean ? lead[k].name : null }))
+            .filter((x) => x !== null);
+        sides = built.map((x, k) => ({ key: k === 0 ? "l" : "r", label: x.label, boxes: x.boxes, rows: x.rows }));
+        built.forEach((x, k) => { if (k === 1)
+            for (const b of x.boxes)
+                place[b.i] = "r"; });
+        const rows = Math.max(1, ...sides.map((s) => s.rows));
+        const y = (rows - 1) / 2;
+        const leftFeeder = built[0]?.root;
+        const finalOrder = leftFeeder !== undefined && feedSide.get(leftFeeder) === 1 ? [1, 0] : [0, 1];
+        final = { i: fin, y, order: finalOrder };
+        built.forEach((x, k) => { const b = sides[k].boxes.find((q) => q.i === x.root); if (b)
+            b.to = y; });
+    }
+    else if (fin !== null && children.get(fin)?.length) {
+        shape = "ltr";
+        const l = lay(fin, "l");
+        sides = [{ key: "l", label: null, boxes: l.boxes, rows: l.rows }];
+    }
+    else {
+        const roots = inTree.filter((i) => parent[i] === -1).sort((a, b) => round[b] - round[a] || first(a, b));
+        const boxes = [];
+        let rows = 0;
+        for (const r of roots) {
+            const l = lay(r, "l");
+            boxes.push(...l.boxes.map((b) => ({ ...b, y: b.y + rows })));
+            rows += l.rows;
+        }
+        if (boxes.length)
+            sides = [{ key: "l", label: null, boxes, rows }];
+        if (fin !== null)
+            shape = "ltr";
+    }
+    for (const s of sides) {
+        const ys = new Map(s.boxes.map((b) => [b.i, b.y]));
+        for (const b of s.boxes) {
+            const p = parent[b.i];
+            if (p !== -1 && ys.has(p))
+                b.to = ys.get(p);
+        }
+    }
+    if (fin !== null && shape === "halves")
+        place[fin] = "f";
+    const columns = [...new Set(sides.flatMap((s) => s.boxes.map((b) => b.round)))].filter((r) => shape !== "halves" || fin === null || r !== round[fin]).sort((a, b) => a - b);
+    const other = inTree.filter((i) => place[i] === "o");
+    const champion = fin !== null && ties[fin].winner !== null ? ties[fin].sides[ties[fin].winner] : null;
+    return {
+        ties, shape, sides, final, finalIndex: fin, columns, rounds,
+        rows: Math.max(1, ...sides.map((s) => s.rows)),
+        other, robin, third: thirds[0] ?? null, place, parent, champion,
+        teams: [...teamMap.values()],
+    };
+}

package/dist/marks.d.ts

@@ -0,0 +1,31 @@
+import type { Team } from "./types.ts";
+/**
+ * Takes inline SVG markup from a caller and makes it safe to put inside a drawing: the outer `<svg>`'s viewBox is kept,
+ * and scripts, event handlers, `<style>`, `<foreignObject>`, comments and `javascript:` addresses are removed. Returns the
+ * viewBox and the inner markup, or `null` when it is not an `<svg>`.
+ */
+export declare function cleanSvg(markup: string): {
+    viewBox: string;
+    inner: string;
+} | null;
+/** Whether an image address is one a drawing will load: http(s), a relative path, or a `data:image/`. */
+export declare function safeUrl(url: string): boolean;
+export interface MarkContext {
+    /** Collects the radii that need a round clip; the drawing writes `<clipPath>` for each. */
+    radii: Set<number>;
+    /** Inline SVG marks, each written once as a `<symbol>` and used wherever the team appears. Keyed by the markup. */
+    symbols: Map<string, {
+        id: string;
+        viewBox: string;
+        inner: string;
+    }>;
+    prefix: string;
+    shape: "round" | "square" | "none";
+}
+/** The id of the circular clip for a radius. */
+export declare const clipId: (prefix: string, r: number) => string;
+/**
+ * A team's mark centred at (cx, cy), `size` across. A logo or flag is clipped to a circle (or left square); a team
+ * with no mark, or one that cannot be used, is its initials on a plain disc. Returns SVG text.
+ */
+export declare function drawMark(team: Team | null, cx: number, cy: number, size: number, ctx: MarkContext, abbrText?: string): string;

package/dist/marks.js

@@ -0,0 +1,84 @@
+import { abbreviate, esc, num } from "./text.js";
+/**
+ * Takes inline SVG markup from a caller and makes it safe to put inside a drawing: the outer `<svg>`'s viewBox is kept,
+ * and scripts, event handlers, `<style>`, `<foreignObject>`, comments and `javascript:` addresses are removed. Returns the
+ * viewBox and the inner markup, or `null` when it is not an `<svg>`.
+ */
+export function cleanSvg(markup) {
+    const text = markup.trim().replace(/^<\?xml[^>]*>/i, "").replace(/<!DOCTYPE[^>]*>/gi, "").replace(/<!--[\s\S]*?-->/g, "");
+    const open = /^<svg\b([^>]*)>/i.exec(text);
+    if (!open || !/<\/svg>\s*$/i.test(text))
+        return null;
+    const attrs = open[1];
+    const viewBox = /\bviewBox\s*=\s*["']([^"']+)["']/i.exec(attrs)?.[1];
+    const w = /\bwidth\s*=\s*["']?([\d.]+)/i.exec(attrs)?.[1];
+    const h = /\bheight\s*=\s*["']?([\d.]+)/i.exec(attrs)?.[1];
+    const box = viewBox ?? (w && h ? `0 0 ${w} ${h}` : "0 0 100 100");
+    let inner = text.slice(open[0].length).replace(/<\/svg>\s*$/i, "");
+    inner = inner
+        .replace(/<script\b[\s\S]*?<\/script\s*>/gi, "")
+        .replace(/<script\b[^>]*\/>/gi, "")
+        .replace(/<style\b[\s\S]*?<\/style\s*>/gi, "")
+        .replace(/<foreignObject\b[\s\S]*?<\/foreignObject\s*>/gi, "")
+        .replace(/\son[a-z]+\s*=\s*("[^"]*"|'[^']*'|[^\s>]+)/gi, "")
+        .replace(/(\s(?:xlink:)?href\s*=\s*)(["'])\s*javascript:[^"']*\2/gi, "$1$2#$2");
+    return { viewBox: box, inner };
+}
+/** Readable text on a team colour: white on a dark one, near-black on a light one; `null` when the colour is not a hex one this can read. */
+function inkOn(color) {
+    const hex = /^#([0-9a-f]{3}|[0-9a-f]{6})$/i.exec(color.trim())?.[1];
+    if (!hex)
+        return null;
+    const full = hex.length === 3 ? [...hex].map((c) => c + c).join("") : hex;
+    const [r, g, b] = [0, 2, 4].map((i) => parseInt(full.slice(i, i + 2), 16) / 255).map((c) => (c <= 0.03928 ? c / 12.92 : ((c + 0.055) / 1.055) ** 2.4));
+    return 0.2126 * r + 0.7152 * g + 0.0722 * b < 0.35 ? "#ffffff" : "#1f2320";
+}
+/** Whether an image address is one a drawing will load: http(s), a relative path, or a `data:image/`. */
+export function safeUrl(url) {
+    const u = url.trim();
+    if (/^data:image\/(png|jpe?g|gif|webp|svg\+xml|avif);/i.test(u))
+        return true;
+    if (/^https?:\/\//i.test(u))
+        return true;
+    return !/^[a-z][a-z0-9+.-]*:/i.test(u) && !u.startsWith("//") ? u.length > 0 : false;
+}
+/** The id of the circular clip for a radius. */
+export const clipId = (prefix, r) => `${prefix}-c${String(num(r)).replace(".", "_")}`;
+/**
+ * A team's mark centred at (cx, cy), `size` across. A logo or flag is clipped to a circle (or left square); a team
+ * with no mark, or one that cannot be used, is its initials on a plain disc. Returns SVG text.
+ */
+export function drawMark(team, cx, cy, size, ctx, abbrText) {
+    const r = size / 2;
+    if (!team)
+        return `<circle class="tb-plain tb-mark" cx="${num(cx)}" cy="${num(cy)}" r="${num(r)}" opacity=".5"/>`;
+    const x = cx - r, y = cy - r;
+    const clip = ctx.shape === "round";
+    if (clip)
+        ctx.radii.add(r);
+    const wrapOpen = clip ? `<g class="tb-mark" transform="translate(${num(cx)} ${num(cy)})" clip-path="url(#${clipId(ctx.prefix, r)})">` : `<g class="tb-mark">`;
+    const ox = clip ? -r : x, oy = clip ? -r : y;
+    const ring = clip ? `<circle class="tb-ring" cx="${num(cx)}" cy="${num(cy)}" r="${num(r)}"/>` : `<rect class="tb-ring" x="${num(x)}" y="${num(y)}" width="${num(size)}" height="${num(size)}" rx="2"/>`;
+    const mark = team.mark?.trim();
+    if (mark) {
+        if (mark.startsWith("<")) {
+            const svg = cleanSvg(mark);
+            if (svg) {
+                let symbol = ctx.symbols.get(mark);
+                if (!symbol) {
+                    symbol = { id: `${ctx.prefix}-m${ctx.symbols.size + 1}`, ...svg };
+                    ctx.symbols.set(mark, symbol);
+                }
+                return `${wrapOpen}<use href="#${symbol.id}" x="${num(ox)}" y="${num(oy)}" width="${num(size)}" height="${num(size)}"/></g>${ring}`;
+            }
+        }
+        else if (safeUrl(mark)) {
+            return `${wrapOpen}<image href="${esc(mark)}" x="${num(ox)}" y="${num(oy)}" width="${num(size)}" height="${num(size)}" preserveAspectRatio="xMidYMid slice"/></g>${ring}`;
+        }
+    }
+    const text = (abbrText ?? team.abbr ?? abbreviate(team.name)).slice(0, 3);
+    const fill = team.color ? ` style="fill:${esc(team.color)}"` : "";
+    const shape = clip ? `<circle class="tb-plain" cx="${num(cx)}" cy="${num(cy)}" r="${num(r)}"${fill}/>` : `<rect class="tb-plain" x="${num(x)}" y="${num(y)}" width="${num(size)}" height="${num(size)}" rx="2"${fill}/>`;
+    const ink = team.color ? inkOn(team.color) : null;
+    return `<g class="tb-mark">${shape}<text class="tb-initials" x="${num(cx)}" y="${num(cy + size * 0.12)}" font-size="${num(size * 0.36)}" font-weight="700" text-anchor="middle"${ink ? ` style="fill:${ink}"` : ""}>${esc(text)}</text></g>${ring}`;
+}

package/dist/matchup.d.ts

@@ -0,0 +1,11 @@
+import type { Matchup, SideId, Team, Tie, Words } from "./types.ts";
+/** A bracket's teams: the list given, plus a team made from every id that a matchup names and the list does not. */
+export declare function collectTeams(matchups: readonly Matchup[], given?: readonly Team[]): Map<SideId, Team>;
+/** One matchup as a tie: sides resolved to teams, the winner and the result worked out. The round is set by the layout. */
+export declare function resolveMatchup(m: Matchup, index: number, teams: ReadonlyMap<SideId, Team>): Tie;
+/** The short name of a team for a small box. */
+export declare const abbrOf: (team: Team | null, words: Words) => string;
+/** The pieces of a note under a tie's score: "a.e.t.", "pens", "in 7", "agg.". */
+export declare function noteParts(tie: Tie, words: Words): string[];
+/** A tie in a sentence, for a tooltip, a table and a description: "Argentina 3, France 3 (a.e.t., pens 4-2). Winner: Argentina". */
+export declare function describeTie(tie: Tie, words: Words): string;

package/dist/matchup.js

@@ -0,0 +1,147 @@
+import { abbreviate } from "./text.js";
+import { fill } from "./words.js";
+/** A bracket's teams: the list given, plus a team made from every id that a matchup names and the list does not. */
+export function collectTeams(matchups, given = []) {
+    const teams = new Map();
+    for (const team of given) {
+        if (teams.has(team.id))
+            throw new Error(`taisen-brackets: two teams have the id ${JSON.stringify(team.id)}`);
+        teams.set(team.id, team);
+    }
+    for (const m of matchups) {
+        for (const side of m.sides) {
+            if (side === null || side === undefined)
+                continue;
+            if (typeof side === "object") {
+                if (!teams.has(side.id))
+                    teams.set(side.id, side);
+            }
+            else if (!teams.has(side))
+                teams.set(side, { id: side, name: String(side) });
+        }
+    }
+    return teams;
+}
+const sideId = (side) => (side === null || side === undefined ? null : typeof side === "object" ? side.id : side);
+/** What the games of a tie come to. `winner` is the side the games settle (0 or 1), or null. */
+function settle(m, kind) {
+    const listed = m.games ?? m.legs ?? [];
+    const lone = listed.length === 0 && m.score && kind !== "series" && kind !== "aggregate" ? { score: m.score, extraTime: m.extraTime, pens: m.pens } : null;
+    const games = lone ? [lone] : listed;
+    const bestOf = m.bestOf ?? null;
+    const base = { kind, bestOf, extraTime: false, replays: 0, pens: null, games: games.map((g) => g.score) };
+    const byScore = (a, b) => (a > b ? 0 : b > a ? 1 : null);
+    const byPens = (pens) => (pens ? byScore(pens[0], pens[1]) : null);
+    if (kind === "series") {
+        let wins = null;
+        if (games.length)
+            wins = [games.filter((g) => g.score[0] > g.score[1]).length, games.filter((g) => g.score[1] > g.score[0]).length];
+        else if (m.score)
+            wins = m.score;
+        const need = bestOf ? Math.ceil(bestOf / 2) : null;
+        const winner = wins && need ? (wins[0] >= need ? 0 : wins[1] >= need ? 1 : null) : null;
+        return { result: { ...base, score: wins, played: games.length || (wins ? wins[0] + wins[1] : 0), decided: winner !== null }, winner };
+    }
+    if (kind === "aggregate") {
+        const last = games.at(-1);
+        const total = games.length ? [games.reduce((s, g) => s + g.score[0], 0), games.reduce((s, g) => s + g.score[1], 0)] : m.score ?? null;
+        const pens = last?.pens ?? m.pens ?? null;
+        const winner = total ? byScore(total[0], total[1]) ?? byPens(pens) : null;
+        return { result: { ...base, score: total, played: games.length, pens, extraTime: games.some((g) => g.extraTime) || !!m.extraTime, decided: winner !== null }, winner };
+    }
+    // A game, or a replay: the last game decides.
+    const last = games.at(-1);
+    if (!last)
+        return { result: { ...base, score: null, played: 0, decided: false }, winner: null };
+    const winner = byScore(last.score[0], last.score[1]) ?? byPens(last.pens ?? null);
+    const replays = kind === "replay" ? games.filter((g) => g.replay).length || Math.max(games.length - 1, 0) : 0;
+    return { result: { ...base, score: last.score, played: games.length, pens: last.pens ?? null, extraTime: !!last.extraTime, replays, decided: winner !== null }, winner };
+}
+/** The kind of tie, read from the fields when `kind` is not given. */
+function kindOf(m) {
+    if (m.kind)
+        return m.kind;
+    if (m.legs?.length)
+        return "aggregate";
+    if ((m.games ?? []).some((g) => g.replay))
+        return "replay";
+    if (m.bestOf || (m.games?.length ?? 0) > 1)
+        return "series";
+    return "game";
+}
+/** One matchup as a tie: sides resolved to teams, the winner and the result worked out. The round is set by the layout. */
+export function resolveMatchup(m, index, teams) {
+    const ids = [sideId(m.sides[0]), sideId(m.sides[1])];
+    if (ids[0] !== null && ids[0] === ids[1])
+        throw new Error(`taisen-brackets: matchup ${index} has ${JSON.stringify(ids[0])} on both sides`);
+    const kind = kindOf(m);
+    const { result, winner: settled } = settle(m, kind);
+    let winner = settled;
+    if (m.winner !== undefined) {
+        if (m.winner === null)
+            winner = null;
+        else if (ids[0] === m.winner)
+            winner = 0;
+        else if (ids[1] === m.winner)
+            winner = 1;
+        else
+            throw new Error(`taisen-brackets: matchup ${index}'s winner ${JSON.stringify(m.winner)} is not one of its sides`);
+    }
+    const sides = ids.map((id) => (id === null ? null : teams.get(id) ?? null));
+    return {
+        index,
+        id: m.id ?? `m${index + 1}`,
+        round: m.round ?? -1,
+        sides,
+        winner,
+        result: { ...result, decided: winner !== null },
+        date: m.date ?? m.games?.[0]?.date ?? m.legs?.[0]?.date ?? "",
+        no: m.no ?? null,
+        third: !!m.third,
+        note: m.note ?? null,
+    };
+}
+/** The short name of a team for a small box. */
+export const abbrOf = (team, words) => (team ? team.abbr ?? abbreviate(team.name) : words.tbd);
+/** The pieces of a note under a tie's score: "a.e.t.", "pens", "in 7", "agg.". */
+export function noteParts(tie, words) {
+    const r = tie.result;
+    const out = [];
+    if (r.kind === "series") {
+        if (r.decided && r.played > 0)
+            out.push(fill(words.inGames, { n: r.played }));
+        else if (r.bestOf)
+            out.push(fill(words.bestOf, { n: r.bestOf }));
+    }
+    else {
+        if (r.kind === "aggregate")
+            out.push(words.aggregate);
+        if (r.kind === "replay")
+            out.push(words.replay);
+        if (r.extraTime)
+            out.push(words.aet);
+        if (r.pens)
+            out.push(words.pens);
+    }
+    if (tie.note)
+        out.push(tie.note);
+    return out;
+}
+/** A tie in a sentence, for a tooltip, a table and a description: "Argentina 3, France 3 (a.e.t., pens 4-2). Winner: Argentina". */
+export function describeTie(tie, words) {
+    const name = (t) => (t ? t.name : words.tbd);
+    const [a, b] = tie.sides;
+    const r = tie.result;
+    let text;
+    if (!r.score)
+        text = `${name(a)} ${words.versus} ${name(b)}`;
+    else {
+        text = `${name(a)} ${r.score[0]}, ${name(b)} ${r.score[1]}`;
+        const extra = noteParts(tie, words).map((part) => (part === words.pens && r.pens ? `${words.pens} ${r.pens[0]}-${r.pens[1]}` : part));
+        if (extra.length)
+            text += ` (${extra.join(", ")})`;
+    }
+    if (tie.winner !== null)
+        text += `. ${words.winner}: ${name(tie.sides[tie.winner])}`;
+    return text;
+}

package/dist/presets-entry.d.ts

@@ -0,0 +1,3 @@
+export { playoffFormat, playoffEras, LEAGUES } from "./presets.ts";
+export type { League, PlayoffFormat, PlayoffRound } from "./presets.ts";
+export { roundName, roundNamesFor } from "./rounds.ts";

package/dist/presets-entry.js

@@ -0,0 +1,2 @@
+export { playoffFormat, playoffEras, LEAGUES } from "./presets.js";
+export { roundName, roundNamesFor } from "./rounds.js";

package/dist/presets.d.ts

@@ -0,0 +1,43 @@
+/**
+ * Playoff formats by era: the round names, the length of each round's series and who has a bye, for the five North
+ * American leagues and the FIFA World Cup. Data only; nothing here draws. Each era was checked against the English
+ * Wikipedia articles in its `sources` (2026-10-13); where a season did something of its own (a strike, a pandemic) it has
+ * its own entry. The year is the year the playoffs are played in: the NHL's 2024 is the 2023-24 season.
+ */
+export type League = "nhl" | "nba" | "mlb" | "nfl" | "cfl" | "worldcup";
+export interface PlayoffRound {
+    /** The round's name as the league calls it. */
+    name: string;
+    /** The length of the series, or 1 for a single game; null when the round is two legs or a group stage. */
+    bestOf: number | null;
+}
+export interface PlayoffFormat {
+    league: League;
+    /** The season (or edition) this was asked for. */
+    year: number;
+    /** The first and last year of the era this entry covers; `to` is null while it is current. */
+    from: number;
+    to: number | null;
+    /** The era in a few words. */
+    label: string;
+    /** The rounds, first round first. */
+    rounds: PlayoffRound[];
+    /** How many teams start the bracket, or null where it varies. */
+    teams: number | null;
+    /** The number of teams of each half that skip the first round. */
+    byes: number;
+    /** The names of the two halves, left first, or null where the bracket is not split in two. */
+    groups: readonly [string, string] | null;
+    note?: string;
+    /** The English Wikipedia articles this entry was checked against (CC BY-SA 4.0; only facts are used). */
+    sources: readonly string[];
+}
+/** The leagues that have a format here. */
+export declare const LEAGUES: readonly League[];
+/**
+ * The playoff format of a league in a season (or a World Cup in its year), or `null` when there was none or this
+ * package does not cover it. The rounds' names go straight to `drawBracket`'s `roundNames`.
+ */
+export declare function playoffFormat(league: League, year: number): PlayoffFormat | null;
+/** Every era of a league, oldest first. */
+export declare function playoffEras(league: League): PlayoffFormat[];