# Implementation Plan

## Validation Checklist

- [x] All specification file paths are correct and exist
- [x] Context priming section is complete
- [x] All implementation phases are defined
- [x] Each phase follows TDD: Prime → Test → Implement → Validate
- [x] Dependencies between phases are clear (no circular dependencies)
- [x] Parallel work is properly tagged with `[parallel: true]`
- [x] Activity hints provided for specialist selection `[activity: type]`
- [x] Every phase references relevant SDD sections
- [x] Every test references PRD acceptance criteria
- [x] Integration & E2E tests defined in final phase
- [x] Project commands match actual project setup
- [x] A developer could follow this plan independently
- [x] All SDD-defined interfaces are implemented
- [x] Analytics tracking events are instrumented
- [x] Accessibility features (reduced motion, ARIA) are included

---

## Codex Review Notes (2026-02-07)

### Blockers Resolved
- ✅ Added analytics event instrumentation tasks (Phase 2)
- ✅ Added all SDD-defined interfaces (.sidebar-expanded, .sidebar-animating, etc.)
- ✅ Added store picker abbreviated/full state handling
- ✅ Added tooltip 300ms delay configuration

### Important Items Addressed
- ✅ Added reduced motion CSS support
- ✅ Added active menu indicator validation
- ✅ Added PRD edge case handling (cursor-on-load, dropdown, page nav)
- ✅ Documented deviation: JS uses constants for timing (not CSS vars) for simplicity
- ✅ Documented deviation: Using width transitions (not transform) per standard sidebar patterns

### Scope Clarifications
- Touch device tap-to-toggle (PRD Could-have) is **out of scope** for this implementation phase

---

## Specification Compliance Guidelines

### How to Ensure Specification Adherence

1. **Before Each Phase**: Read the referenced SDD/PRD sections
2. **During Implementation**: Use exact CSS variable names and class names from SDD
3. **After Each Task**: Test in browser across all supported viewports
4. **Phase Completion**: Verify all acceptance criteria from PRD

### Deviation Protocol

If implementation cannot follow specification exactly:
1. Document the deviation in this plan
2. Get approval before proceeding
3. Update SDD if the deviation is an improvement
4. Never deviate without documentation

## Metadata Reference

- `[parallel: true]` - Tasks that can run concurrently
- `[component: component-name]` - For multi-component features
- `[ref: document/section; lines: 1, 2-3]` - Links to specifications
- `[activity: type]` - Activity hint for specialist agent selection

---

## Context Priming

*GATE: You MUST fully read all files mentioned in this section before starting any implementation.*

**Specification**:

- `docs/specs/034-collapsible-sidebar-menu/product-requirements.md` - Product Requirements
- `docs/specs/034-collapsible-sidebar-menu/solution-design.md` - Solution Design

**Key Files to Modify**:

- `public_html/css/admin/tokens.css` - Add sidebar dimension variables
- `public_html/css/admin/admin-theme.css` - Add collapsible sidebar styles
- `public_html/js/sb-admin-2.js` - Add SidebarController
- `userfrosting/templates/themes/default/menus/sidebar.html` - Add pin button, data attributes

**Key Design Decisions** (from SDD):

1. **CSS-first approach**: CSS transitions as primary mechanism, JS only for timing
2. **Collapsed by default**: Sidebar starts at 64px on desktop
3. **localStorage for pin state**: Persist user preference client-side
4. **Bootstrap tooltips**: Reuse for collapsed icon labels
5. **64px collapsed width**: Industry standard pattern

**Implementation Context**:

- Build CSS: `php userfrosting/conductor build-css --minify`
- Watch CSS: `php userfrosting/conductor build-css --watch`
- Test deployment: `./deploy.sh`
- No automated UI tests - manual browser testing required

**Patterns to Follow**:

- Use CSS custom properties from `tokens.css`
- Follow existing JS patterns in `sb-admin-2.js`
- MetisMenu integration must be preserved

---

## Implementation Phases

### Phase 1: CSS Foundation - Design Tokens & Base Styles

