triqura-ecd/docs/intent/intake-intent-proces/bouwplan-cortex-shared-components.md

🚀 Mission Control — Bouwplan Cortex Shared Components

Projectnaam: Cortex Intake Intent System - Shared Components Versie: v1.0 Datum: 03-02-2026 Auteur: Colin Lit

---

1. Doel en Context

🎯 Doel: Bouwen van herbruikbare shared components en hooks voor alle Cortex Intake Blocks. Deze componenten vormen de foundation voor de intake-gerelateerde intents.

📘 Context: De Cortex Command Center heeft momenteel 7 werkende intents, maar geen van de 26 intake-gerelateerde intents is geïmplementeerd. De shared components zijn de eerste stap om dit te realiseren. Ze worden hergebruikt door alle nieuwe intake blocks.

Relatie met andere documenten:

Document	Relatie
fo-to-cortex-shared-components.md	Functionele en technische specificaties
intake-process-intents.md	Intent definities die deze components gebruiken
gap-analyse-intake-cortex.md	Identificeert de behoefte aan deze components

---

2. Uitgangspunten

2.1 Technische Stack

Component	Technologie	Reden
Framework	Next.js 14 (App Router)	Bestaande stack
UI Library	React 18 + TypeScript	Type safety, DX
Styling	Tailwind CSS	Utility-first, consistent met project
Icons	Lucide React	Bestaande icon library
Components	shadcn/ui	Button, etc. al in gebruik
State	Zustand (cortex-store)	Bestaande state management
Animations	Framer Motion	Optioneel, al in project

2.2 Projectkaders

Kader	Waarde
Tijd	1 dag bouwtijd
Scope	4 components + 2 hooks
Team	1 developer
Data	Geen nieuwe data, alleen UI
Doel	Foundation voor intake blocks

2.3 Programmeer Uitgangspunten

Code Quality Principles:

• DRY - Herbruikbare components en utility functions
• KISS - Eenvoudige oplossingen, geen premature optimization
• SOC - UI gescheiden van business logic, hooks voor data
• YAGNI - Alleen bouwen wat nu nodig is

Development Practices:

• TypeScript strict mode
• Props interfaces geëxporteerd voor hergebruik
• Consistente naamgeving (Block* prefix)
• JSDoc comments voor public API
• Tree-shakeable exports via index.ts

---

3. Epics & Stories Overzicht

Epic ID	Titel	Doel	Status	Stories	Geschat
E0	Block States	Loading/Error/Empty states	⏳ To Do	3	2 uur
E1	Block Layout	Section/Item/Footer components	⏳ To Do	3	2 uur
E2	Custom Hooks	Data fetching en context hooks	⏳ To Do	2	2 uur
E3	Integration	Exports en documentatie	⏳ To Do	2	1 uur

Totaal geschat: ~7 uur (1 werkdag)

---

4. Epics & Stories (Uitwerking)

Epic 0 — Block States

Epic Doel: Consistente states voor alle blocks (loading, error, empty).

Story ID	Beschrijving	Acceptatiecriteria	Status	Afhankelijkheden	SP
E0.S1	BlockLoading component	Spinner + message, centered, animatie	⏳	—	1
E0.S2	BlockError component	Error icon + message + retry button	⏳	—	1
E0.S3	BlockEmpty component	Custom icon + message + action button	⏳	—	1

Technical Notes:

// Verwachte exports
export { BlockLoading } from './block-states';
export { BlockError } from './block-states';
export { BlockEmpty } from './block-states';

Acceptatiecriteria E0:

• Alle 3 states renderen correct
• Props zijn fully typed met interfaces
• Responsive op alle block sizes (sm/md/lg)
• Consistent met bestaande design (slate colors, tailwind)

---

Epic 1 — Block Layout

Epic Doel: Herbruikbare layout components voor block content.

