@opndev/tennis-match-center 0.0.1

package/lib/four-team-planner.mjs

@@ -0,0 +1,216 @@
+// SPDX-FileCopyrightText: 2026 Wesley Schwengle <wesley@opndev.io>
+//
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+import {
+  buildUnits as buildPairedUnits,
+  placeLayout,
+  unitLayout,
+  unitSizes,
+} from './paired-court-planner.mjs'
+
+export { placeLayout }
+
+/**
+ * Plans 4-team groups.
+ *
+ * A 4-team group does not take a court to itself. It plays its round
+ * robin as three rounds of two matches, a round takes both courts at
+ * once, and groups take turns: every group's first round, then every
+ * group's second, then its third.
+ *
+ *   1: A v B   C v D          two groups, six slots
+ *   2: A v B   C v D          three groups, nine slots
+ *   1: A v C   B v D
+ *   2: A v C   B v D          no slot idle, and a group waits out the
+ *   1: A v D   B v C          others between its own rounds - which is
+ *   2: A v D   B v C          what the bundling is for
+ *
+ * The bundling and layout mechanics themselves live in
+ * paired-court-planner.mjs, shared with three-team-planner.mjs (its
+ * own round robin needs only one court a round, not two, but the same
+ * "groups take turns" bundling gives it the same rest). This module
+ * owns only what is genuinely 4-team's own: its template, and the
+ * public names callers already depend on.
+ *
+ * Groups are pooled across divisions on purpose: a division with a
+ * single 4-team group has nobody of its own to share with.
+ */
+
+/**
+ * @param {Object} params
+ * @param {Array<Object>} params.groups
+ *   {id, competitionId, divisionId, divisionName, divisionGender, groupName, teamIds, poolSize}
+ * @param {Array<Object>} params.courts in the order they should be used
+ * @param {Array<Object>} params.slots the day's slots, with start/end minutes
+ * @param {string} params.date
+ * @param {Object} params.occupancy shared with the other planner
+ * @param {?number} params.darkFrom minutes past midnight
+ * @param {boolean} params.dense pack into fewer pairs when courts are scarce
+ * @returns {{blocks: Array<Object>, unplaced: Array<Object>}}
+ */
+export function planFourTeamGroups({
+  groups,
+  courts,
+  slots,
+  date,
+  occupancy,
+  darkFrom = null,
+  dense = false,
+}) {
+  const blocks = []
+  const unplaced = []
+
+  for (const unit of buildUnits(groups, { dense })) {
+    const placed = placeUnit({ unit, courts, slots, date, occupancy, darkFrom, blocks })
+
+    if (!placed) {
+      unplaced.push(...unit)
+    }
+  }
+
+  return { blocks, unplaced }
+}
+
+/**
+ * Splits the groups into units sharing a pair.
+ *
+ * What decides the split is parity, not greed: a group left over on
+ * its own has nobody to share with, so an odd count takes exactly one
+ * unit of three and pairs off the rest.
+ */
+export function buildUnits(groups, { dense = false } = {}) {
+  return buildPairedUnits(groups, { dense })
+}
+
+/**
+ * The first pair of adjacent courts that can host the whole unit, and
+ * the earliest start on it. See placeLayout - this just computes the
+ * unit's layout and looks its groups up by id.
+ */
+function placeUnit({ unit, courts, slots, date, occupancy, darkFrom, blocks }) {
+  const layout = fourTeamUnitLayout(unit.map(group => ({
+    id: group.id,
+    teamIds: group.teamIds,
+    groupSize: group.poolSize,
+  })))
+
+  return placeLayout({
+    layout,
+    lookup: groupId => unit.find(entry => entry.id === groupId),
+    courts,
+    slots,
+    date,
+    occupancy,
+    darkFrom,
+    blocks,
+  })
+}
+
+/**
+ * A 4-team group's round robin: three rounds of two matches, a round
+ * taking both courts of the pair at once.
+ */
+export const FOUR_TEAM_TEMPLATE = [
+  { slot: 1, day: 1, pairs: [[1, 2], [3, 4]] },
+  { slot: 2, day: 1, pairs: [[1, 3], [2, 4]] },
+  { slot: 3, day: 1, pairs: [[1, 4], [2, 3]] },
+]
+
+/**
+ * The template with every seat above `teams` left vacant.
+ *
+ * Three teams in a division drawn for four is this same group with one
+ * bye, not a three-team round robin. It keeps its turn on the pair and
+ * its rest still comes from waiting that turn out; the vacant seat has
+ * no match, so the partner court simply stands empty while it plays.
+ *
+ * @param {number} teams
+ */
+export function fourTeamTemplate(teams) {
+  if (teams >= 4) {
+    return FOUR_TEAM_TEMPLATE
+  }
+
+  return FOUR_TEAM_TEMPLATE
+    .map(entry => ({
+      ...entry,
+      pairs: entry.pairs.filter(([home, visitor]) => home <= teams && visitor <= teams),
+    }))
+    .filter(entry => entry.pairs.length > 0)
+}
+
+/**
+ * A group's matches in play order.
+ *
+ * A slot holds two pairs playing at once on two courts, so the flat
+ * index - not the template slot number - is what a planned cell
+ * records as its match_slot, and what Scheduling reads back to know
+ * which pair belongs in the cell.
+ *
+ * @param {{teamIds: number[]}} group
+ */
+export function fourTeamMatches(group) {
+  const matches = []
+  const seenInDay = new Map()
+
+  for (const entry of fourTeamTemplate(group.teamIds.length)) {
+    const position = (seenInDay.get(entry.day) ?? 0) + 1
+    seenInDay.set(entry.day, position)
+
+    entry.pairs.forEach((pair, pairIndex) => {
+      matches.push({
+        index: matches.length,
+        slot: entry.slot,
+        runSlot: entry.runSlot ?? position,
+        day: entry.day,
+        pairIndex,
+        pair,
+      })
+    })
+  }
+
+  return matches
+}
+
+/**
+ * How a set of 4-team groups is split into units sharing a court pair.
+ *
+ * See paired-court-planner.mjs's unitSizes - this is a thin, shape-
+ * named entry point onto that shared math.
+ *
+ * @param {number} count
+ * @param {{dense?: boolean}} options
+ * @returns {number[]} unit sizes, largest first
+ */
+export function fourTeamUnitSizes(count, { dense = false } = {}) {
+  return unitSizes(count, { dense })
+}
+
+/**
+ * Lays out a set of 4-team groups sharing one pair of courts.
+ *
+ * A 4-team group plays its round robin as three rounds of two matches,
+ * and a round takes both courts at once. Groups take turns: every
+ * group plays its first round, then every group its second, then its
+ * third.
+ *
+ * Nothing sits idle, and a group waits out as many slots between its
+ * own rounds as there are other groups in the unit. That is what the
+ * bundling is for - two groups alone on a pair cannot fill the gap
+ * their own rest requires.
+ *
+ *   Two groups, six slots        Three groups, nine slots
+ *   1: A v B   C v D             1: A v B   C v D
+ *   2: A v B   C v D             2: A v B   C v D
+ *   1: A v C   B v D             3: A v B   C v D
+ *   2: A v C   B v D             1: A v C   B v D
+ *   1: A v D   B v C             ...
+ *   2: A v D   B v C
+ *
+ * @param {Array<{id: number, teamIds: number[]}>} groups
+ * @returns {Array<Array<{groupId: number, index: number}>>} slot by court
+ */
+export function fourTeamUnitLayout(groups) {
+  return unitLayout(groups, { template: FOUR_TEAM_TEMPLATE, matchesFor: fourTeamMatches })
+}

