6.1 KiB
Feature Specification: Fixed Layout Bars
Feature Branch: 022-fixed-layout-bars
Created: 2026-03-09
Status: Draft
Input: User description: "I would like to have the 'add creature' bar as a fixed bottom bar and the bar where we have the current round and next/previous buttons as a top bar. Those should never scroll out of the screen and we should only scroll the combatants in between."
User Scenarios & Testing (mandatory)
User Story 1 - Fixed Navigation and Add-Creature Bars (Priority: P1)
As a DM managing a large encounter with many combatants, I want the round/turn navigation bar pinned to the top of the screen and the add-creature bar pinned to the bottom, so that I can always advance turns and add new creatures without scrolling away from the action.
Why this priority: This is the core of the feature. Without fixed positioning of both bars, the user must scroll to reach essential controls during combat, which interrupts the flow of play.
Independent Test: Can be fully tested by adding enough combatants to cause scrolling, then verifying both bars remain visible while scrolling through the combatant list.
Acceptance Scenarios:
- Given an encounter with enough combatants to overflow the viewport, When the user scrolls through the combatant list, Then the turn navigation bar (Previous / Round X / Next) remains fixed at the top of the encounter area and never scrolls out of view.
- Given an encounter with enough combatants to overflow the viewport, When the user scrolls through the combatant list, Then the add-creature bar remains fixed at the bottom of the encounter area and never scrolls out of view.
- Given an encounter with enough combatants to overflow the viewport, When the user scrolls, Then only the combatant list between the two bars scrolls.
- Given an encounter with few combatants that fit within the viewport, When the user views the tracker, Then the layout still displays the navigation bar at top and add-creature bar at bottom with the combatant list in between (no unnecessary empty space or visual artifacts).
User Story 2 - Consistent Behavior Across Viewports (Priority: P2)
As a DM using different devices (desktop, tablet), I want the fixed-bar layout to work consistently regardless of screen size, so that the experience is reliable on any device I use at the table.
Why this priority: The tracker is used on various devices during play sessions. The fixed layout must adapt to different viewport sizes without breaking.
Independent Test: Can be tested by resizing the browser window to various sizes and verifying the bars stay fixed and the combatant list remains scrollable.
Acceptance Scenarios:
- Given any viewport width, When the encounter tracker is displayed, Then the top navigation bar and bottom add-creature bar remain fixed and the combatant list scrolls independently.
- Given a viewport where the stat block side panel is visible (wide desktop), When the user scrolls the combatant list, Then the fixed bars and scrollable list behave correctly alongside the stat block panel.
Edge Cases
- What happens when there are zero combatants? The top and bottom bars should still be visible with the empty state between them.
- What happens when there is exactly one combatant? No scrolling needed; layout should not look broken.
- What happens when the autocomplete/suggestion dropdown appears above the add-creature input? It should still be accessible and not clipped by the scrollable area.
- What happens when the viewport is very short (e.g., 400px tall)? The combatant list area should still be scrollable, even if only a small portion is visible.
- What happens when the active combatant is scrolled off-screen and the turn changes? The list auto-scrolls to bring the newly active combatant into view smoothly.
Requirements (mandatory)
Functional Requirements
- FR-001: The turn navigation bar (Previous button, round/turn display, Next button) MUST remain fixed at the top of the encounter tracker area and never scroll out of view.
- FR-002: The add-creature bar (name input, add button, bestiary search toggle) MUST remain fixed at the bottom of the encounter tracker area and never scroll out of view.
- FR-003: The combatant list MUST be the only scrollable region between the fixed top and bottom bars.
- FR-004: The scrollable combatant list MUST automatically allow scrolling (touch, wheel, keyboard) when combatants overflow the available vertical space.
- FR-005: The autocomplete suggestion dropdown from the add-creature bar MUST remain fully visible and interactive, not clipped by the scroll container.
- FR-006: The layout MUST preserve existing visual styling, spacing, and responsiveness of all components (turn navigation, combatant rows, action bar, stat block panel).
- FR-007: When the active turn changes (via Next/Previous), the active combatant's row MUST automatically scroll into view if it is not currently visible in the scrollable area.
Success Criteria (mandatory)
Measurable Outcomes
- SC-001: With 20+ combatants in an encounter, the turn navigation bar and add-creature bar remain visible at all scroll positions without any user action beyond normal scrolling.
- SC-002: Users can add a new creature and navigate turns at any point during scrolling without needing to scroll to a specific position first.
- SC-003: The layout renders correctly on viewports from 360px to 2560px wide and 400px to 1440px tall without visual breakage.
- SC-004: Existing functionality (autocomplete suggestions, bestiary search, stat block panel, combatant interactions) continues to work identically after the layout change.
Assumptions
- The "Initiative Tracker" heading can scroll away with the combatant list or be repositioned as needed -- the key fixed elements are only the turn navigation bar and the add-creature bar.
- The stat block side panel (fixed right sidebar on desktop) remains independent of this layout change and continues to function as-is.
- No new data entities or state changes are needed -- this is a purely presentational/layout change.