- [ ] **T1 Add CSS Variables & Collapsed State Styles**

    - [ ] T1.1 Prime Context
        - [ ] T1.1.1 Read SDD Interface Specifications `[ref: solution-design.md; CSS custom properties interface]`
        - [ ] T1.1.2 Read current sidebar styles `[ref: public_html/css/admin/admin-theme.css; lines: 1698-2020]`
        - [ ] T1.1.3 Read design tokens file `[ref: public_html/css/admin/tokens.css]`

    - [ ] T1.2 Write Tests (Manual Browser Tests)
        - [ ] T1.2.1 Create test checklist: `.sidebar-collapsed` class reduces width to 64px `[ref: PRD/Feature 1: Collapsed Default State]` `[activity: frontend]`
        - [ ] T1.2.2 Create test checklist: `#page-wrapper` margin adjusts with sidebar `[ref: PRD/Feature 1]` `[activity: frontend]`
        - [ ] T1.2.3 Create test checklist: Text labels hidden in collapsed state `[activity: frontend]`
        - [ ] T1.2.4 Create test checklist: Active menu indicator visible in collapsed state `[ref: PRD/Feature 1]` `[activity: frontend]`
        - [ ] T1.2.5 Create test checklist: Store picker shows abbreviated typeNum in collapsed state `[ref: PRD/Feature 1]` `[activity: frontend]`

    - [ ] T1.3 Implement CSS Tokens `[activity: frontend]`
        - [ ] T1.3.1 Add to `tokens.css`:
            ```css
            --sidebar-width-collapsed: 64px;
            --sidebar-width-expanded: 250px;
            --sidebar-transition-duration: 200ms;
            --sidebar-hover-delay: 150ms;
            --sidebar-leave-delay: 200ms;
            ```
        - [ ] T1.3.2 Verify tokens follow existing naming convention in file

    - [ ] T1.4 Implement Collapsed Styles `[activity: frontend]`
        - [ ] T1.4.1 Add `.sidebar-wrapper` base transition (width, ease-out) with `will-change: width`
        - [ ] T1.4.2 Add `.sidebar-wrapper.sidebar-collapsed` width rule (64px)
        - [ ] T1.4.3 Add `.sidebar-wrapper.sidebar-expanded` width rule (250px) `[ref: SDD/CSS Class Interface]`
        - [ ] T1.4.4 Add `.sidebar-wrapper.sidebar-animating` class for transition guard `[ref: SDD/CSS Class Interface]`
        - [ ] T1.4.5 Add `.sidebar-collapsed .sidebar-nav-item` opacity:0 for text labels
        - [ ] T1.4.6 Add `.sidebar-hide-collapsed` utility (hidden when collapsed) `[ref: SDD/CSS Class Interface]`
        - [ ] T1.4.7 Add `.sidebar-show-collapsed` utility (only shown when collapsed) `[ref: SDD/CSS Class Interface]`
        - [ ] T1.4.8 Add `.sidebar-collapsed .sidebar-store-details` hidden (full store name)
        - [ ] T1.4.9 Add store picker abbreviated ID visible in collapsed state
        - [ ] T1.4.10 Add `.sidebar-collapsed .glyphicon.arrow` hidden
        - [ ] T1.4.11 Add `#page-wrapper` margin-left transition
        - [ ] T1.4.12 Add `body.sidebar-collapsed #page-wrapper` reduced margin
        - [ ] T1.4.13 Ensure active menu border-left indicator visible in collapsed state
        - [ ] T1.4.14 Add `prefers-reduced-motion` media query to disable animations `[ref: SDD/Accessibility]`

    - [ ] T1.5 Template Updates for SDD Interfaces `[activity: frontend]`
        - [ ] T1.5.1 Add `data-sidebar-collapsible="true"` attribute to `.sidebar-wrapper` `[ref: SDD/Data Attributes Interface]`
        - [ ] T1.5.2 Add abbreviated store ID element (typeNum only) for collapsed state
        - [ ] T1.5.3 Add `.sidebar-hide-collapsed` class to full store name/city elements
        - [ ] T1.5.4 Add `.sidebar-show-collapsed` class to abbreviated store ID element

    - [ ] T1.6 Validate
        - [ ] T1.6.1 Run `php userfrosting/conductor build-css --minify` `[activity: run-build]`
        - [ ] T1.6.2 Manually add `.sidebar-collapsed` class in DevTools
        - [ ] T1.6.3 Verify sidebar collapses to 64px
        - [ ] T1.6.4 Verify content area expands to fill space
        - [ ] T1.6.5 Verify animation is smooth (60fps)
        - [ ] T1.6.6 Verify active menu indicator visible in collapsed state
        - [ ] T1.6.7 Verify store picker shows abbreviated typeNum when collapsed
        - [ ] T1.6.8 Verify reduced motion disables animations (set in DevTools emulation)

