release/86 #2

Merged
dahyeon merged 108 commits from release/86 into main 2026-07-15 08:56:05 +00:00
4 changed files with 657 additions and 0 deletions
Showing only changes of commit 81b951889f - Show all commits

No files matched your search

@@ -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<void>) | undefined;
export function createTeamSeriesGroups(
activeSeries: readonly SeriesProjection[],
tournamentCodes: readonly TeamTournamentCodeView[],
): TeamSeriesGroup[] {
const codesBySeriesId = new Map<string, TeamTournamentCodeView[]>();
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<TournamentCodeCopyFeedback> {
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<SeriesProjection, { status: "completed" }>[],
): Array<Extract<SeriesProjection, { status: "completed" }>> {
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;
}
@@ -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<SeriesProjection, { status: "completed" }> {
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> = {},
): 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<string | SeriesId>,
): BracketRoundView {
return {
stage,
roundNumber,
displayOrder,
label: `${stage}-${roundNumber}`,
seriesIds: seriesIds.map((id) => id as SeriesId),
};
}
@@ -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.