test(web): specify team progress presentation

This commit is contained in:
dahyeon committed 2026-07-13 21:16:23 -07:00
1 parent 96bae0ce28
commit 81b951889f
4 files changed
+657

No files matched your search

@@ -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.
+133
View File
@@ -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,
);
<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.
- 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.