feat: phase 3+4 timeline animation + education entities

- Add education entities (A-Levels, MPharm) to constellation data - Add 'education' node type with dashed border styling - Create useTimelineAnimation hook with rAF scheduler + state machine (IDLE → PLAYING → PAUSED → HOLDING → RESETTING → loop) - Chronological reveal: entities oldest-first with skill stagger, link draw-on, reinforcement pulse for already-visible skills - Year indicator overlay (monospace, top-left) - Multiplicative opacity: animation visibility × highlight emphasis - Highlight system respects visibleNodeIdsRef (unrevealed stay hidden) - Interaction pause/resume wired to animation hook - Play/pause button (bottom-right, larger touch target on mobile) - prefers-reduced-motion: shows final state immediately, no animation - Remove Phase 2 entry animation (replaced by timeline animation)
2026-02-16 14:31:11 +00:00
parent 7d7628c8a7
commit 8b674ffe14
10 changed files with 675 additions and 171 deletions
@@ -8,8 +8,8 @@ interface AccessibleNodeOverlayProps {
  dimensions: { width: number; height: number; scaleFactor: number }
  onFocus: (nodeId: string) => void
  onBlur: () => void
-  onClick: (nodeId: string, nodeType: 'role' | 'skill') => void
-  onKeyDown: (e: React.KeyboardEvent, nodeId: string, nodeType: 'role' | 'skill') => void
+  onClick: (nodeId: string, nodeType: 'role' | 'skill' | 'education') => void
+  onKeyDown: (e: React.KeyboardEvent, nodeId: string, nodeType: 'role' | 'skill' | 'education') => void
 }

 export const AccessibleNodeOverlay: React.FC<AccessibleNodeOverlayProps> = ({
@@ -22,10 +22,11 @@ export const AccessibleNodeOverlay: React.FC<AccessibleNodeOverlayProps> = ({
  onKeyDown,
 }) => {
  const domainOrder: Record<string, number> = { technical: 0, clinical: 1, leadership: 2 }
+  const isEntity = (t: string) => t === 'role' || t === 'education'
  const sorted = [...nodes].sort((a, b) => {
-    if (a.type === 'role' && b.type !== 'role') return -1
-    if (a.type !== 'role' && b.type === 'role') return 1
-    if (a.type === 'role' && b.type === 'role') {
+    if (isEntity(a.type) && !isEntity(b.type)) return -1
+    if (!isEntity(a.type) && isEntity(b.type)) return 1
+    if (isEntity(a.type) && isEntity(b.type)) {
      return (b.startYear ?? 0) - (a.startYear ?? 0)
    }
    const da = domainOrder[a.domain ?? 'technical'] ?? 0
@@ -56,15 +57,16 @@ export const AccessibleNodeOverlay: React.FC<AccessibleNodeOverlayProps> = ({
          : `${node.startYear}-present`

        const position = nodeButtonPositions[node.id] ?? { x: dimensions.width * 0.5, y: dimensions.height * 0.5 }
-        const buttonWidth = node.type === 'role' ? (isMobileBtn ? MOBILE_ROLE_WIDTH : Math.round(ROLE_WIDTH * btnSf)) : Math.round(34 * btnSf)
-        const buttonHeight = node.type === 'role' ? Math.round(ROLE_HEIGHT * btnSf) : Math.round(34 * btnSf)
+        const isEntityBtn = isEntity(node.type)
+        const buttonWidth = isEntityBtn ? (isMobileBtn ? MOBILE_ROLE_WIDTH : Math.round(ROLE_WIDTH * btnSf)) : Math.round(34 * btnSf)
+        const buttonHeight = isEntityBtn ? Math.round(ROLE_HEIGHT * btnSf) : Math.round(34 * btnSf)

        return (
          <button
            key={node.id}
            type="button"
            aria-label={
-              node.type === 'role'
+              isEntityBtn
                ? `${node.label} at ${node.organization}, ${yearRange}. Press Enter to view details.`
                : `${node.label} skill node. Press Enter to view details.`
            }
@@ -1,10 +1,11 @@
 import React, { useRef, useEffect, useState, useCallback, useMemo } from 'react'
 import * as d3 from 'd3'
 import { constellationNodes, roleSkillMappings } from '@/data/constellation'
-import { timelineCareerEntities } from '@/data/timeline'
+import { timelineEntities } from '@/data/timeline'
 import { useForceSimulation, getHeight } from '@/hooks/useForceSimulation'
 import { useConstellationHighlight } from '@/hooks/useConstellationHighlight'
 import { useConstellationInteraction } from '@/hooks/useConstellationInteraction'
+import { useTimelineAnimation } from '@/hooks/useTimelineAnimation'
 import { MobileAccordion } from './MobileAccordion'
 import { ConstellationLegend } from './ConstellationLegend'
 import { AccessibleNodeOverlay } from './AccessibleNodeOverlay'
@@ -12,7 +13,7 @@ import {
  MIN_HEIGHT,
  SKILL_RADIUS_DEFAULT, SKILL_RADIUS_ACTIVE,
  MOBILE_SKILL_RADIUS_DEFAULT, MOBILE_SKILL_RADIUS_ACTIVE,
-  supportsCoarsePointer,
+  supportsCoarsePointer, prefersReducedMotion,
 } from './constants'

 interface CareerConstellationProps {
@@ -24,29 +25,29 @@ interface CareerConstellationProps {
 }

 const nodeById = new Map(constellationNodes.map(node => [node.id, node]))
-const careerEntityById = new Map(timelineCareerEntities.map(entity => [entity.id, entity]))
+const careerEntityById = new Map(timelineEntities.map(entity => [entity.id, entity]))
 const srDescription = buildScreenReaderDescription()

 function buildScreenReaderDescription(): string {
-  const roles = constellationNodes.filter(n => n.type === 'role')
+  const entities = constellationNodes.filter(n => n.type === 'role' || n.type === 'education')
  const skills = constellationNodes.filter(n => n.type === 'skill')

-  const roleDescriptions = roles.map(role => {
-    const mapping = roleSkillMappings.find(m => m.roleId === role.id)
+  const entityDescriptions = entities.map(entity => {
+    const mapping = roleSkillMappings.find(m => m.roleId === entity.id)
    const skillNames = mapping
      ? mapping.skillIds
          .map(sid => skills.find(s => s.id === sid)?.label)
          .filter(Boolean)
          .join(', ')
      : ''
-    const yearRange = role.endYear
-      ? `${role.startYear}-${role.endYear}`
-      : `${role.startYear}-present`
-    return `${role.label} at ${role.organization} (${yearRange}): ${skillNames}`
+    const yearRange = entity.endYear
+      ? `${entity.startYear}-${entity.endYear}`
+      : `${entity.startYear}-present`
+    return `${entity.label} at ${entity.organization} (${yearRange}): ${skillNames}`
  })

-  return `Career constellation graph showing ${roles.length} roles and ${skills.length} skills in reverse-chronological order along a vertical timeline, with the most recent role at the top. ` +
-    roleDescriptions.join('. ') + '.'
+  return `Career constellation graph showing ${entities.length} roles and ${skills.length} skills in reverse-chronological order along a vertical timeline, with the most recent role at the top. ` +
+    entityDescriptions.join('. ') + '.'
 }

 const CareerConstellation: React.FC<CareerConstellationProps> = ({
@@ -69,7 +70,6 @@ const CareerConstellation: React.FC<CareerConstellationProps> = ({
    highlightedNodeIdRef.current = highlightedNodeId ?? null
  }, [highlightedNodeId])

-  // ResizeObserver for container dimensions
  useEffect(() => {
    const container = containerRef.current
    if (!container) return
@@ -90,7 +90,6 @@ const CareerConstellation: React.FC<CareerConstellationProps> = ({
    return () => observer.disconnect()
  }, [containerHeight])

-  // Compute layout-dependent skill radii for highlight hook
  const isMobile = typeof window !== 'undefined' && window.innerWidth < 640
  const sf = isMobile ? 1 : dimensions.scaleFactor
  const srDefault = isMobile ? MOBILE_SKILL_RADIUS_DEFAULT : Math.round(SKILL_RADIUS_DEFAULT * sf)
@@ -103,20 +102,22 @@ const CareerConstellation: React.FC<CareerConstellationProps> = ({

  const resolveRoleFallback = useCallback(() => {
    const hId = highlightedNodeIdRef.current
-    if (hId && nodeById.get(hId)?.type === 'role') return hId
+    const hType = hId ? nodeById.get(hId)?.type : null
+    if (hId && hType && hType !== 'skill') return hId
    const pId = pinnedNodeIdRef.current
-    if (pId && nodeById.get(pId)?.type === 'role') return pId
+    const pType = pId ? nodeById.get(pId)?.type : null
+    if (pId && pType && pType !== 'skill') return pId
    return null
  }, [])

-  // Highlight hook (needs to be created before simulation so we can pass applyHighlight)
+  // Shared refs for hooks
  const highlightGraphRef = useRef<((activeNodeId: string | null) => void) | null>(null)
  const nodesRef = useRef<import('./types').SimNode[]>([])
  const nodeSelectionRef = useRef<d3.Selection<SVGGElement, import('./types').SimNode, SVGGElement, unknown> | null>(null)
  const linkSelectionRef = useRef<d3.Selection<SVGPathElement, import('./types').SimLink, SVGGElement, unknown> | null>(null)
  const connectedMapRef = useRef<Map<string, Set<string>>>(new Map())
-
  const skillRestRadiiRef = useRef<Map<string, number>>(new Map())
+  const visibleNodeIdsRef = useRef<Set<string>>(new Set())

  const { applyGraphHighlight } = useConstellationHighlight({
    nodeSelectionRef,
@@ -126,11 +127,11 @@ const CareerConstellation: React.FC<CareerConstellationProps> = ({
    srActive,
    nodesRef,
    skillRestRadii: skillRestRadiiRef.current,
+    visibleNodeIdsRef,
  })

  highlightGraphRef.current = applyGraphHighlight

-  // Stable options ref for simulation to avoid re-creating on every render
  const simOptionsRef = useRef({
    resolveGraphFallback,
    applyHighlight: applyGraphHighlight,
@@ -144,19 +145,31 @@ const CareerConstellation: React.FC<CareerConstellationProps> = ({

  const sim = useForceSimulation(svgRef, dimensions, stableSimOptions)

-  // Sync simulation refs to our local refs for highlight/interaction hooks
+  // Sync simulation refs
  useEffect(() => {
    nodesRef.current = sim.nodesRef.current
    nodeSelectionRef.current = sim.nodeSelectionRef.current
    linkSelectionRef.current = sim.linkSelectionRef.current
-    if (sim.connectedMap.size > 0) {
-      connectedMapRef.current = sim.connectedMap
-    }
-    if (sim.skillRestRadii.size > 0) {
-      skillRestRadiiRef.current = sim.skillRestRadii
-    }
+    if (sim.connectedMap.size > 0) connectedMapRef.current = sim.connectedMap
+    if (sim.skillRestRadii.size > 0) skillRestRadiiRef.current = sim.skillRestRadii
  })

+  // Animation hook
+  const animation = useTimelineAnimation({
+    nodeSelectionRef,
+    linkSelectionRef,
+    simulationRef: sim.simulationRef,
+    yearIndicatorRef: sim.yearIndicatorRef,
+    connectorSelectionRef: sim.connectorSelectionRef,
+    timelineGroupRef: sim.timelineGroupRef,
+    skillRestRadiiRef,
+    srDefault,
+    dimensionsTrigger: dimensions.width + dimensions.height,
+  })
+
+  // Sync visibleNodeIdsRef from animation hook
+  visibleNodeIdsRef.current = animation.visibleNodeIdsRef.current
+
  // Interaction hook
  const { pinnedNodeId, setPinnedNodeId, pinnedNodeIdRef } = useConstellationInteraction({
    highlightGraphRef,
@@ -166,6 +179,8 @@ const CareerConstellation: React.FC<CareerConstellationProps> = ({
    resolveGraphFallback,
    resolveRoleFallback,
    dimensionsTrigger: dimensions.width + dimensions.height,
+    pauseForInteraction: animation.pauseForInteraction,
+    resumeAfterInteraction: animation.resumeAfterInteraction,
  })

  // External highlight sync
@@ -178,9 +193,7 @@ const CareerConstellation: React.FC<CareerConstellationProps> = ({
  useEffect(() => {
    if (!svgRef.current) return
    const svg = d3.select(svgRef.current)
-
    svg.selectAll('.focus-ring').attr('stroke', 'transparent')
-
    if (focusedNodeId) {
      svg.selectAll<SVGGElement, { id: string }>('g.node')
        .filter(d => d.id === focusedNodeId)
@@ -190,18 +203,17 @@ const CareerConstellation: React.FC<CareerConstellationProps> = ({
    }
  }, [focusedNodeId])

-  const handleNodeKeyDown = useCallback((e: React.KeyboardEvent, nodeId: string, nodeType: 'role' | 'skill') => {
+  const handleNodeKeyDown = useCallback((e: React.KeyboardEvent, nodeId: string, nodeType: 'role' | 'skill' | 'education') => {
    if (e.key !== 'Enter' && e.key !== ' ') return
    e.preventDefault()
    setPinnedNodeId(nodeId)
    pinnedNodeIdRef.current = nodeId
    highlightGraphRef.current?.(nodeId)
-    onNodeHover?.(nodeType === 'role' ? nodeId : resolveRoleFallback())
-    ;(nodeType === 'role' ? onRoleClick : onSkillClick)(nodeId)
+    onNodeHover?.(nodeType !== 'skill' ? nodeId : resolveRoleFallback())
+    ;(nodeType !== 'skill' ? onRoleClick : onSkillClick)(nodeId)
  }, [onRoleClick, onSkillClick, onNodeHover, resolveRoleFallback, setPinnedNodeId, pinnedNodeIdRef])

-  // Pinned career entity for mobile accordion
-  const pinnedRoleNode = pinnedNodeId ? constellationNodes.find(n => n.id === pinnedNodeId && n.type === 'role') : null
+  const pinnedRoleNode = pinnedNodeId ? constellationNodes.find(n => n.id === pinnedNodeId && (n.type === 'role' || n.type === 'education')) : null
  const pinnedCareerEntity = pinnedRoleNode ? careerEntityById.get(pinnedRoleNode.id) ?? null : null
  const domainCounts = useMemo(() => {
    const counts: Record<string, number> = {}
@@ -237,22 +249,50 @@ const CareerConstellation: React.FC<CareerConstellationProps> = ({

      <ConstellationLegend isTouch={supportsCoarsePointer} domainCounts={domainCounts} />

-      <MobileAccordion
-        pinnedCareerEntity={pinnedCareerEntity}
-        show={showAccordion}
-      />
+      <MobileAccordion pinnedCareerEntity={pinnedCareerEntity} show={showAccordion} />
+
+      {!prefersReducedMotion && (
+        <button
+          onClick={animation.togglePlayPause}
+          aria-label={animation.isPlaying ? 'Pause animation' : 'Play animation'}
+          style={{
+            position: 'absolute',
+            bottom: isMobile ? 8 : 12,
+            right: isMobile ? 8 : 12,
+            width: isMobile ? 44 : 36,
+            height: isMobile ? 44 : 36,
+            borderRadius: '50%',
+            border: '1px solid var(--border-light)',
+            background: 'var(--surface)',
+            cursor: 'pointer',
+            display: 'flex',
+            alignItems: 'center',
+            justifyContent: 'center',
+            opacity: 0.6,
+            transition: 'opacity 150ms ease',
+          }}
+          onMouseEnter={e => (e.currentTarget.style.opacity = '1')}
+          onMouseLeave={e => (e.currentTarget.style.opacity = '0.6')}
+        >
+          {animation.isPlaying ? (
+            <svg width="14" height="14" viewBox="0 0 14 14" fill="var(--text-secondary)">
+              <rect x="2" y="1" width="4" height="12" rx="1" />
+              <rect x="8" y="1" width="4" height="12" rx="1" />
+            </svg>
+          ) : (
+            <svg width="14" height="14" viewBox="0 0 14 14" fill="var(--text-secondary)">
+              <polygon points="3,1 13,7 3,13" />
+            </svg>
+          )}
+        </button>
+      )}

      <p
        style={{
          position: 'absolute',
-          width: 1,
-          height: 1,
-          padding: 0,
-          margin: -1,
-          overflow: 'hidden',
-          clip: 'rect(0,0,0,0)',
-          whiteSpace: 'nowrap',
-          border: 0,
+          width: 1, height: 1, padding: 0, margin: -1,
+          overflow: 'hidden', clip: 'rect(0,0,0,0)',
+          whiteSpace: 'nowrap', border: 0,
        }}
      >
        {srDescription}
@@ -266,7 +306,7 @@ const CareerConstellation: React.FC<CareerConstellationProps> = ({
          setFocusedNodeId(nodeId)
          highlightGraphRef.current?.(nodeId)
          const node = nodeById.get(nodeId)
-          if (node?.type === 'role') onNodeHover?.(nodeId)
+          if (node?.type !== 'skill') onNodeHover?.(nodeId)
        }}
        onBlur={() => {
          setFocusedNodeId(null)
@@ -277,7 +317,7 @@ const CareerConstellation: React.FC<CareerConstellationProps> = ({
          setPinnedNodeId(nodeId)
          pinnedNodeIdRef.current = nodeId
          highlightGraphRef.current?.(nodeId)
-          if (nodeType === 'role') {
+          if (nodeType !== 'skill') {
            onNodeHover?.(nodeId)
            onRoleClick(nodeId)
          } else {
@@ -39,6 +39,20 @@ export const ENTRY_ROLE_DURATION_MS = 300
 export const ENTRY_SKILL_STAGGER_MS = 30
 export const ENTRY_SKILL_DURATION_MS = 250

+// Timeline animation
+export const ANIM_ENTITY_REVEAL_MS = 600
+export const ANIM_SKILL_REVEAL_MS = 350
+export const ANIM_SKILL_STAGGER_MS = 60
+export const ANIM_LINK_DRAW_MS = 300
+export const ANIM_LINK_STAGGER_MS = 40
+export const ANIM_REINFORCEMENT_MS = 350
+export const ANIM_STEP_GAP_MS = 400
+export const ANIM_HOLD_MS = 3000
+export const ANIM_RESET_MS = 400
+export const ANIM_RESTART_DELAY_MS = 200
+export const ANIM_INTERACTION_RESUME_MS = 800
+export const ANIM_SETTLE_ALPHA = 0.05
+
 // Domain color map
 export const DOMAIN_COLOR_MAP: Record<string, string> = {
  clinical: '#059669',
@@ -39,3 +39,14 @@ export interface ConstellationCallbacks {
  onSkillClick: (id: string) => void
  onNodeHover?: (id: string | null) => void
 }
+
+export type AnimationState = 'IDLE' | 'PLAYING' | 'PAUSED' | 'HOLDING' | 'RESETTING'
+
+export interface AnimationStep {
+  entityId: string
+  startYear: number
+  skillIds: string[]
+  newSkillIds: string[]
+  reinforcedSkillIds: string[]
+  linkPairs: Array<{ source: string; target: string }>
+}