initiative/specs/034-topbar-redesign/tasks.md

Tasks: Redesign Top Bar with Dedicated Round and Turn Fields

Input: Design documents from /specs/034-topbar-redesign/ Prerequisites: plan.md, spec.md, research.md, data-model.md, quickstart.md

Tests: Not explicitly requested in the feature specification. Tests are included because this is a refactor of an existing component with no prior test coverage — adding tests protects against regressions.

Organization: Tasks are grouped by user story to enable independent implementation and testing of each story.

Format: [ID] [P?] [Story] Description

• [P]: Can run in parallel (different files, no dependencies)
• [Story]: Which user story this task belongs to (e.g., US1, US2, US3)
• Include exact file paths in descriptions

---

Phase 1: Setup

Purpose: No project initialization needed — this is a refactor of an existing component in an established codebase. Skip directly to implementation.

(No tasks in this phase)

---

Phase 2: Foundational (Blocking Prerequisites)

Purpose: No foundational infrastructure changes needed. The existing Encounter type and TurnNavigation component provide everything required. No new dependencies, no data model changes, no new ports or adapters.

(No tasks in this phase)

Checkpoint: Foundation ready — user story implementation can begin immediately.

---

Phase 3: User Story 1 — Scanning Round and Combatant at a Glance (Priority: P1) 🎯 MVP

Goal: Replace the combined "Round N — Name" display with a muted round badge on the left and a prominent centered combatant name, as separate visual elements.

Independent Test: Start an encounter with combatants, verify the round badge appears as a pill near the left side and the combatant name appears centered. Advance turns and confirm both update independently without layout shift.

Implementation for User Story 1

• T001 [US1] Refactor the center status section in apps/web/src/components/turn-navigation.tsx — replace the single <div className="text-center text-sm"> block (lines 42–54) with a three-zone flex layout: (1) left zone containing the previous-turn button and a round badge pill (<span> with rounded-full bg-muted text-muted-foreground text-xs px-2 py-0.5 font-medium showing "R{number}"), (2) center zone (flex-1 min-w-0) with the combatant name as a prominent truncate label, (3) right zone with action buttons and next-turn button (unchanged). The outer container switches from justify-between with inline children to three explicit flex groups.

• T002 [US1] Add unit tests for the refactored round badge and combatant name display in apps/web/src/components/__tests__/turn-navigation.test.tsx — test that: (a) the round badge renders with the correct round number text (e.g., "R1", "R2"), (b) the combatant name renders separately from the round badge with no em dash, (c) the round badge and combatant name are in separate DOM elements, (d) advancing the round updates the badge text, (e) advancing the turn always renders the next combatant's name with no intermediate empty state.

Checkpoint: At this point, the core visual redesign is complete — round and combatant are displayed as separate elements in a three-zone layout.

---

Phase 4: User Story 2 — Consistent Left-Center-Right Layout (Priority: P1)

Goal: Ensure the three-zone layout remains balanced across varying combatant name lengths and viewport widths.

Independent Test: Load encounters with names of varying length ("O", "Goblin", "Ancient Red Dragon Wyrm of the Northern Wastes") and confirm the layout stays balanced. Resize the viewport from 320px to 1920px and verify all zones remain visible.

Implementation for User Story 2

• T003 [P] [US2] Ensure truncation and responsive behavior in apps/web/src/components/turn-navigation.tsx — verify the center zone has min-w-0 and the combatant name element has truncate class applied. Confirm the left and right zones use flex-shrink-0 so they never collapse. Test that the layout handles the full range of name lengths without overflow or button displacement.

• T004 [US2] Add unit tests for layout robustness in apps/web/src/components/__tests__/turn-navigation.test.tsx — test that: (a) a combatant with a very long name (50+ chars) renders with truncation styles (the element has the truncate class), (b) a combatant with a single-character name still renders the three-zone layout correctly, (c) all action buttons remain present and accessible regardless of name length, (d) a combatant name of exactly 40 characters renders without truncation (per SC-004).

Checkpoint: The layout is visually stable across all name lengths and viewport sizes.

---

Phase 5: User Story 3 — No Combatants State (Priority: P2)

Goal: Handle the empty encounter state gracefully in the new three-zone layout.

Independent Test: Create an encounter with no combatants and verify the round badge shows the round number and the center area shows a placeholder message.

Implementation for User Story 3

• T005 [P] [US3] Update the no-combatants branch in apps/web/src/components/turn-navigation.tsx — when activeCombatant is falsy, the round badge still renders with the current round number and the center zone displays "No combatants" as muted placeholder text. Ensure the three-zone layout structure is maintained (not replaced with a single centered span).

• T006 [US3] Add unit test for no-combatants state in apps/web/src/components/__tests__/turn-navigation.test.tsx — test that: (a) when the encounter has no combatants, the round badge still shows the round number, (b) the center area shows "No combatants" placeholder text, (c) navigation buttons are appropriately disabled.

Checkpoint: All user stories are now independently functional.

---

Phase 6: Polish & Cross-Cutting Concerns

Purpose: Final validation and quality gate compliance.

• T007 Run pnpm check to verify all quality gates pass (Biome formatting/linting, TypeScript typecheck, Vitest tests, Knip unused code, jscpd duplication)
• T008 Verify (manual) the component visually in the browser at multiple viewport widths (320px, 768px, 1920px) using pnpm --filter web dev

---

Dependencies & Execution Order

Phase Dependencies

• Setup (Phase 1): Skipped — no setup needed
• Foundational (Phase 2): Skipped — no prerequisites needed
• User Story 1 (Phase 3): Can start immediately — core layout refactor
• User Story 2 (Phase 4): Depends on T001 (the layout must exist before verifying its robustness)
• User Story 3 (Phase 5): Depends on T001 (the three-zone layout must exist before updating the no-combatants branch)
• Polish (Phase 6): Depends on all user stories being complete

User Story Dependencies

• User Story 1 (P1): No dependencies — creates the new layout
• User Story 2 (P1): Depends on US1 (refines the layout created in US1)
• User Story 3 (P2): Depends on US1 (updates the empty state for the new layout)

Within Each User Story

• Implementation before tests (tests verify the new rendering)
• T001 is the critical path — all other tasks depend on the layout refactor

Parallel Opportunities

• T003 and T005 can run in parallel (both depend on T001 but modify different code paths)
• T002, T004, and T006 can be consolidated into a single test file written after all implementation tasks

---

Parallel Example: After T001 Completes

# These can run in parallel after T001 (layout refactor):
Task T003: "Ensure truncation and responsive behavior" (different code path — CSS classes)
Task T005: "Update no-combatants branch" (different conditional branch)

---

Implementation Strategy

MVP First (User Story 1 Only)

1. Complete T001: Core layout refactor (the only required change)
2. Complete T002: Tests for the new layout
3. STOP and VALIDATE: Visual check in browser + pnpm check
4. This alone delivers the full visual redesign

Incremental Delivery

1. T001 → Core three-zone layout with round badge and centered name (MVP!)
2. T003 → Verify truncation and responsive behavior
3. T005 → Update no-combatants state for new layout
4. T002 + T004 + T006 → Full test coverage
5. T007 + T008 → Final quality validation

---

Notes

• All changes are in a single file (turn-navigation.tsx) plus one new test file
• No domain or application layer changes — purely adapter-layer refactor
• The TurnNavigationProps interface is unchanged
• Commit after T001+T002 (MVP), then after T003-T006 (polish), then after T007-T008 (final)