@opndev/tennis-match-center 0.0.1

package/lib/knockout-waves.mjs

@@ -0,0 +1,156 @@
+// SPDX-FileCopyrightText: 2026 Wesley Schwengle <wesley@opndev.io>
+//
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+/**
+ * How much court time a knockout draw needs, round by round, worked
+ * out from the draw itself.
+ *
+ * Planning used to be handed the answer as a list of counts by the
+ * server. It is worked out here instead, for the same reason group
+ * capacity is (see auto-planner.mjs's own note on it): the backend
+ * returns and stores the draw, and how much court time that draw
+ * needs is a question about the draw. One component owns the answer
+ * and the two can no longer disagree.
+ *
+ * A bye is the whole reason this is not just "half the field, then
+ * half again": a row with one side filled and the other empty
+ * advances a team without a game being played, so it needs no court
+ * time at all.
+ */
+
+/**
+ * Bracket rounds in play order, biggest field first - the same labels
+ * a saved bracket's rows carry.
+ */
+export const ROUND_ORDER = ['R256', 'R128', 'R64', 'R32', 'R16', 'QF', 'SF', 'F']
+
+/**
+ * The rounds of a bracket that has actually been drawn and saved.
+ *
+ * A round's name comes off its own saved rows, never from how many
+ * matches it holds: a bye-shrunk R16 (4 real matches once half its
+ * field has a bye) lands on the exact same count as a genuine QF, so
+ * a count can never say which round it is.
+ *
+ * @param {Array<{round: string, home: boolean, visitor: boolean}>} matches
+ * @returns {Array<{round: string, count: number}>}
+ */
+export function wavesFromSavedMatches(matches) {
+  const rounds = new Set()
+  const real = new Map()
+
+  for (const match of matches) {
+    rounds.add(match.round)
+
+    // Both sides filled: a real match. Both still empty: a TBD row
+    // waiting on winners, which will need its slot once they are
+    // known. Exactly one side filled: a bye, and no court time.
+    if (match.home === match.visitor) {
+      real.set(match.round, (real.get(match.round) ?? 0) + 1)
+    }
+  }
+
+  return ROUND_ORDER
+    .filter(round => rounds.has(round))
+    .map(round => ({ round, count: real.get(round) ?? 0 }))
+}
+
+/**
+ * The rounds a draw of this many entrants will need, before one has
+ * been drawn.
+ *
+ * The draw is the next power of two at or above the entrant count, and
+ * the gap is byes. Only the first round is short of half the draw -
+ * every team with a bye is through to round two without playing, so
+ * round two onward is the plain halving sequence.
+ *
+ * @param {number} entrants
+ * @returns {Array<{round: string, count: number}>}
+ */
+export function wavesForEntrants(entrants) {
+  if (entrants <= 1) {
+    return []
+  }
+
+  const half = nextPowerOfTwo(entrants) / 2
+  const counts = []
+
+  for (let matches = half; matches >= 1; matches /= 2) {
+    counts.push(matches)
+  }
+
+  // Round one, minus the byes.
+  counts[0] = entrants - half
+
+  // A draw that has not been drawn yet is exactly the canonical
+  // halving sequence by construction, so here - unlike a saved
+  // bracket's possibly bye-shrunk rounds - a round's name can be read
+  // off its position. Both lists end at the Final, so a count's name
+  // is whichever ROUND_ORDER entry sits the same distance from the end.
+  const offset = ROUND_ORDER.length - counts.length
+
+  return counts.map((count, index) => ({ round: ROUND_ORDER[offset + index], count }))
+}
+
+/**
+ * A division's knockout rounds: off its saved bracket where it has
+ * one, and off its roster where it does not.
+ *
+ * Once a real bracket exists, the estimate gets out of the way rather
+ * than keep reserving capacity for a shape that is not what was saved.
+ *
+ * @param {Object} division
+ * @param {Array<{round: string, home: boolean, visitor: boolean}>} [division.knockout_matches]
+ * @param {number} [division.team_count] Eligible teams on its roster.
+ * @param {number} [division.group_size] Teams to a group.
+ * @param {number} [division.advance_per_group] How many each group sends on.
+ * @param {Object} [options]
+ * @param {boolean} [options.itf] An ITF division plays no group stage:
+ *   every eligible team enters the draw directly.
+ * @returns {Array<{round: string, count: number}>}
+ */
+export function wavesForDivision(division, { itf = false } = {}) {
+  const saved = division.knockout_matches ?? []
+
+  if (saved.length > 0) {
+    return wavesFromSavedMatches(saved)
+  }
+
+  return wavesForEntrants(entrantsFor(division, { itf }))
+}
+
+/**
+ * How many teams reach the draw: every eligible team for an ITF
+ * division, and however many its groups send on for anyone else.
+ */
+export function entrantsFor(division, { itf = false } = {}) {
+  const teams = division.team_count ?? 0
+
+  if (teams === 0) {
+    return 0
+  }
+
+  if (itf) {
+    return teams
+  }
+
+  const groupSize = division.group_size ?? 0
+  const advancing = division.advance_per_group ?? 0
+
+  if (groupSize <= 0 || advancing <= 0) {
+    return 0
+  }
+
+  return Math.ceil(teams / groupSize) * advancing
+}
+
+function nextPowerOfTwo(n) {
+  let value = 1
+
+  while (value < n) {
+    value *= 2
+  }
+
+  return value
+}

