Files
lolympus-tournament-support/docs/specs/team-progress-page-ux-refresh.md
T

6.2 KiB
Raw Blame History

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/TeamSeriesCard.tsx owns the page-specific Series summary, leaving bracket/history card geometry and behavior unchanged.
  • 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:

const seriesCodes = tournamentCodesForSeries(
  teamView.tournamentCodes,
  series.seriesId,
);

<button aria-label={`${setLabel} 토너먼트 코드 복사`}>
  복사
</button>

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.
  • Test every page-specific Series lifecycle/outcome branch, including played and administrative draws, so the local summary cannot drift silently.
  • Run the complete web suite, lint, and build after the focused tests pass.
  • When the in-app browser is available, 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, scoped lint, and build pass. Responsive runtime review is recorded separately when the in-app browser is available.

Verification Record

  • Focused view-model tests: 9 passed.
  • Full web suite: 87 passed without skips.
  • Scoped ESLint for all team-progress files: passed.
  • Production TypeScript/Vite build: passed; only the existing large-chunk warning remains.
  • Full repository lint remains blocked by pre-existing errors in unrelated files.
  • Runtime screenshot/keyboard verification was not claimed because the required in-app browser was unavailable in this session.

Open Questions

None. The user approved the audit recommendations and requested implementation.