134 lines
8.9 KiB
Markdown
134 lines
8.9 KiB
Markdown
# Feature Specification: Quick HP Input
|
|
|
|
**Feature Branch**: `011-quick-hp-input`
|
|
**Created**: 2026-03-05
|
|
**Status**: Draft
|
|
**Input**: User description: "Add a feature to quickly input healing and damage numbers and subtract from the current HP on input with nice ux and sleek design. Make it easy to use in the heat of combat."
|
|
|
|
## User Scenarios & Testing
|
|
|
|
### User Story 1 - Apply Damage via Quick Input (Priority: P1)
|
|
|
|
As a game master in the heat of combat, I want to type a damage number and immediately apply it to a combatant's HP so that I can keep up with fast-paced encounters without mental arithmetic.
|
|
|
|
**Why this priority**: Applying damage is the most frequent HP interaction during combat. A dedicated numeric input for damage amounts is the core value proposition.
|
|
|
|
**Independent Test**: Can be fully tested by having a combatant with HP set, entering a damage number, and verifying current HP decreases by that amount.
|
|
|
|
**Acceptance Scenarios**:
|
|
|
|
1. **Given** a combatant has 20/20 HP, **When** the user focuses the damage input and enters 7, **Then** current HP decreases to 13.
|
|
2. **Given** a combatant has 10/20 HP, **When** the user enters damage of 15, **Then** current HP is clamped to 0 (not negative).
|
|
3. **Given** a combatant has 5/20 HP, **When** the user enters damage of 0, **Then** the input is rejected and HP remains unchanged.
|
|
4. **Given** a combatant has 20/20 HP, **When** the user enters damage and confirms, **Then** the input field clears and is ready for the next entry.
|
|
|
|
---
|
|
|
|
### User Story 2 - Apply Healing via Quick Input (Priority: P1)
|
|
|
|
As a game master, I want to type a healing number and immediately apply it to a combatant's HP so that I can process healing spells and potions quickly.
|
|
|
|
**Why this priority**: Healing is the second most common HP interaction during combat and completes the damage/heal pair.
|
|
|
|
**Independent Test**: Can be fully tested by having a combatant with reduced HP, entering a healing number, and verifying current HP increases by that amount.
|
|
|
|
**Acceptance Scenarios**:
|
|
|
|
1. **Given** a combatant has 10/20 HP, **When** the user focuses the heal input and enters 5, **Then** current HP increases to 15.
|
|
2. **Given** a combatant has 18/20 HP, **When** the user enters healing of 10, **Then** current HP is clamped to 20 (max HP).
|
|
3. **Given** a combatant has 20/20 HP, **When** the user enters healing of 5, **Then** current HP remains at 20.
|
|
4. **Given** a combatant has 0/20 HP, **When** the user enters healing of 8, **Then** current HP increases to 8.
|
|
|
|
---
|
|
|
|
### User Story 3 - Toggle Between Damage and Heal Modes (Priority: P1)
|
|
|
|
As a game master, I want a clear and fast way to switch between applying damage and healing so that I don't accidentally heal when I mean to damage (or vice versa).
|
|
|
|
**Why this priority**: Mode clarity is essential to prevent errors during fast-paced combat. A misapplied heal or damage can disrupt the game.
|
|
|
|
**Independent Test**: Can be fully tested by toggling between modes and verifying the correct operation is applied.
|
|
|
|
**Acceptance Scenarios**:
|
|
|
|
1. **Given** the quick input is in damage mode, **When** the user toggles to heal mode, **Then** the input visually indicates heal mode and subsequent entries add to HP.
|
|
2. **Given** the quick input is in heal mode, **When** the user toggles to damage mode, **Then** the input visually indicates damage mode and subsequent entries subtract from HP.
|
|
3. **Given** the quick input is active, **When** the user looks at the input, **Then** the current mode (damage or heal) is clearly distinguishable at a glance.
|
|
|
|
---
|
|
|
|
### User Story 4 - Keyboard-Driven Workflow (Priority: P2)
|
|
|
|
As a game master, I want to enter damage/healing values using only the keyboard so that I can work as fast as possible during tense combat moments.
|
|
|
|
**Why this priority**: Speed is critical during combat encounters. Mouse-only interactions slow down the game master.
|
|
|
|
**Independent Test**: Can be fully tested by using only keyboard interactions to apply damage and healing values.
|
|
|
|
**Acceptance Scenarios**:
|
|
|
|
1. **Given** the quick input is focused, **When** the user types a number and presses Enter, **Then** the value is applied immediately and the input clears.
|
|
2. **Given** the quick input is focused, **When** the user presses Escape, **Then** the input is dismissed without applying any change.
|
|
3. **Given** the quick input is focused in damage mode, **When** the user presses Tab, **Then** the mode toggles to heal (or vice versa).
|
|
|
|
---
|
|
|
|
### Edge Cases
|
|
|
|
- What happens when the user enters a non-numeric value? The input rejects non-numeric characters; only digits are accepted.
|
|
- 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 quick input controls are not available 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 rapidly enters multiple values? Each entry is applied sequentially; no values are lost or merged.
|
|
|
|
## Clarifications
|
|
|
|
### Session 2026-03-05
|
|
|
|
- Q: How is the quick input presented per combatant? → A: Always visible inline in each combatant row in a compact resting state; becomes fully interactive on focus. No extra click needed to reveal it.
|
|
- Q: Do +/- 1 buttons currently exist? → A: No. The +/- 1 buttons were removed in a prior iteration and do not exist in the current product.
|
|
- Q: Should direct editing of the current HP absolute value still be possible? → A: Yes. Keep direct HP entry alongside the new quick damage/heal input. Both methods are available.
|
|
|
|
## Requirements
|
|
|
|
### Functional Requirements
|
|
|
|
- **FR-001**: The system MUST provide an always-visible inline numeric input per combatant for entering damage and healing amounts. The input MUST be in a compact resting state and become fully interactive on focus.
|
|
- **FR-002**: The system MUST support two modes: damage (subtracts from current HP) and heal (adds to current HP).
|
|
- **FR-003**: Damage mode MUST be the default mode when the input is first activated.
|
|
- **FR-004**: The user MUST be able to toggle between damage and heal modes with a single interaction.
|
|
- **FR-005**: When a damage value is confirmed, the system MUST subtract the entered amount from the combatant's current HP, clamping to 0.
|
|
- **FR-006**: When a healing value is confirmed, the system MUST add the entered amount to the combatant's current HP, clamping to max HP.
|
|
- **FR-007**: After a value is confirmed, the input MUST clear automatically to accept the next entry.
|
|
- **FR-008**: The input MUST only accept positive integers. Zero, negative numbers, and non-numeric input MUST be rejected.
|
|
- **FR-009**: The input MUST be confirmable via Enter key press.
|
|
- **FR-010**: The input MUST be dismissable via Escape key without applying changes.
|
|
- **FR-011**: The current mode MUST be visually distinct -- damage and heal modes MUST have clearly different visual treatments (color, icon, or label).
|
|
- **FR-012**: The quick input MUST only be available for combatants that have HP tracking active (max HP is set).
|
|
- **FR-013**: The quick input is the primary method for adjusting current HP during combat. Direct editing of the current HP absolute value MUST remain available alongside the quick input.
|
|
- **FR-014**: The design MUST be optimized for speed of use during combat -- minimal clicks, clear affordances, and immediate feedback.
|
|
- **FR-015**: The direct HP entry and the quick damage/heal input MUST coexist without conflict. Direct entry sets an absolute value; quick input applies a delta.
|
|
|
|
### Key Entities
|
|
|
|
- **HP Adjustment**: A value applied to a combatant's current HP. Has an amount (positive integer) and a direction (damage or heal).
|
|
|
|
## Success Criteria
|
|
|
|
### Measurable Outcomes
|
|
|
|
- **SC-001**: A user can apply a damage or healing value to a combatant in under 3 seconds (type number, confirm).
|
|
- **SC-002**: Current HP never exceeds max HP or drops below 0 after any quick input operation.
|
|
- **SC-003**: The active mode (damage or heal) is identifiable within 1 second of looking at the interface.
|
|
- **SC-004**: Users can complete a full damage/heal cycle (apply damage, switch mode, apply healing) using only the keyboard.
|
|
- **SC-005**: The quick input workflow requires no more than 2 interactions to apply a value (enter number + confirm).
|
|
|
|
## Assumptions
|
|
|
|
- The quick input is the primary HP adjustment method during combat. There are no existing +/- buttons. 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 damage resistance/vulnerability calculation in the MVP baseline.
|
|
- There is no hit log or damage history in the MVP baseline.
|
|
- The Tab key toggling between damage/heal mode is an assumption for keyboard workflow. The exact keybinding is an implementation detail.
|