Files
lolympus-tournament-support/docs/specs/series-result-history-ui.md
dahyeon 3bd3120eb1 feat: link competition games to detail analysis
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.
2026-07-13 10:41:44 +00:00

7.4 KiB

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:

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.