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

135 lines
6.1 KiB
Markdown

# 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:
```ts
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.