From 81b951889f9f3deb95b425b6f019b3dbfac659f1 Mon Sep 17 00:00:00 2001 From: dahyeon Date: Mon, 13 Jul 2026 21:16:23 -0700 Subject: [PATCH] test(web): specify team progress presentation --- .../web/src/pages/match-team-progress-view.ts | 198 +++++++++++++++ .../web/test/match-team-progress-view.test.ts | 228 ++++++++++++++++++ docs/plans/team-progress-page-ux-refresh.md | 98 ++++++++ docs/specs/team-progress-page-ux-refresh.md | 133 ++++++++++ 4 files changed, 657 insertions(+) create mode 100644 apps/web/src/pages/match-team-progress-view.ts create mode 100644 apps/web/test/match-team-progress-view.test.ts create mode 100644 docs/plans/team-progress-page-ux-refresh.md create mode 100644 docs/specs/team-progress-page-ux-refresh.md diff --git a/apps/web/src/pages/match-team-progress-view.ts b/apps/web/src/pages/match-team-progress-view.ts new file mode 100644 index 00000000..e1a6ce39 --- /dev/null +++ b/apps/web/src/pages/match-team-progress-view.ts @@ -0,0 +1,198 @@ +import type { + BracketRoundView, + SeriesId, + SeriesProjection, + TeamTournamentCodeView, +} from "@lolympus/contracts"; + +export interface TeamSeriesGroup { + series: SeriesProjection; + codes: TeamTournamentCodeView[]; +} + +export type TournamentCodeTone = + | "pending" + | "available" + | "expired" + | "used"; + +export interface TournamentCodePresentation { + label: string; + tone: TournamentCodeTone; + canCopy: boolean; +} + +export type TournamentCodeCopyFeedback = + | { kind: "success"; message: string } + | { kind: "error"; message: string }; + +type ClipboardWriter = ((value: string) => Promise) | undefined; + +export function createTeamSeriesGroups( + activeSeries: readonly SeriesProjection[], + tournamentCodes: readonly TeamTournamentCodeView[], +): TeamSeriesGroup[] { + const codesBySeriesId = new Map(); + for (const assignment of tournamentCodes) { + const seriesId = String(assignment.seriesId); + const existing = codesBySeriesId.get(seriesId) ?? []; + existing.push(assignment); + codesBySeriesId.set(seriesId, existing); + } + + return [...activeSeries] + .sort(compareSeriesDisplayOrder) + .map((series) => ({ + series, + codes: [...(codesBySeriesId.get(String(series.seriesId)) ?? [])].sort( + compareTournamentCodes, + ), + })); +} + +export function getTeamSeriesDisplayLabel( + series: SeriesProjection, + rounds: readonly BracketRoundView[], +): string { + const round = rounds.find(({ seriesIds }) => + seriesIds.some((seriesId) => seriesId === series.seriesId), + ); + const stage = round?.stage ?? series.stage.type; + const roundNumber = round?.roundNumber ?? series.stage.roundNumber ?? 1; + const baseLabel = isFinalRound(round, rounds) + ? stage === "upper" + ? "승자조 결승" + : "패자조 결승" + : stageLabel(stage, roundNumber); + + if (!round || round.seriesIds.length <= 1) return baseLabel; + const matchIndex = round.seriesIds.findIndex( + (seriesId) => seriesId === series.seriesId, + ); + return matchIndex >= 0 + ? `${baseLabel} · ${matchIndex + 1}경기` + : baseLabel; +} + +export function getTournamentCodePresentation( + assignment: TeamTournamentCodeView, + now = Date.now(), +): TournamentCodePresentation { + if (assignment.state === "used") { + return { label: "사용 완료", tone: "used", canCopy: false }; + } + if (assignment.state === "pending" || !assignment.code) { + return { label: "발급 대기", tone: "pending", canCopy: false }; + } + if (isExpired(assignment.expiresAt, now)) { + return { label: "만료", tone: "expired", canCopy: false }; + } + return { label: "사용 가능", tone: "available", canCopy: true }; +} + +export function getTournamentCodeCopyLabel( + assignment: TeamTournamentCodeView, + seriesLabel: string, +): string { + return `${seriesLabel} ${assignment.ordinal}세트 토너먼트 코드 복사 (전체 ${assignment.displayNumber}번 게임)`; +} + +export async function copyTournamentCode( + writeText: ClipboardWriter, + code: string, + gameLabel: string, +): Promise { + try { + if (!writeText) throw new Error("Clipboard API unavailable"); + await writeText(code); + return { + kind: "success", + message: `${gameLabel} 코드를 복사했습니다.`, + }; + } catch { + return { + kind: "error", + message: `${gameLabel} 코드를 복사하지 못했습니다. 코드를 직접 선택해 복사해 주세요.`, + }; + } +} + +export function sortCompletedTeamSeries( + series: readonly Extract[], +): Array> { + return [...series].sort( + (left, right) => + timestampValue(right.outcome.completedAt) - + timestampValue(left.outcome.completedAt) || + right.stage.displayOrder - left.stage.displayOrder || + String(left.seriesId).localeCompare(String(right.seriesId)), + ); +} + +function compareSeriesDisplayOrder( + left: SeriesProjection, + right: SeriesProjection, +): number { + return ( + left.stage.displayOrder - right.stage.displayOrder || + String(left.seriesId).localeCompare(String(right.seriesId)) + ); +} + +function compareTournamentCodes( + left: TeamTournamentCodeView, + right: TeamTournamentCodeView, +): number { + return ( + left.ordinal - right.ordinal || + left.displayNumber - right.displayNumber || + String(left.gameSlotId).localeCompare(String(right.gameSlotId)) + ); +} + +function isFinalRound( + round: BracketRoundView | undefined, + rounds: readonly BracketRoundView[], +): boolean { + if (!round || (round.stage !== "upper" && round.stage !== "lower")) { + return false; + } + const stageRoundNumbers = rounds + .filter(({ stage }) => stage === round.stage) + .map(({ roundNumber }) => roundNumber ?? 0); + return ( + stageRoundNumbers.length > 0 && + (round.roundNumber ?? 0) === Math.max(...stageRoundNumbers) + ); +} + +function stageLabel( + stage: SeriesProjection["stage"]["type"], + roundNumber: number, +): string { + switch (stage) { + case "upper": + return `승자조 ${roundNumber}라운드`; + case "lower": + return `패자조 ${roundNumber}라운드`; + case "grand-final": + return "그랜드 파이널"; + case "reset-final": + return "리셋 파이널"; + case "round-robin": + return `${roundNumber}라운드`; + case "pair": + return "공식 대진"; + } +} + +function isExpired(expiresAt: string | null, now: number): boolean { + if (!expiresAt) return false; + const timestamp = Date.parse(expiresAt); + return Number.isFinite(timestamp) && timestamp <= now; +} + +function timestampValue(value: string): number { + const timestamp = Date.parse(value); + return Number.isFinite(timestamp) ? timestamp : Number.NEGATIVE_INFINITY; +} diff --git a/apps/web/test/match-team-progress-view.test.ts b/apps/web/test/match-team-progress-view.test.ts new file mode 100644 index 00000000..2b9ef5c5 --- /dev/null +++ b/apps/web/test/match-team-progress-view.test.ts @@ -0,0 +1,228 @@ +import assert from "node:assert/strict"; +import test from "node:test"; +import type { + BracketRoundView, + CompetitionFactId, + GameSlotId, + SeriesId, + SeriesProjection, + TeamId, + TeamTournamentCodeView, +} from "@lolympus/contracts"; +import { + copyTournamentCode, + createTeamSeriesGroups, + getTeamSeriesDisplayLabel, + getTournamentCodeCopyLabel, + getTournamentCodePresentation, + sortCompletedTeamSeries, +} from "../src/pages/match-team-progress-view.ts"; + +const TEAM_A = "team-a" as TeamId; +const TEAM_B = "team-b" as TeamId; + +test("groups only matching tournament codes under each active Series", () => { + const earlier = readySeries("series-earlier", 1); + const later = readySeries("series-later", 2); + const groups = createTeamSeriesGroups( + [later, earlier], + [ + tournamentCode("later-2", later.seriesId, 2, 20), + tournamentCode("orphan", "series-orphan" as SeriesId, 1, 99), + tournamentCode("earlier-1", earlier.seriesId, 1, 17), + tournamentCode("later-1", later.seriesId, 1, 19), + ], + ); + + assert.deepEqual( + groups.map(({ series, codes }) => ({ + seriesId: series.seriesId, + gameSlotIds: codes.map(({ gameSlotId }) => gameSlotId), + })), + [ + { seriesId: earlier.seriesId, gameSlotIds: ["earlier-1"] }, + { seriesId: later.seriesId, gameSlotIds: ["later-1", "later-2"] }, + ], + ); +}); + +test("uses Korean round names while keeping global game numbers secondary", () => { + const opening = readySeries("upper-opening-2", 1, "WB_R1_M2"); + const final = readySeries("upper-final", 3, "WB_FINAL"); + const rounds: BracketRoundView[] = [ + round("upper", 1, 1, ["upper-opening-1", opening.seriesId]), + round("upper", 3, 3, [final.seriesId]), + ]; + + assert.equal( + getTeamSeriesDisplayLabel(opening, rounds), + "승자조 1라운드 · 2경기", + ); + assert.equal(getTeamSeriesDisplayLabel(final, rounds), "승자조 결승"); + + const assignment = tournamentCode("final-1", final.seriesId, 1, 19); + assert.equal( + getTournamentCodeCopyLabel(assignment, "승자조 결승"), + "승자조 결승 1세트 토너먼트 코드 복사 (전체 19번 게임)", + ); +}); + +test("distinguishes pending, available, expired, and used code states", () => { + const now = Date.parse("2026-07-13T12:00:00.000Z"); + const pending = tournamentCode("pending", "series-a" as SeriesId, 1, 1, { + state: "pending", + code: null, + }); + const available = tournamentCode( + "available", + "series-a" as SeriesId, + 2, + 2, + { expiresAt: "2026-07-13T13:00:00.000Z" }, + ); + const expired = tournamentCode( + "expired", + "series-a" as SeriesId, + 3, + 3, + { expiresAt: "2026-07-13T11:00:00.000Z" }, + ); + const used = tournamentCode("used", "series-a" as SeriesId, 4, 4, { + state: "used", + expiresAt: "2026-07-13T11:00:00.000Z", + }); + + assert.deepEqual(getTournamentCodePresentation(pending, now), { + label: "발급 대기", + tone: "pending", + canCopy: false, + }); + assert.deepEqual(getTournamentCodePresentation(available, now), { + label: "사용 가능", + tone: "available", + canCopy: true, + }); + assert.deepEqual(getTournamentCodePresentation(expired, now), { + label: "만료", + tone: "expired", + canCopy: false, + }); + assert.deepEqual(getTournamentCodePresentation(used, now), { + label: "사용 완료", + tone: "used", + canCopy: false, + }); +}); + +test("returns explicit game-specific clipboard success and failure feedback", async () => { + const writes: string[] = []; + const success = await copyTournamentCode( + async (value) => { + writes.push(value); + }, + "KR-CODE-19", + "승자조 결승 1세트", + ); + const failure = await copyTournamentCode( + async () => { + throw new Error("clipboard denied"); + }, + "KR-CODE-20", + "승자조 결승 2세트", + ); + + assert.deepEqual(writes, ["KR-CODE-19"]); + assert.deepEqual(success, { + kind: "success", + message: "승자조 결승 1세트 코드를 복사했습니다.", + }); + assert.deepEqual(failure, { + kind: "error", + message: + "승자조 결승 2세트 코드를 복사하지 못했습니다. 코드를 직접 선택해 복사해 주세요.", + }); +}); + +test("sorts completed Series by most recent decision time", () => { + const older = completedSeries("older", "2026-07-12T10:00:00.000Z", 1); + const newer = completedSeries("newer", "2026-07-13T10:00:00.000Z", 2); + + assert.deepEqual( + sortCompletedTeamSeries([older, newer]).map(({ seriesId }) => seriesId), + [newer.seriesId, older.seriesId], + ); +}); + +function readySeries( + id: string, + displayOrder: number, + code = id.toUpperCase(), +): SeriesProjection { + return { + seriesId: id as SeriesId, + code, + stage: { type: "upper", roundNumber: displayOrder, displayOrder }, + rule: { type: "first-to", winsRequired: 2, maxGames: 3 }, + status: "ready", + entries: [ + { slot: "A", teamId: TEAM_A, gameWins: 0 }, + { slot: "B", teamId: TEAM_B, gameWins: 0 }, + ], + }; +} + +function completedSeries( + id: string, + completedAt: string, + displayOrder: number, +): Extract { + return { + ...readySeries(id, displayOrder), + status: "completed", + entries: [ + { slot: "A", teamId: TEAM_A, gameWins: 0 }, + { slot: "B", teamId: TEAM_B, gameWins: 0 }, + ], + outcome: { + type: "walkover", + winnerTeamId: TEAM_A, + loserTeamId: TEAM_B, + decisionFactId: `${id}-fact` as CompetitionFactId, + completedAt, + }, + }; +} + +function tournamentCode( + id: string, + seriesId: SeriesId, + ordinal: number, + displayNumber: number, + overrides: Partial = {}, +): TeamTournamentCodeView { + return { + gameSlotId: id as GameSlotId, + seriesId, + ordinal, + displayNumber, + state: "reserved", + code: `KR-${id}`, + expiresAt: null, + ...overrides, + }; +} + +function round( + stage: BracketRoundView["stage"], + roundNumber: number, + displayOrder: number, + seriesIds: Array, +): BracketRoundView { + return { + stage, + roundNumber, + displayOrder, + label: `${stage}-${roundNumber}`, + seriesIds: seriesIds.map((id) => id as SeriesId), + }; +} diff --git a/docs/plans/team-progress-page-ux-refresh.md b/docs/plans/team-progress-page-ux-refresh.md new file mode 100644 index 00000000..37b7da80 --- /dev/null +++ b/docs/plans/team-progress-page-ux-refresh.md @@ -0,0 +1,98 @@ +# Implementation Plan: Team Progress Page UX Refresh + +## Overview + +Deliver the redesign in three verifiable slices: tested presentation rules, shared +Series semantics, and the integrated page/copy experience. No API or dependency +change is required because the team view already exposes `seriesId`, ordinal, round +metadata, outcome categories, and code expiry. + +## Architecture Decisions + +- Keep API/query ownership in the page and move deterministic presentation logic + into a pure module that the existing Node test runner can exercise. +- Compose the active-Series card with code rows instead of maintaining a separate + page-wide code grid. +- Reuse existing Competition history result and score helpers instead of creating + a second interpretation of adjudicated outcomes. +- Use one responsive layout and native disclosure/table semantics rather than + separate desktop and mobile component trees. + +## Task List + +### Phase 1: Tested View Model + +- [ ] Add failing tests for Series/code grouping, stable ordering, Korean round + labels, code availability/expiry, unique copy labels, and explicit clipboard + results. + - Acceptance: the new focused test fails because the behavior is not implemented. + - Verify: `pnpm --filter web exec node --test --experimental-strip-types test/match-team-progress-view.test.ts` + - Files: `apps/web/test/match-team-progress-view.test.ts` +- [ ] Implement the minimal pure view helpers. + - Acceptance: all focused assertions pass without React or DOM mocks. + - Verify: rerun the focused command once after implementation. + - Files: `apps/web/src/pages/match-team-progress-view.ts` + +### Checkpoint: View Model + +- [ ] Focused tests pass and no API/contract file changed. + +### Phase 2: Series Semantics and Code Interaction + +- [ ] Update the shared Series card to prefer supplied human labels, show technical + codes secondarily, and hide misleading pre-start/adjudicated scores. + - Acceptance: ready and adjudicated cards show `—`; result categories remain + text-visible; bracket geometry stays unchanged. + - Verify: `pnpm --filter web test` + - Files: `apps/web/src/components/competition/SeriesScoreCard.tsx` +- [ ] Add the responsive tournament-code list with accessible clipboard feedback. + - Acceptance: code rows show local set number first, full selectable codes, + unique 44px copy controls, expiry/state text, and success/failure announcements. + - Verify: TypeScript build plus runtime keyboard/copy check. + - Files: `apps/web/src/components/competition/TeamTournamentCodes.tsx` + +### Checkpoint: Interaction + +- [ ] Full web tests pass and the web build succeeds. + +### Phase 3: Page Hierarchy and Polish + +- [ ] Reorder the page and integrate code rows with matching active Series. + - Acceptance: order is next match, roster, recent results; every code appears + under exactly one matching Series; empty states remain meaningful. + - Verify: desktop and mobile runtime screenshots. + - Files: `apps/web/src/pages/MatchTeamProgressPage.tsx` +- [ ] Compact and order the roster, and collapse results beyond the newest two. + - Acceptance: position labels are Korean and role-ordered, captain is adjacent, + and older results remain keyboard-accessible. + - Verify: 320/768/1024/1440px reflow and keyboard traversal. + - Files: `apps/web/src/pages/MatchTeamProgressPage.tsx` + +### Checkpoint: Complete + +- [ ] Focused and full tests pass without skips. +- [ ] Lint and build pass. +- [ ] Runtime review confirms no console errors or horizontal overflow. +- [ ] Final diff contains only the spec, plan, focused tests, and team-progress UI. + +## Risks and Mitigations + +| Risk | Impact | Mitigation | +|---|---|---| +| A code appears under the wrong Series | High | Join only on exact `seriesId` and cover opponent/other-Series codes in tests. | +| Global and local game numbers are confused | High | Lead with `ordinal` as set number and demote `displayNumber`. | +| Adjudication looks like a played 0–0 | High | Reuse tested outcome/score helpers from Competition history. | +| Clipboard permissions fail silently | Medium | Return a typed result and render an alert with manual-selection guidance. | +| Long codes overflow at mobile widths | Medium | Use `minmax(0,1fr)`, `break-all`, selectable text, and a stacked mobile row. | +| Shared Series card changes bracket dimensions | Medium | Preserve the bracket variant's fixed geometry and compact metadata treatment. | + +## Dependencies + +```text +View-model tests -> view helpers -> code component -> page composition +Existing history outcome helpers -> Series score semantics -> recent results +``` + +## Open Questions + +None. diff --git a/docs/specs/team-progress-page-ux-refresh.md b/docs/specs/team-progress-page-ux-refresh.md new file mode 100644 index 00000000..7bc00a37 --- /dev/null +++ b/docs/specs/team-progress-page-ux-refresh.md @@ -0,0 +1,133 @@ +# Spec: Team Progress Page UX Refresh + +## Objective + +Reorganize the team progress page around the participant's primary task: identify +the next opponent, understand the Series state, and copy the correct tournament +code without cross-referencing separate sections. Keep the existing Competition +API and visual language while making status, adjudicated results, copy feedback, +the roster, and past results clearer on desktop and mobile. + +The primary user is a team participant preparing to join an official internal-match +game. Success means every active Series and its codes form one understandable work +area, human-facing Korean labels lead internal identifiers, and the copy flow is +accessible and explicit. + +## Approved Product Decisions + +- Group tournament codes under their matching active Series using `seriesId`. +- Label a Series-local game as `1세트`, `2세트`, and so on; retain global + `Game 19`-style numbers only as secondary metadata. +- Derive Korean round labels from Competition round metadata and retain raw Series + codes such as `WB_FINAL` as secondary diagnostic text. +- Show pre-start and adjudicated Series without misleading `0–0` scores. +- Distinguish `부전승`, `기권승`, `판정승`, and `무승부` using the existing + outcome discriminator. Do not invent a free-form reason that is not public data. +- Make copy targets at least 44 CSS pixels high, uniquely label each button, keep + the complete code visible/selectable, and announce copy success or failure. +- Order the page as header, next matches with codes, compact roster, then recent + results. Show two recent results and collapse older entries. +- Preserve existing loading, selection, empty, error, revision-consistency, and + authorization behavior. + +## Tech Stack + +- React 19 and TypeScript 6 under `apps/web` +- Tailwind CSS 4 and daisyUI 5 using the repository's square bordered surfaces +- Node's built-in test runner for pure view-model behavior +- Existing `lucide-react` icon set; no new dependency + +## Commands + +- Focused tests: `pnpm --filter web exec node --test --experimental-strip-types test/match-team-progress-view.test.ts` +- Full web tests: `pnpm --filter web test` +- Web lint: `pnpm --filter web lint` +- Web build: `pnpm --filter web build` +- Development server: `pnpm --filter web start:dev` + +## Project Structure + +- `apps/web/src/pages/MatchTeamProgressPage.tsx` owns queries, snapshot guards, + page ordering, and top-level team navigation. +- `apps/web/src/pages/match-team-progress-view.ts` owns pure grouping, ordering, + labels, code state, and copy-result behavior. +- `apps/web/src/components/competition/TeamTournamentCodes.tsx` owns code rows and + clipboard feedback. +- `apps/web/src/components/competition/SeriesScoreCard.tsx` remains the shared + Series summary while respecting pre-start and adjudicated score semantics. +- `apps/web/test/match-team-progress-view.test.ts` specifies the new pure behavior. + +## Code Style + +Keep data transformation outside React and render semantic native controls: + +```ts +const seriesCodes = tournamentCodesForSeries( + teamView.tournamentCodes, + series.seriesId, +); + + +``` + +Use `text-content-subtle` and `text-content-muted` for secondary text. Semantic +colors may provide a border or background accent, while normal-size text remains a +high-contrast base-content color. + +## Testing Strategy + +- Test code-to-Series association by exact `seriesId` and deterministic ordinal + ordering before adding the UI. +- Test Korean round labels, code availability/expiry state, unique copy labels, + and explicit clipboard success/failure results as pure functions. +- Reuse existing tested Competition history helpers for adjudicated result labels + and score visibility. +- Run the complete web suite, lint, and build after the focused tests pass. +- Runtime verification covers 320px, 768px, 1024px, and 1440px; keyboard focus, + copy announcements, long-code reflow, and console output are checked manually. + +## Boundaries + +### Always + +- Join assignments to active Series only by the contract's `seriesId`. +- Keep the full tournament code selectable and copy the unmodified string. +- Preserve native link, button, list, table, heading, and disclosure semantics. +- Use the existing design tokens and icon dependency. + +### Ask First + +- Change the API or public contract. +- Add a dependency or browser-test framework. +- Change tournament-code authorization or visibility policy. +- Deploy, push, or alter CI. + +### Never + +- Infer a Series association from global game numbers. +- Display an adjudicated `0–0` as if it were a played result. +- Expose private facts or fabricate an adjudication reason. +- Hide copy failure or rely on color alone for state. +- Modify unrelated Competition, bracket, or theme behavior. + +## Success Criteria + +- Each active Series appears as a full-width next-match panel containing only its + own ordered code rows. +- Human Korean labels lead raw Series codes, and Series-local set numbers lead + global game numbers. +- Ready Series show a pending score, while adjudicated results show their result + category instead of a numeric score. +- Copy buttons have unique accessible names, 44px targets, visible/live feedback, + and an explicit failure path. +- The roster uses Korean position labels in canonical role order, with the captain + marker close to the player name. +- At most two recent results are expanded by default; older results are available + through a keyboard-accessible disclosure. +- Focused and full tests, lint, build, and responsive runtime review pass. + +## Open Questions + +None. The user approved the audit recommendations and requested implementation.