Story ID	Beschrijving	Acceptatiecriteria	Status	Afhankelijkheden	SP
E1.S1	BlockSection component	Icon + title + count + children wrapper	⏳	—	1
E1.S2	BlockItem component	Title + subtitle + badge, clickable optie	⏳	—	2
E1.S3	BlockFooter component	Secondary + primary action buttons	⏳	E1.S2	1

Technical Notes:

// Badge variants voor BlockItem
type BadgeVariant = 'default' | 'success' | 'warning' | 'danger';

// Helper functie
export function getRiskBadgeVariant(level: string): BadgeVariant;

Acceptatiecriteria E1:

• Section toont icon met configureerbare kleur
• Item is klikbaar wanneer onClick meegegeven
• Item hover state alleen bij klikbaar
• Footer acties correct aligned (left/right)
• Footer toont loading spinner op primary action

---

Epic 2 — Custom Hooks

Epic Doel: Hooks voor data fetching en context management.

Story ID	Beschrijving	Acceptatiecriteria	Status	Afhankelijkheden	SP
E2.S1	useBlockData hook	Generic fetch met loading/error states, refetch	⏳	error-handler.ts	3
E2.S2	useIntakeContext hook	Patient + Intake context van store/prefill	⏳	cortex-store	2

Technical Notes:

// useBlockData interface
interface UseBlockDataResult<T> {
  data: T | null;
  isLoading: boolean;
  error: string | null;
  refetch: () => Promise<void>;
}

// useIntakeContext interface
interface UseIntakeContextResult {
  patientId: string | null;
  intakeId: string | null;
  patientName: string | null;
  hasPatientContext: boolean;
  hasIntakeContext: boolean;
}

Acceptatiecriteria E2:

• useBlockData handelt errors via bestaande error-handler
• useBlockData toont toast bij error
• useBlockData supported enabled flag voor conditional fetching
• useIntakeContext valt terug op activePatient uit store
• useIntakeContext is memoized om re-renders te voorkomen

---

Epic 3 — Integration

Epic Doel: Exports, documentatie en integratie met bestaande code.

Story ID	Beschrijving	Acceptatiecriteria	Status	Afhankelijkheden	SP
E3.S1	Index exports	Barrel file met alle exports	⏳	E0, E1, E2	1
E3.S2	Update bestaande blocks	Refactor ZoekenBlock naar shared components	⏳	E3.S1	2

Technical Notes:

// components/cortex/shared/index.ts
// Block States
export { BlockLoading, BlockError, BlockEmpty } from './block-states';

// Block Layout
export { BlockSection } from './block-section';
export { BlockItem, getRiskBadgeVariant, type BadgeVariant } from './block-item';
export { BlockFooter } from './block-footer';

// Existing (unchanged)
export { PatientListItem, PatientListEmpty, PatientListLoading } from './patient-list-item';
export { LinkedEvidence } from './linked-evidence';

Acceptatiecriteria E3:

• Alle components importeerbaar via @/components/cortex/shared
• Hooks importeerbaar via @/lib/cortex/hooks
• Geen breaking changes voor bestaande code
• ZoekenBlock werkt nog na refactor (smoke test)

---

5. Implementatie Volgorde

E0.S1 BlockLoading     ──┐
E0.S2 BlockError       ──┼──▶ E0 Complete
E0.S3 BlockEmpty       ──┘
                              │
E1.S1 BlockSection     ──┐    │
E1.S2 BlockItem        ──┼──▶ E1 Complete
E1.S3 BlockFooter      ──┘    │
                              │
E2.S1 useBlockData     ──┬──▶ E2 Complete
E2.S2 useIntakeContext ──┘    │
                              │
E3.S1 Index exports    ──┬──▶ E3 Complete ──▶ ✅ DONE
E3.S2 Refactor test    ──┘

---

6. Bestandsstructuur (Deliverables)

components/cortex/shared/
├── block-states.tsx        🆕 E0.S1-S3
├── block-section.tsx       🆕 E1.S1
├── block-item.tsx          🆕 E1.S2
├── block-footer.tsx        🆕 E1.S3
├── index.ts                🆕 E3.S1 (update)
├── patient-list-item.tsx   ✅ Bestaat
└── linked-evidence.tsx     ✅ Bestaat