---

### Phase 2: JavaScript Controller - Hover & State Management

- [ ] **T2 Implement SidebarController for Hover Behavior**

    - [ ] T2.1 Prime Context
        - [ ] T2.1.1 Read SDD JavaScript Interface `[ref: solution-design.md; JavaScript Interface section]`
        - [ ] T2.1.2 Read current `sb-admin-2.js` patterns `[ref: public_html/js/sb-admin-2.js]`
        - [ ] T2.1.3 Read SDD Runtime View sequence diagrams `[ref: solution-design.md; Runtime View]`
        - [ ] T2.1.4 Read PRD Tracking Requirements `[ref: product-requirements.md; Tracking Requirements]`
        - [ ] T2.1.5 Read PRD Business Rules & Edge Cases `[ref: product-requirements.md; Business Rules, Edge Cases]`

    - [ ] T2.2 Write Tests (Manual Browser Tests)
        - [ ] T2.2.1 Test: Hover over sidebar for 150ms+ triggers expansion `[ref: PRD/Feature 2: Hover-to-Expand]` `[activity: frontend]`
        - [ ] T2.2.2 Test: Mouse leave waits 200ms before collapse `[ref: PRD/Feature 2]` `[activity: frontend]`
        - [ ] T2.2.3 Test: Rapid mouse in/out doesn't cause jitter `[ref: PRD/Edge Cases]` `[activity: frontend]`
        - [ ] T2.2.4 Test: Page loads with sidebar collapsed `[ref: PRD/Feature 1]` `[activity: frontend]`
        - [ ] T2.2.5 Test: Cursor already over sidebar on page load expands immediately `[ref: PRD/Edge Cases]` `[activity: frontend]`
        - [ ] T2.2.6 Test: Expanded state persists across page navigation until mouse leaves `[ref: PRD/Business Rules]` `[activity: frontend]`
        - [ ] T2.2.7 Test: Store picker dropdown clickable in collapsed state `[ref: SDD/Implementation Gotchas]` `[activity: frontend]`

    - [ ] T2.3 Implement SidebarController `[activity: frontend]`
        - [ ] T2.3.1 Create `window.SidebarController` object with state properties
        - [ ] T2.3.2 Implement `init()` - add collapsed class on load, bind events
        - [ ] T2.3.3 Implement `handleMouseEnter()` with hover delay timer
        - [ ] T2.3.4 Implement `handleMouseLeave()` with leave delay timer
        - [ ] T2.3.5 Implement `expand()` - remove collapsed class, add expanded class
        - [ ] T2.3.6 Implement `collapse()` - add collapsed class, remove expanded class
        - [ ] T2.3.7 Add `.sidebar-animating` class during transitions `[ref: SDD/CSS Class Interface]`
        - [ ] T2.3.8 Add timer cancellation logic to prevent jitter
        - [ ] T2.3.9 Bind to `.sidebar-wrapper` mouseenter/mouseleave events
        - [ ] T2.3.10 Add media query check to skip on mobile (<768px)
        - [ ] T2.3.11 Handle cursor-over-sidebar on page load (expand immediately) `[ref: PRD/Edge Cases]`
        - [ ] T2.3.12 Pause collapse timer if MetisMenu dropdown is open `[ref: PRD/Edge Cases]`

    - [ ] T2.4 Implement Analytics Events `[ref: PRD/Tracking Requirements]` `[activity: frontend]`
        - [ ] T2.4.1 Add `sidebar_expand` event (trigger: hover/pin/keyboard, duration_ms)
        - [ ] T2.4.2 Add `sidebar_collapse` event (trigger: mouseout/unpin/keyboard, duration_ms)
        - [ ] T2.4.3 Add `sidebar_nav_click` event (section, subsection, collapsed_state)
        - [ ] T2.4.4 Integrate with existing analytics pattern in codebase

    - [ ] T2.5 Validate
        - [ ] T2.5.1 Test hover expansion timing with stopwatch `[activity: frontend]`
        - [ ] T2.5.2 Test collapse timing after mouse leave `[activity: frontend]`
        - [ ] T2.5.3 Test rapid mouse movement (no flicker) `[activity: frontend]`
        - [ ] T2.5.4 Verify mobile sidebar overlay still works `[activity: frontend]`
        - [ ] T2.5.5 Verify MetisMenu submenus still expand/collapse `[activity: frontend]`
        - [ ] T2.5.6 Verify cursor-over-sidebar on load expands immediately `[activity: frontend]`
        - [ ] T2.5.7 Verify store picker dropdown works in collapsed state `[activity: frontend]`
        - [ ] T2.5.8 Verify analytics events fire in browser console/network `[activity: frontend]`

