Route each result-history Game by its global display number and preserve the Competition return target. Refuse stale detail fallbacks so a missing requested Game cannot silently show another Game.
163 lines
7.4 KiB
Markdown
163 lines
7.4 KiB
Markdown
# Spec: Series Result History UI
|
|
|
|
## Objective
|
|
|
|
Replace the compact `Game N - winner` cards below Competition brackets with a
|
|
chronological, Series-centric result history. Users should be able to scan when a
|
|
Series was played, its round, participants, official result, and current score,
|
|
then expand the row to inspect the accepted Games that produced that record.
|
|
|
|
This first version is a truthful activity/result history, not a future schedule.
|
|
It uses only recorded Competition projection data and does not invent scheduled
|
|
times, venues, replay links, or team logos.
|
|
|
|
## Approved Product Decisions
|
|
|
|
- Keep the bracket first as the topology view and place the chronological history
|
|
below it.
|
|
- Render one primary row per Series, never one primary row per Game.
|
|
- Include a started `in-progress` Series when it has at least one accepted Game, so
|
|
completed Games do not disappear while a best-of Series is still running.
|
|
- Include every completed Series, including draw, walkover, forfeit, and
|
|
administrative outcomes with no accepted Game.
|
|
- Exclude inactive, waiting, ready, and game-less in-progress Series because they do
|
|
not have a truthful result timestamp.
|
|
- Use the earliest accepted Game `startedAt` as the Series activity time. For a
|
|
game-less decision, group by `outcome.completedAt` but display no fake start time.
|
|
- Group and format dates explicitly in `Asia/Seoul`.
|
|
- Keep individual Games in a native, keyboard-accessible disclosure below the Series
|
|
row.
|
|
- Make each disclosed Game row a real link to its internal-stat Game detail. Keep the
|
|
visible Series-local `ordinal`, but build the route from the globally unique
|
|
`displayNumber`.
|
|
- Preserve the current Competition page path in router state so the detail page can
|
|
return users to the same result view.
|
|
- Use the coral semantic primary token as an interaction cue on Game links (leading
|
|
edge, focus ring, subtle state background, and arrow), not as a winner or score
|
|
color.
|
|
- Scope that primary override to the result-history section so the exact coral remains
|
|
consistent in light and dark themes without changing unrelated dark-theme actions.
|
|
|
|
## Tech Stack
|
|
|
|
- React 19 and TypeScript 6 under `apps/web`
|
|
- Tailwind CSS 4 and daisyUI semantic tokens
|
|
- Shared Competition contracts from `@lolympus/contracts`
|
|
- Node's built-in test runner with TypeScript type stripping for pure model tests
|
|
|
|
## Commands
|
|
|
|
- Focused RED/GREEN test:
|
|
`pnpm --filter web exec node --test --experimental-strip-types test/competition-series-history.test.ts`
|
|
- Full web tests: `pnpm --filter web test`
|
|
- Web lint: `pnpm --filter web lint`
|
|
- Web build: `pnpm --filter web build`
|
|
|
|
## Project Structure
|
|
|
|
- `apps/web/src/components/competition/competition-series-history.ts` derives the
|
|
stable, timezone-aware history view model without React.
|
|
- `apps/web/src/components/competition/CompetitionSeriesHistory.tsx` renders the
|
|
semantic date sections and responsive Series rows.
|
|
- `apps/web/src/components/competition/CompetitionGameHistory.tsx` renders the
|
|
disclosed, navigable Game rows and their responsive interaction states.
|
|
- `apps/web/src/components/competition/CompetitionResults.tsx` replaces the existing
|
|
completed-Game card grid with the new component and supplies the route context.
|
|
- `apps/web/src/lib/internal-match-game-selection.ts` keeps explicit Game-detail
|
|
routes from silently falling back to a different recorded Game.
|
|
- `apps/web/test/competition-series-history.test.ts` specifies aggregation, ordering,
|
|
outcome, and formatting behavior.
|
|
|
|
## Code Style
|
|
|
|
Use contract discriminators and team IDs as the source of truth:
|
|
|
|
```ts
|
|
const shouldInclude =
|
|
(series.status === "in-progress" && games.length > 0) ||
|
|
series.status === "completed";
|
|
|
|
const winnerTeamId =
|
|
series.status === "completed" && series.outcome.type !== "draw"
|
|
? series.outcome.winnerTeamId
|
|
: undefined;
|
|
```
|
|
|
|
The UI uses flat, full-width rows and existing semantic tokens. It does not reuse
|
|
the bordered bracket card layout or introduce new dependencies.
|
|
|
|
## Testing Strategy
|
|
|
|
Develop the pure model test-first. Cover:
|
|
|
|
- Games aggregated by `seriesId` and ordered by Series-local `ordinal`;
|
|
- Series score preserved from A/B entries even when blue/red sides change;
|
|
- chronological ordering independent of projection graph order;
|
|
- `Asia/Seoul` grouping across the UTC day boundary;
|
|
- started in-progress Series and game-less completed decisions;
|
|
- exclusion of unstarted and orphan data;
|
|
- played, draw, walkover, forfeit, and administrative status semantics;
|
|
- deterministic tie-breaking and legacy zero-duration formatting.
|
|
- Game-detail route generation from `displayNumber`, including rejection of invalid
|
|
legacy display numbers.
|
|
- Exact internal Game selection, including a missing-result case when the requested
|
|
display number is absent from a stale or legacy detail payload.
|
|
|
|
After unit tests, run full web tests, changed-file lint, and the TypeScript/Vite build.
|
|
Review the markup for native keyboard interaction, heading order, visible status text,
|
|
and mobile layouts down to 320px.
|
|
|
|
## Boundaries
|
|
|
|
### Always
|
|
|
|
- Use `series.entries` for A/B score and `outcome.winnerTeamId` for the official
|
|
winner; never infer identity from score, array position, or blue/red side.
|
|
- Keep game-less adjudications visible without presenting `0 : 0` as a played score.
|
|
- Omit `durationSeconds === 0` because it represents missing legacy data.
|
|
- Use `displayNumber`, never Series-local `ordinal`, for the internal Game URL.
|
|
- Keep each Game row as one semantic anchor with no nested interactive control.
|
|
- Keep link text readable in both themes; coral may indicate interaction but must not
|
|
be the only visible cue.
|
|
- Never substitute another Game when the Game number explicitly requested by the URL
|
|
is not present in the internal-stat payload.
|
|
- Preserve all unrelated working-tree changes.
|
|
|
|
### Ask First
|
|
|
|
- Change the public Competition contract, database schema, or projector.
|
|
- Add Series scheduling or external replay/venue data.
|
|
- Add a frontend dependency or test framework.
|
|
|
|
### Never
|
|
|
|
- Present `completedAt` as a scheduled or actual start time.
|
|
- Reuse free-text `match.schedule` as official Series scheduling data.
|
|
- Parse `series.code` for identity, winner, or ordering.
|
|
- Make status or winner understandable only through color.
|
|
|
|
## Success Criteria
|
|
|
|
- A completed `2 : 1` Series appears as one chronological row with both teams, the
|
|
official score, round label, status, and an expandable three-Game history.
|
|
- In-progress Series retain already accepted Games and display `진행 중`.
|
|
- No-game decisions appear with the correct decision label and no misleading score
|
|
or start time.
|
|
- Date grouping and time display are stable in `Asia/Seoul` regardless of runtime
|
|
timezone.
|
|
- The layout is readable without horizontal scrolling at 320px and uses the wider
|
|
double-elimination page naturally on desktop.
|
|
- Each recorded Game can be opened by pointer or keyboard, lands on its matching
|
|
internal-stat Game, and provides a return link to the Competition result page.
|
|
- A temporarily stale or inconsistent detail payload shows an explicit missing-Game
|
|
state rather than silently rendering the first Game.
|
|
- Game rows expose an always-visible detail cue and coral hover, active, and focus
|
|
affordances without changing winner semantics.
|
|
- Focused/full tests, changed-file lint, and web build pass without modifying
|
|
unrelated work.
|
|
|
|
## Open Questions
|
|
|
|
None. The user approved the Series-centric, result-history-first direction and
|
|
requested implementation.
|