# 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.