lib/cortex/hooks/
├── use-block-data.ts       🆕 E2.S1
├── use-intake-context.ts   🆕 E2.S2
├── use-patient-search.ts   ✅ Bestaat
└── use-patient-selection.ts ✅ Bestaat

---

7. Kwaliteit & Testplan

Test Types

Test Type	Scope	Hoe	Status
Type Check	Alle files	pnpm types:check	⏳
Lint	Alle files	pnpm lint	⏳
Visual	Components	Browser inspection	⏳
Integration	ZoekenBlock	Manual smoke test	⏳

Manual Test Checklist

Block States:

• BlockLoading toont spinner + tekst
• BlockError toont error + retry knop werkt
• BlockEmpty toont icon + message + action werkt

Block Layout:

• BlockSection toont icon in juiste kleur
• BlockSection toont count badge
• BlockItem is klikbaar met hover state
• BlockItem toont badge in juiste kleur
• BlockFooter toont beide acties
• BlockFooter primary loading state werkt

Hooks:

• useBlockData fetcht data correct
• useBlockData toont loading state
• useBlockData toont error bij failure
• useBlockData refetch werkt
• useIntakeContext leest activePatient
• useIntakeContext leest prefill data

Integration:

• Alle exports werken via index.ts
• ZoekenBlock werkt nog na changes
• Geen TypeScript errors
• Geen console errors

---

8. Definition of Done

Een story is DONE wanneer:

• Code is geschreven volgens FO/TO spec
• TypeScript compileert zonder errors
• ESLint toont geen errors
• Component/hook werkt in browser
• Props zijn gedocumenteerd met JSDoc
• Export is toegevoegd aan index.ts

Het project is DONE wanneer:

• Alle 10 stories zijn DONE
• Manual test checklist is 100% ✅
• ZoekenBlock smoke test passed
• pnpm build slaagt

---

9. Risico's & Mitigatie

Risico	Kans	Impact	Mitigatie
Breaking changes bestaande blocks	Middel	Hoog	Backward compatible exports, smoke test
Performance issues hooks	Laag	Middel	useMemo, useCallback waar nodig
Inconsistente styling	Laag	Laag	Tailwind design tokens hergebruiken
Scope creep (extra features)	Middel	Middel	Strict aan FO/TO houden, YAGNI

---

10. Dependencies Check

Bestaande dependencies (geen installatie nodig):

• ✅ lucide-react - Icons
• ✅ @/components/ui/button - shadcn Button
• ✅ @/lib/utils - cn() helper
• ✅ @/lib/cortex/error-handler - safeFetch, getErrorInfo
• ✅ @/stores/cortex-store - useCortexStore
• ✅ @/hooks/use-toast - Toast notifications

Geen nieuwe dependencies nodig ✅

---

11. Referenties

Project Documents:

• docs/intent/intake-intent-proces/fo-to-cortex-shared-components.md - FO/TO
• docs/intent/intake-intent-proces/intake-process-intents.md - Intents
• docs/intent/intake-intent-proces/gap-analyse-intake-cortex.md - Gap analyse
• docs/intent/intake-intent-proces/block-template-pattern.md - Patterns

Bestaande Code (referentie):

• components/cortex/shared/patient-list-item.tsx - Pattern voorbeeld
• components/cortex/blocks/zoeken-block.tsx - Block voorbeeld
• lib/cortex/hooks/use-patient-search.ts - Hook voorbeeld

---

12. Glossary

Term	Betekenis
Block	UI component in Cortex canvas-area
Shared Component	Herbruikbare UI component voor blocks
Hook	React custom hook voor logic/state
Prefill	Data meegegeven aan block bij openen
Intent	Gebruikers intentie (spraak/tekst)

---

Versiehistorie:

Versie	Datum	Auteur	Wijziging
v1.0	03-02-2026	Colin Lit	Initiële versie