107 lines
8.7 KiB
Markdown
107 lines
8.7 KiB
Markdown
# Feature Specification: Turn Navigation
|
|
|
|
**Feature Branch**: `012-turn-navigation`
|
|
**Created**: 2026-03-05
|
|
**Status**: Draft
|
|
**Input**: User description: "Introduce a previous Turn button and put both, the previous and the next turn buttons at the top of the tracker. Make the UI/UX modern and sleek. Easy to use."
|
|
|
|
## User Scenarios & Testing
|
|
|
|
### User Story 1 - Go Back to the Previous Turn (Priority: P1)
|
|
|
|
As a game master running a combat encounter, I want to go back to the previous combatant's turn so that I can correct mistakes (e.g., a forgotten action, an incorrectly skipped combatant) without restarting the encounter.
|
|
|
|
**Why this priority**: The ability to undo a turn advancement is the core new capability. Without it, game masters must work around mistakes manually, disrupting the flow of combat.
|
|
|
|
**Independent Test**: Can be fully tested as a pure state transition. Given an Encounter and a RetreatTurn action, assert the resulting Encounter state and emitted domain events.
|
|
|
|
**Acceptance Scenarios**:
|
|
|
|
1. **Given** an encounter with combatants [A, B, C], activeIndex 1, roundNumber 1, **When** RetreatTurn, **Then** activeIndex is 0, roundNumber is 1, and a TurnRetreated event is emitted with previousCombatantId B, newCombatantId A, roundNumber 1.
|
|
2. **Given** an encounter with combatants [A, B, C], activeIndex 0, roundNumber 2, **When** RetreatTurn, **Then** activeIndex is 2, roundNumber is 1, and events are emitted: TurnRetreated (previousCombatantId A, newCombatantId C, roundNumber 1) then RoundRetreated (newRoundNumber 1).
|
|
3. **Given** an encounter with combatants [A, B, C], activeIndex 0, roundNumber 1, **When** RetreatTurn, **Then** the operation MUST fail with an error. The encounter is at the very beginning -- there is no previous turn to return to.
|
|
4. **Given** an encounter with a single combatant [A], activeIndex 0, roundNumber 3, **When** RetreatTurn, **Then** activeIndex is 0, roundNumber is 2, and events are emitted: TurnRetreated then RoundRetreated (newRoundNumber 2).
|
|
5. **Given** an encounter with an empty combatant list, **When** RetreatTurn, **Then** the operation MUST fail with an invalid-encounter error. No events are emitted. State is unchanged.
|
|
|
|
---
|
|
|
|
### User Story 2 - Turn Navigation Controls at the Top of the Tracker (Priority: P1)
|
|
|
|
As a game master, I want the Previous Turn and Next Turn buttons placed prominently at the top of the encounter tracker so that I can quickly navigate turns without scrolling to the bottom of a long combatant list.
|
|
|
|
**Why this priority**: Relocating the turn controls to the top directly improves usability -- the most-used combat controls should be immediately visible and accessible.
|
|
|
|
**Independent Test**: Can be fully tested by loading the tracker with combatants and verifying that the turn navigation controls appear above the combatant list and function correctly.
|
|
|
|
**Acceptance Scenarios**:
|
|
|
|
1. **Given** the encounter tracker is displayed, **When** the user looks at the screen, **Then** the Previous Turn and Next Turn buttons are visible at the top of the tracker, above the combatant list.
|
|
2. **Given** the tracker has many combatants requiring scrolling, **When** the user scrolls down, **Then** the turn navigation controls remain accessible at the top (no need to scroll to find them).
|
|
3. **Given** the encounter is at round 1 with the first combatant active, **When** the user views the turn controls, **Then** the Previous Turn button is disabled (visually indicating it cannot be used).
|
|
4. **Given** the encounter has no combatants, **When** the user views the tracker, **Then** the turn navigation controls are hidden or disabled.
|
|
|
|
---
|
|
|
|
### User Story 3 - Modern, Sleek Turn Navigation Design (Priority: P2)
|
|
|
|
As a game master, I want the turn navigation controls to have a clean, modern design with clear visual hierarchy so that I can navigate combat intuitively and confidently.
|
|
|
|
**Why this priority**: A polished design enhances usability and reduces errors during the fast pace of combat. However, functionality comes first.
|
|
|
|
**Independent Test**: Can be fully tested by visually inspecting the turn navigation area and verifying it meets design criteria.
|
|
|
|
**Acceptance Scenarios**:
|
|
|
|
1. **Given** the turn navigation is displayed, **When** the user looks at the controls, **Then** the Previous and Next buttons are visually distinct with clear labels or icons indicating direction.
|
|
2. **Given** the encounter is in progress, **When** the user views the turn navigation area, **Then** the current round number and active combatant name are displayed alongside the navigation controls.
|
|
3. **Given** the Previous Turn action is not available (round 1, first combatant), **When** the user views the Previous button, **Then** the button appears in a disabled state that is visually distinct from the active state.
|
|
|
|
---
|
|
|
|
### Edge Cases
|
|
|
|
- What happens when retreating at the very start of the encounter (round 1, activeIndex 0)? The operation fails with an error; the Previous Turn button is disabled in this state.
|
|
- What happens when retreating past the round boundary? The round number decrements by 1 and activeIndex wraps to the last combatant.
|
|
- What happens with a single combatant at round 1? RetreatTurn fails because there is no previous turn. The Previous Turn button is disabled.
|
|
- What happens when retreating would bring the round number below 1? This cannot happen -- round 1, activeIndex 0 is the earliest possible state and is blocked.
|
|
|
|
## Requirements
|
|
|
|
### Functional Requirements
|
|
|
|
- **FR-001**: The system MUST provide a RetreatTurn operation that moves the active turn to the previous combatant in initiative order.
|
|
- **FR-002**: RetreatTurn MUST decrement activeIndex by 1. When activeIndex would go below 0, it MUST wrap to the last combatant and decrement roundNumber by 1.
|
|
- **FR-003**: RetreatTurn at round 1 with activeIndex 0 MUST fail with an error. This is the earliest possible encounter state.
|
|
- **FR-004**: RetreatTurn on an empty encounter MUST fail with an error without modifying state or emitting events.
|
|
- **FR-005**: RetreatTurn MUST emit a TurnRetreated domain event on success. When the round boundary is crossed (going backward), a RoundRetreated event MUST also be emitted, in order: TurnRetreated first, then RoundRetreated.
|
|
- **FR-006**: RetreatTurn MUST be a pure function of the current encounter state. Given identical input, output MUST be identical.
|
|
- **FR-007**: The Previous Turn and Next Turn buttons MUST be positioned at the top of the encounter tracker, above the combatant list.
|
|
- **FR-008**: The Previous Turn button MUST be disabled when the encounter is at its earliest state (round 1, first combatant active).
|
|
- **FR-009**: Both turn navigation buttons MUST be disabled or hidden when the encounter has no combatants.
|
|
- **FR-010**: The turn navigation area MUST display the current round number and the active combatant's name.
|
|
- **FR-011**: The turn navigation buttons MUST have clear directional indicators (icons, labels, or both) so the user can distinguish Previous from Next at a glance.
|
|
|
|
### Key Entities
|
|
|
|
- **Encounter**: Existing aggregate. Contains combatants, activeIndex, and roundNumber. RetreatTurn operates on this entity.
|
|
- **TurnRetreated (new domain event)**: Emitted when the turn is moved backward. Carries: previousCombatantId, newCombatantId, roundNumber.
|
|
- **RoundRetreated (new domain event)**: Emitted when retreating crosses a round boundary. Carries: newRoundNumber.
|
|
|
|
## Success Criteria
|
|
|
|
### Measurable Outcomes
|
|
|
|
- **SC-001**: A user can reverse a turn advancement in under 1 second using a single click on the Previous Turn button.
|
|
- **SC-002**: Turn navigation controls are visible without scrolling, regardless of the number of combatants in the encounter.
|
|
- **SC-003**: The Previous Turn button is correctly disabled at the earliest encounter state (round 1, first combatant), preventing invalid operations 100% of the time.
|
|
- **SC-004**: All RetreatTurn acceptance scenarios pass as deterministic, pure-function tests with no I/O dependencies.
|
|
- **SC-005**: Users can identify which direction each button navigates (forward or backward) within 1 second of viewing the controls.
|
|
|
|
## Assumptions
|
|
|
|
- RetreatTurn is the inverse of AdvanceTurn. It does not restore any other state (e.g., HP changes made during a combatant's turn are not undone). It only changes the active combatant and round number.
|
|
- The Next Turn button is relocated from the bottom action bar to the new top navigation area. The bottom action bar retains the "Add Combatant" form.
|
|
- The existing AdvanceTurn domain operation and its events remain unchanged.
|
|
- The MVP baseline does not include a full undo/redo stack. RetreatTurn is a simple backward step through initiative order, not a state history undo.
|
|
- The MVP baseline does not include keyboard shortcuts for Previous/Next Turn navigation.
|