@opndev/tennis-match-center 0.0.1

package/lib/bracket-autofill.mjs

@@ -0,0 +1,174 @@
+// SPDX-FileCopyrightText: 2026 Wesley Schwengle <wesley@opndev.io>
+//
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+import { SingleEliminationBracket } from './bracket-single-elimination.mjs'
+
+const ROUND_ORDER = ['R256', 'R128', 'R64', 'R32', 'R16', 'QF', 'SF', 'F']
+
+/**
+ * Gate 2's own auto-fill, factored out of <tennis-bracket-board> so it
+ * can run without a live element - a bulk "generate everything" pass
+ * (Competitions overview's "Generate all groups", which needs a
+ * bracket for every division right after its groups are seeded, not
+ * just the one being looked at in the Roster tab) calls this directly
+ * instead of driving the board headlessly.
+ *
+ * Takes the same `seeds` BracketController::index returns and produces
+ * the same `matches` shape <tennis-bracket-board>'s save() posts to
+ * BracketController::store - first round real, later rounds TBD
+ * shells. An empty seed list produces no matches at all, same as the
+ * board showing nothing to prefill.
+ *
+ * @param {Array<{team_id: number, tier: number, group_name: string}>} seeds
+ * @returns {Array<{round: string, home_team_id: ?number, visitor_team_id: ?number}>}
+ */
+export function autoFillBracket(seeds) {
+  if (seeds.length === 0) {
+    return []
+  }
+
+  const pools = poolsFromSeeds(seeds)
+  // Sized to the real number of advancing teams, not padded to some
+  // minimum - see <tennis-bracket-board>'s own prefill().
+  const draw = Math.max(2, nextPowerOfTwo(seeds.length))
+
+  let round, rawMatches
+
+  if (draw < 8) {
+    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]
+  }
+
+  const firstRoundSlots = rawMatches.map(entry => {
+    const [home, visitor] = entry.split(' vs ')
+
+    return {
+      home_team_id: home === 'Bye' ? null : Number(home),
+      visitor_team_id: visitor === 'Bye' ? null : Number(visitor),
+    }
+  })
+
+  return buildMatches(round, firstRoundSlots)
+}
+
+/**
+ * Every later round 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 but the match
+ * count is not.
+ */
+function buildMatches(round, firstRoundSlots) {
+  const firstRound = firstRoundSlots
+    .filter(slot => slot.home_team_id || slot.visitor_team_id)
+    .map(slot => ({
+      round,
+      home_team_id: slot.home_team_id,
+      visitor_team_id: slot.visitor_team_id,
+    }))
+
+  const laterRounds = []
+  let count = Math.max(1, Math.floor(firstRoundSlots.length / 2))
+
+  for (const laterRound of roundsFrom(round).slice(1)) {
+    for (let i = 0; i < count; i++) {
+      laterRounds.push({
+        round: laterRound,
+        home_team_id: null,
+        visitor_team_id: null,
+      })
+    }
+
+    if (laterRound === 'F') {
+      break
+    }
+
+    count = Math.max(1, Math.floor(count / 2))
+  }
+
+  return [...firstRound, ...laterRounds]
+}
+
+/**
+ * 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 - see <tennis-bracket-board>'s own copy of this
+ * doc comment for the full rationale.
+ */
+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))
+
+    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) -
+ * see <tennis-bracket-board>'s own copy of this doc comment.
+ */
+function standardSeedOrder(n) {
+  if (n === 1) {
+    return [1]
+  }
+
+  return standardSeedOrder(n / 2).flatMap(seed => [seed, n + 1 - seed])
+}
+
+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)
+}

package/lib/bracket-single-elimination.mjs

