Files
lolympus-tournament-support/docs/specs/double-elimination-connector-routing.md
T

6.1 KiB

Spec: Double-Elimination Connector Routing

Objective

Make winner advancement lines in the desktop double-elimination bracket bend at a consistent horizontal position. Two winner lines entering the same match should read as one visual pair when their vertical spans can share a rail: use the center of the 40px inter-column corridor when it is safe, and move the pair together only when another connector would interfere. If an accepted A/B mapping reverses the source order and makes those spans overlap, preserve separate deterministic, stroke-clear rails instead of creating a collinear overlap.

The primary user is a participant or organizer tracing advancement through a busy eight-team bracket. Success means the solid coral winner paths are visually aligned without degrading the existing dashed loser paths, card placement, or keyboard-driven connector highlighting.

Approved Product Decisions

  • Treat the two winner connectors entering one Series as a semantic bundle.
  • Prefer target.x - columnGap / 2 for a winner bundle.
  • If the preferred rail causes crossings, collinear overlap, or less than 5px of clearance from an overlapping parallel route, move a shareable bundle to the nearest safe rail. Retain separate rails only when the pair's own vertical spans overlap and therefore cannot safely share any rail; move those rails to the nearest deterministic positions needed to preserve the same 5px clearance.
  • Preserve the current loser/reset rail ordering unless moving one is required to maintain valid geometry.
  • Keep every connector as a separate H-V-H SVG path so focus highlighting and accessible labels remain independent.
  • Keep long-distance bends inside the corridor immediately before the target column; do not use the midpoint between source and target cards.

Tech Stack

  • React 19, TypeScript 6, Vite 8, Tailwind CSS 4, and daisyUI under apps/web
  • Node's built-in test runner for the pure bracket layout calculation

Commands

  • Focused layout tests: pnpm --filter web exec node --test --experimental-strip-types test/double-elimination-bracket-layout.test.ts
  • Full web tests: pnpm --filter web test
  • Web lint: pnpm --filter web lint
  • Web production build: pnpm --filter web build:prod
  • Development server: pnpm --filter web start:dev

Project Structure

  • apps/web/src/components/competition/double-elimination-bracket-layout.ts validates the bracket graph, positions cards, assigns connector rails, and emits SVG path geometry.
  • apps/web/src/components/competition/DoubleEliminationBracket.tsx renders the computed paths and must not need routing-specific changes.
  • apps/web/test/double-elimination-bracket-layout.test.ts contains canonical four-team, eight-team, and reset-final fixtures plus geometry assertions.

Code Style

Keep routing deterministic and express geometry through small named helpers:

const preferredX = target.x - geometry.columnGap / 2;
const verticalX = nearestSafeRail(preferredX, bundle, occupiedRoutes);

Use existing layout types and semantic connector kinds. Do not add a dependency, DOM measurement, mutable global state, or renderer-specific routing behavior.

Testing Strategy

  • Add regression tests before implementation and confirm they fail against the current per-edge rail allocator.
  • Assert observable geometry: safe winner pairs share a rail, quiet corridors use their exact midpoint, busy corridors keep a pair aligned, and mixed winner/loser entries remain distinguishable.
  • Cover reversed A/B winner input explicitly: it remains deterministic and uses separate rails without collinear overlap or focused-stroke clearance conflicts because no shared H-V-H rail is safe.
  • Replace the obsolete "all rails in a target column are unique" assertion with interval-aware overlap and 5px focused-stroke clearance protection.
  • Preserve deterministic output for shuffled input, finite path coordinates, target-corridor bounds, card avoidance, endpoint alignment, and canonical graph validation.
  • Verify four-team, eight-team, and reset-final layouts; run the complete web test, lint, and production build commands.

Boundaries

Always

  • Keep winner, loser, and reset connectors visually distinguishable by the existing solid/dashed patterns and brand tokens.
  • Keep connector rails strictly inside the target corridor.
  • Avoid strict segment crossings and collinear overlaps whenever a safe candidate exists.
  • Keep overlapping parallel winner and loser rails at least 5px apart, matching the widest focused connector underlay.
  • Produce the same layout regardless of projection input ordering.

Ask First

  • Add dependencies or change the public projection contract.
  • Change bracket card dimensions, round columns, or the 40px column gap.
  • Redesign mobile bracket presentation or connector interaction behavior.

Never

  • Route a connector through a match card.
  • Infer routing from Series codes; use canonical graph identity and topology.
  • Merge two logical connectors into one SVG path.
  • Modify unrelated competition or score-card behavior.

Success Criteria

  • The two winner paths into LB_R3_M1 bend at the corridor midpoint and share the same verticalX.
  • The winner paths into the grand final share the corridor midpoint when safe.
  • Every same-target winner pair whose vertical spans do not overlap shares one verticalX, using the nearest collision-safe rail when the midpoint is busy.
  • A reversed A/B pair with overlapping vertical spans retains deterministic separate rails, produces no collinear segment overlap, and remains at least 5px from every overlapping vertical route.
  • Loser/reset paths retain their baseline rails, and winner bundles remain at least 5px away where their vertical runs overlap.
  • All rails remain inside their target corridors without card penetration or collinear overlap.
  • Canonical four-team, eight-team, reset-final, and shuffled-input tests pass.
  • Full web tests and production build pass; changed-file lint passes, and any unrelated full-lint baseline failures are documented.

Open Questions

None. The user reviewed the proposed bundle-aware routing behavior and requested implementation.