121 lines
8.8 KiB
Markdown
121 lines
8.8 KiB
Markdown
# Patient Pathway Graph Stability + Unified Timeline Plan
|
|
|
|
## Scope
|
|
Refactor pathway graph + timeline cards so career and education are rendered from one canonical dataset, hover behavior is shared and stable, and sidebar tags are derived from canonical skills frequency.
|
|
|
|
## Root-Cause Findings
|
|
- Hover jiggle source: `CareerConstellation` re-creates the full SVG and force simulation whenever `highlightedNodeId` changes because the main D3 effect depends on `[dimensions, highlightedNodeId, pinnedNodeId]` (`src/components/CareerConstellation.tsx`).
|
|
- Date mismatch source: duplicated timeline/date models across:
|
|
- `consultations` (`date` and `duration` strings) in `src/data/consultations.ts`
|
|
- `constellationNodes` (`startYear`/`endYear`) in `src/data/constellation.ts`
|
|
- education card details built separately from `documents` in `src/components/EducationSubsection.tsx`
|
|
- Experience/education split source: `DashboardLayout` renders `WorkExperienceSubsection` and `EducationSubsection` as separate blocks (`src/components/DashboardLayout.tsx`), so hover wiring and pill treatment are inconsistent by design.
|
|
- Sidebar tags source mismatch: tags are static in `src/data/tags.ts` and consumed directly in `src/components/Sidebar.tsx`, not derived from actual timeline entities.
|
|
|
|
## Target Canonical Model
|
|
Define a single timeline entity type in `src/types/pmr.ts` and canonical data module in `src/data/timeline.ts`.
|
|
|
|
Required per-entry fields:
|
|
- `id: string`
|
|
- `kind: 'career' | 'education'`
|
|
- `title: string` (full card title)
|
|
- `graphLabel: string` (short node label)
|
|
- `organization: string`
|
|
- `orgColor: string`
|
|
- `dateRange: { start: string; end: string | null; display: string; startYear: number; endYear: number | null }`
|
|
- `description: string`
|
|
- `details: string[]` (card bullets)
|
|
- `skills: string[]` (skill IDs for graph links + aggregation)
|
|
|
|
Derived selectors/utilities in `src/data/timeline.ts`:
|
|
- `timelineEntities` (canonical array, sorted reverse-chronological)
|
|
- `buildConstellationData()` => role nodes + links from canonical entities + skills catalog
|
|
- `getTopTimelineSkills(limit)` => ordered skills by descending frequency for sidebar tags
|
|
|
|
## File-Level Implementation Plan
|
|
1. Add canonical types/data and migrate existing records.
|
|
- Files: `src/types/pmr.ts`, new `src/data/timeline.ts`, optionally thin compatibility exports from `src/data/consultations.ts`/`src/data/constellation.ts`.
|
|
- Action: move career + education entries into `timelineEntities`; stop hand-maintained duplicate date fields.
|
|
|
|
2. Refactor graph data construction to consume canonical entities only.
|
|
- Files: `src/data/constellation.ts` (or replace with derived module), `src/components/CareerConstellation.tsx`.
|
|
- Action: remove hard-coded role node years/labels from graph source and generate from canonical date ranges.
|
|
|
|
3. Stabilize hover interaction and remove graph-wide re-init on hover.
|
|
- File: `src/components/CareerConstellation.tsx`.
|
|
- Action:
|
|
- Split graph init/layout effect from highlight-only effect.
|
|
- Keep simulation/SVG creation dependent on dimensions/data only.
|
|
- Apply highlight updates imperatively via ref without rebuilding nodes/forces.
|
|
- Keep `onNodeHover` contract for role nodes; ensure null reset on leave/touch clear.
|
|
|
|
4. Unify timeline card rendering (career + education in one flow).
|
|
- Files: replace `src/components/WorkExperienceSubsection.tsx` and `src/components/EducationSubsection.tsx` usage with a unified list component (new `src/components/TimelineInterventionsSubsection.tsx` or equivalent), update `src/components/DashboardLayout.tsx`.
|
|
- Action:
|
|
- Remove standalone work-experience subheader and old role pill treatment.
|
|
- Render both kinds in one chronological list.
|
|
- Career cards: `Career Intervention` pill.
|
|
- Education cards: right-aligned card layout + `Education Intervention` pill inside each card.
|
|
- Remove separate education block under work experience.
|
|
|
|
5. Unify graph/card highlight source of truth.
|
|
- Files: `src/components/DashboardLayout.tsx`, unified timeline component, `src/components/CareerConstellation.tsx`.
|
|
- Action:
|
|
- Replace split `highlightedNodeId`/`highlightedRoleId` with one active timeline entry ID for role-type entities.
|
|
- Hovering graph role node highlights matching card; hovering matching card highlights graph node.
|
|
- Keep click behavior opening detail panel by entity kind.
|
|
|
|
6. Feed sidebar tags from canonical skill aggregation.
|
|
- Files: `src/components/Sidebar.tsx`, `src/data/tags.ts` (remove static dependency or convert to fallback only), `src/data/timeline.ts`.
|
|
- Action:
|
|
- Compute top N frequent skills from `timelineEntities.skills`.
|
|
- Map aggregated skills to existing `Tag` shape with deterministic color-variant mapping.
|
|
|
|
7. Regression sweep + quality gates.
|
|
- Files: `src/components/CommandPalette.tsx`, `src/lib/search.ts` only if section IDs/labels or timeline references need consistency updates.
|
|
- Action: ensure route/anchor labels still work after removing separate education section.
|
|
|
|
## Build/Verification Checklist
|
|
- Hovering graph node and corresponding card produce identical highlight result.
|
|
- Hover no longer causes graph jitter/repositioning.
|
|
- Graph timeline date ranges and card date ranges match for every entry.
|
|
- Canonical timeline dataset is the only source for career + education cards and graph role nodes/links.
|
|
- Sidebar tags are generated from canonical skill frequencies (descending).
|
|
- Career entries show `Career Intervention`; education entries are right-aligned with `Education Intervention`.
|
|
- Separate education section below experience is removed.
|
|
- `npm run lint`
|
|
- `npm run typecheck`
|
|
- `npm run build`
|
|
|
|
## Runtime Task Mapping
|
|
- `task-1771244841-616d`: canonical model/data unification
|
|
- `task-1771244841-cb07`: graph stability + shared hover lifecycle
|
|
- `task-1771244841-2f8e`: unified career/education timeline presentation
|
|
- `task-1771244841-9748`: sidebar tag aggregation + quality gates
|
|
|
|
## Progress Updates
|
|
- 2026-02-16: Completed `task-1771244841-616d`.
|
|
- Added canonical timeline schema (`TimelineEntity`, `TimelineEntityDateRange`, `TimelineEntityKind`) in `src/types/pmr.ts`.
|
|
- Added `src/data/timeline.ts` as source-of-truth for timeline entities, including `timelineEntities`, `timelineConsultations`, `buildConstellationData()`, and `getTopTimelineSkills()`.
|
|
- Replaced static duplicated `consultations` and `constellation` datasets with compatibility exports derived from canonical timeline data.
|
|
- Validation run: `npm run lint`, `npm run typecheck`, `npm run build` all passed (warnings only).
|
|
- 2026-02-16: Completed `task-1771244841-cb07`.
|
|
- Refactored `src/components/CareerConstellation.tsx` so the D3 initialization/simulation effect depends only on `dimensions` rather than hover/pin state.
|
|
- Added ref-backed highlight target tracking (`highlightedNodeIdRef`, `pinnedNodeIdRef`) so hover and pin changes update styling without tearing down/recreating the SVG simulation.
|
|
- Updated pointer/touch handlers and render tick highlight fallback to read from refs, preserving graph-card hover sync while eliminating hover-driven graph reinitialization jitter.
|
|
- Validation run: `npm run lint`, `npm run typecheck`, `npm run build` all passed (same pre-existing warnings only).
|
|
- 2026-02-16: Completed `task-1771244841-2f8e`.
|
|
- Added `src/components/TimelineInterventionsSubsection.tsx` to render career + education entries in one canonical timeline flow sourced from `timelineEntities`.
|
|
- Replaced separate `WorkExperienceSubsection` + `EducationSubsection` blocks in `src/components/DashboardLayout.tsx` with unified timeline rendering; removed standalone education section beneath work experience.
|
|
- Removed legacy chronology "Role/Education" badge pills around the split sections, and added per-card intervention pills:
|
|
- Career cards show `Career Intervention`.
|
|
- Education cards show `Education Intervention`.
|
|
- Added right-aligned treatment for education cards in `src/index.css` via `.timeline-intervention-item--education`.
|
|
- Preserved graph/card hover parity by keeping existing `onNodeHighlight` + `highlightedRoleId` wiring across unified cards.
|
|
- Validation run: `npm run lint`, `npm run typecheck`, `npm run build` all passed (same pre-existing warnings only).
|
|
- 2026-02-16: Completed `task-1771244841-9748`.
|
|
- Replaced static sidebar tags in `src/data/tags.ts` with canonical aggregation via `getTopTimelineSkills()`, preserving deterministic ordering (most frequent skills first) and mapping to existing tag color variants.
|
|
- Kept sidebar rendering path unchanged in `src/components/Sidebar.tsx` so tags now automatically follow canonical timeline skill frequencies.
|
|
- Validation run: `npm run lint`, `npm run typecheck`, `npm run build`, `npm audit --omit=dev` passed (`eslint` retains the same 2 pre-existing react-refresh warnings).
|
|
- Repository check confirmed no automated test/spec files are currently present under `src/`.
|