package/lib/group-schedule.mjs

@@ -0,0 +1,175 @@
+// SPDX-FileCopyrightText: 2026 Wesley Schwengle <wesley@opndev.io>
+//
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+import { fourTeamTemplate } from './four-team-planner.mjs'
+
+/**
+ * The fixed group-stage match templates - "Group Stage Scheduling" in
+ * spec.md. Each entry is one "slot": a set of matches that share no
+ * team and so can run at the same real hour. Different slots for the
+ * same group always share at least one team with a neighbouring slot,
+ * so they must run at strictly later real hours - see
+ * scheduleGroupMatches's readyAtHourIndex.
+ *
+ * Pairs are 1-based positions into a group's team_ids (seed order),
+ * matching spec.md's tables directly.
+ *
+ * The 4-team template is played on two courts at once (spec.md: "6
+ * matches per group, 1 day, 2 courts"), with two or three groups
+ * rotating through the same pair, one group's whole round at a time.
+ *
+ * A group that ends up with only 4 real teams in a division otherwise
+ * configured for 5 uses that same 4-team template. It cannot play
+ * three matches a day on a court of its own - a round robin of four
+ * has six pairs, and after any two with no shared team every
+ * remaining pair reuses one - so it is bundled with the other short
+ * groups, and its rest comes from waiting its turn on the pair.
+ */
+export { fourTeamUnitSizes, fourTeamUnitLayout } from './four-team-planner.mjs'
+
+export const GROUP_TEMPLATES = {
+  // Team Cup: one court per group, its three encounters in a cycle.
+  // Every pair of encounters in a group of three shares a team, so
+  // there is no ordering that rests everyone - but an encounter is
+  // itself three matches, so a team following one with another has
+  // had a long stretch off court either way.
+  3: [
+    { slot: 1, day: 1, pairs: [[1, 2]] },
+    { slot: 2, day: 1, pairs: [[2, 3]] },
+    { slot: 3, day: 1, pairs: [[3, 1]] },
+  ],
+  5: [
+    { slot: 1, day: 1, pairs: [[1, 2]] },
+    { slot: 2, day: 1, pairs: [[3, 4]] },
+    { slot: 3, day: 1, pairs: [[1, 5]] },
+    { slot: 4, day: 1, pairs: [[2, 3]] },
+    { slot: 5, day: 1, pairs: [[4, 5]] },
+    { slot: 6, day: 2, pairs: [[1, 3]] },
+    { slot: 7, day: 2, pairs: [[2, 5]] },
+    { slot: 8, day: 2, pairs: [[1, 4]] },
+    { slot: 9, day: 2, pairs: [[3, 5]] },
+    { slot: 10, day: 2, pairs: [[2, 4]] },
+  ],
+}
+
+
+/**
+ * Which template a group uses - its real team count picks it, not the
+ * pool size its division is configured for.
+ *
+ * @param {{teamIds: number[]}} group
+ */
+function templateFor(group) {
+  const teams = group.teamIds.length
+  const size = group.groupSize ?? teams
+
+  // Four seats, however many of them are filled, is the 4-team
+  // planner's shape and it owns the bye that goes with a vacant one.
+  if (teams === 4 || (teams === 3 && size >= 4)) {
+    return fourTeamTemplate(teams)
+  }
+
+  return GROUP_TEMPLATES[teams] ?? null
+}
+
+/**
+ * A group's template flattened into individual matches, in play order.
+ * A 4-team slot holds two pairs playing at once on two courts, so the
+ * flat index - not the template slot number - is what identifies one
+ * match of a group.
+ *
+ * @param {{teamIds: number[], groupSize: 4|5}} group
+ */
+export function templateMatches(group) {
+  const template = templateFor(group)
+
+  if (!template) {
+    return []
+  }
+
+  const matches = []
+  const seenInDay = new Map()
+
+  for (const entry of template) {
+    // Where in the day's court run this match sits. Usually that is
+    // just its order within the day, but a template may leave a slot
+    // empty to keep a team off court two matches running.
+    const position = (seenInDay.get(entry.day) ?? 0) + 1
+    seenInDay.set(entry.day, position)
+
+    entry.pairs.forEach((pair, pairIndex) => {
+      matches.push({
+        index: matches.length,
+        slot: entry.slot,
+        runSlot: entry.runSlot ?? position,
+        day: entry.day,
+        pairIndex,
+        pair,
+      })
+    })
+  }
+
+  return matches
+}
+
+/**
+ * The court runs a group needs: one run per day per parallel court.
+ * A 5-team group takes one court for five consecutive matches on each
+ * of two days; a 4-team group takes two courts for three each on one
+ * day. Planning reserves capacity in exactly these units, so this is
+ * what decides which cells a group is booked into.
+ *
+ * @returns {Array<{day: number, pairIndex: number, indices: number[]}>}
+ */
+export function groupRuns(group) {
+  const runs = new Map()
+
+  for (const match of templateMatches(group)) {
+    const key = `${match.day}:${match.pairIndex}`
+
+    if (!runs.has(key)) {
+      runs.set(key, { day: match.day, pairIndex: match.pairIndex, indices: [], positions: [] })
+    }
+
+    const run = runs.get(key)
+
+    run.indices.push(match.index)
+
+    // positions is the run laid out slot by slot, so a template that
+    // skips a slot leaves a hole here rather than closing the gap up.
+    run.positions[match.runSlot - 1] = match.index
+  }
+
+  for (const run of runs.values()) {
+    for (let i = 0; i < run.positions.length; i++) {
+      if (run.positions[i] === undefined) {
+        run.positions[i] = null
+      }
+    }
+  }
+
+  return [...runs.values()]
+}
+
+/**
+ * How many matches a group's template actually has, using its real
+ * team count (see GROUP_TEMPLATES) rather than GAMES_PER_GROUP's
+ * configured-pool-size assumption - so a scheduling legend's "N/M
+ * scheduled" for an uneven last group compares against what it can
+ * really play (6 for an actual 4-team group), not the bigger template
+ * it was nominally configured for.
+ *
+ * @param {{teamIds: number[], groupSize: 4|5}} group
+ * @returns {number}
+ */
+export function reachableMatchCount(group) {
+  const template = templateFor(group)
+
+  if (!template) {
+    return 0
+  }
+
+  return template.reduce((count, entry) => count + entry.pairs.length, 0)
+}
+

