@opndev/tennis-match-center 0.0.1

package/lib/court-bands.mjs

@@ -0,0 +1,185 @@
+// SPDX-FileCopyrightText: 2026 Wesley Schwengle <wesley@opndev.io>
+//
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+/**
+ * Shared court-layout math for every planner shape (3/4/5-team groups,
+ * knockout): divisions in priority order get a contiguous band, a
+ * fraction of the court list, so the strongest field always sits on the
+ * lowest courts and its neighbour in priority order sits beside it
+ * rather than wherever a "first free court" search happens to land it.
+ *
+ * Lifted out of five-team-planner.mjs, where this was proven against a
+ * real tournament's worth of scheduling before any other planner shape
+ * had it at all.
+ *
+ * @param {Object} params
+ * @param {Array<string|number>} params.divisions Priority order - the
+ *   strongest field first.
+ * @param {Map<string|number, number>} params.totals How many runs each
+ *   division needs across every section, keyed by division id.
+ * @param {number[]} params.capacities How many courts each section can
+ *   actually host (already filtered for lit/usable, per caller).
+ * @returns {{
+ *   quotasBySection: Array<Map<string|number, number>>,
+ *   bandsBySection: Array<Map<string|number, {start: number, end: number}>>
+ * }}
+ */
+export function computeSectionBands({ divisions, totals, capacities }) {
+  const sectionCount = capacities.length
+  const quotasBySection = []
+  const bandsBySection = []
+  const granted = new Map(divisions.map(id => [id, 0]))
+
+  for (let section = 0; section < sectionCount; section++) {
+    const quotas = new Map(divisions.map(id => [id, 0]))
+    let left = capacities[section] ?? 0
+
+    // One spot each, before anything is shared out proportionally, so a
+    // division missing from a section never leaves a group with nowhere
+    // to play.
+    for (const id of divisions) {
+      if (left <= 0) {
+        break
+      }
+
+      quotas.set(id, 1)
+      left -= 1
+    }
+
+    const runsTotal = divisions.reduce((sum, id) => sum + (totals.get(id) ?? 0), 0)
+
+    if (runsTotal > 0 && left > 0) {
+      // Largest remainder over what is left after the floors.
+      const exact = divisions.map(id => (left * (totals.get(id) ?? 0)) / runsTotal)
+
+      divisions.forEach((id, index) => {
+        quotas.set(id, quotas.get(id) + Math.floor(exact[index]))
+      })
+
+      let spare = left - exact.reduce((sum, value) => sum + Math.floor(value), 0)
+
+      const byRemainder = exact
+        .map((value, index) => ({ index, remainder: value - Math.floor(value) }))
+        .sort((a, b) => b.remainder - a.remainder)
+
+      for (const { index } of byRemainder) {
+        if (spare <= 0) {
+          break
+        }
+
+        quotas.set(divisions[index], quotas.get(divisions[index]) + 1)
+        spare -= 1
+      }
+    }
+
+    // A division may hold no more of a section than an even share of
+    // its day - otherwise one with few runs can be handed a generous
+    // quota early and be spent before later sections need it.
+    for (const id of divisions) {
+      const runs = totals.get(id) ?? 0
+      const evenShare = Math.max(1, Math.ceil(runs / sectionCount))
+
+      quotas.set(id, Math.min(quotas.get(id), evenShare))
+    }
+
+    // Every court of the section is shared out here, not left to a
+    // fallback that knows nothing about the bands - that is what
+    // scattered a division's tail runs to the end of the row.
+    const sectionsLeft = sectionCount - section - 1
+    let room = (capacities[section] ?? 0) - divisions.reduce((sum, id) => sum + quotas.get(id), 0)
+
+    const headroom = id => (totals.get(id) ?? 0) - granted.get(id) - quotas.get(id)
+
+    while (room > 0) {
+      const able = divisions.filter(id => headroom(id) > sectionsLeft)
+
+      if (able.length === 0) {
+        break
+      }
+
+      const next = able.reduce((a, b) => (headroom(b) > headroom(a) ? b : a))
+
+      quotas.set(next, quotas.get(next) + 1)
+      room -= 1
+    }
+
+    // The band a division sits in, as a fraction of the section's own
+    // courts, straight from what it was just given. Divisions come in
+    // priority order, so the strongest field takes the lowest courts
+    // and its neighbour in priority sits beside it.
+    const placed = divisions.reduce((sum, id) => sum + quotas.get(id), 0)
+    let filled = 0
+    const bands = new Map()
+
+    for (const id of divisions) {
+      granted.set(id, granted.get(id) + quotas.get(id))
+
+      const start = placed === 0 ? 0 : filled / placed
+      filled += quotas.get(id)
+      const end = placed === 0 ? 1 : filled / placed
+
+      bands.set(id, { start, end })
+    }
+
+    quotasBySection.push(quotas)
+    bandsBySection.push(bands)
+  }
+
+  return { quotasBySection, bandsBySection }
+}
+
+/**
+ * How far a court (as a fraction of its list) sits from a division's
+ * band. Zero inside the band; a band is an interval, not a point, so a
+ * court just past either edge is still closer than one at the far end
+ * of the row.
+ */
+/**
+ * Chops a day's slots into named sections - S1, S2, S3, S4 - the unit
+ * every planner shape works in, not clock times but a whole run's worth
+ * of court time (a 5-team run, a 4-team round, a knockout round). Every
+ * planner needs the same answer to "what section is this slot in, and
+ * is it played under lights" instead of working it out its own way.
+ *
+ * Only a section that can hold a whole run counts - rounding up
+ * invents a final section out of the few slots left over, and whatever
+ * gets shared out to it is then unplaceable.
+ *
+ * @param {Array} slots The day's slots for one competition, in order.
+ * @param {number} runLength How many slots one run/round occupies.
+ * @param {Object} [context]
+ * @param {Array} [context.courts] The courts these runs may use, so a
+ *   section's capacity can be reported alongside it.
+ * @param {Function} [context.usable] (court, slot) => boolean
+ * @returns {Array<{index: number, label: string, slots: Array, night: boolean, capacity: number}>}
+ */
+export function sectionsFor(slots, runLength, { courts = [], usable = () => true } = {}) {
+  const sectionCount = Math.max(1, Math.floor(slots.length / runLength))
+  const sections = []
+
+  for (let index = 0; index < sectionCount; index++) {
+    const first = index * runLength
+    const own = slots.slice(first, first + runLength)
+
+    sections.push({
+      index,
+      label: `S${index + 1}`,
+      slots: own,
+      night: own.some(slot => slot.lit_required),
+      capacity: own.length === 0
+        ? 0
+        : courts.filter(court => own.every(slot => usable(court, slot))).length,
+    })
+  }
+
+  return sections
+}
+
+export function bandDistance(position, band) {
+  if (position >= band.start && position < band.end) {
+    return 0
+  }
+
+  return Math.min(Math.abs(position - band.start), Math.abs(position - band.end))
+}

