# Feature Specification: Stat Block Panel Fold/Unfold and Pin **Feature Branch**: `035-statblock-fold-pin` **Created**: 2026-03-11 **Status**: Draft **Input**: User description: "Stat block panel: fold/unfold and pin to second panel" ## User Scenarios & Testing *(mandatory)* ### User Story 1 - Fold and Unfold Stat Block Panel (Priority: P1) As a DM running an encounter, I want to collapse the stat block panel to a slim tab so I can temporarily reclaim screen space without losing my place, then quickly expand it again to reference creature stats. **Why this priority**: The fold/unfold mechanism replaces the existing close button and is the core interaction model for the redesigned panel. Without it, users have no way to dismiss or restore the panel. **Independent Test**: Can be fully tested by opening a stat block, folding it, verifying the tab appears with the creature name, then unfolding it and verifying the full panel returns with the same creature displayed. **Acceptance Scenarios**: 1. **Given** the stat block panel is open showing a creature, **When** the user clicks the fold button, **Then** the panel slides out to the right edge and a slim vertical tab appears showing the creature's name. 2. **Given** the stat block panel is folded to a tab, **When** the user clicks the tab, **Then** the panel slides back in showing the same creature that was displayed before folding. 3. **Given** the stat block panel is open, **When** the user looks for a close button, **Then** no close button is present — only a fold toggle. 4. **Given** the stat block panel is open, **When** the user looks at the panel header, **Then** no "Stat Block" heading text is visible. 5. **Given** the panel is folding or unfolding, **When** the animation plays, **Then** it completes with a smooth slide transition (~200ms ease-out). --- ### User Story 2 - Pin Creature to Second Panel (Priority: P2) As a DM comparing creatures or referencing one creature while browsing others, I want to pin the current creature to a secondary panel on the left side of the screen so I can keep it visible while browsing different creatures in the right panel. **Why this priority**: Pinning enables a dual-panel workflow that significantly enhances usability for creature comparison and mid-combat reference. It depends on the fold/unfold panel being functional first. **Independent Test**: Can be fully tested by opening a stat block, clicking the pin button, verifying a second panel appears on the left with the same creature, then selecting a different creature and verifying it appears in the right panel while the pinned creature remains on the left. **Acceptance Scenarios**: 1. **Given** the stat block panel is showing a creature on a wide screen, **When** the user clicks the pin button, **Then** the current creature appears in a new panel on the left side of the screen. 2. **Given** a creature is pinned to the left panel, **When** the user clicks a different combatant in the encounter list, **Then** the right panel updates to show the new creature while the left panel continues showing the pinned creature. 3. **Given** a creature is pinned to the left panel, **When** the user clicks the unpin button on the left panel, **Then** the left panel is removed and only the right panel remains. 4. **Given** the user is on a small screen or mobile viewport, **When** the stat block panel is displayed, **Then** the pin button is not visible. --- ### User Story 3 - Fold Behavior with Pinned Panel (Priority: P3) As a DM with a creature pinned, I want to fold the right (browse) panel independently so I can focus on just the pinned creature when needed, or fold both panels to see the full encounter list. **Why this priority**: This is an interaction refinement for the dual-panel state that builds on both P1 and P2 stories. **Independent Test**: Can be tested by pinning a creature, then folding the right panel and verifying the pinned panel remains visible, and vice versa. **Acceptance Scenarios**: 1. **Given** both pinned (left) and browse (right) panels are open, **When** the user folds the right panel, **Then** the left pinned panel remains visible and the right panel collapses to a tab. 2. **Given** the right panel is folded and the left panel is pinned, **When** the user unfolds the right panel, **Then** it slides back showing the last browsed creature. --- ### Edge Cases - What happens when the user pins a creature and then that creature is removed from the encounter? The pinned panel continues displaying the creature's stat block (data is already loaded). - What happens when the user folds the panel and then the active combatant changes (auto-show logic on desktop)? The panel stays folded but updates the selected creature internally, so unfolding shows the current active combatant's stat block. The fold state is respected — the user chose to fold, so advancing turns should not override that. - What happens when the viewport is resized from wide to narrow while a creature is pinned? The pinned (left) panel is hidden and the pin button disappears; if resized back to wide, the pinned panel reappears. - What happens when the user is in bulk import mode and tries to fold? The fold/unfold behavior applies to the bulk import panel identically. - What happens when the panel is showing a source fetch prompt (creature not yet loaded)? The pin button is hidden — pinning only makes sense when a creature is actually displayed. ## Requirements *(mandatory)* ### Functional Requirements - **FR-001**: System MUST replace the close button on the stat block panel with a fold/unfold toggle control. - **FR-002**: System MUST remove the "Stat Block" heading text from the panel header. - **FR-003**: When folded, the panel MUST collapse to a slim vertical tab anchored to the right edge of the screen displaying the creature's name. - **FR-004**: Folding and unfolding MUST use a smooth CSS slide animation (~200ms ease-out). - **FR-005**: The fold/unfold toggle MUST preserve the currently displayed creature — unfolding shows the same creature that was visible when folded. - **FR-006**: The panel MUST include a pin button that copies the current creature to a new panel on the left side of the screen. - **FR-007**: After pinning, the right panel MUST remain active for browsing different creatures independently. - **FR-008**: The pinned (left) panel MUST include an unpin button that removes it when clicked. - **FR-009**: The pin button MUST be hidden on viewports where dual panels would not fit (small screens / mobile). - **FR-010**: On mobile viewports, the existing drawer/backdrop behavior MUST be preserved — fold/unfold replaces only the close button behavior for the desktop layout. ### Key Entities - **Panel State**: Represents whether a stat block panel is expanded, folded, or absent. Each panel (browse and pinned) has independent state. - **Pinned Creature**: The creature whose stat block is locked into the left panel, independent of the browse panel's current selection. ## Success Criteria *(mandatory)* ### Measurable Outcomes - **SC-001**: Users can fold the stat block panel in a single click and unfold it in a single click, with the transition completing in under 300ms. - **SC-002**: Users can pin a creature and browse a different creature's stat block simultaneously, without any additional navigation steps. - **SC-003**: The pinned panel is never visible on screens narrower than the dual-panel breakpoint, ensuring mobile usability is not degraded. - **SC-004**: All fold/unfold and pin/unpin interactions are discoverable through visible button controls without requiring documentation or tooltips. ## Assumptions - The dual-panel breakpoint will be determined by the existing desktop breakpoint (currently 1024px) plus the width needed for two panels. A reasonable default is ~1280px or wider. - The slim folded tab will be oriented vertically with the creature name rotated or truncated to fit a narrow strip (~32-40px wide). - The pinned panel will have the same width and styling as the browse panel but positioned on the left edge. - On mobile, the existing slide-in drawer with backdrop behavior is preserved; the fold/unfold toggle replaces the close button but the backdrop click still dismisses the panel.