# Feature Specification: Bottom Bar Overhaul **Feature Branch**: `036-bottombar-overhaul` **Created**: 2026-03-11 **Status**: Draft **Input**: User description: "Overhaul bottom bar: batch add, stat block view, custom creature fields" ## User Scenarios & Testing *(mandatory)* ### User Story 1 - Batch Add Predefined Creatures (Priority: P1) As a DM, I want to quickly add multiple copies of the same creature from the bestiary so I can set up encounters with groups of identical monsters without repetitive searching and clicking. **Why this priority**: This is the most impactful workflow improvement — setting up encounters with multiple identical creatures (e.g., 4 goblins) is currently tedious, requiring one search-and-add per creature. **Independent Test**: Can be fully tested by searching for a creature, clicking the dropdown entry multiple times to increment count, then confirming — delivers batch-add value independently. **Acceptance Scenarios**: 1. **Given** the search field is focused and the user types a query, **When** results appear in the dropdown, **Then** the dropdown opens automatically as the user types. 2. **Given** the dropdown is showing results, **When** the user clicks on a creature entry, **Then** a count badge showing "1" and a confirm button appear on that row. 3. **Given** a creature entry already shows a count of N, **When** the user clicks that same entry again, **Then** the count increments to N+1. 4. **Given** the user has queued creature A with count 3 and then clicks creature B, **Then** creature A's queue is replaced by creature B with count 1 (only one creature type can be queued at a time). 5. **Given** a creature is queued with count N, **When** the user clicks the confirm button on that row, **Then** N copies of that creature are added to combat and the queue resets. 6. **Given** a creature is queued with count N, **When** the user presses Enter, **Then** N copies of that creature are added to combat and the queue resets. --- ### User Story 2 - Custom Creature with Optional Fields (Priority: P2) As a DM, I want to type a custom creature name that doesn't match the bestiary and optionally provide initiative, AC, and max HP values so I can add homebrew or improvised creatures with pre-filled stats. **Why this priority**: Supports the common case of adding homebrew or one-off creatures with known stats, reducing the need to manually edit each field after adding. **Independent Test**: Can be tested by typing a non-matching name, optionally filling in the extra fields, and adding — the creature appears in combat with the provided values. **Acceptance Scenarios**: 1. **Given** the user types a name that has no bestiary match, **When** the dropdown shows no results (or the query is too short for bestiary matches), **Then** optional input fields for initiative, AC, and max HP appear below or beside the name field. 2. **Given** the optional fields are visible, **When** the user leaves all optional fields empty and submits, **Then** the creature is added with only the name (no stats pre-filled). 3. **Given** the optional fields are visible, **When** the user fills in some or all fields and submits, **Then** the creature is added with the provided values applied. 4. **Given** the optional fields are visible, **Then** each field has a clear label (e.g., "Initiative", "AC", "Max HP") so the user knows what each input is for. --- ### User Story 3 - Stat Block Viewer from Dropdown (Priority: P3) As a DM, I want to preview a creature's stat block directly from the search dropdown so I can review creature details before deciding to add them to the encounter. **Why this priority**: Enhances the search experience by allowing stat block previews without committing to adding the creature, but is not essential for the core add-creature workflow. **Independent Test**: Can be tested by searching for a creature in the dropdown, triggering the stat block view for the highlighted/selected entry, and verifying the stat block panel opens with the correct creature data. **Acceptance Scenarios**: 1. **Given** the dropdown is showing bestiary results, **When** the user clicks the search/view button (repurposed from the current search icon), **Then** the stat block for the currently focused/highlighted creature in the dropdown opens in the stat block panel. 2. **Given** no creature is focused in the dropdown, **When** the user clicks the stat block view button, **Then** nothing happens (button is disabled or no-op). --- ### User Story 4 - Improved Search Hint Text (Priority: P3) As a DM, I want the search field to have clear, action-oriented placeholder text so I immediately understand its purpose. **Why this priority**: Small UX polish that improves discoverability but does not change functionality. **Independent Test**: Can be verified by inspecting the placeholder text on the search input field. **Acceptance Scenarios**: 1. **Given** the bottom bar is visible, **When** the search field is empty, **Then** the placeholder reads action-oriented text such as "Search creatures to add...". --- ### Edge Cases - What happens when the user queues a creature, then changes the search query? The queue resets when the queued creature is no longer visible in the results. - What happens when the user queues a count and then presses Escape? The queue resets and the dropdown closes. - What happens if the user types a name that initially matches the bestiary but then extends it to no longer match? The optional custom fields appear once there are no bestiary matches. - What happens when the user submits a custom creature with non-numeric values in the optional fields? Invalid numeric input is ignored (treated as empty). ## Requirements *(mandatory)* ### Functional Requirements - **FR-001**: The search field placeholder MUST display action-oriented hint text (e.g., "Search creatures to add..."). - **FR-002**: The dropdown MUST open automatically when the user types at least 2 characters. - **FR-003**: Clicking a bestiary dropdown entry MUST show a count badge (starting at 1) and a confirm button on that row. - **FR-004**: Clicking the same entry again MUST increment the count by 1. - **FR-005**: Only one creature type MAY be queued at a time; selecting a different creature MUST replace the current queue. - **FR-006**: Confirming the queue MUST add N copies of the selected creature to combat and reset the queue state. - **FR-007**: The existing search button MUST be repurposed to open the stat block for the currently focused/selected creature in the dropdown. - **FR-008**: When no bestiary match exists for the typed name, the system MUST show optional input fields for initiative, AC, and max HP. - **FR-009**: Custom creatures MUST be addable with or without the optional fields filled in. - **FR-010**: Each optional field MUST have a visible label indicating its purpose. - **FR-011**: Pressing Enter with a queued creature MUST behave the same as clicking the confirm button. ### Key Entities - **Queued Creature**: A transient UI-only state representing a bestiary creature selected for batch-add, containing the creature reference and a count (1+). - **Custom Creature Input**: A transient UI-only state representing a user-typed creature name with optional initiative (number), AC (number), and max HP (number) fields. ## Success Criteria *(mandatory)* ### Measurable Outcomes - **SC-001**: A DM can add 4 identical creatures to combat in 3 steps (type search query, click creature entry 4 times to set count, confirm) — down from 4 separate search-and-add cycles. - **SC-002**: Custom creatures can be added with pre-filled stats in a single form submission without needing to edit stats after adding. - **SC-003**: Stat block preview is accessible directly from the search dropdown without leaving the add-creature flow. - **SC-004**: All existing add-creature functionality continues to work (no regression in custom name or bestiary-based adding). ## Assumptions - The batch-add count has no upper limit; the user can click as many times as they want to increment the count. - The optional fields for custom creatures (initiative, AC, max HP) accept numeric input only; non-numeric input is ignored. - The stat block viewer reuses the existing stat block panel infrastructure (no new panel type needed). - "Focused/selected creature" for the stat block view button refers to the keyboard-highlighted or last-clicked creature in the dropdown. - The batch-add queue is purely ephemeral UI state — it is not persisted.