package/lib/court-runs.mjs

@@ -0,0 +1,76 @@
+// SPDX-FileCopyrightText: 2026 Wesley Schwengle <wesley@opndev.io>
+//
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+/**
+ * Whether a court can host a run of consecutive slots.
+ *
+ * Lifted out of auto-planner.mjs, where the group planner has always
+ * asked this before taking a court: a run goes on a court only when
+ * the whole run fits there, never a first slot now and the rest
+ * wherever happens to be free later.
+ */
+
+/**
+ * Whether a court may be played on in this slot at all.
+ *
+ * @param {{lit: boolean, availableFromMinutes: ?number}} court
+ * @param {{lit_required: boolean, start_minutes: number}} slot
+ * @returns {boolean}
+ */
+export function courtUsableAt(court, slot) {
+  if (slot.lit_required && !court.lit) {
+    return false
+  }
+
+  // A court opened up for the day only from a given time onward (see
+  // openCourtsFor) - baked onto the court object itself, so this needs
+  // no date of its own to enforce it.
+  const opensAt = court.availableFromMinutes
+
+  if (opensAt != null && slot.start_minutes < opensAt) {
+    return false
+  }
+
+  return true
+}
+
+/**
+ * Whether a run of runLength slots, starting at slotIndex, fits on
+ * this court end to end.
+ *
+ * @param {Object} court
+ * @param {Object} context
+ * @param {Array} context.slots The asking competition's own slots.
+ * @param {number} context.slotIndex Where the run starts.
+ * @param {string} context.date
+ * @param {Object} context.taken Occupancy (see occupancy.mjs).
+ * @param {boolean} [context.requireLit] The run must touch a lit slot.
+ * @param {number} runLength
+ * @returns {boolean}
+ */
+export function runFits(
+  court, { slots, slotIndex, date, taken, requireLit }, runLength
+) {
+  if (slotIndex + runLength > slots.length) {
+    return false
+  }
+
+  let touchesLit = false
+
+  for (let i = 0; i < runLength; i++) {
+    const slot = slots[slotIndex + i]
+
+    const vacant = taken.free(
+      date, court.id, slot.start_minutes, slot.end_minutes
+    )
+
+    if (!courtUsableAt(court, slot) || !vacant) {
+      return false
+    }
+
+    touchesLit = touchesLit || slot.lit_required
+  }
+
+  return requireLit ? touchesLit : true
+}