---

### Phase 3: Pin Feature & Persistence `[parallel: true]`

- [ ] **T3 Implement Pin Button and localStorage Persistence**

    - [ ] T3.1 Prime Context
        - [ ] T3.1.1 Read SDD storage interface `[ref: solution-design.md; storage interface]`
        - [ ] T3.1.2 Read SDD Data Attributes Interface `[ref: solution-design.md; Data Attributes Interface]`
        - [ ] T3.1.3 Read PRD Feature 5 & 6 `[ref: product-requirements.md; Should Have Features]`
        - [ ] T3.1.4 Read PRD Tracking Requirements `[ref: product-requirements.md; Tracking Requirements]`

    - [ ] T3.2 Template Updates `[activity: frontend]`
        - [ ] T3.2.1 Add pin button to `sidebar.html` in sidebar-top area
        - [ ] T3.2.2 Add `data-sidebar-pin` attribute to button
        - [ ] T3.2.3 Add FontAwesome icon (fa-thumbtack) with rotation on pin
        - [ ] T3.2.4 Add aria-label for accessibility

    - [ ] T3.3 Implement Pin Logic in SidebarController `[activity: frontend]`
        - [ ] T3.3.1 Implement `togglePin()` method
        - [ ] T3.3.2 Implement `isPinnedState()` to check localStorage
        - [ ] T3.3.3 Implement `savePinState(boolean)` to save to localStorage
        - [ ] T3.3.4 Add `.sidebar-pinned` class when pinned
        - [ ] T3.3.5 Disable hover collapse when pinned
        - [ ] T3.3.6 Bind click event to pin button
        - [ ] T3.3.7 On init, restore pin state from localStorage
        - [ ] T3.3.8 Add `sidebar_pin` analytics event (action: pin/unpin, session_id) `[ref: PRD/Tracking Requirements]`

    - [ ] T3.4 CSS for Pin State `[activity: frontend]`
        - [ ] T3.4.1 Style pin button (position, hover states)
        - [ ] T3.4.2 Add `.sidebar-pinned` icon rotation (90deg)
        - [ ] T3.4.3 Hide pin button in collapsed state
        - [ ] T3.4.4 Show pin button in expanded state

    - [ ] T3.5 Validate
        - [ ] T3.5.1 Test pin click keeps sidebar expanded `[ref: PRD/Feature 5]` `[activity: frontend]`
        - [ ] T3.5.2 Test unpin allows collapse on mouse leave `[activity: frontend]`
        - [ ] T3.5.3 Test refresh with pinned state restores expanded `[ref: PRD/Feature 6]` `[activity: frontend]`
        - [ ] T3.5.4 Test localStorage in DevTools Application tab `[activity: frontend]`
        - [ ] T3.5.5 Test localStorage unavailable doesn't break functionality `[activity: frontend]`