package/lib/lighting.mjs

@@ -0,0 +1,50 @@
+// SPDX-FileCopyrightText: 2026 Wesley Schwengle <wesley@opndev.io>
+//
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+/**
+ * A slot needs a lit court when the match played in it ENDS after
+ * dark, not when it starts after some fixed clock time. That
+ * distinction is what keeps the rule general across competitions: a
+ * group can only use an unlit court if its whole section finishes
+ * before dark, so with 45-minute slots and dark at 18:00 a 5-team
+ * competition (5-match, 3h45 sections) runs out of unlit capacity at
+ * 15:30 while a 4-team one (3-match, 2h15 sections) keeps going until
+ * 17:00 - same courts, same lights, different boundary, both derived
+ * rather than configured.
+ *
+ * The backend sends raw times only and passes dark-from as an
+ * attribute on the element; deciding what that means for a court is a
+ * scheduling decision and belongs client-side (spec.md).
+ *
+ * @param {{slots: Array<{end_minutes?: number}>}} state
+ * @param {string} [darkFromTime] "HH:MM"
+ * @returns {Object} the same state, its slots carrying lit_required
+ */
+export function withLitRequired(state, darkFromTime) {
+  if (!state?.slots) {
+    return state
+  }
+
+  const darkFrom = toMinutes(darkFromTime)
+
+  return {
+    ...state,
+    slots: state.slots.map(slot => ({
+      ...slot,
+      lit_required: darkFrom == null || slot.end_minutes == null
+        ? slot.lit_required ?? false
+        : slot.end_minutes > darkFrom,
+    })),
+  }
+}
+
+function toMinutes(time) {
+  if (typeof time !== 'string') {
+    return null
+  }
+
+  const [hours, minutes] = time.split(':').map(Number)
+
+  return Number.isFinite(hours) ? hours * 60 + (Number.isFinite(minutes) ? minutes : 0) : null
+}

package/lib/match-time.mjs

@@ -0,0 +1,13 @@
+// SPDX-FileCopyrightText: 2026 Wesley Schwengle <wesley@opndev.io>
+//
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+/**
+ * How long a match takes, and how long a team is owed between two of
+ * its own - the two figures every planner shape measures its slots
+ * against. Shared so the group side and the knockout side cannot drift
+ * apart on what a match costs.
+ */
+export const MATCH_MINUTES = 45
+
+export const REST_MINUTES = 45

package/lib/occupancy.mjs

@@ -0,0 +1,74 @@
+// SPDX-FileCopyrightText: 2026 Wesley Schwengle <wesley@opndev.io>
+//
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+/**
+ * Which courts are busy, and when.
+ *
+ * Held as real time spans rather than cells of a grid: competitions do
+ * not share a clock - one runs 45-minute matches from 08:00, another
+ * 90-minute ones from 09:00 - and no single grid holds both. The only
+ * question worth asking is whether a court is already occupied for the
+ * stretch being asked about.
+ *
+ * Shared by both planners so neither can double-book what the other
+ * has taken.
+ */
+export function makeOccupancy() {
+  const spans = new Map()
+
+  const key = (date, courtId) => `${date}|${courtId}`
+
+  return {
+    free(date, courtId, start, end) {
+      const taken = spans.get(key(date, courtId))
+
+      return !taken?.some(([from, to]) => start < to && from < end)
+    },
+
+    /**
+     * Whether a court is free for every one of these slots.
+     */
+    freeFor(date, courtId, slots) {
+      return slots.every(slot => this.free(date, courtId, slot.start_minutes, slot.end_minutes))
+    },
+
+    take(date, courtId, start, end) {
+      const id = key(date, courtId)
+
+      if (!spans.has(id)) {
+        spans.set(id, [])
+      }
+
+      spans.get(id).push([start, end])
+    },
+  }
+}
+
+/**
+ * Whether a court can host a stretch of play.
+ *
+ * Lighting is a question about the whole stretch, not the individual
+ * match: a run reaching past dark needs a lit court from its first
+ * match, because everyone on court at the same time plays in the same
+ * conditions.
+ */
+export function courtCanHost(court, slots, darkFromMinutes) {
+  if (!court.active) {
+    return false
+  }
+
+  // A court a director has opened up for the day only from a given
+  // time onward (auto-planner.mjs's openCourtsFor) - baked onto the
+  // court object itself, so this needs no date of its own to enforce.
+  if (court.availableFromMinutes != null
+    && slots.some(slot => slot.start_minutes < court.availableFromMinutes)) {
+    return false
+  }
+
+  if (darkFromMinutes == null || court.lit) {
+    return true
+  }
+
+  return slots.every(slot => slot.end_minutes <= darkFromMinutes)
+}

