initiative/specs/035-statblock-fold-pin/spec.md

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.