---

### Phase 4: Tooltips for Collapsed Icons `[parallel: true]`

- [ ] **T4 Add Bootstrap Tooltips for Icon Labels**

    - [ ] T4.1 Prime Context
        - [ ] T4.1.1 Read PRD Feature 4 `[ref: product-requirements.md; Feature 4: Tooltips]`
        - [ ] T4.1.2 Read Bootstrap 5 tooltip documentation `[activity: frontend]`

    - [ ] T4.2 Template Updates `[activity: frontend]`
        - [ ] T4.2.1 Add `data-bs-toggle="tooltip"` to main nav items in `sidebar.html`
        - [ ] T4.2.2 Add `data-bs-placement="right"` for right-side tooltips
        - [ ] T4.2.3 Add `title` attribute with section names
        - [ ] T4.2.4 Only add to top-level items (Dashboard, Store Settings, etc.)

    - [ ] T4.3 Implement Tooltip Controller `[activity: frontend]`
        - [ ] T4.3.1 Initialize Bootstrap tooltips on DOM ready with `delay: { show: 300, hide: 0 }` `[ref: PRD/Feature 4]`
        - [ ] T4.3.2 Enable tooltips only when `.sidebar-collapsed` is active
        - [ ] T4.3.3 Dispose/hide all tooltips immediately when sidebar expands `[ref: PRD/Feature 4]`
        - [ ] T4.3.4 Handle tooltip cleanup on sidebar state change
        - [ ] T4.3.5 Re-initialize tooltips after page navigation if needed `[ref: SDD/Implementation Gotchas]`

    - [ ] T4.4 CSS Adjustments `[activity: frontend]`
        - [ ] T4.4.1 Ensure tooltip z-index is above sidebar
        - [ ] T4.4.2 Match tooltip styling to design system (optional)

    - [ ] T4.5 Validate
        - [ ] T4.5.1 Test hover on collapsed icon shows tooltip `[ref: PRD/Feature 4]` `[activity: frontend]`
        - [ ] T4.5.2 Test tooltip appears to right of sidebar `[activity: frontend]`
        - [ ] T4.5.3 Test tooltip has 300ms delay (count manually) `[ref: PRD/Feature 4]` `[activity: frontend]`
        - [ ] T4.5.4 Test tooltip disappears immediately when sidebar expands `[activity: frontend]`
        - [ ] T4.5.5 Verify no tooltip conflicts with store dropdown `[activity: frontend]`

---

### Phase 5: Integration & End-to-End Validation

