105 lines
6.9 KiB
Markdown
105 lines
6.9 KiB
Markdown
# Feature Specification: Inline HP Delta Input
|
|
|
|
**Feature Branch**: `014-inline-hp-delta`
|
|
**Created**: 2026-03-05
|
|
**Status**: Draft
|
|
**Input**: User description: "change the quick hp input to be an inline HP delta input per combatant. Users type a number and press Enter to apply damage by default, or click small damage/heal buttons to apply the value explicitly. Clear the input after applying. No toggle for damage and heal anymore."
|
|
|
|
## User Scenarios & Testing
|
|
|
|
### User Story 1 - Apply Damage via Enter Key (Priority: P1)
|
|
|
|
As a game master in the heat of combat, I want to type a damage number and press Enter to immediately subtract it from a combatant's HP, so that damage application is as fast as possible with minimal interaction.
|
|
|
|
**Why this priority**: Damage is the most frequent HP change during combat. Enter-to-damage is the fastest possible workflow for the most common action.
|
|
|
|
**Independent Test**: Can be fully tested by having a combatant with HP, typing a number, pressing Enter, and verifying HP decreases.
|
|
|
|
**Acceptance Scenarios**:
|
|
|
|
1. **Given** a combatant has 20/20 HP, **When** the user types 7 into the delta input and presses Enter, **Then** current HP decreases to 13.
|
|
2. **Given** a combatant has 10/20 HP, **When** the user types 15 and presses Enter, **Then** current HP is clamped to 0 (not negative).
|
|
3. **Given** a combatant has 20/20 HP, **When** the user types a number and presses Enter, **Then** the input field clears and is ready for the next entry.
|
|
4. **Given** a combatant has 5/20 HP, **When** the user types 0 and presses Enter, **Then** the input is rejected and HP remains unchanged.
|
|
|
|
---
|
|
|
|
### User Story 2 - Apply Damage or Heal via Explicit Buttons (Priority: P1)
|
|
|
|
As a game master, I want small damage and heal buttons next to the input so that I can explicitly choose whether to apply the entered value as damage or healing.
|
|
|
|
**Why this priority**: While Enter defaults to damage, users still need a way to heal. Explicit buttons remove ambiguity and eliminate the need for a mode toggle.
|
|
|
|
**Independent Test**: Can be fully tested by typing a number and clicking the heal button, verifying HP increases.
|
|
|
|
**Acceptance Scenarios**:
|
|
|
|
1. **Given** a combatant has 10/20 HP and the user has typed 5, **When** the user clicks the heal button, **Then** current HP increases to 15 and the input clears.
|
|
2. **Given** a combatant has 18/20 HP and the user has typed 10, **When** the user clicks the heal button, **Then** current HP is clamped to 20 (max HP) and the input clears.
|
|
3. **Given** a combatant has 20/20 HP and the user has typed 7, **When** the user clicks the damage button, **Then** current HP decreases to 13 and the input clears.
|
|
4. **Given** a combatant has 0/20 HP and the user has typed 8, **When** the user clicks the heal button, **Then** current HP increases to 8 and the input clears.
|
|
|
|
---
|
|
|
|
### User Story 3 - Keyboard-Driven Workflow (Priority: P2)
|
|
|
|
As a game master, I want to use only the keyboard to apply damage quickly so that I can keep up with fast-paced combat without reaching for the mouse.
|
|
|
|
**Why this priority**: Speed is critical during combat encounters. The keyboard workflow should cover the most common action (damage) end-to-end.
|
|
|
|
**Independent Test**: Can be fully tested by using only keyboard interactions to apply damage values.
|
|
|
|
**Acceptance Scenarios**:
|
|
|
|
1. **Given** the delta input is focused, **When** the user types a number and presses Enter, **Then** damage is applied immediately and the input clears.
|
|
2. **Given** the delta input is focused, **When** the user presses Escape, **Then** the input value is cleared without applying any change.
|
|
|
|
---
|
|
|
|
### Edge Cases
|
|
|
|
- What happens when the user enters a non-numeric value? The input only accepts digits; non-numeric characters are rejected.
|
|
- What happens when the user enters a very large number (e.g., 99999)? The value is applied normally; clamping to 0 or max HP ensures no invalid state.
|
|
- What happens when the combatant has no HP tracking (no max HP set)? The delta input is not shown for that combatant.
|
|
- What happens when the user submits an empty input? No change is applied; the input remains ready for the next entry.
|
|
- What happens when the user clicks a button with an empty input? No change is applied.
|
|
- What happens when the user rapidly enters multiple values? Each entry is applied sequentially; no values are lost or merged.
|
|
|
|
## Requirements
|
|
|
|
### Functional Requirements
|
|
|
|
- **FR-001**: The system MUST provide an inline numeric input per combatant for entering HP delta amounts.
|
|
- **FR-002**: When the user types a number and presses Enter, the system MUST apply the value as damage (subtract from current HP), clamping to 0.
|
|
- **FR-003**: The system MUST provide a small damage button that applies the entered value as damage (subtract from current HP), clamping to 0.
|
|
- **FR-004**: The system MUST provide a small heal button that applies the entered value as healing (add to current HP), clamping to max HP.
|
|
- **FR-005**: After any value is applied (via Enter or button click), the input MUST clear automatically.
|
|
- **FR-006**: The input MUST only accept positive integers. Zero, negative numbers, and non-numeric input MUST be rejected.
|
|
- **FR-007**: Pressing Escape while the input is focused MUST clear the input value without applying any change.
|
|
- **FR-008**: The delta input MUST only be available for combatants that have HP tracking active (max HP is set).
|
|
- **FR-009**: There MUST NOT be a toggle between damage and heal modes. The input is mode-free; the action is determined by which button is clicked or by pressing Enter (which defaults to damage).
|
|
- **FR-010**: Direct editing of the current HP absolute value MUST remain available alongside the delta input.
|
|
- **FR-011**: The damage and heal buttons MUST be visually distinct from each other (e.g., different colors or icons).
|
|
|
|
### Key Entities
|
|
|
|
- **HP Delta**: A numeric value entered by the user, applied as either damage or healing to a combatant's current HP.
|
|
|
|
## Success Criteria
|
|
|
|
### Measurable Outcomes
|
|
|
|
- **SC-001**: A user can apply damage to a combatant in 2 interactions or fewer (type number + press Enter).
|
|
- **SC-002**: A user can apply healing to a combatant in 3 interactions or fewer (type number + click heal button).
|
|
- **SC-003**: Current HP never exceeds max HP or drops below 0 after any delta input operation.
|
|
- **SC-004**: No mode toggle exists in the interface -- damage and heal are always available as distinct actions.
|
|
|
|
## Assumptions
|
|
|
|
- This feature replaces the existing quick HP input (011-quick-hp-input) which used a damage/heal mode toggle. The toggle is removed in favor of explicit actions.
|
|
- Enter key defaults to damage because damage is the most frequent HP change during combat.
|
|
- Direct HP entry (absolute value) remains available for overrides and corrections.
|
|
- There is no undo/redo for HP changes in the MVP baseline.
|
|
- There is no damage type tracking (fire, slashing, etc.) in the MVP baseline.
|
|
- There is no hit log or damage history in the MVP baseline.
|