460c65bf49
Replace the close button and heading with fold/unfold controls that collapse the panel to a slim right-edge tab showing the creature name vertically, and add a pin button (xl+ viewports with creature loaded) that opens the creature in a second left-side panel for simultaneous reference. Fold state is respected on turn change. 19 acceptance tests. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
103 lines
8.1 KiB
Markdown
103 lines
8.1 KiB
Markdown
# 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.
|