- [ ] **T5 Complete Feature Validation**

    - [ ] T5.1 Cross-Browser Testing `[activity: qa]`
        - [ ] T5.1.1 Test Chrome (latest 2 versions)
        - [ ] T5.1.2 Test Safari (latest 2 versions)
        - [ ] T5.1.3 Test Firefox (latest 2 versions)
        - [ ] T5.1.4 Test Edge (latest 2 versions)

    - [ ] T5.2 Responsive Testing `[activity: qa]`
        - [ ] T5.2.1 Test at 1920px width (large desktop)
        - [ ] T5.2.2 Test at 1280px width (laptop)
        - [ ] T5.2.3 Test at 1024px width (small laptop)
        - [ ] T5.2.4 Test at 768px width (breakpoint)
        - [ ] T5.2.5 Test at 767px width (mobile - should use overlay, not collapse)

    - [ ] T5.3 Full User Flow Testing `[ref: PRD/Test Scenarios]` `[activity: qa]`
        - [ ] T5.3.1 Scenario: Page Load - Default Collapsed
        - [ ] T5.3.2 Scenario: Hover to Expand
        - [ ] T5.3.3 Scenario: Mouse Leave to Collapse
        - [ ] T5.3.4 Scenario: Pin to Keep Expanded
        - [ ] T5.3.5 Scenario: Page Load with Pinned State
        - [ ] T5.3.6 Scenario: Mobile Unchanged

    - [ ] T5.4 MetisMenu Integration `[activity: qa]`
        - [ ] T5.4.1 Test all 14 main menu sections expand submenus
        - [ ] T5.4.2 Test submenu items are clickable
        - [ ] T5.4.3 Test submenu stays open when moving from parent to child
        - [ ] T5.4.4 Test nested navigation in Store Settings section

    - [ ] T5.5 Accessibility Validation `[activity: qa]`
        - [ ] T5.5.1 Run Axe browser extension on admin page
        - [ ] T5.5.2 Verify pin button has aria-label
        - [ ] T5.5.3 Test with keyboard navigation (if implemented)
        - [ ] T5.5.4 Enable `prefers-reduced-motion` in DevTools and verify animations disabled `[ref: SDD/Accessibility]`

    - [ ] T5.6 Performance Validation `[ref: SDD/Quality Requirements]` `[activity: qa]`
        - [ ] T5.6.1 Check animation frame rate in DevTools (target: 60fps)
        - [ ] T5.6.2 Measure hover response time (target: <100ms visual feedback)
        - [ ] T5.6.3 Verify no layout thrashing during transitions

    - [ ] T5.7 Analytics Validation `[ref: PRD/Tracking Requirements]` `[activity: qa]`
        - [ ] T5.7.1 Verify `sidebar_expand` event fires on expand
        - [ ] T5.7.2 Verify `sidebar_collapse` event fires on collapse
        - [ ] T5.7.3 Verify `sidebar_pin` event fires on pin/unpin
        - [ ] T5.7.4 Verify `sidebar_nav_click` event fires on menu item click
        - [ ] T5.7.5 Check all event properties are populated correctly

    - [ ] T5.8 Build & Deploy
        - [ ] T5.8.1 Run `php userfrosting/conductor build-css --minify` `[activity: run-build]`
        - [ ] T5.8.2 Verify `version.txt` updated for cache busting
        - [ ] T5.8.3 Commit changes with clear message
        - [ ] T5.8.4 Test on staging environment if available

    - [ ] T5.9 PRD Acceptance Verification `[ref: product-requirements.md]`
        - [ ] T5.9.1 ✅ Feature 1: Collapsed Default State - all criteria met
        - [ ] T5.9.2 ✅ Feature 2: Hover-to-Expand - all criteria met
        - [ ] T5.9.3 ✅ Feature 3: Smooth Animation - all criteria met
        - [ ] T5.9.4 ✅ Feature 4: Tooltips for Collapsed Icons - all criteria met
        - [ ] T5.9.5 ✅ Feature 5: Pin/Lock Expanded State - all criteria met
        - [ ] T5.9.6 ✅ Feature 6: User Preference Persistence - all criteria met
        - [ ] T5.9.7 ✅ All tracking events implemented per PRD Tracking Requirements

---

## Phase Dependencies

```mermaid
graph LR
    T1[Phase 1: CSS Foundation] --> T2[Phase 2: JS Controller]
    T2 --> T3[Phase 3: Pin Feature]
    T2 --> T4[Phase 4: Tooltips]
    T3 --> T5[Phase 5: Validation]
    T4 --> T5
```

**Notes:**
- Phases 3 and 4 can run in parallel after Phase 2
- Phase 1 must complete before Phase 2 (CSS classes needed for JS)
- Phase 5 requires all other phases complete

---

## Rollback Plan

If issues discovered after deployment:

1. **Quick Rollback**: Remove `sidebar-collapsed` class from init in JS (reverts to always-expanded)
2. **CSS Rollback**: Revert `admin-theme.css` changes, rebuild with `conductor build-css --minify`
3. **Full Rollback**: Revert all file changes via git