156 lines
8.1 KiB
Markdown
156 lines
8.1 KiB
Markdown
# Task: CareerConstellation Overhaul
|
||
|
||
Refactor, visually improve, and add chronological animation to the CareerConstellation D3 force chart — the centrepiece of the portfolio's Patient Pathway section.
|
||
|
||
## Requirements
|
||
|
||
### Phase 1 — Refactor the Monolith
|
||
|
||
Decompose `src/components/CareerConstellation.tsx` (1102 lines) into focused modules:
|
||
|
||
```
|
||
src/components/constellation/
|
||
CareerConstellation.tsx -- Orchestrator (< 300 lines)
|
||
MobileAccordion.tsx -- Mobile tap-to-expand accordion
|
||
ConstellationLegend.tsx -- Domain legend with node counts
|
||
AccessibleNodeOverlay.tsx -- Keyboard navigation button overlay
|
||
constants.ts -- All magic numbers as named exports
|
||
types.ts -- SimNode, SimLink, LayoutParams, local interfaces
|
||
|
||
src/hooks/
|
||
useForceSimulation.ts -- D3 simulation lifecycle (setup, forces, tick, cleanup)
|
||
useConstellationHighlight.ts -- applyGraphHighlight + connectedMap + highlight refs
|
||
useConstellationInteraction.ts -- Mouse/touch/pin handlers, callback refs
|
||
```
|
||
|
||
- [ ] Constants extracted (forces, sizes, opacities, durations)
|
||
- [ ] Types extracted (SimNode, SimLink, LayoutParams)
|
||
- [ ] MobileAccordion extracted as standalone component
|
||
- [ ] ConstellationLegend extracted
|
||
- [ ] AccessibleNodeOverlay extracted
|
||
- [ ] useForceSimulation hook created
|
||
- [ ] useConstellationHighlight hook created
|
||
- [ ] useConstellationInteraction hook created
|
||
- [ ] Orchestrator composed from hooks + sub-components (< 300 lines)
|
||
- [ ] All existing behaviour preserved (hover, click, tap, keyboard, mobile, detail panel)
|
||
- [ ] `npm run lint && npm run typecheck && npm run build` passes
|
||
|
||
### Phase 2 — Visual Improvements
|
||
|
||
Enhance the chart aesthetics while maintaining the PMR design language:
|
||
|
||
**Links:**
|
||
- [ ] Strength-weighted stroke width at rest: `0.5 + strength * 1.5` (range 0.5–2px)
|
||
- [ ] Domain-colored at rest (very low opacity: `0.08 + strength * 0.12`)
|
||
- [ ] Improved bezier curves: offset control point by vertical distance (`cx = (sx+tx)/2 + (ty-sy)*0.15`)
|
||
- [ ] On highlight: width `1 + strength * 2`, domain color at higher opacity
|
||
|
||
**Skill nodes:**
|
||
- [ ] Thin domain-colored stroke at rest (`stroke-width: 1, stroke-opacity: 0.4`)
|
||
- [ ] Size encoding by connected role count: `baseRadius + roleCount * 0.8`
|
||
- [ ] On highlight: subtle glow filter (feGaussianBlur, 2–3px stdDeviation, domain color)
|
||
|
||
**Role nodes:**
|
||
- [ ] Fill gradient: left-to-right from orgColor@0.08 to orgColor@0.18
|
||
- [ ] On highlight: fill-opacity 0.25, stroke-width 2, shadow-md filter
|
||
|
||
**Entry animation (mount, replaced by over-time animation in Phase 3):**
|
||
- [ ] Timeline guides fade in (200ms)
|
||
- [ ] Role nodes slide in from left along connectors (staggered 80ms, 300ms each)
|
||
- [ ] Skill nodes scale up from 0 (staggered 30ms, 250ms each)
|
||
- [ ] Links draw on via stroke-dashoffset (after source+target visible)
|
||
- [ ] Skipped entirely when `prefers-reduced-motion`
|
||
|
||
**Legend:**
|
||
- [ ] Domain node counts displayed: "Technical (8) · Clinical (6) · Leadership (7)"
|
||
|
||
### Phase 3 — Over-Time Animation
|
||
|
||
Build the constellation chronologically from 2009 to present:
|
||
|
||
**Data changes:**
|
||
- [ ] Modify `buildConstellationData()` in `src/data/timeline.ts` to include education entities
|
||
- [ ] Education entities appear as nodes on the timeline (use `type: 'role'` with education styling, or add `type: 'education'`)
|
||
- [ ] Update `src/types/pmr.ts` if new node types are needed
|
||
- [ ] Timeline order (oldest first): A-Levels (2009) → MPharm (2011) → Pre-Reg (2015) → Duty Manager (2016) → Pharmacy Manager (2017) → High Cost Drugs (2022) → Deputy Head (2024) → Interim Head (2025)
|
||
|
||
**Animation architecture:**
|
||
- [ ] Create `useTimelineAnimation` hook in `src/hooks/`
|
||
- [ ] All nodes present in simulation from start but hidden (opacity: 0) — stable positions, no layout jitter
|
||
- [ ] Reveal chronologically: each role/education entity appears, then its skills animate in
|
||
- [ ] Skills already visible from earlier roles just get new links (reinforcement pulse: scale 1.3x → 1.0x over 350ms)
|
||
- [ ] Uses requestAnimationFrame + timestamp scheduler (not setTimeout chains)
|
||
- [ ] Animation state machine in refs: IDLE → PLAYING → PAUSED → HOLDING → RESETTING → loop back to PLAYING
|
||
- [ ] Auto-plays on load (after force simulation settles)
|
||
- [ ] Loops continuously: hold 3s at end → fade all 400ms → pause 200ms → restart
|
||
|
||
**Visual effects during reveal:**
|
||
- [ ] Role/education nodes scale from 0 with ease-out-back
|
||
- [ ] New skill nodes scale from 0 with ease-out
|
||
- [ ] Links draw on via stroke-dashoffset animation
|
||
- [ ] Year indicator overlay (top-left of SVG, monospace font, var(--text-tertiary))
|
||
|
||
**Accessibility:**
|
||
- [ ] `prefers-reduced-motion`: skip animation entirely, show final state immediately
|
||
- [ ] Play/pause button with appropriate aria-label
|
||
|
||
### Phase 4 — Animation + Interaction Integration
|
||
|
||
Wire the animation to the existing highlight system:
|
||
|
||
- [ ] Hover/tap pauses animation, applies highlight normally (on visible nodes only)
|
||
- [ ] Highlight only operates on revealed nodes — unrevealed nodes stay at opacity 0
|
||
- [ ] Multiplicative opacity: animation visibility (0 or target) × highlight emphasis (1.0 or 0.15)
|
||
- [ ] Resume animation 800ms after last interaction ends (mouseout / background tap)
|
||
- [ ] Explicit pause via button stays paused until user clicks play again
|
||
- [ ] Play/pause toggle button (bottom-right of SVG area, subtle styling, larger touch target on mobile)
|
||
- [ ] Mobile accordion works during paused state
|
||
- [ ] Keyboard navigation works during paused state
|
||
- [ ] Click → detail panel works during paused state
|
||
|
||
## Success Criteria
|
||
|
||
All of the following must be true for LOOP_COMPLETE:
|
||
|
||
- [ ] `npm run lint && npm run typecheck && npm run build` passes with zero errors
|
||
- [ ] CareerConstellation orchestrator is < 300 lines
|
||
- [ ] Education entities (A-Levels, MPharm) appear in the constellation
|
||
- [ ] Animation auto-plays on load and loops continuously
|
||
- [ ] Network builds chronologically from 2009 through to present
|
||
- [ ] Skills accumulate visually — existing skills get new links, not duplicated
|
||
- [ ] Hover/tap pauses animation and shows highlight on visible nodes
|
||
- [ ] Animation resumes after 800ms of no interaction
|
||
- [ ] Play/pause button visible and functional
|
||
- [ ] Existing interactions preserved: click → detail panel, keyboard nav, mobile accordion
|
||
- [ ] `prefers-reduced-motion` shows final state immediately with no animation
|
||
- [ ] Links show domain colors and strength-weighted width at rest
|
||
- [ ] No TypeScript `any` types introduced
|
||
- [ ] No dead code or commented-out blocks
|
||
|
||
## Constraints
|
||
|
||
- TypeScript strict mode (`noUnusedLocals`, `noUnusedParameters`)
|
||
- Path alias: `@/*` → `src/*`
|
||
- Styling: Tailwind utilities + CSS custom properties for design tokens
|
||
- D3 v6 (already installed)
|
||
- Framer Motion for non-D3 animations; respect `prefers-reduced-motion`
|
||
- Design tokens: Primary teal #00897B, Accent coral #FF6B6B, PMR greens/teals/greys
|
||
- Font tokens: `--font-ui` (Elvaro), `--font-geist-mono` (monospace), `--font-primary` / `--font-secondary`
|
||
- No automated tests — quality gates are lint + typecheck + build
|
||
- D3 patterns: reference `.claude/skills/d3-visualization/` for force layout examples
|
||
|
||
## Key Architecture Decisions
|
||
|
||
1. **"All nodes hidden" for animation** — every node participates in the force simulation from the start (positions are stable). Reveal via opacity transitions only. Do NOT dynamically add/remove nodes from the simulation.
|
||
|
||
2. **Ref-based animation state** — the animation state machine lives in refs (not React state) to avoid re-renders in the rAF loop. Only sync to React state for UI controls (play/pause button).
|
||
|
||
3. **Multiplicative opacity model** — animation controls visibility (0 or target), highlight controls emphasis (1.0 or 0.15). Final opacity = animation × highlight. This prevents the two systems from conflicting.
|
||
|
||
4. **Imperative D3 + React hybrid** — D3 manages SVG rendering and force simulation imperatively via refs. React manages keyboard overlay buttons and UI controls. Follow the existing pattern in the codebase.
|
||
|
||
## Status
|
||
|
||
Track progress here. Mark items complete as you go.
|
||
When ALL success criteria are met, print LOOP_COMPLETE.
|