151 lines
6.5 KiB
Markdown
151 lines
6.5 KiB
Markdown
# 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.
|
||
- Use the bracket's canonical visible round names from Competition round metadata:
|
||
upper round 1 is `브래킷 1R`, later upper rounds are `브래킷 상위 nR`, and
|
||
lower rounds are `브래킷 하위 nR`. 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/double-elimination-bracket-layout.ts`
|
||
remains the canonical source for visible bracket round names.
|
||
- `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:
|
||
|
||
```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 bracket-aligned 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.
|
||
- Bracket-aligned 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: 88 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.
|