@opndev/tennis-match-center 0.0.1

package/lib/components/planning-board.mjs

@@ -0,0 +1,1179 @@
+// SPDX-FileCopyrightText: 2026 Wesley Schwengle <wesley@opndev.io>
+//
+// SPDX-License-Identifier: AGPL-3.0-or-later
+
+import { HTMLElementSugar } from '@skirbi/sugar'
+import { withLitRequired } from '../lighting.mjs'
+import { autoFillPlanning, activeSession } from '../auto-planner.mjs'
+import { rowsForDate } from '../day-rows.mjs'
+import { withBusyButton } from '../busy-button.mjs'
+import { competitionHue, divisionHues } from '../division-hues.mjs'
+
+const SAVING = { busy: 'Saving…', done: 'Saved', failed: 'Save failed' }
+
+// A row's fallback length when a booked block's slot no longer matches
+// any configured session (spec.md never promises one) - just enough to
+// give it a real height on the timeline rather than none at all.
+const FALLBACK_SLOT_MINUTES = 45
+
+// Pixels per minute of real time on the timeline. A 45-minute slot -
+// the shortest common match length - needs room for four lines
+// (competition, division, group, round) plus padding, not just the
+// one or two a bare label used to need.
+const PX_PER_MINUTE = 64 / 45
+
+/**
+ * <tennis-planning-board api="..." save-api="...">
+ *
+ * The Scheduling grid - "Group Stage Scheduling" / "Time Slots" in
+ * spec.md: one tab per day, one grid per day, drawn to scale like a
+ * Google Calendar day view - courts are columns, and each slot is
+ * positioned/sized from its own real start/end minutes rather than a
+ * uniform row, so competitions on different clocks (45-minute matches
+ * from 08:00 next to 90-minute ones from 09:00) still line up by
+ * actual time (see rowsFor/dayRangeFor). A court can only ever host
+ * one match in a given hour, group or knockout, so there is exactly
+ * one grid to avoid double-booking across phases. Excel-style range
+ * selection:
+ * click-drag across a block of cells, then click a competition in the
+ * legend to assign that whole block at once. A competition's
+ * divisions share whatever capacity it's given; we don't schedule at
+ * division granularity. Only ever mutates the in-browser copy until
+ * Save is pressed.
+ *
+ * Which competitions are offered in a given day's legend is driven by
+ * the API's per-competition group_dates/knockout_dates (computed
+ * server-side from the competition's start_date/end_date - see
+ * MatchDayPlanningController): a competition only shows up on the
+ * days it's actually relevant to, and the legend already knows which
+ * phase (group or knockout) applies on that day, so a click just
+ * assigns the current selection to that competition+phase.
+ *
+ * Each competition's games_needed (from the API, assuming full
+ * groups), split by phase, is shown next to the phase that's active
+ * that day so the director can judge how much capacity a competition
+ * still needs, without this component knowing anything about how
+ * that number is computed.
+ *
+ * "Auto-fill from sessions" (auto-planner.mjs) replaces the whole
+ * grid with an automated allocation driven by each competition's
+ * configured CompetitionSession rows, instead of a director
+ * click-dragging every cell by hand - the manual tools above still
+ * work afterward to touch up the result.
+ *
+ * Day tabs are built as a <semtic-tabbed> subtree entirely in memory
+ * and inserted in one shot: that component only ever looks at its
+ * <semtic-tab> children once, in its own connectedCallback, so they
+ * all have to already exist by the time it's connected - there's no
+ * "add another day later" once it's live.
+ */
+export class TennisPlanningBoardElement extends HTMLElementSugar {
+  static tag = 'tennis-planning-board'
+  static renderGuardSelector = '[data-schedule]'
+
+  static attributeDefs = {
+    'shell-api': {},
+    'competitions-api': {},
+    'save-api': {},
+    'csrf-token': {},
+    'dark-from': {},
+
+    // The last hour anything may start. A knockout draw that cannot
+    // finish under it is laid out again with its rounds broken into
+    // equal parts rather than allowed to run into the small hours or
+    // spill onto the next morning - see auto-planner.mjs's own retry.
+    'day-end': {},
+  }
+
+  static HtmlTemplate = ['tennis-planning-board-template', function () {
+    return this.tpl(`
+      <div>
+        <p data-status>Loading…</p>
+        <button data-auto-fill type="button" hidden>Auto-fill from sessions</button>
+        <label data-registration hidden>
+          <input data-registration-closed type="checkbox">
+          Registration closed
+        </label>
+        <label data-always-bye hidden>
+          <input data-always-bye-short-groups type="checkbox">
+          Always give a short group its bye
+        </label>
+        <p data-short-groups hidden></p>
+        <p data-auto-fill-shortfall hidden></p>
+        <p data-auto-fill-warnings hidden></p>
+        <button data-clear-all type="button" hidden>Clear planning (all)</button>
+        <button data-clear-day type="button" hidden>Clear planning (day)</button>
+        <label data-view-toggle hidden>
+          <input data-show-data type="checkbox">
+          Show data
+        </label>
+        <pre data-plan hidden></pre>
+        <div data-schedule hidden></div>
+        <button data-save type="button" hidden>Save planning</button>
+      </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-save]').addEventListener('click', () => this.save())
+      this.$('[data-auto-fill]').addEventListener('click', () => this.autoFill())
+      // Config for whatever Auto-fill computes next, not a trigger of
+      // their own - a director flips one of these deliberately, then
+      // presses Auto-fill when ready, not the moment they change their
+      // mind about it. render() still reflects the new choice in the
+      // short-groups status line immediately, without recomputing or
+      // replacing the grid.
+      this.$('[data-registration-closed]').addEventListener('change', () => this.render())
+      this.$('[data-always-bye-short-groups]').addEventListener('change', () => this.render())
+      this.$('[data-show-data]').addEventListener('change', () => this.render())
+      this.$('[data-clear-all]').addEventListener('click', () => this.clearAll())
+      this.$('[data-clear-day]').addEventListener('click', () => {
+        const activeDate = this.$('[data-schedule] semtic-tabbed')?.getAttribute('current')
+        this.clearDay(activeDate)
+      })
+
+      // Bound on window, not this element, so releasing the mouse
+      // outside the grid (a very normal thing to do mid-drag) still
+      // ends the selection instead of leaving it stuck "selecting".
+      window.addEventListener('mouseup', () => {
+        this.isSelecting = false
+      })
+
+      // Backspace/Delete clears the current selection - the same
+      // action as clicking "Clear selection" in the legend, just
+      // faster for a director working through a lot of cells.
+      window.addEventListener('keydown', event => {
+        if (event.key !== 'Backspace' && event.key !== 'Delete') {
+          return
+        }
+
+        if (!this.selectionDate || this.selection.size === 0) {
+          return
+        }
+
+        event.preventDefault()
+        this.assignSelection(null)
+      })
+    }
+
+    // The shell (courts/days/slots/the already-saved plan) is plain
+    // queries - fast regardless of event size - so it renders the
+    // real grid immediately. competitions-api is the expensive part
+    // (GameCounter runs per division) and is never let hold up that
+    // first paint - on a slow connection especially, a grid that
+    // shows up while the legend is still catching up reads as "busy",
+    // not "broken", the way one long blank "Loading..." does.
+    const shellApplied = await this.fetchShell()
+
+    if (!shellApplied) {
+      return
+    }
+
+    this.blocks = this.state.blocks.map(block => ({ ...block }))
+    this.selection = new Set()
+    this.selectionDate = null
+    this.isSelecting = false
+
+    this.render()
+
+    await this.fetchCompetitions()
+    this.render()
+  }
+
+  /**
+   * @returns {Promise<boolean>} false if a newer fetch has since
+   *   started and this one's result must be discarded.
+   */
+  async fetchShell() {
+    const data = await this.fetchJSON(this.getConfig()['shell-api'])
+
+    if (!data) {
+      return false
+    }
+
+    this.state = withLitRequired({ ...data, competitions: [] }, this.getConfig()['dark-from'])
+    this._divisionHues = null
+
+    return true
+  }
+
+  /**
+   * Re-fetches competitions-api and replaces this.state.competitions -
+   * the competitions/groups config (pairing, pool_size, sessions, ...)
+   * a director just changed on another page (Competitions), not only
+   * whatever was current on the last fetch. Without this, "Auto-fill"
+   * kept computing against whatever config was current when Planning
+   * was last opened (or last auto-filled), and picking up a changed
+   * pairing meant reloading the whole page. Only this, the expensive
+   * half, needs re-fetching for that - the grid shell it's layered
+   * onto (courts, days, slots) does not change from a pairing edit.
+   *
+   * @returns {Promise<boolean>} false if a newer fetch has since
+   *   started and this one's result must be discarded.
+   */
+  async fetchCompetitions() {
+    const data = await this.fetchJSON(this.getConfig()['competitions-api'])
+
+    if (!data) {
+      return false
+    }
+
+    this.state.competitions = data.competitions
+    this._divisionHues = null
+
+    return true
+  }
+
+  /**
+   * Shared double-connect/stale-request guard: only the result of the
+   * most recently started fetch (shell or competitions, whichever)
+   * is ever allowed to apply - an earlier one resolving after a newer
+   * fetch has already started returns null instead.
+   */
+  async fetchJSON(url) {
+    const requestId = (this._fetchGeneration = (this._fetchGeneration ?? 0) + 1)
+
+    const response = await fetch(url, {
+      headers: { Accept: 'application/json' },
+    })
+
+    const data = await response.json()
+
+    return requestId === this._fetchGeneration ? data : null
+  }
+
+  /**
+   * Competitions relevant to one day, each tagged with the phase that
+   * applies on that day - group_dates and knockout_dates for the same
+   * competition never overlap, so at most one entry per competition.
+   */
+  competitionsForDate(date) {
+    const entries = []
+
+    for (const competition of this.state.competitions) {
+      if (competition.group_dates.includes(date)) {
+        entries.push({ competition, phase: 'group' })
+      }
+      if (competition.knockout_dates.includes(date)) {
+        entries.push({ competition, phase: 'knockout' })
+      }
+    }
+
+    return entries
+  }
+
+  blockAt(courtId, date, slot) {
+    return this.blocks.find(block =>
+      block.court_id === courtId && block.date === date && block.slot === slot
+    )
+  }
+
+  isSelectable(court, slot) {
+    // A physical impossibility, not a soft preference - spec.md: "a
+    // non-lit court cannot be assigned to the evening slot".
+    return !(slot.lit_required && !court.lit)
+  }
+
+  cellKey(row, col) {
+    return `${row},${col}`
+  }
+
+  startSelection(date, row, col) {
+    // A fresh day's grid always starts a fresh selection - dragging
+    // never spans two days, since they're on different tabs and can't
+    // both be visible to drag across in the first place.
+    if (date !== this.selectionDate) {
+      this.selection = new Set()
+    }
+
+    this.selectionDate = date
+    this.isSelecting = true
+    this.selectionAnchor = { row, col }
+    this.updateSelection(row, col)
+  }
+
+  updateSelection(row, col) {
+    if (!this.selectionAnchor) {
+      return
+    }
+
+    const rowMin = Math.min(this.selectionAnchor.row, row)
+    const rowMax = Math.max(this.selectionAnchor.row, row)
+    const colMin = Math.min(this.selectionAnchor.col, col)
+    const colMax = Math.max(this.selectionAnchor.col, col)
+
+    const selection = new Set()
+
+    // Rows follow what is actually drawn for the day, not the
+    // standing slot list - they are no longer the same thing.
+    const rows = this.rowsFor(this.selectionDate)
+
+    for (let r = rowMin; r <= rowMax; r++) {
+      for (let c = colMin; c <= colMax; c++) {
+        const court = this.state.courts[c]
+        const slot = rows[r]
+
+        if (this.isSelectable(court, slot)) {
+          selection.add(this.cellKey(r, c))
+        }
+      }
+    }
+
+    this.selection = selection
+    this.paintSelection()
+  }
+
+  /**
+   * Toggles the visual selected state directly, without rebuilding the
+   * grid, so a drag-select stays smooth even on a large tournament's
+   * worth of cells. Scoped to the active day only.
+   */
+  paintSelection() {
+    const day = this.$(`planning-day[data-day="${this.selectionDate}"]`)
+
+    if (!day) {
+      return
+    }
+
+    for (const slot of day.querySelectorAll('planning-slot[data-row]')) {
+      const key = this.cellKey(Number(slot.dataset.row), Number(slot.dataset.col))
+      slot.toggleAttribute('data-selected', this.selection.has(key))
+    }
+  }
+
+  /**
+   * Assigns (or, with competitionId null, clears) every cell in the
+   * current selection at once - the actual "Excel blob" action. The
+   * phase comes from whichever legend entry was clicked (a
+   * competition can only have one applicable phase on a given day).
+   */
+  assignSelection(competitionId, phase) {
+    if (!this.selectionDate || this.selection.size === 0) {
+      return
+    }
+
+    const rows = this.rowsFor(this.selectionDate)
+
+    for (const key of this.selection) {
+      const [row, col] = key.split(',').map(Number)
+      const court = this.state.courts[col]
+      const slot = rows[row]
+
+      this.blocks = this.blocks.filter(block =>
+        !(block.court_id === court.id && block.date === this.selectionDate && block.slot === slot.key)
+      )
+
+      if (competitionId) {
+        this.blocks.push({
+          id: null,
+          court_id: court.id,
+          date: this.selectionDate,
+          slot: slot.key,
+          phase,
+          competition_id: competitionId,
+        })
+      }
+    }
+
+    this.dispatchEvent(new CustomEvent('tennis-planning:changed', {
+      bubbles: true,
+      detail: { blocks: this.blocks },
+    }))
+
+    this.selection = new Set()
+    this.render()
+  }
+
+  /**
+   * How many one-hour matches are currently scheduled for a
+   * competition in the given phase, so the legend can show
+   * "scheduled X" next to its games_needed for that phase.
+   */
+  scheduledGames(competitionId, phase) {
+    return this.blocks.filter(block => block.competition_id === competitionId && block.phase === phase).length
+  }
+
+  /**
+   * Replaces the whole grid with an automated allocation driven by
+   * each competition's configured sessions (see auto-planner.mjs) -
+   * only ever mutates the in-browser copy, same as a manual
+   * assignment; Save still has to be pressed to persist it. A
+   * competition with no sessions configured is silently skipped by
+   * the algorithm (nothing to say when it should start), not reported
+   * as a shortfall.
+   */
+  /**
+   * Whether the rosters are final.
+   *
+   * While registration is open a group that looks short may still fill
+   * from the waitlist, so planning holds a full run for it. Once it is
+   * closed the short groups are real, and they are pooled onto shared
+   * court pairs instead.
+   */
+  registrationClosed() {
+    return this.$('[data-registration-closed]')?.checked ?? false
+  }
+
+  /**
+   * A director's explicit departure from that default: keep giving a
+   * short group its bye - held as a full run of its division's
+   * configured size - even once registration is closed, rather than
+   * ever pooling it with other short groups.
+   */
+  alwaysByeShortGroups() {
+    return this.$('[data-always-bye-short-groups]')?.checked ?? false
+  }
+
+  /**
+   * The groups that will be pooled rather than given a court of their
+   * own. Worth saying out loud: they are the ones a director can still
+   * fill from the waitlist.
+   */
+  shortGroups() {
+    return this.state.competitions.flatMap(competition =>
+      (competition.groups ?? []).filter(
+        group => (group.team_count ?? 0) === 4 && group.pool_size === 5
+      )
+    )
+  }
+
+  /**
+   * Re-fetches the competitions/groups config before computing, so a
+   * pairing (or any other config) changed on the Competitions page
+   * just before clicking this is what actually gets planned against -
+   * not whatever was current when this page happened to load.
+   */
+  async autoFill() {
+    // fetchCompetitions()'s own round trip plus the fill itself is
+    // real, visible time on a plan this size - a click that changes
+    // nothing on screen until it's done reads as broken, not busy.
+    const button = this.$('[data-auto-fill]')
+    const label = button.textContent
+    button.disabled = true
+    button.textContent = 'Auto-filling…'
+
+    try {
+      const applied = await this.fetchCompetitions()
+
+      if (!applied) {
+        return
+      }
+
+      const { blocks, shortfall, warnings } = autoFillPlanning({
+        courts: this.state.courts,
+        slots: this.state.slots,
+        days: this.state.days,
+        competitions: this.state.competitions,
+        registrationClosed: this.registrationClosed(),
+        alwaysByeShortGroups: this.alwaysByeShortGroups(),
+        courtOverrides: this.state.court_overrides ?? [],
+
+        // Group play follows each competition's own session, so a
+        // competition starting at 09:00 starts at 09:00. The list is
+        // still passed because the knockout pass has not been moved
+        // over yet and would otherwise have no slots at all.
+        groupSlotsFromSessions: true,
+        darkFrom: this.getConfig()['dark-from'],
+        dayEnd: this.getConfig()['day-end'] || undefined,
+      })
+
+      this.blocks = blocks
+      this.lastAutoFillShortfall = shortfall
+      this.lastAutoFillWarnings = warnings
+      this.selection = new Set()
+
+      const short = this.shortGroups()
+
+      if (short.length > 0) {
+        this.dispatchEvent(new CustomEvent('tennis-planning:short-groups', {
+          bubbles: true,
+          detail: { groups: short, closed: this.registrationClosed() },
+        }))
+      }
+
+      this.dispatchEvent(new CustomEvent('tennis-planning:changed', {
+        bubbles: true,
+        detail: { blocks: this.blocks },
+      }))
+
+      this.render()
+    }
+    finally {
+      button.disabled = false
+      button.textContent = label
+    }
+  }
+
+  /**
+   * Empties the whole grid - only ever mutates the in-browser copy
+   * until Save is pressed, same as any other change here.
+   */
+  clearAll() {
+    this.blocks = []
+    this.selection = new Set()
+    this.lastAutoFillShortfall = null
+    this.lastAutoFillWarnings = null
+
+    this.dispatchEvent(new CustomEvent('tennis-planning:changed', {
+      bubbles: true,
+      detail: { blocks: this.blocks },
+    }))
+
+    this.render()
+  }
+
+  /**
+   * Empties just the currently active day tab's cells, leaving every
+   * other day untouched.
+   */
+  clearDay(date) {
+    if (!date) {
+      return
+    }
+
+    this.blocks = this.blocks.filter(block => block.date !== date)
+    this.selection = new Set()
+
+    this.dispatchEvent(new CustomEvent('tennis-planning:changed', {
+      bubbles: true,
+      detail: { blocks: this.blocks },
+    }))
+
+    this.render()
+  }
+
+  render() {
+    this.$('[data-status]').hidden = true
+    this.$('[data-auto-fill]').hidden = false
+    this.$('[data-clear-all]').hidden = false
+    this.$('[data-clear-day]').hidden = false
+    this.$('[data-schedule]').hidden = false
+    this.$('[data-save]').hidden = false
+    this.$('[data-registration]').hidden = false
+    this.$('[data-always-bye]').hidden = false
+    this.$('[data-view-toggle]').hidden = false
+
+    // The plan as data, for reading rather than looking at.
+    const showData = this.$('[data-show-data]').checked
+    const plan = this.$('[data-plan]')
+
+    plan.hidden = !showData
+    this.$('[data-schedule]').hidden = showData
+
+    if (showData) {
+      plan.textContent = JSON.stringify(this.planData(), null, 2)
+      return
+    }
+
+    // Short groups are worth naming on the board, not just in a toast
+    // that scrolls away: they are the ones a director can still fill
+    // from the waitlist.
+    const short = this.shortGroups()
+    const shortEl = this.$('[data-short-groups]')
+
+    if (short.length > 0) {
+      shortEl.hidden = false
+      shortEl.textContent = this.registrationClosed() && !this.alwaysByeShortGroups()
+        ? `${short.length} group(s) short their 5th team - now pooled together, registration is closed`
+        : this.alwaysByeShortGroups()
+          ? `${short.length} group(s) short their 5th team - kept their own court regardless`
+          : `${short.length} group(s) short their 5th team - held a court each in case the waitlist fills them`
+    } else {
+      shortEl.hidden = true
+    }
+
+    const shortfallEl = this.$('[data-auto-fill-shortfall]')
+    if (this.lastAutoFillShortfall?.length) {
+      shortfallEl.hidden = false
+      shortfallEl.textContent = this.lastAutoFillShortfall
+        .map(({ competition_id: competitionId, phase, missing }) => {
+          const name = this.state.competitions.find(c => c.id === competitionId)?.name ?? `#${competitionId}`
+          return `${name} (${phase}): ${missing} cells short`
+        })
+        .join(' · ')
+    } else {
+      shortfallEl.hidden = true
+    }
+
+    // What the plan could not honour, or had to guess. A plan that
+    // quietly does something other than what it was set up to do is
+    // the hardest kind of wrong to spot, so it says so here rather
+    // than leaving it to be read off the grid hour by hour.
+    const warningsEl = this.$('[data-auto-fill-warnings]')
+
+    if (this.lastAutoFillWarnings?.length) {
+      warningsEl.hidden = false
+      warningsEl.textContent = this.lastAutoFillWarnings
+        .map(warning => {
+          const name = this.state.competitions
+            .find(c => c.id === warning.competition_id)?.name ?? `#${warning.competition_id}`
+
+          if (warning.kind === 'no-template') {
+            return `${name}: ${warning.division_name ?? 'a division'}'s group `
+              + `${warning.group_name ?? ''} has only ${warning.teams} team(s) registered - `
+              + `no match schedule exists for that few, so it was not planned at all`
+          }
+
+          return `${name} (${warning.phase}, ${warning.date}) was due on at `
+            + `${warning.expected} but opens at ${warning.earliest}`
+        })
+        .join(' · ')
+    } else {
+      warningsEl.hidden = true
+    }
+
+    this.renderSchedule()
+  }
+
+  renderSchedule() {
+    const container = this.$('[data-schedule]')
+
+    // Preserve whichever day tab was active - assigning a selection
+    // re-renders the whole schedule, and without this it would always
+    // snap back to the first day.
+    const activeDate = container.querySelector('semtic-tabbed')?.getAttribute('current')
+
+    container.replaceChildren()
+
+    if (!this.state.days.length) {
+      return
+    }
+
+    const tabbed = document.createElement('semtic-tabbed')
+    // Open on a day that has something on it. The event's first days
+    // are often empty - nothing is planned until a competition's own
+    // session starts - and opening on one of those makes a full plan
+    // look like an empty board.
+    const firstBooked = this.state.days.find(day => this.blocks.some(block => block.date === day))
+    const initial = this.state.days.includes(activeDate) ? activeDate : (firstBooked ?? this.state.days[0])
+
+    tabbed.setAttribute('current', initial)
+
+    // A day's grid is a full court x slot layout - expensive to build,
+    // and a long-running event (a weekly league spanning months) can
+    // have far more days than a director ever actually opens in one
+    // sitting. So only the initially-open day is built now; every
+    // other day is built the moment a director actually switches to
+    // it, via semtic-tabbed's `:activated` event - not depended on for
+    // the initial day, since that event only fires once semtic-tabbed's
+    // real custom element class has upgraded the tag, which a caller
+    // that hasn't loaded @skirbi/semtic can't rely on (this package
+    // itself does not depend on it - it's supplied by the host app).
+    const built = new Set()
+
+    const buildDay = date => {
+      if (built.has(date)) {
+        return
+      }
+      built.add(date)
+
+      const tab = tabbed.querySelector(`:scope > semtic-tab[tab="${date}"]`)
+      if (!tab) {
+        return
+      }
+      tab.appendChild(this.legendForDate(date))
+      tab.appendChild(this.dayForDate(date))
+    }
+
+    for (const date of this.state.days) {
+      const tab = document.createElement('semtic-tab')
+      tab.setAttribute('tab', date)
+      tab.setAttribute('label', date)
+      tabbed.appendChild(tab)
+    }
+
+    buildDay(initial)
+
+    tabbed.addEventListener('semtic-tabbed:activated', event => buildDay(event.detail.tab))
+
+    container.appendChild(tabbed)
+  }
+
+  /**
+   * Each competition relevant to this day is a button: select a block
+   * of cells first, then click a competition here to assign the whole
+   * block to it in one action. Clear does the same for unassigning.
+   */
+  legendForDate(date) {
+    const legend = document.createElement('ul')
+    legend.dataset.legend = ''
+
+    const clearItem = document.createElement('li')
+    const clearButton = document.createElement('button')
+    clearButton.type = 'button'
+    clearButton.dataset.legendClear = ''
+    clearButton.textContent = 'Clear selection'
+    clearButton.addEventListener('click', () => this.assignSelection(null))
+    clearItem.appendChild(clearButton)
+    legend.appendChild(clearItem)
+
+    for (const { competition, phase } of this.competitionsForDate(date)) {
+      const item = document.createElement('li')
+      item.dataset.competitionId = competition.id
+      item.dataset.phase = phase
+
+      const button = document.createElement('button')
+      button.type = 'button'
+      button.dataset.legendAssign = ''
+
+      const name = document.createElement('span')
+      name.dataset.legendName = ''
+      name.textContent = `${competition.name} (${phase === 'knockout' ? 'Knockout' : 'Group'})`
+
+      const count = document.createElement('span')
+      count.dataset.legendCount = ''
+      // Knockout capacity is planned against the bye-padded bracket
+      // shape (games_needed_by_round), not the exact advancing-team
+      // math (games_needed.knockout) - a division whose advancing
+      // count isn't a power of two always schedules more slots than
+      // that exact figure, on purpose, so comparing against it made a
+      // fully-planned knockout look short.
+      const needed = phase === 'knockout'
+        ? (competition.games_needed_by_round ?? []).reduce((total, wave) => total + wave.count, 0)
+        : competition.games_needed[phase]
+      count.textContent = `${this.scheduledGames(competition.id, phase)} scheduled / ${needed} games needed`
+
+      button.append(name, count)
+      button.addEventListener('click', () => this.assignSelection(competition.id, phase))
+
+      item.appendChild(button)
+      legend.appendChild(item)
+    }
+
+    return legend
+  }
+
+  /**
+   * The rows to draw for a day.
+   *
+   * Competitions no longer share a clock - one starts at 08:00 in
+   * 45-minute matches, another at 09:00 in 90-minute ones - so the
+   * rows are every time something is actually booked, merged with the
+   * standing grid. Drawing only the grid hid every competition whose
+   * hours did not happen to land on it.
+   */
+  rowsFor(date) {
+    return rowsForDate({
+      date,
+      competitions: this.state.competitions ?? [],
+      cells: this.blocks,
+      fallbackSlots: this.state.slots ?? [],
+    })
+  }
+
+  /**
+   * The stretch of the day worth drawing: from the earliest row's
+   * start to the latest row's end. A day is drawn to scale - a
+   * Google-Calendar-style timeline, not a table of uniform rows - so
+   * the canvas needs real bounds to measure every block's position
+   * against.
+   */
+  dayRangeFor(rows) {
+    if (rows.length === 0) {
+      return { start: 0, end: 0 }
+    }
+
+    return {
+      start: Math.min(...rows.map(row => row.start_minutes)),
+      end: Math.max(...rows.map(row => row.end_minutes)),
+    }
+  }
+
+  /**
+   * The plan as plain data: a day holds courts, a court holds slots, a
+   * slot holds what is played in it. The same shape the markup has,
+   * without the markup.
+   */
+  planData() {
+    const activeDate = this.$('[data-schedule] semtic-tabbed')?.getAttribute('current')
+      ?? this.state.days.find(day => this.blocks.some(block => block.date === day))
+      ?? this.state.days[0]
+
+    const competitions = new Map(this.state.competitions.map(c => [c.id, c.name]))
+
+    const courts = this.state.courts
+      .map(court => {
+        const slots = this.blocks
+          .filter(block => block.date === activeDate && block.court_id === court.id)
+          .sort((a, b) => a.slot.localeCompare(b.slot))
+          .map(block => ({
+            start: block.slot,
+            competition: competitions.get(block.competition_id) ?? block.competition_id,
+            phase: block.phase,
+            division: block.division_name ?? null,
+            group: block.group_name ?? null,
+            round: block.round ?? null,
+            fixture: block.match_slot ?? null,
+            shared_pair: block.short_group ? true : undefined,
+          }))
+
+        return slots.length === 0 ? null : { court: court.name, lit: court.lit, slots }
+      })
+      .filter(Boolean)
+
+    return { date: activeDate, courts }
+  }
+
+  /**
+   * The hue this division is drawn in, shared with Scheduling.
+   *
+   * @see division-hues.mjs
+   */
+  divisionHue(competitionId, divisionId) {
+    this._divisionHues ??= divisionHues(this.state.competitions)
+
+    const hue = this._divisionHues.get(divisionId)
+
+    if (hue != null) {
+      return hue
+    }
+
+    return competitionHue(
+      this.state.competitions.findIndex(c => c.id === competitionId),
+      this.state.competitions.length
+    )
+  }
+
+  /**
+   * A day, as courts rather than a table.
+   *
+   * The grid used to be rows of hours crossed with columns of courts,
+   * which forced every competition onto one set of rows. They do not
+   * share a clock - one starts at 08:00 in 45-minute matches, another
+   * at 09:00 in 90-minute ones - so the markup says what is actually
+   * true instead: a court holds slots, and a slot holds what is played
+   * in it.
+   *
+   *   <planning-court court="8">
+   *     <planning-slot start="09:00" duration="45">
+   *       <planning-match competition="Singles" division="adv men" .../>
+   *
+   * Slots carry the row they occupy so courts still line up across the
+   * day without a table to hold them in step.
+   *
+   * Drawn to scale, Google-Calendar-day-view style: a slot's box is
+   * positioned and sized from its real start/end minutes rather than
+   * a uniform row height, so a 90-minute match reads twice as tall as
+   * a 45-minute one and an idle stretch between two competitions'
+   * clocks shows as real blank space instead of being squashed flat
+   * against whatever books next. The bookable moments are still
+   * exactly the slots each competition's own session configures - the
+   * canvas is continuous, the cells on it are not.
+   */
+  dayForDate(date) {
+    const day = document.createElement('planning-day')
+    day.dataset.day = date
+    day.setAttribute('date', date)
+
+    const rows = this.rowsFor(date)
+    const range = this.dayRangeFor(rows)
+
+    day.style.setProperty('--planning-day-height', `${this.pxFor(range.end - range.start)}px`)
+
+    day.appendChild(this.timeColumn(rows, range))
+
+    this.state.courts.forEach((court, courtIndex) => {
+      day.appendChild(this.courtColumn(court, courtIndex, date, rows, range))
+    })
+
+    return day
+  }
+
+  /**
+   * Minutes of the day, in pixels on the timeline.
+   */
+  pxFor(minutes) {
+    return minutes * PX_PER_MINUTE
+  }
+
+  /**
+   * The hours down the side. Its own column rather than a cell in
+   * every row, so a court knows nothing about how the day is labelled.
+   */
+  timeColumn(rows, range) {
+    const column = document.createElement('planning-times')
+
+    // Stands in for the court name, so the hours line up with the
+    // slots rather than riding a row above them.
+    column.appendChild(document.createElement('planning-times-head'))
+
+    const body = document.createElement('planning-rows')
+    body.style.setProperty('--planning-day-height', `${this.pxFor(range.end - range.start)}px`)
+
+    rows.forEach(slot => {
+      const time = document.createElement('planning-time')
+      time.setAttribute('start', slot.key)
+      time.style.top = `${this.pxFor(slot.start_minutes - range.start)}px`
+      time.style.height = `${this.pxFor(slot.end_minutes - slot.start_minutes)}px`
+      time.textContent = slot.label ?? slot.key
+      body.appendChild(time)
+    })
+
+    column.appendChild(body)
+
+    return column
+  }
+
+  courtColumn(court, courtIndex, date, rows, range) {
+    const column = document.createElement('planning-court')
+    column.setAttribute('court', court.name)
+    column.dataset.courtId = court.id
+
+    if (court.lit) {
+      column.setAttribute('lit', '')
+    }
+
+    if (court.pro) {
+      column.setAttribute('pro', '')
+    }
+
+    const heading = document.createElement('planning-court-name')
+    heading.textContent = court.name
+    column.appendChild(heading)
+
+    const body = document.createElement('planning-rows')
+    body.style.setProperty('--planning-day-height', `${this.pxFor(range.end - range.start)}px`)
+
+    // A row's own span is only ever the finest clock running that day
+    // (see rowsFor) - a real match longer than that (Team Cup's 90
+    // minutes among someone else's 45) draws its own slot taller
+    // instead, covering however many of these rows its real length
+    // reaches. Those covered rows are this court's alone to skip - a
+    // different court still gets its own row here, whatever its own
+    // match (or lack of one) actually needs.
+    let coveredUntil = -Infinity
+
+    rows.forEach((slot, rowIndex) => {
+      if (slot.start_minutes < coveredUntil) {
+        return
+      }
+
+      const element = this.slotElement(court, date, slot, rowIndex, courtIndex, range)
+      body.appendChild(element)
+
+      const spanEnd = Number(element.dataset.spanEnd)
+
+      if (!Number.isNaN(spanEnd)) {
+        coveredUntil = spanEnd
+      }
+    })
+
+    column.appendChild(body)
+
+    return column
+  }
+
+  /**
+   * How long the match actually in this slot really runs - its own
+   * competition's own configured playtime, not whatever length this
+   * row happens to carry (that's only ever the day's finest clock -
+   * see rowsFor). An empty slot has no match of its own to ask, so it
+   * keeps the row's length exactly as before.
+   */
+  blockDurationMinutes(block, date) {
+    const competition = this.state.competitions.find(c => c.id === block.competition_id)
+    const session = activeSession(competition?.sessions ?? [], date)
+
+    return session?.playtime ?? FALLBACK_SLOT_MINUTES
+  }
+
+  slotElement(court, date, slot, rowIndex, courtIndex, range) {
+    const element = document.createElement('planning-slot')
+    const block = this.blockAt(court.id, date, slot.key)
+    const duration = block
+      ? this.blockDurationMinutes(block, date)
+      : slot.end_minutes - slot.start_minutes
+
+    element.setAttribute('start', slot.key)
+    element.style.top = `${this.pxFor(slot.start_minutes - range.start)}px`
+    element.style.height = `${this.pxFor(duration)}px`
+
+    if (slot.start_minutes != null) {
+      element.setAttribute('duration', duration)
+      element.dataset.spanEnd = slot.start_minutes + duration
+    }
+
+    if (!this.isSelectable(court, slot)) {
+      element.setAttribute('blocked', '')
+      return element
+    }
+
+    element.dataset.row = rowIndex
+    element.dataset.col = courtIndex
+
+    element.addEventListener('mousedown', event => {
+      event.preventDefault()
+      this.startSelection(date, rowIndex, courtIndex)
+    })
+
+    element.addEventListener('mouseenter', () => {
+      if (this.isSelecting && this.selectionDate === date) {
+        this.updateSelection(rowIndex, courtIndex)
+      }
+    })
+
+    if (block) {
+      element.appendChild(this.matchElement(block))
+    }
+
+    return element
+  }
+
+  /**
+   * What is played in a slot. Everything Planning has decided about it
+   * is an attribute, so the booking can be read straight off the DOM.
+   */
+  matchElement(block) {
+    const competition = this.state.competitions.find(c => c.id === block.competition_id)
+    const match = document.createElement('planning-match')
+
+    match.setAttribute('competition', competition?.name ?? '')
+    match.setAttribute('phase', block.phase)
+
+    if (block.division_name) {
+      match.setAttribute('division', block.division_name)
+    }
+
+    // 'x' (mixed/team) and unset both mean there is no single gender
+    // to show - the icon stays off rather than guessing.
+    const gender = block.division_gender === 'm' ? 'men' : block.division_gender === 'f' ? 'women' : null
+
+    if (gender) {
+      match.setAttribute('gender', gender)
+    }
+
+    if (block.group_name) {
+      match.setAttribute('group', block.group_name)
+    }
+
+    if (block.round) {
+      match.setAttribute('round', block.round)
+    }
+
+    if (block.match_slot != null) {
+      match.setAttribute('fixture', block.match_slot)
+    }
+
+    if (block.short_group) {
+      match.setAttribute('shared-pair', '')
+    }
+
+    if (competition) {
+      match.dataset.competitionId = competition.id
+
+      const hue = this.divisionHue(competition.id, block.division_id)
+
+      if (hue != null) {
+        match.style.setProperty('--division-hue', hue)
+      }
+    }
+
+    if (block.division_id) {
+      match.dataset.divisionId = block.division_id
+    }
+
+    const name = document.createElement('planning-competition')
+    name.textContent = competition?.name ?? ''
+    match.appendChild(name)
+
+    if (block.round) {
+      const round = document.createElement('planning-round')
+      round.textContent = block.round
+      match.appendChild(round)
+    }
+
+    if (block.division_name) {
+      const division = document.createElement('planning-division')
+      division.textContent = block.division_name
+      match.appendChild(division)
+    }
+
+    if (block.group_name) {
+      const group = document.createElement('planning-group')
+      group.textContent = block.group_name
+      match.appendChild(group)
+    }
+
+    return match
+  }
+
+
+  async save() {
+    return withBusyButton(this.$('[data-save]'), async () => {
+
+      const config = this.getConfig()
+
+      const blocks = this.blocks.map(block => ({
+        competition_id: block.competition_id,
+        division_id: block.division_id ?? null,
+        group_id: block.group_id ?? null,
+        phase: block.phase,
+        round: block.round ?? null,
+        match_slot: block.match_slot ?? null,
+        court_id: block.court_id,
+        date: block.date,
+        slot: block.slot,
+      }))
+
+      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({ blocks }),
+      })
+
+      const body = await response.json()
+
+      if (!response.ok) {
+        this.dispatchEvent(new CustomEvent('tennis-planning:save-error', {
+          bubbles: true,
+          detail: body,
+        }))
+        return false
+      }
+
+      // The board already holds what it just sent, so the save only has
+      // to confirm. Having the server return the whole plan and
+      // re-rendering from it added several seconds to every save for
+      // nothing - a full plan is over a thousand cells.
+      this.dispatchEvent(new CustomEvent('tennis-planning:save', {
+        bubbles: true,
+        detail: { saved: body },
+      }))
+
+      return true
+    }, SAVING)
+  }
+
+}
+
+/**
+ * A row's label reads as the stretch it covers, not the moment it
+ * starts: a 45-minute 09:30 and a 90-minute one are different rows.
+ */
+function minutesToTime(minutes) {
+  return `${String(Math.floor(minutes / 60) % 24).padStart(2, '0')}:${String(minutes % 60).padStart(2, '0')}`
+}
+
+function timeToMinutes(key) {
+  const [hours, minutes] = String(key).split(':').map(Number)
+  return hours * 60 + (minutes || 0)
+}
+