Implement the 022-fixed-layout-bars feature that pins turn navigation to the top and add-creature bar to the bottom of the encounter tracker with only the combatant list scrolling between them, and auto-scrolls to the active combatant on turn change

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>
2026-03-09 11:36:59 +01:00
parent fa078be2f9
commit 11c4c0237e
10 changed files with 464 additions and 57 deletions
--- a/specs/022-fixed-layout-bars/plan.md
+++ b/specs/022-fixed-layout-bars/plan.md
@@ -0,0 +1,112 @@
+# Implementation Plan: Fixed Layout Bars
+
+**Branch**: `022-fixed-layout-bars` | **Date**: 2026-03-09 | **Spec**: [spec.md](./spec.md)
+**Input**: Feature specification from `/specs/022-fixed-layout-bars/spec.md`
+
+## Summary
+
+Pin the turn navigation bar to the top and the add-creature action bar to the bottom of the encounter tracker, making only the combatant list scrollable between them. This is achieved by converting the current single-scroll page layout into a CSS flexbox three-zone layout within the existing `h-screen` container.
+
+## Technical Context
+
+**Language/Version**: TypeScript 5.8 (strict mode, verbatimModuleSyntax) + React 19, Tailwind CSS v4
+**Primary Dependencies**: React 19, Tailwind CSS v4, Vite 6
+**Storage**: N/A (no storage changes -- purely presentational)
+**Testing**: Vitest (existing tests must continue to pass; no new domain/application tests needed)
+**Target Platform**: Web browser (desktop and tablet)
+**Project Type**: Web application (single-page app)
+**Performance Goals**: No performance impact -- CSS-only layout change
+**Constraints**: Must not break existing autocomplete dropdown, stat block panel, or responsive behavior
+**Scale/Scope**: Single file change (App.tsx layout restructure), possible minor adjustments to ActionBar
+
+## Constitution Check
+
+*GATE: Must pass before Phase 0 research. Re-check after Phase 1 design.*
+
+| Principle | Status | Notes |
+|-----------|--------|-------|
+| I. Deterministic Domain Core | PASS | No domain changes |
+| II. Layered Architecture | PASS | Change is purely in the adapter/UI layer |
+| III. Agent Boundary | N/A | No agent features involved |
+| IV. Clarification-First | PASS | Spec assumptions documented; no ambiguity remains |
+| V. Escalation Gates | PASS | Implementation stays within spec scope |
+| VI. MVP Baseline Language | PASS | No scope exclusions needed |
+| VII. No Gameplay Rules | PASS | No gameplay logic involved |
+| Merge Gate | PASS | `pnpm check` will be run before commit |
+
+**Post-design re-check**: All gates still pass. No data model, contracts, or domain changes introduced.
+
+## Project Structure
+
+### Documentation (this feature)
+
+```text
+specs/022-fixed-layout-bars/
+├── plan.md              # This file
+├── research.md          # Layout strategy research
+├── quickstart.md        # Development quickstart
+├── spec.md              # Feature specification
+└── checklists/
+    └── requirements.md  # Spec quality checklist
+```
+
+### Source Code (repository root)
+
+```text
+apps/web/src/
+├── App.tsx                          # PRIMARY: Layout restructure (flex zones), auto-scroll on turn change
+└── components/
+    ├── combatant-row.tsx            # Minor: accept ref prop for auto-scroll
+    ├── turn-navigation.tsx          # No changes expected (flex-shrink-0 applied by parent)
+    └── action-bar.tsx               # Minor: verify dropdown not clipped by new layout
+```
+
+**Structure Decision**: No new files or directories. The change restructures the existing layout in App.tsx by wrapping the three sections (TurnNavigation, combatant list, ActionBar) in a flex column where top and bottom are non-shrinkable and the middle is the sole scrollable area.
+
+## Design
+
+### Current Layout (App.tsx)
+
+```
+div.h-screen.overflow-y-auto          ← entire page scrolls
+  div.mx-auto.max-w-2xl.flex-col.gap-6
+    h1 "Initiative Tracker"
+    TurnNavigation                     ← scrolls with page
+    combatant list                     ← scrolls with page
+    ActionBar                          ← scrolls with page
+  StatBlockPanel (sibling, fixed)
+```
+
+### Target Layout (App.tsx)
+
+```
+div.h-screen.flex.flex-col             ← no overflow on root
+  div.mx-auto.max-w-2xl.flex-1.flex-col.min-h-0
+    TurnNavigation (flex-shrink-0)     ← fixed at top
+    div.flex-1.overflow-y-auto         ← only this scrolls
+      h1 "Initiative Tracker"
+      combatant list
+    ActionBar (flex-shrink-0)          ← fixed at bottom
+  StatBlockPanel (sibling, fixed)      ← unchanged
+```
+
+### Key CSS Changes
+
+1. **Root container**: Remove `overflow-y-auto`, add `flex flex-col`
+2. **Inner wrapper**: Add `flex-1 min-h-0` (min-h-0 is critical for flex children to shrink below content size)
+3. **TurnNavigation wrapper**: `flex-shrink-0` to prevent compression
+4. **Scrollable area**: New wrapper `div` with `flex-1 overflow-y-auto` containing the heading and combatant list
+5. **ActionBar wrapper**: `flex-shrink-0` to prevent compression
+6. **Padding**: Move `py-8` from the outer wrapper to the scrollable inner area; top/bottom bars get their own padding
+
+### Auto-Scroll on Turn Change
+
+When `encounter.activeIndex` changes, the active combatant's row scrolls into view using `scrollIntoView({ block: "nearest", behavior: "smooth" })`. This only scrolls if the row is off-screen (`block: "nearest"`), so no jarring jumps occur when the active row is already visible. Implemented via a `ref` on the active `CombatantRow` and a `useEffect` keyed on `activeIndex`.
+
+### Autocomplete Dropdown
+
+The ActionBar's suggestion dropdown uses `absolute bottom-full z-50`. Since ActionBar will be a flex-shrink-0 child at the bottom of the flex container (not inside the overflow-y-auto area), the dropdown will render upward overlaying the scrollable area. The `z-50` ensures it stays above combatant rows. The dropdown's parent container has `position: relative`, so no clipping from `overflow-y-auto` occurs (the dropdown is outside that container).
+
+## Complexity Tracking
+
+No constitution violations. No complexity justifications needed.