@opndev/tennis-match-center 0.0.1

package/lib/busy-button.mjs

@@ -0,0 +1,58 @@
+// SPDX-FileCopyrightText: 2026 Wesley Schwengle <wesley@opndev.io>
+//
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+/** How long a finished action keeps saying so, in milliseconds. */
+const SETTLE_MS = 2000
+
+const DEFAULT_LABELS = {
+  busy: 'Working…', done: 'Done', failed: 'Failed',
+}
+
+/**
+ * Runs something slow with the button reporting what it is doing.
+ *
+ * The button carries the state as `data-state` - busy, done or error -
+ * so a page can animate it, and says the same in its own text for a
+ * page that does not. It is disabled while the work is in flight, so a
+ * second press cannot start one on top of the first.
+ *
+ * @param {?HTMLElement} button
+ * @param {() => Promise<boolean>} run Resolves true where the work
+ *   succeeded.
+ * @param {{busy: string, done: string, failed: string}} [labels] What
+ *   the button says while it works, and afterwards.
+ * @returns {Promise<boolean>}
+ */
+export async function withBusyButton(button, run, labels = {}) {
+  if (!button) {
+    return run()
+  }
+
+  const { busy, done, failed } = { ...DEFAULT_LABELS, ...labels }
+
+  const label = button.dataset.label ?? button.textContent
+  button.dataset.label = label
+  button.disabled = true
+  button.dataset.state = 'busy'
+  button.textContent = busy
+
+  let ok = false
+
+  try {
+    ok = await run()
+  } finally {
+    button.disabled = false
+    button.dataset.state = ok ? 'done' : 'error'
+    button.textContent = ok ? done : failed
+
+    const settle = setTimeout(() => {
+      button.dataset.state = 'idle'
+      button.textContent = label
+    }, SETTLE_MS)
+
+    settle.unref?.()
+  }
+
+  return ok
+}

package/lib/components/bracket-board.mjs

