test(web): specify team progress presentation
This commit is contained in:
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.
|
||||
@@ -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.
|
||||
Reference in new issue
Block a user