@@ -0,0 +1,496 @@
+// SPDX-FileCopyrightText: 2026 Wesley Schwengle <wesley@opndev.io>
+//
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+/**
+ * Single-elimination bracket seeding, ported line-for-line from the Perl
+ * reference implementation named in spec.md:
+ * Games::Tournament::Format::Elimination::Single
+ * (opndev/games-tournament-format). Kept as its own module, independent
+ * of any Sugar component, because the seeding logic has nothing to do
+ * with rendering.
+ *
+ * Entries are plain strings ("Seed 1 vs Seed 8", "Seed 1 vs Bye") to stay
+ * a faithful, fixture-verified port of the Perl module first. Mapping
+ * those back to real team ids/objects is the caller's job.
+ */
+export class SingleEliminationBracket {
+  /**
+   * @param {object} options
+   * @param {number} options.draw - power of two, minimum 8
+   * @param {string[]} [options.seeded]
+   * @param {string[]} [options.unseeded]
+   * @param {string[]} [options.wildcards]
+   * @param {string[]} [options.qualifiers]
+   * @param {boolean} [options.weakestSeed=true]
+   * @param {boolean} [options.weakestOpponent=true]
+   * @param {boolean} [options.wildcardAsSeed=false]
+   * @param {boolean} [options.qualifierAsSeed=false]
+   * @param {string[]} [options.order] - subset/reorder of
+   *   ['unseeded', 'qualifier', 'wildcard']
+   */
+  constructor(options = {}) {
+    if (options.draw != null) {
+      if (!isPowerOfTwo(options.draw)) {
+        throw new Error(`Unable to set draw of ${options.draw}, not a power of 2`)
+      }
+
+      if (options.draw < 8) {
+        throw new Error('Unable to set draw with a size less than 8')
+      }
+    }
+
+    if (!('seeded' in options) && !('unseeded' in options)) {
+      throw new Error('No seeded or unseeded participants')
+    }
+
+    const draw = options.draw ?? 8
+    const defaultOrder = ['unseeded', 'qualifier', 'wildcard']
+    const requestedOrder = options.order ?? defaultOrder
+    const order = requestedOrder.filter(key => defaultOrder.includes(key))
+
+    this.draw = draw
+    this.weakestSeed = options.weakestSeed ?? true
+    this.weakestOpponent = options.weakestOpponent ?? true
+    this.wildcardAsSeed = options.wildcardAsSeed ?? false
+    this.qualifierAsSeed = options.qualifierAsSeed ?? false
+
+    this.seeded = []
+    this.unseeded = []
+    this.wildcards = []
+    this.qualifiers = []
+    this.order = [...order]
+    this.playerCount = 0
+
+    this.unseededIdx = 0
+    this.wildcardIdx = 0
+    this.qualifierIdx = 0
+
+    this.maxMatches = draw / 2
+    this.maxBracketMatches = this.maxMatches / 2
+
+    this._addSeeded(options.seeded ?? [])
+    this._addUnseeded(options.unseeded ?? [])
+    this._addQualifiers(options.qualifiers ?? [])
+    this._addWildcards(options.wildcards ?? [])
+
+    if (!this.playerCount) {
+      throw new Error('Cannot have a tourney without participants')
+    }
+
+    if (this.playerCount > draw) {
+      throw new Error('Cannot have a tourney with more players than the draw size!')
+    }
+
+    this._addByePlayers()
+
+    this._roundsCount = powerOfTwoExponent(draw)
+
+    let roundsArr = ['F', 'SF', 'QF']
+
+    if (this._roundsCount > 3) {
+      let p = 16
+
+      for (let i = 4; i <= this._roundsCount; i++) {
+        roundsArr.push(`R${p}`)
+        p *= 2
+      }
+    }
+
+    this._roundsArr = roundsArr.slice().reverse()
+
+    this._left = []
+    this._right = []
+    this._matches = []
+    this._seededMatches = []
+    this._unseededMatches = []
+
+    this._initSeededMatches()
+    this._bracketMatches()
+    this._addMatches()
+  }
+
+  // -- public API, mirroring the Perl module's methods --------------------
+
+  matches(side) {
+    if (!side) {
+      return [...this._matches]
+    }
+
+    if (['bottom', 'right'].includes(side)) {
+      return [...this._right]
+    }
+
+    if (['top', 'left'].includes(side)) {
+      return [...this._left]
+    }
+
+    return [...this._matches]
+  }
+
+  getPlayerCount() {
+    return this.playerCount
+  }
+
+  numberOfRounds() {
+    return this._roundsCount
+  }
+
+  getByes() {
+    return this.byesCount
+  }
+
+  rounds() {
+    return [...this._roundsArr]
+  }
+
+  round(ask) {
+    if (/^[0-9]$/.test(String(ask))) {
+      if (Number(ask) > this._roundsCount) {
+        throw new Error('Unable to ask for such a round')
+      }
+
+      return this._roundsArr[Number(ask) - 1]
+    }
+
+    const found = this._roundsArr.find(r => r === String(ask).toUpperCase())
+
+    if (found) {
+      return found
+    }
+
+    throw new Error('Unable to determine what you want')
+  }
+
+  games() {
+    const count = this.playerCount - 1
+
+    return Array.from({ length: Math.max(0, count) }, (_, i) => i + 1)
+  }
+
+  // -- construction helpers -------------------------------------------
+
+  _addUnseeded(items) {
+    this.unseeded.push(...items)
+
+    if (!this.order.includes('unseeded')) {
+      this.order.push('unseeded')
+    }
+
+    this.playerCount += items.length
+  }
+
+  _addSeeded(items) {
+    this.seeded.push(...items)
+    this.playerCount += items.length
+  }
+
+  _addWildcards(items) {
+    if (this.wildcardAsSeed) {
+      this._addSeeded(items)
+      return
+    }
+
+    this.wildcards.push(...items)
+
+    if (!this.order.includes('wildcard')) {
+      this.order.push('wildcard')
+    }
+
+    this.playerCount += items.length
+  }
+
+  _addQualifiers(items) {
+    if (this.qualifierAsSeed) {
+      this._addSeeded(items)
+      return
+    }
+
+    this.qualifiers.push(...items)
+
+    if (!this.order.includes('qualifier')) {
+      this.order.push('qualifier')
+    }
+
+    this.playerCount += items.length
+  }
+
+  _addByePlayers() {
+    // Perl has two variables named "byes": a scalar $byes (constant, this
+    // is it) and an array @byes (a shrinking countdown, that's
+    // _byesQueueLength below) - conflating them was the first bug this
+    // port's fixture diff against the real Perl module caught.
+    this.byesCount = this.draw - this.playerCount
+    this._byesQueueLength = this.byesCount
+  }
+
+  // -- seeding pipeline, in the same order as _init_seeded_matches -----
+
+  _initSeededMatches() {
+    this._addByeMatches()
+
+    for (const key of this.order) {
+      if (key === 'unseeded') this._addSeededMatches('unseeded', [...this.unseeded])
+      if (key === 'qualifier') this._addSeededMatches('qualifier', [...this.qualifiers])
+      if (key === 'wildcard') this._addSeededMatches('wildcard', [...this.wildcards])
+    }
+
+    const l = [...this.seeded]
+    let right = l.splice(this.maxMatches)
+
+    if (this.weakestSeed) {
+      right = right.reverse()
+    }
+
+    this._addSeededMatches('seeded', right)
+
+    this._matches = [...this._seededMatches]
+  }
+
+  _addByeMatches() {
+    if (!this.byesCount) {
+      return
+    }
+
+    let max = this.seeded.length - this.byesCount
+
+    if (max < 0) {
+      max *= -1
+
+      for (const key of this.order) {
+        const source = key === 'unseeded' ? this.unseeded
+          : key === 'wildcard' ? this.wildcards
+          : key === 'qualifier' ? this.qualifiers
+          : null
+
+        if (!source) continue
+
+        if (source.length >= max) {
+          const grab = source.splice(0, max)
+          this.seeded.push(...grab)
+          max = 0
+        }
+        else if (source.length < max) {
+          this.seeded.push(...source)
+          max -= source.length
+          source.length = 0
+        }
+      }
+    }
+
+    for (let i = 1; i <= this.byesCount; i++) {
+      if (this.seeded[i - 1] === undefined) break
+
+      this._seededMatches.push(`${this.seeded[i - 1]} vs Bye`)
+      this._byesQueueLength--
+    }
+  }
+
+  _addSeededMatches(src, source) {
+    if (!this.seeded.length) return
+    if (this._seededMatches.length === this.seeded.length) return
+
+    const idx = this._seededMatches.length
+    let max = this.seeded.length - this._seededMatches.length + idx
+
+    if (source.length < max) {
+      max = source.length
+    }
+
+    // How many of `source` this call actually consumed, so the next
+    // stage (_addUnseededMatches) knows to skip exactly that many
+    // before drawing from what's left. Recording the loop's own index
+    // instead undercounted by one whenever the loop broke out early
+    // (byes leaving fewer seeded slots than there were unseeded/
+    // wildcard/qualifier entrants to pair against them) - `i` names
+    // the entrant just consumed, not how many have been so far, so
+    // the next stage skipped one too few: it re-drew the entrant right
+    // after the one just placed (a real player entered twice) and
+    // never reached the last entrant at all (dropped from the draw
+    // entirely).
+    let consumed = 0
+
+    for (let i = 0; i < max; i++) {
+      const s = source.shift()
+
+      this._seededMatches.push(`${this.seeded[i + idx]} vs ${s}`)
+      consumed = i + 1
+
+      if (this._seededMatches.length === this.seeded.length) break
+    }
+
+    if (src === 'unseeded') this.unseededIdx = consumed
+    if (src === 'wildcard') this.wildcardIdx = consumed
+    if (src === 'qualifier') this.qualifierIdx = consumed
+  }
+
+  _addUnseededMatches(src, max, source) {
+    if (!max) return 0
+    if (!source.length) return 0
+
+    const idx = src === 'unseeded' ? this.unseededIdx
+      : src === 'wildcard' ? this.wildcardIdx
+      : this.qualifierIdx
+
+    source.splice(0, idx)
+
+    if (source.length > max) {
+      source.splice(max)
+    }
+
+    this._unseededMatches.push(...source)
+
+    if (src === 'unseeded') this.unseededIdx += source.length
+    if (src === 'wildcard') this.wildcardIdx += source.length
+    if (src === 'qualifier') this.qualifierIdx += source.length
+
+    return max - source.length
+  }
+
+  _addUnseededMatchesOpp(src, idx, source) {
+    if (!source.length) return idx
+
+    const max = this._unseededMatches.length - idx
+
+    if (!max) return idx
+
+    const s = src === 'unseeded' ? this.unseededIdx
+      : src === 'wildcard' ? this.wildcardIdx
+      : this.qualifierIdx
+
+    source.splice(0, s)
+
+    if (source.length > max) {
+      source.splice(max)
+    }
+
+    if (!source.length) return idx
+
+    for (const item of source) {
+      this._unseededMatches[idx] += ` vs ${item}`
+      idx++
+    }
+
+    if (src === 'unseeded') this.unseededIdx += source.length
+    if (src === 'wildcard') this.wildcardIdx += source.length
+    if (src === 'qualifier') this.qualifierIdx += source.length
+
+    return idx
+  }
+
+  _addMatches() {
+    if (this._matches.length === this.maxMatches) return
+
+    const mLeft = this.maxBracketMatches - this._left.length
+    const mRight = this.maxBracketMatches - this._right.length
+    let matchesToAdd = mLeft + mRight
+
+    for (const key of this.order) {
+      if (key === 'unseeded') matchesToAdd = this._addUnseededMatches(key, matchesToAdd, [...this.unseeded])
+      if (key === 'wildcard') matchesToAdd = this._addUnseededMatches(key, matchesToAdd, [...this.wildcards])
+      if (key === 'qualifier') matchesToAdd = this._addUnseededMatches(key, matchesToAdd, [...this.qualifiers])
+    }
+
+    let idx = 0
+    for (const key of this.order) {
+      if (key === 'unseeded') idx = this._addUnseededMatchesOpp(key, idx, [...this.unseeded])
+      if (key === 'wildcard') idx = this._addUnseededMatchesOpp(key, idx, [...this.wildcards])
+      if (key === 'qualifier') idx = this._addUnseededMatchesOpp(key, idx, [...this.qualifiers])
+    }
+
+    while (this._byesQueueLength > 0) {
+      this._byesQueueLength -= 2
+      this._unseededMatches.push('Bye vs Bye')
+    }
+
+    idx = 1
+    let s = this._left.length > this._right.length ? -1 : 1
+    let c = 0
+
+    while (this._unseededMatches.length) {
+      const match = this._unseededMatches.shift()
+      const source = s > 0 ? this._left : this._right
+
+      if (source.length) {
+        source.splice(idx, 0, match)
+      }
+      else {
+        source.push(match)
+      }
+
+      s *= -1
+
+      if (c % 2) {
+        idx *= -1
+        if (idx > 0) idx += 2
+        if (idx > this._left.length / 2) idx = 1
+      }
+
+      c++
+    }
+
+    this._matches = []
+    for (let i = 0; i < this._left.length; i++) {
+      this._matches.push(this._left[i], this._right[i])
+    }
+  }
+
+  _bracketMatches() {
+    while (this._matches.length) {
+      this._left.push(this._matches.shift())
+
+      if (this._matches.length) {
+        this._right.push(this._matches.shift())
+      }
+    }
+
+    if (this._left.length > 1 && this._left.length > this._right.length) {
+      this._right.push(this._left.pop())
+    }
+
+    this._left = this._shuffleBracket(this._left)
+    this._right = this._shuffleBracket(this._right)
+
+    for (let i = 0; i < this._left.length; i += 2) {
+      if (this._left[i]) this._matches.push(this._left[i])
+      if (this._right[i]) this._matches.push(this._right[i])
+      if (this._left[i + 1]) this._matches.push(this._left[i + 1])
+      if (this._right[i + 1]) this._matches.push(this._right[i + 1])
+    }
+  }
+
+  _shuffleBracket(bracket) {
+    bracket = [...bracket]
+
+    const l = []
+    const r = []
+
+    while (bracket.length) {
+      l.push(bracket.shift(), bracket.pop())
+      r.push(bracket.shift(), bracket.pop())
+
+      if (!this.weakestOpponent || !bracket.length) continue
+
+      const b = bracket.splice(Math.floor(bracket.length / 2))
+
+      bracket = [...bracket.reverse(), ...b.reverse()]
+    }
+
+    return [...l, ...r.reverse()].filter(v => v !== undefined)
+  }
+}
+
+function isPowerOfTwo(value) {
+  return (value & (value - 1)) === 0
+}
+
+function powerOfTwoExponent(value) {
+  let count = 0
+
+  while (value !== 1) {
+    value = value >> 1
+    count++
+  }
+
+  return count
+}