package/lib/index.mjs

@@ -0,0 +1,9 @@
+// SPDX-FileCopyrightText: 2023 - 2026 Wesley Schwengle <wesley@opndev.io>
+//
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+const VERSION = "0.0.1"
+
+export { VERSION }
+export { autoFillBracket } from './bracket-autofill.mjs'
+

package/lib/knockout-draw.mjs

@@ -0,0 +1,209 @@
+// SPDX-FileCopyrightText: 2026 Wesley Schwengle <wesley@opndev.io>
+//
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+/**
+ * How a knockout round may be cut when it cannot go on whole: in half,
+ * in quarters, in eighths, and nothing else - a split is a cut of the
+ * bracket, so the parts are the bracket's own halves. Ordered fewest
+ * cuts first, which is the order they are preferred in.
+ */
+export const SPLIT_SIZES = [1, 2, 4, 8]
+
+/**
+ * The smallest a part may be, below a straight halving.
+ *
+ * A round can always be halved, however narrow that leaves it: a semi
+ * playing 1/1 is two halves of the bracket, and the Final is after
+ * both. Cutting deeper than that is only a bracket cut while the parts
+ * still hold matches of their own - a QF goes 2/2 and no further,
+ * where quarters of one would have it dribbling out a match at a time.
+ */
+const MIN_ROUND_PART = 2
+
+/**
+ * One division's draw as the planner works through it: which round it
+ * is on, how much of that round is already booked, the courts it is
+ * committed to, and when it is next free.
+ */
+export class KnockoutDraw {
+
+  /**
+   * @param {Object} params
+   * @param {Object} params.competition The competition it belongs to.
+   * @param {Array<{round: string, count: number}>} params.waves Its
+   *   rounds in play order, widest first.
+   * @param {?number} [params.divisionId]
+   * @param {?string} [params.divisionName]
+   * @param {?string} [params.divisionGender]
+   * @param {number} [params.level] 0 is the strongest field.
+   * @param {boolean} [params.isPro] Pro draws use the pro courts only.
+   */
+  constructor({
+    competition, waves, divisionId = null, divisionName = null,
+    divisionGender = null, level = 0, isPro = false,
+  }) {
+    this.competition = competition
+    this.waves = waves
+    this.divisionId = divisionId
+    this.divisionName = divisionName
+    this.divisionGender = divisionGender
+    this.level = level
+    this.isPro = isPro
+
+    this.roundIndex = 0
+    this.placedInRound = 0
+    this.placed = 0
+    this.roundCourts = null
+    this.lastParts = 1
+    this.freeFrom = -Infinity
+  }
+
+  /** Whether every round of the draw has been planned. */
+  get done() {
+    return this.roundIndex >= this.waves.length
+  }
+
+  /** The round being planned, or null once the draw is done. */
+  get round() {
+    return this.waves[this.roundIndex] ?? null
+  }
+
+  /** How many matches the current round holds in total. */
+  get width() {
+    return this.round?.count ?? 0
+  }
+
+  /** How many of them are still to be booked. */
+  get remaining() {
+    return this.width - this.placedInRound
+  }
+
+  /** Whether the current round is part way through. */
+  get underway() {
+    return this.placedInRound > 0
+  }
+
+  /**
+   * How many rounds are left after this one - 0 is the Final, 1 the
+   * semi. Doubles as "how important is this match" wherever the lower
+   * courts are handed out.
+   */
+  get roundsRemaining() {
+    return this.waves.length - 1 - this.roundIndex
+  }
+
+  /**
+   * Matches of the whole draw that never found a court - what it is
+   * short by, for the plan to report.
+   */
+  get unplanned() {
+    const total = this.waves.reduce((sum, wave) => sum + wave.count, 0)
+
+    return Math.max(0, total - this.placed)
+  }
+
+  /**
+   * Whether this draw may go on in this slot: it has a round left and
+   * has had whatever rest it is owed.
+   *
+   * @param {number} slotIndex
+   * @returns {boolean}
+   */
+  readyAt(slotIndex) {
+    return !this.done && slotIndex >= this.freeFrom
+  }
+
+  /**
+   * The cuts the current round could be played in, fewest first.
+   *
+   * A round goes on whole where the room is there and is otherwise cut
+   * the way the bracket cuts. Halving is always available, however
+   * narrow it leaves the parts; quarters and eighths need parts that
+   * still hold matches of their own.
+   *
+   * @param {boolean} split Whether cutting is allowed at all.
+   * @returns {Array<{parts: number, count: number}>} Courts needed
+   *   (count) for each number of parts.
+   */
+  cuts(split) {
+    const options = []
+
+    for (const parts of SPLIT_SIZES) {
+      if (parts > 1 && (!split || this.width % parts !== 0)) {
+        continue
+      }
+
+      const count = parts === 1 ? this.width : this.width / parts
+
+      if (parts > 2 && count < MIN_ROUND_PART) {
+        continue
+      }
+
+      options.push({ parts, count })
+    }
+
+    return options
+  }
+
+  /**
+   * Whether taking this cut would abandon a split the draw is already
+   * in. Its second half is a round behind its first all the way down,
+   * and going back to whole rounds would put the two halves on court
+   * together. The Final ends it: a semi split 1/1 still leads to one
+   * Final.
+   *
+   * @param {number} parts
+   * @returns {boolean}
+   */
+  breaksStride(parts) {
+    return this.lastParts > 1
+      && this.round?.round !== 'F'
+      && parts !== this.lastParts
+  }
+
+  /**
+   * Commits the round to these courts for as long as it runs. Whatever
+   * it starts on it finishes on - re-picking each slot is what had a
+   * round open on C10/C11 and close on C14/C15 an hour later.
+   *
+   * A round too wide for the day to finish pins nothing: there is no
+   * set of courts it could finish on, and pinning would only keep it
+   * off the ones that free up later.
+   *
+   * @param {Array} courts
+   */
+  pin(courts) {
+    this.roundCourts = this.roundCourts ?? courts.map(court => court.id)
+  }
+
+  /**
+   * Records matches booked, and says when the draw is next free.
+   *
+   * A split is its own rest: the half that played first has sat out
+   * every band the second half took, so no rest slot is charged on top
+   * of it.
+   *
+   * @param {Object} params
+   * @param {number} params.count How many matches were just booked.
+   * @param {number} params.parts The cut they were booked in.
+   * @param {number} params.slotIndex Where the cut started.
+   * @param {number} params.restSlots Slots owed after a whole round.
+   */
+  book({ count, parts, slotIndex, restSlots }) {
+    this.placed += count
+
+    if (this.placedInRound + count < this.width) {
+      this.placedInRound += count
+      this.freeFrom = slotIndex + parts
+
+      return
+    }
+
+    this.lastParts = parts
+    this.roundIndex += 1
+    this.placedInRound = 0
+    this.roundCourts = null
+    this.freeFrom = slotIndex + parts + (parts > 1 ? 0 : restSlots)
+  }
+}