package/lib/paired-court-planner.mjs

@@ -0,0 +1,236 @@
+// SPDX-FileCopyrightText: 2026 Wesley Schwengle <wesley@opndev.io>
+//
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+import { courtCanHost } from './occupancy.mjs'
+
+/**
+ * Plans any group shape whose round robin needs more than one court at
+ * once, courtsPerRound of them, all bundled groups taking their turn
+ * on the same set before handing it to the next: 4-team's three rounds
+ * of two matches is the shape this was written for, but the same
+ * mechanism gives a 3-team group (courtsPerRound 1 - it never needs a
+ * second court, but still bundles with another 3-team group so each
+ * gets a rest between its own matches instead of playing straight
+ * through alone) the same courts, the same rest, the same priority
+ * order, as 4-team - see three-team-planner.mjs.
+ *
+ *   courtsPerRound 2 (4-team):        courtsPerRound 1 (3-team):
+ *   1: A v B   C v D                  1: A v B
+ *   2: A v B   C v D                  1: C v D
+ *   1: A v C   B v D                  2: A v B
+ *   ...                               2: C v D
+ *                                     ...
+ *
+ * That waiting is the whole reason to bundle: alone, a group's own
+ * round robin runs its matches back to back with no rest between a
+ * team's own appearances. Bundled with another group of the same
+ * shape, they take turns - one court (or courtsPerRound of them) a
+ * turn - so a team gets the other group's turn to rest through.
+ *
+ * TODO: 4-team and 5-team should both be able to choose courtsPerRound
+ * explicitly (a division opting into "pairs" plays its round robin
+ * across 2 courts for the rest that gives; opting out runs the whole
+ * thing on one, the run-queue-planner.mjs way) rather than 4-team
+ * being hardcoded to 2 and 5-team's engine never touching this module
+ * at all. Not built yet - flagged here so the two do not drift apart
+ * when it is.
+ */
+
+/**
+ * Lays out a set of same-shape groups sharing courtsPerRound courts at
+ * once.
+ *
+ * Groups take turns: every group's first round, then every group's
+ * second, and so on - nothing sits idle, and a group waits out as many
+ * slots between its own rounds as there are other groups in the unit.
+ *
+ * @param {Array<{id: number, teamIds: number[]}>} groups
+ * @param {Object} params
+ * @param {Array<{slot: number, pairs: number[][]}>} params.template The
+ *   group shape's own round robin, one entry per round - see
+ *   group-schedule.mjs's GROUP_TEMPLATES and four-team-planner.mjs's
+ *   FOUR_TEAM_TEMPLATE. A round's pairs.length is courtsPerRound.
+ * @param {(group: {id: number, teamIds: number[]}) => Array<{slot: number, pairIndex: number, index: number}>} params.matchesFor
+ *   A group's own matches, flattened and indexed in play order.
+ * @returns {Array<Array<{groupId: number, index: number}|null>>} slot by court
+ */
+export function unitLayout(groups, { template, matchesFor }) {
+  const slots = []
+
+  for (const round of template) {
+    // What each group actually plays this round: courtsPerRound
+    // matches, or fewer where a vacant seat leaves one empty.
+    const turns = groups
+      .map(group => {
+        const matches = matchesFor(group)
+
+        return round.pairs
+          .map((pair, pairIndex) => {
+            const index = matches.findIndex(
+              match => match.slot === round.slot && match.pairIndex === pairIndex
+            )
+
+            return index === -1 ? null : { groupId: group.id, index }
+          })
+          .filter(Boolean)
+      })
+      .filter(turn => turn.length > 0)
+
+    // One turn to a slot, so groups take it in turns rather than all
+    // at once - the rest the bundling exists for.
+    for (const turn of turns) {
+      slots.push(round.pairs.map((_, courtIndex) => turn[courtIndex] ?? null))
+    }
+  }
+
+  return slots
+}
+
+/**
+ * Places an already-computed layout (see unitLayout) onto the lowest
+ * stretch of courts that is actually free, and the earliest start on
+ * it - no bands, no reservation.
+ *
+ * Split out from placeUnit so a caller that needs to place only part
+ * of a unit's layout - auto-planner.mjs cuts a unit's sequence in half
+ * across two days when its dates span two of them - can reuse this
+ * search directly instead of reimplementing it.
+ *
+ * A unit only ever needs as many courts as some row of the layout
+ * actually uses - a unit of nothing but byes never has two matches at
+ * once, and searching for courtsPerRound of them would strand a
+ * perfectly usable neighbouring court idle beside every one of its
+ * slots for no reason.
+ *
+ * @param {Array<Array<{groupId: number, index: number}|null>>} layout
+ * @param {(groupId: number) => {id, competitionId, divisionId, divisionName, divisionGender, groupName}} lookup
+ */
+export function placeLayout({ layout, lookup, courts, slots, date, occupancy, darkFrom, blocks }) {
+  if (layout.length === 0) {
+    return false
+  }
+
+  const width = Math.max(1, ...layout.map(row => row.filter(Boolean).length))
+
+  for (let start = 0; start + layout.length <= slots.length; start++) {
+    const window = slots.slice(start, start + layout.length)
+
+    // Neighbours among the courts that can actually host this window,
+    // not among the courts as they are numbered. An unlit court in the
+    // middle of the row would otherwise strand the court beside it: a
+    // pair needs two, and if one of them can never host the run the
+    // other is never offered to anybody.
+    const eligible = courts.filter(court => courtCanHost(court, window, darkFrom))
+
+    for (let index = 0; index + width <= eligible.length; index++) {
+      const set = eligible.slice(index, index + width)
+
+      const usable = set.every(court =>
+        occupancy.freeFor(date, court.id, window)
+      )
+
+      if (!usable) {
+        continue
+      }
+
+      layout.forEach((row, offset) => {
+        row.forEach((cell, courtIndex) => {
+          if (!cell) {
+            return
+          }
+
+          const group = lookup(cell.groupId)
+          const court = set[courtIndex]
+          const slot = window[offset]
+
+          blocks.push({
+            competition_id: group.competitionId,
+            division_id: group.divisionId ?? null,
+            division_name: group.divisionName ?? null,
+            division_gender: group.divisionGender ?? null,
+            group_id: group.id,
+            group_name: group.groupName ?? null,
+            phase: 'group',
+            round: 'group',
+            match_slot: cell.index,
+            court_id: court.id,
+            date,
+            slot: slot.key,
+            short_group: true,
+          })
+
+          occupancy.take(date, court.id, slot.start_minutes, slot.end_minutes)
+        })
+      })
+
+      return true
+    }
+  }
+
+  return false
+}
+
+/**
+ * How a set of same-shape groups is split into units sharing courts.
+ *
+ * Units of two are the default: a shorter window drops into the light
+ * where a unit of three will not. What decides the split is parity
+ * rather than 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.
+ *
+ *   7 groups -> 3, 2, 2      9 groups -> 3, 2, 2, 2
+ *
+ * When courts are scarce the same no-leftovers rule is applied the
+ * other way round, taking as many threes as possible to hold fewer at
+ * once:
+ *
+ *   7 groups -> 3, 2, 2      9 groups -> 3, 3, 3
+ *
+ * @param {number} count
+ * @param {{dense?: boolean}} options
+ * @returns {number[]} unit sizes, largest first
+ */
+export function unitSizes(count, { dense = false } = {}) {
+  if (count < 2) {
+    // Nothing to share with. The caller decides what to do with it
+    // rather than being handed a unit of one.
+    return []
+  }
+
+  if (!dense) {
+    const threes = count % 2 === 0 ? 0 : 1
+    return sizes(threes, (count - threes * 3) / 2)
+  }
+
+  // As many threes as fit without stranding a single group: a
+  // remainder of one means dropping back a three to leave four, which
+  // pairs off.
+  let threes = Math.floor(count / 3)
+
+  if (count - threes * 3 === 1) {
+    threes -= 1
+  }
+
+  return sizes(threes, (count - threes * 3) / 2)
+}
+
+function sizes(threes, twos) {
+  return [...Array(threes).fill(3), ...Array(twos).fill(2)]
+}
+
+/**
+ * Splits a set of same-shape groups into units sharing a court set.
+ */
+export function buildUnits(groups, { dense = false } = {}) {
+  const units = []
+  let cursor = 0
+
+  for (const size of unitSizes(groups.length, { dense })) {
+    units.push(groups.slice(cursor, cursor + size))
+    cursor += size
+  }
+
+  return units
+}