package/lib/day-rows.mjs

@@ -0,0 +1,116 @@
+// SPDX-FileCopyrightText: 2026 Wesley Schwengle <wesley@opndev.io>
+//
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+import { slotsForDate } from './auto-planner.mjs'
+
+/** What an hour is worth when nothing says otherwise. */
+const FALLBACK_SLOT_MINUTES = 45
+
+function timeToMinutes(time) {
+  const [hours, minutes] = String(time).split(':').map(Number)
+
+  return hours * 60 + (minutes ?? 0)
+}
+
+function minutesToTime(minutes) {
+  return `${String(Math.floor(minutes / 60)).padStart(2, '0')}`
+    + `:${String(minutes % 60).padStart(2, '0')}`
+}
+
+/**
+ * The rows one day of the grid has, in order.
+ *
+ * Competitions do not share a clock: a 90 minute tie and a 45 minute
+ * match starting the same morning sit on different hours, so a day
+ * carries each competition's own lattice rather than one grid for the
+ * event. Planning and Scheduling draw the same rows by asking here.
+ *
+ * @param {Object} params
+ * @param {string} params.date
+ * @param {Array} params.competitions Each with its own sessions.
+ * @param {Array} params.cells What is already booked that day, so a
+ *   cell is never stranded on a row the sessions no longer describe.
+ * @param {Array} [params.fallbackSlots] Used only where the day has no
+ *   session at all, so there is still something to drag onto.
+ * @returns {Array<{key: string, label: string, start_minutes: number,
+ *   end_minutes: number}>}
+ */
+export function rowsForDate({ date, competitions, cells, fallbackSlots = [] }) {
+
+  const byKey = new Map()
+
+  // Only competitions that open on this date, each on its own clock.
+  for (const competition of competitions ?? []) {
+    const sessions = [...(competition.sessions ?? [])]
+      .sort((a, b) =>
+        (a.date + a.start_time).localeCompare(b.date + b.start_time)
+      )
+
+    if (!sessions.some(session => session.date === date)) {
+      continue
+    }
+
+    // From the hour it holds a court, not the hour its session
+    // opens: the leading empty rows of a competition that waits are
+    // dropped. What follows its last cell stays.
+    const mine = cells
+      .filter(cell =>
+        cell.date === date && cell.competition_id === competition.id
+      )
+      .map(cell => cell.slot)
+      .sort()
+
+    for (const slot of slotsForDate(sessions, date, null)) {
+      if (mine.length > 0 && slot.key < mine[0]) {
+        continue
+      }
+
+      // Two competitions can open at the same minute with different
+      // playtimes. The row takes the finer of the two; a coarser
+      // competition's own cell still draws its full span.
+      const existing = byKey.get(slot.key)
+      const duration = slot.end_minutes - slot.start_minutes
+
+      const finer = existing
+        && existing.end_minutes - existing.start_minutes <= duration
+
+      if (finer) {
+        continue
+      }
+
+      byKey.set(slot.key, {
+        ...slot,
+        label: `${slot.key}-${minutesToTime(slot.end_minutes)}`,
+      })
+    }
+  }
+
+  // A day nothing is configured for still needs a grid to drag on.
+  if (byKey.size === 0) {
+    for (const slot of fallbackSlots ?? []) {
+      byKey.set(slot.key, slot)
+    }
+  }
+
+  // Whatever is already booked, so a block is never stranded on a
+  // row the sessions no longer describe - a competition whose
+  // knockout runs past the day its session opens, or a plan saved
+  // before the sessions were changed. It still needs a real span on
+  // the timeline, not just a label, so it gets one at the fallback
+  // length.
+  for (const cell of cells) {
+    if (cell.date === date && !byKey.has(cell.slot)) {
+      const start = timeToMinutes(cell.slot)
+
+      byKey.set(cell.slot, {
+        key: cell.slot,
+        label: cell.slot,
+        start_minutes: start,
+        end_minutes: start + FALLBACK_SLOT_MINUTES,
+      })
+    }
+  }
+
+  return [...byKey.values()].sort((a, b) => a.key.localeCompare(b.key))
+}

