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,84 @@
|
||||
# Implementation Plan: Double-Elimination Connector Routing
|
||||
|
||||
## Overview
|
||||
|
||||
Replace per-edge winner rail staggering with deterministic, collision-aware winner
|
||||
bundles while retaining the existing target-corridor `H-V-H` path model and the
|
||||
current loser/reset routing behavior.
|
||||
|
||||
## Architecture Decisions
|
||||
|
||||
- Keep routing as a pure layout calculation; the React renderer consumes unchanged
|
||||
`BracketConnectorLayout` paths.
|
||||
- Allocate baseline rails first, then choose one rail for each same-target winner
|
||||
bundle while leaving loser/reset coordinates unchanged.
|
||||
- Score complete candidate paths by parallel-stroke clearance, strict crossings,
|
||||
and distance from the corridor midpoint.
|
||||
- Permit shared `verticalX` only when the participating vertical intervals do not
|
||||
overlap; otherwise search the same corridor for the nearest deterministic pair
|
||||
of separate rails with focused-stroke clearance.
|
||||
|
||||
## Task List
|
||||
|
||||
### Phase 1: Regression Contract
|
||||
|
||||
- [x] Add tests proving quiet winner bundles use the corridor midpoint and all
|
||||
shareable same-target winner paths remain aligned.
|
||||
- [x] Replace target-column rail uniqueness with interval-aware segment assertions.
|
||||
- [x] Cover reversed A/B input where overlapping vertical spans require the
|
||||
deterministic separate-rail fallback.
|
||||
- [x] Confirm the focused test fails with the current allocator.
|
||||
|
||||
### Checkpoint: RED
|
||||
|
||||
- [x] The new behavioral assertion fails for the expected unequal `verticalX`.
|
||||
- [x] Existing tests remain unchanged except where their invariant is obsolete.
|
||||
|
||||
### Phase 2: Bundle-Aware Allocator
|
||||
|
||||
- [x] Represent connector routing inputs with precomputed source/target anchors.
|
||||
- [x] Retain stable independent rails for loser/reset routes.
|
||||
- [x] Group the two winners entering each target and select the nearest safe shared
|
||||
rail without card penetration, forbidden overlap, or avoidable added crossings.
|
||||
- [x] Fall back to the nearest deterministic, stroke-clear separate rails only
|
||||
when the pair's own vertical intervals overlap and cannot safely share a rail.
|
||||
|
||||
### Checkpoint: GREEN
|
||||
|
||||
- [x] Focused layout tests pass for four-team, eight-team, reset-final, and shuffled
|
||||
input fixtures.
|
||||
- [x] Strict crossing, collinear-overlap, and 5px parallel-clearance safeguards pass.
|
||||
|
||||
### Phase 3: Verification and Review
|
||||
|
||||
- [x] Run the full web suite, lint, and production build; document the unrelated
|
||||
pre-existing full-lint failures while verifying changed files separately.
|
||||
- [x] Inspect the diff for correctness, simplicity, security, performance, and
|
||||
adherence to the approved spec.
|
||||
- [x] Perform an independent review and address all required findings.
|
||||
|
||||
### Checkpoint: Complete
|
||||
|
||||
- [x] All success criteria in the spec are verified.
|
||||
- [x] No unrelated files are modified.
|
||||
|
||||
## Risks and Mitigations
|
||||
|
||||
| Risk | Impact | Mitigation |
|
||||
|---|---|---|
|
||||
| Blind midpoint alignment adds crossings in busy upper rounds | High | Score complete candidate paths and move the winner bundle together to the nearest safe rail. |
|
||||
| Shared rails create overlapping vertical segments | High | Check interval overlap before allowing a shared `verticalX`; search deterministic fallback rails with 5px clearance otherwise. |
|
||||
| Visually parallel rails pass exact-coordinate tests but overlap at stroke width | High | Require 5px clearance across overlapping vertical runs and cover it for 4/8-team fixtures. |
|
||||
| Routing changes depend on input array order | Medium | Sort routes and bundles by graph display order and retain shuffled-fixture equality tests. |
|
||||
| A long connector bends through an intermediate card | High | Restrict every candidate to the target corridor and retain card-penetration assertions. |
|
||||
| Reset-final slot carry-over is accidentally treated as a winner pair | Medium | Bundle only connectors whose computed kind is `winner`; keep reset paths independent. |
|
||||
|
||||
## Dependencies
|
||||
|
||||
```text
|
||||
Regression contract -> bundle-aware rail allocator -> full verification -> review
|
||||
```
|
||||
|
||||
## Open Questions
|
||||
|
||||
None.
|
||||
@@ -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