feat(web): align double-elimination winner connector rails
This commit is contained in:
1 parent
61f1db0e6a
commit
8ec9edc35f
5 files changed
+866
-44
No files matched your search
@@ -0,0 +1,134 @@
|
||||
# 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.
|
||||
Reference in new issue
Block a user