package/lib/division-hues.mjs

@@ -0,0 +1,52 @@
+// SPDX-FileCopyrightText: 2026 Wesley Schwengle <wesley@opndev.io>
+//
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+/**
+ * The angle successive divisions are spaced by, in degrees.
+ *
+ * The golden angle rather than an even split of the circle: an even
+ * split over six lands them all in the same part of the spectrum,
+ * which reads as six shades of green.
+ */
+const GOLDEN_ANGLE = 137.508
+
+/**
+ * A hue per division, in the order the competitions list them.
+ *
+ * A hue, not a colour. A board decides which divisions should look
+ * different from each other; how strongly that reads is the page's
+ * business, so the hue goes out as a custom property and the
+ * stylesheet picks saturation and lightness to suit its theme.
+ *
+ * Planning and Scheduling both draw it, from the same order, so a
+ * division a director learned the colour of on one board is that
+ * colour on the other.
+ *
+ * @param {Array<{divisions: ?Array<number|{id: number}>}>} competitions
+ * @returns {Map<number, number>}
+ */
+export function divisionHues(competitions) {
+  const divisionIds = competitions.flatMap(
+    competition => (competition.divisions ?? [])
+      .map(division => division?.id ?? division)
+  )
+
+  return new Map(
+    divisionIds.map((id, index) => [
+      id, Math.round((index * GOLDEN_ANGLE) % 360),
+    ])
+  )
+}
+
+/**
+ * The hue a competition falls back to where its divisions are not
+ * known - an even split of the circle, since there are few of them.
+ *
+ * @param {number} index
+ * @param {number} total
+ * @returns {?number}
+ */
+export function competitionHue(index, total) {
+  return index < 0 ? null : Math.round((index * 360) / Math.max(1, total))
+}

package/lib/five-team-planner.mjs

@@ -0,0 +1,21 @@
+// SPDX-FileCopyrightText: 2026 Wesley Schwengle <wesley@opndev.io>
+//
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+import { makeRunQueuePlanner } from './run-queue-planner.mjs'
+
+/**
+ * A 5-team division's group play: five teams, one court to itself, the
+ * whole ten-match round robin run off across two days as one unbroken
+ * stretch per day.
+ *
+ * This is a thin, shape-named entry point onto run-queue-planner.mjs's
+ * shared engine - see that module for how enqueue/prepare/pick/commit
+ * actually work. Kept as its own module (rather than callers reaching
+ * for makeRunQueuePlanner directly) so a 5-team competition's planner
+ * stays its own testable unit, distinct from three-team-planner.mjs's,
+ * even though today they share every line of implementation.
+ */
+export function makeFiveTeamPlanner() {
+  return makeRunQueuePlanner()
+}

package/lib/flags.mjs

@@ -0,0 +1,60 @@
+// SPDX-FileCopyrightText: 2026 Wesley Schwengle <wesley@opndev.io>
+//
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+import twemoji from '@twemoji/api'
+
+/**
+ * Writes a name, drawing the flag in front of it as an image where the
+ * platform will not draw it as a flag.
+ *
+ * Windows has no flag glyphs: a regional indicator pair renders as the
+ * two letters of the country code, so "AW Alice" where every other
+ * platform shows a flag. Parsing the emoji into Twemoji's SVG puts the
+ * flag back.
+ *
+ * @param {HTMLElement} element
+ * @param {string} value
+ * @param {string} [mode] always, never, or windows (the default):
+ *   parse only where the platform needs it.
+ * @returns {void}
+ */
+export function setNameText(element, value, mode = 'windows') {
+  element.textContent = value
+
+  if (!shouldParseFlags(mode)) {
+    return
+  }
+
+  twemoji.parse(element, { folder: 'svg', ext: '.svg' })
+}
+
+/**
+ * @param {string} mode
+ * @returns {boolean}
+ */
+export function shouldParseFlags(mode = 'windows') {
+  const setting = String(mode || 'windows').toLowerCase()
+
+  if (setting === 'always') {
+    return true
+  }
+
+  if (setting === 'never') {
+    return false
+  }
+
+  return isWindows()
+}
+
+/**
+ * @returns {boolean}
+ */
+export function isWindows() {
+  if (typeof navigator === 'undefined') {
+    return false
+  }
+
+  return Boolean(navigator.platform?.startsWith('Win'))
+    || Boolean(navigator.userAgent?.includes('Windows'))
+}