@@ -0,0 +1,586 @@
+// SPDX-FileCopyrightText: 2026 Wesley Schwengle <wesley@opndev.io>
+//
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+import { HTMLElementSugar } from '@skirbi/sugar'
+import { SingleEliminationBracket } from '../bracket-single-elimination.mjs'
+
+const ROUND_ORDER = ['R256', 'R128', 'R64', 'R32', 'R16', 'QF', 'SF', 'F']
+
+/**
+ * <tennis-bracket-board api="..." save-api="...">
+ *
+ * Gate 2: Bracket Setup (spec.md). Loads the current seed-1 team of
+ * each saved Roster group from `api`, builds the first-round bracket
+ * client-side via SingleEliminationBracket, and only ever mutates the
+ * in-browser copy until Save is pressed.
+ *
+ * Renders the full bracket tree, not just the first round: later
+ * rounds are drawn as TBD placeholder slots so the shape of the draw
+ * is visible immediately, even though only first-round matches are
+ * actual saveable rows.
+ *
+ * v1: only the top seed of each group feeds the bracket (one entrant
+ * per group) - advancing more than one team per group, and filling
+ * later rounds once group play completes, are follow-up work.
+ */
+export class TennisBracketBoardElement extends HTMLElementSugar {
+  static tag = 'tennis-bracket-board'
+  static renderGuardSelector = '[data-rounds]'
+
+  static attributeDefs = {
+    api: {},
+    'save-api': {},
+    'csrf-token': {},
+  }
+
+  static HtmlTemplate = ['tennis-bracket-board-template', function () {
+    return this.tpl(`
+      <div>
+        <p data-status>Loading…</p>
+        <div data-toolbar hidden>
+          <button data-prefill type="button">Prefill</button>
+          <button data-clear type="button">Clear</button>
+          <button data-reset type="button">Reset from database</button>
+          <button data-save type="button">Save</button>
+        </div>
+        <div data-rounds></div>
+      </div>
+    `)
+  }]
+
+  async connectedCallback() {
+    super.connectedCallback()
+
+    // Guard the one-time DOM setup, but always (re)fetch and render
+    // below. A morph-driven insertion can disconnect/reconnect this
+    // element once synchronously right after creation; if fetch were
+    // also skipped on the second connect, whichever instance ends up
+    // permanently live would never get real data.
+    if (!this.hasRenderedShape()) {
+      this.appendChild(this.renderFromTemplate())
+    }
+
+    if (!this._listenersBound) {
+      this._listenersBound = true
+      this.$('[data-prefill]').addEventListener('click', () => this.prefill())
+      this.$('[data-clear]').addEventListener('click', () => this.clear())
+      this.$('[data-reset]').addEventListener('click', () => this.resetFromDatabase())
+      this.$('[data-save]').addEventListener('click', () => this.save())
+    }
+
+    // That same double-connect means two of these fetches can be in
+    // flight at once. Without this token, whichever one resolves last
+    // wins - including a stray first-connect fetch resolving *after*
+    // the user has already clicked Prefill using the second connect's
+    // data, silently discarding it. Only the fetch started by the most
+    // recent connectedCallback call is allowed to apply its result.
+    const requestId = (this._fetchGeneration = (this._fetchGeneration ?? 0) + 1)
+
+    const { api } = this.getConfig()
+
+    const response = await fetch(api, {
+      headers: { Accept: 'application/json' },
+    })
+
+    const data = await response.json()
+
+    if (requestId !== this._fetchGeneration) {
+      return
+    }
+
+    this.saved = data
+    this.matches = this.saved.matches.map(match => ({ ...match }))
+
+    // Same reconstruction as resetFromDatabase() - only the first
+    // round becomes slots, not every saved round. Duplicated here
+    // rather than calling that method directly because this path
+    // additionally needs the stray-fetch guard above it.
+    this.round = firstRoundOf(this.matches)
+    this.firstRoundSlots = matchesToSlots(
+      this.matches.filter(match => match.round === this.round)
+    )
+
+    this.render()
+  }
+
+  prefill() {
+    const seeds = this.saved.seeds
+    const labelById = new Map(seeds.map(seed => [String(seed.team_id), seed.label]))
+
+    const pools = poolsFromSeeds(seeds)
+    // The draw is sized to the real number of advancing teams, not
+    // padded to some minimum - 2 advancing teams is a straight Final,
+    // 4 is a Final and a Semi-Final, nothing more. A forced-up draw
+    // gave every entrant a bye in rounds that shouldn't exist at all,
+    // and threw off which position in the draw each seed landed in.
+    const draw = Math.max(2, nextPowerOfTwo(seeds.length))
+
+    let round, rawMatches
+
+    if (draw < 8) {
+      // SingleEliminationBracket is a faithful port of a module built
+      // for real pro-tour draws (a mandatory minimum of 8, and
+      // seeded/unseeded/wildcard/qualifier pools meant to interleave a
+      // partly-seeded field of dozens) - a division's own top 2 or 4
+      // group finishers don't need any of that, they just need
+      // standard tournament seeding (1 vs 4, 2 vs 3 in a 4-draw, so
+      // the top two seeds can only meet in the Final).
+      const entrants = [...pools.seeded, ...pools.unseeded, ...pools.wildcards, ...pools.qualifiers]
+      const slots = standardSeedOrder(draw).map(seedNumber => entrants[seedNumber - 1] ?? 'Bye')
+
+      rawMatches = []
+      for (let i = 0; i < slots.length; i += 2) {
+        rawMatches.push(`${slots[i]} vs ${slots[i + 1]}`)
+      }
+      round = firstRoundForDraw(draw)
+    } else {
+      const bracket = new SingleEliminationBracket({
+        draw,
+        seeded: pools.seeded,
+        unseeded: pools.unseeded,
+        wildcards: pools.wildcards,
+        qualifiers: pools.qualifiers,
+      })
+
+      rawMatches = bracket.matches()
+      round = bracket.rounds()[0]
+    }
+
+    this.round = round
+
+    this.firstRoundSlots = rawMatches.map(entry => {
+      const [home, visitor] = entry.split(' vs ')
+
+      return {
+        home_team_id: home === 'Bye' ? null : Number(home),
+        home_label: home === 'Bye' ? 'Bye' : labelById.get(home),
+        visitor_team_id: visitor === 'Bye' ? null : Number(visitor),
+        visitor_label: visitor === 'Bye' ? 'Bye' : labelById.get(visitor),
+      }
+    })
+
+    this.rebuildMatches()
+    this.render()
+  }
+
+  clear() {
+    this.matches = []
+    this.firstRoundSlots = []
+    this.render()
+  }
+
+  resetFromDatabase() {
+    this.matches = this.saved.matches.map(match => ({ ...match }))
+
+    // Every round is saved, first round included - matchesToSlots must
+    // only ever see that one. Handed the whole list, firstRoundSlots
+    // silently became "every saved match, whichever round", so its
+    // length (used everywhere downstream - render()'s column counts,
+    // rebuildMatches()' later-round shell counts) no longer meant "one
+    // per first-round match": a 4-real-match, 3-TBD-round save came
+    // back looking like an 11-wide first round.
+    this.round = firstRoundOf(this.matches)
+    this.firstRoundSlots = matchesToSlots(
+      this.matches.filter(match => match.round === this.round)
+    )
+    this.render()
+  }
+
+  /**
+   * Manual override (spec.md's "Positions can be swapped manually to
+   * override the seeding"): exchanges two first-round slots wholesale.
+   * Only the first round is editable - later rounds are TBD
+   * placeholders with nothing real to swap yet.
+   */
+  swapEntrants(indexA, sideA, indexB, sideB) {
+    if (indexA === indexB && sideA === sideB) {
+      return
+    }
+
+    const a = this.firstRoundSlots[indexA]
+    const b = this.firstRoundSlots[indexB]
+
+    const aTeamId = a[`${sideA}_team_id`]
+    const aLabel = a[`${sideA}_label`]
+
+    a[`${sideA}_team_id`] = b[`${sideB}_team_id`]
+    a[`${sideA}_label`] = b[`${sideB}_label`]
+    b[`${sideB}_team_id`] = aTeamId
+    b[`${sideB}_label`] = aLabel
+
+    this.rebuildMatches()
+
+    this.dispatchEvent(new CustomEvent('tennis-bracket:changed', {
+      bubbles: true,
+      detail: { firstRoundSlots: this.firstRoundSlots },
+    }))
+
+    this.render()
+  }
+
+  /**
+   * Every later round is persisted as TBD shells too, not just the
+   * first. Planning and Scheduling both need to see the whole bracket
+   * in advance to reserve capacity for it - the entrants are unknown,
+   * the match count is not.
+   */
+  rebuildMatches() {
+    // A bye is still a real slot - the team standing in it is walking
+    // straight through to the next round, not absent from the draw.
+    // Requiring both sides filled dropped every "X vs Bye" match
+    // before it ever reached the server: only the other, genuinely
+    // paired matches got saved, so a reload could no longer say which
+    // team the bye even belonged to - just that some entrant, unnamed,
+    // must have advanced.
+    const firstRound = this.firstRoundSlots
+      .filter(slot => slot.home_team_id || slot.visitor_team_id)
+      .map(slot => ({
+        round: this.round,
+        home_team_id: slot.home_team_id,
+        home_label: slot.home_label,
+        visitor_team_id: slot.visitor_team_id,
+        visitor_label: slot.visitor_label,
+      }))
+
+    const laterRounds = []
+    let count = Math.max(1, Math.floor(this.firstRoundSlots.length / 2))
+
+    for (const round of roundsFrom(this.round).slice(1)) {
+      for (let i = 0; i < count; i++) {
+        laterRounds.push({
+          round,
+          home_team_id: null,
+          home_label: 'TBD',
+          visitor_team_id: null,
+          visitor_label: 'TBD',
+        })
+      }
+
+      if (round === 'F') {
+        break
+      }
+
+      count = Math.max(1, Math.floor(count / 2))
+    }
+
+    this.matches = [...firstRound, ...laterRounds]
+  }
+
+  render() {
+    this.$('[data-status]').hidden = true
+    this.$('[data-toolbar]').hidden = false
+
+    const container = this.$('[data-rounds]')
+    container.replaceChildren()
+
+    const slotCount = this.firstRoundSlots.length
+
+    if (!slotCount) {
+      return
+    }
+
+    const firstRound = this.matches[0]?.round ?? this.firstRoundSlots[0]?.round
+    const roundNames = roundsFrom(firstRound ?? ROUND_ORDER.at(-1))
+
+    let count = slotCount
+
+    for (const round of roundNames) {
+      container.appendChild(this.columnFor(round, count, round === roundNames[0]))
+
+      if (round === 'F') break
+
+      count = Math.max(1, Math.floor(count / 2))
+    }
+  }
+
+  columnFor(round, slotCount, isFirstRound) {
+    const column = document.createElement('div')
+
+    column.dataset.round = round
+
+    const heading = document.createElement('h4')
+    heading.textContent = round
+    column.appendChild(heading)
+
+    const list = document.createElement('div')
+    list.dataset.roundMatches = ''
+
+    for (let i = 0; i < slotCount; i++) {
+      const slot = isFirstRound ? this.firstRoundSlots[i] : null
+
+      list.appendChild(this.matchBoxFor(slot, isFirstRound ? i : null))
+    }
+
+    column.appendChild(list)
+
+    return column
+  }
+
+  matchBoxFor(slot, slotIndex) {
+    const box = document.createElement('div')
+    box.dataset.matchBox = ''
+
+    box.appendChild(this.entrantRowFor(slot, 'home', slotIndex))
+    box.appendChild(this.entrantRowFor(slot, 'visitor', slotIndex))
+
+    return box
+  }
+
+  /**
+   * One side of a match box. This shows the draw's structure - "Winner
+   * A", "Runner-up B" - not the real team name: at Gate 2 nothing is
+   * actually decided yet (groups haven't been played), so a real name
+   * here would overstate certainty the bracket doesn't have. Once group
+   * results exist and shells get filled from actual standings, this is
+   * where that real name will replace the slot label.
+   */
+  entrantRowFor(slot, side, slotIndex) {
+    const row = document.createElement('div')
+    row.dataset[side] = ''
+
+    const label = document.createElement('span')
+    label.dataset.entrantLabel = ''
+
+    const teamId = slot?.[`${side}_team_id`]
+    const origin = teamId != null ? this.seedOrigins().get(teamId) : null
+
+    // Never fall back to the real team label here, even if the origin
+    // lookup fails (e.g. a saved match whose team no longer appears in
+    // the current seed list after groups were regenerated) - this view
+    // is the draw's configuration, not a roster, on purpose. A missing
+    // `slot` is a not-yet-generated later round (TBD); a slot whose
+    // side has no team_id is a real bye.
+    label.textContent = !slot
+      ? 'TBD'
+      : teamId == null
+        ? 'Bye'
+        : origin
+          ? `${tierLabel(origin.tier)} ${origin.groupName}`
+          : 'Unknown slot'
+
+    row.appendChild(label)
+
+    // Only first-round slots are real - later rounds are TBD
+    // placeholders with nothing to swap yet.
+    if (slotIndex != null) {
+      this.makeSwappable(row, slotIndex, side)
+    }
+
+    return row
+  }
+
+  makeSwappable(row, slotIndex, side) {
+    row.draggable = true
+
+    row.addEventListener('dragstart', event => {
+      event.dataTransfer.setData('text/plain', JSON.stringify({ slotIndex, side }))
+      event.dataTransfer.effectAllowed = 'move'
+      row.dataset.dragging = ''
+    })
+
+    row.addEventListener('dragend', () => {
+      delete row.dataset.dragging
+    })
+
+    row.addEventListener('dragover', event => {
+      event.preventDefault()
+      event.dataTransfer.dropEffect = 'move'
+      row.dataset.dragover = ''
+    })
+
+    row.addEventListener('dragleave', () => {
+      delete row.dataset.dragover
+    })
+
+    row.addEventListener('drop', event => {
+      event.preventDefault()
+      delete row.dataset.dragover
+
+      const from = JSON.parse(event.dataTransfer.getData('text/plain'))
+
+      this.swapEntrants(from.slotIndex, from.side, slotIndex, side)
+    })
+  }
+
+  /**
+   * team_id -> { groupName, tier }, from the currently loaded seed
+   * list. Kept live off `this.saved.seeds` rather than baked into
+   * matches, so origin tags still show up for matches loaded back from
+   * the database (TournamentMatch itself doesn't store group/tier).
+   */
+  seedOrigins() {
+    return new Map(
+      this.saved.seeds.map(seed => [
+        seed.team_id,
+        { groupName: seed.group_name, tier: seed.tier },
+      ])
+    )
+  }
+
+  async save() {
+    const config = this.getConfig()
+
+    const matches = this.matches.map(match => ({
+      round: match.round,
+      home_team_id: match.home_team_id,
+      visitor_team_id: match.visitor_team_id,
+    }))
+
+    const response = await fetch(config['save-api'], {
+      method: 'POST',
+      headers: {
+        Accept: 'application/json',
+        'Content-Type': 'application/json',
+        'X-CSRF-TOKEN': config['csrf-token'],
+      },
+      body: JSON.stringify({ matches }),
+    })
+
+    const body = await response.json()
+
+    if (!response.ok) {
+      this.dispatchEvent(new CustomEvent('tennis-bracket:save-error', {
+        bubbles: true,
+        detail: body,
+      }))
+      return
+    }
+
+    this.saved = body
+    this.matches = this.saved.matches.map(match => ({ ...match }))
+
+    // Same reconstruction as resetFromDatabase()/connectedCallback() -
+    // only the first round becomes slots. A third place this bug
+    // lived: the response to Save itself updates the view in place,
+    // before any reload - so this is the one a director actually saw
+    // first, immediately after clicking Save.
+    this.round = firstRoundOf(this.matches)
+    this.firstRoundSlots = matchesToSlots(
+      this.matches.filter(match => match.round === this.round)
+    )
+
+    this.dispatchEvent(new CustomEvent('tennis-bracket:save', {
+      bubbles: true,
+      detail: { state: this.saved },
+    }))
+
+    this.render()
+  }
+}
+
+function tierLabel(tier) {
+  return { 1: 'Winner', 2: 'Runner-up' }[tier] ?? `${tier}th place`
+}
+
+/**
+ * Buckets seeds by advancement tier (1st of each group, 2nd of each
+ * group, ...) into SingleEliminationBracket's four pools, so a group's
+ * own representatives are kept apart rather than merely ranked by
+ * overall strength - the generic seeding algorithm has no notion of
+ * "these two came from the same source" on its own.
+ *
+ * Tier 1 -> seeded, in group order. Every later tier is rotated by
+ * half its own length before becoming the next pool, so
+ * pool[i] never comes from the same group as seeded[i]: with the
+ * algorithm's own "Seed k vs Unseeded k" round-1 pairing, that keeps a
+ * group's pair in different bracket positions from round 1 onward.
+ * When the tier count is a power of two this provably keeps a group's
+ * representatives in opposite halves of the draw (they can only meet
+ * in the Final) - see bracket-board.test for the worked proof. With an
+ * uneven group count or more than 4 tiers (this pool mechanism only
+ * has four) the guarantee is best-effort rather than proven.
+ */
+function poolsFromSeeds(seeds) {
+  const tierNumbers = [...new Set(seeds.map(seed => seed.tier))].sort((a, b) => a - b)
+  const poolNames = ['seeded', 'unseeded', 'wildcards', 'qualifiers']
+
+  const pools = { seeded: [], unseeded: [], wildcards: [], qualifiers: [] }
+
+  tierNumbers.forEach((tier, tierIndex) => {
+    const ordered = seeds
+      .filter(seed => seed.tier === tier)
+      .sort((a, b) => a.group_name.localeCompare(b.group_name))
+      .map(seed => String(seed.team_id))
+
+    const rotated = tierIndex === 0
+      ? ordered
+      : rotate(ordered, Math.floor(ordered.length / 2))
+
+    // A 5th+ tier has nowhere to go - the algorithm only has four
+    // pools - so it folds into qualifiers rather than being dropped.
+    const poolName = poolNames[tierIndex] ?? 'qualifiers'
+
+    pools[poolName].push(...rotated)
+  })
+
+  return pools
+}
+
+function rotate(array, offset) {
+  return [...array.slice(offset), ...array.slice(0, offset)]
+}
+
+function nextPowerOfTwo(n) {
+  let value = 1
+
+  while (value < n) {
+    value *= 2
+  }
+
+  return value
+}
+
+/**
+ * Standard tournament seeding order for a draw of n (a power of 2):
+ * which seed number occupies each bracket position, so that pairing
+ * consecutive positions gives 1 vs n, 2 vs (n-1), etc. one level down,
+ * recursively - the same convention SingleEliminationBracket documents
+ * for its own (8+) draws, worked out directly here since that module
+ * won't build draws this small.
+ */
+function standardSeedOrder(n) {
+  if (n === 1) {
+    return [1]
+  }
+
+  return standardSeedOrder(n / 2).flatMap(seed => [seed, n + 1 - seed])
+}
+
+/**
+ * The round a draw of this size starts in - a 4-draw starts at SF, a
+ * 2-draw is just the Final. Matches ROUND_ORDER's own convention
+ * (bracket.rounds()[0] for an 8+ draw): the Final is always last.
+ */
+function firstRoundForDraw(draw) {
+  return ROUND_ORDER[ROUND_ORDER.length - Math.log2(draw)]
+}
+
+function roundsFrom(firstRound) {
+  const idx = ROUND_ORDER.indexOf(firstRound)
+
+  return idx === -1 ? [firstRound] : ROUND_ORDER.slice(idx)
+}
+
+/**
+ * The widest round among a set of saved matches - not just whichever
+ * happens to be first in the array. The store endpoint saves every
+ * round in one transaction with no ORDER BY on the way back out, so
+ * matches[0] is whatever the database felt like returning first, not
+ * necessarily the actual first round.
+ */
+function firstRoundOf(matches) {
+  const present = new Set(matches.map(match => match.round))
+
+  return ROUND_ORDER.find(round => present.has(round)) ?? matches[0]?.round
+}
+
+function matchesToSlots(matches) {
+  return matches.map(match => ({
+    home_team_id: match.home_team_id,
+    home_label: match.home_label,
+    visitor_team_id: match.visitor_team_id,
+    visitor_label: match.visitor_label,
+  }))
+}
+