@jmruthers/pace-core 0.5.193 → 0.6.2

package/docs/migration/V0.5.190_TO_V0.6.1_MIGRATION.md

@@ -0,0 +1,1153 @@
+# Migration Guide: v0.5.190 → v0.6.1
+
+**Version:** 0.6.1  
+**Previous Version:** 0.5.190  
+**Migration Date:** January 2025  
+**Breaking Changes:** Yes
+
+## Overview
+
+This comprehensive migration guide covers all changes between pace-core v0.5.190 and v0.6.1. This upgrade includes major breaking changes including React 19 upgrade, database schema changes, and new features.
+
+**⚠️ CRITICAL**: This migration requires:
+1. React 19 upgrade (breaking)
+2. Database migrations (breaking)
+3. Code updates for table name changes (breaking)
+4. TypeScript type regeneration
+
+**Estimated Migration Time:** 2-4 hours depending on codebase size
+
+---
+
+## Table of Contents
+
+1. [Quick Start Checklist](#quick-start-checklist)
+2. [Breaking Changes](#breaking-changes)
+   - [React 19 Upgrade](#1-react-19-upgrade-breaking)
+   - [Database Schema Changes](#2-database-schema-changes-breaking)
+   - [Table Naming Standardization](#21-table-naming-standardization)
+   - [Person-Scoped Profiles Migration](#22-person-scoped-profiles-migration)
+3. [New Features](#new-features)
+   - [useFormDialog Hook](#useformdialog-hook)
+   - [DateTimeField Component](#datetimefield-component)
+   - [DatePickerWithTimezone Component](#datepickerwithtimezone-component)
+   - [Timezone Utilities](#timezone-utilities)
+   - [Location Utilities](#location-utilities)
+4. [Step-by-Step Migration](#step-by-step-migration)
+5. [Code Examples](#code-examples)
+6. [Testing Checklist](#testing-checklist)
+7. [Troubleshooting](#troubleshooting)
+
+---
+
+## Quick Start Checklist
+
+Use this checklist to track your migration progress:
+
+### Pre-Migration
+- [ ] Backup your project and database
+- [ ] Review this entire migration guide
+- [ ] Identify all database queries in your codebase
+- [ ] Identify all React component patterns that may need updates
+- [ ] Test current version in development environment
+
+### Phase 1: Dependencies
+- [ ] Upgrade React to 19.2.3+
+- [ ] Upgrade React DOM to 19.2.3+
+- [ ] Upgrade @types/react to 19.2.7+
+- [ ] Upgrade @types/react-dom to 19.2.3+
+- [ ] Upgrade @vitejs/plugin-react to 5.1.2+
+- [ ] Install babel-plugin-react-compiler (optional but recommended)
+- [ ] Update pace-core to 0.6.1
+
+### Phase 2: Database Migrations
+- [ ] Apply person-scoped profiles migration (`20251205211120_migrate_profiles_to_person_scoped.sql`)
+- [ ] Apply table naming standardization migration (`20251206111258_standardize_table_naming_app_entity.sql`)
+- [ ] Verify all migrations applied successfully
+- [ ] Regenerate TypeScript database types
+
+### Phase 3: Code Updates
+- [ ] Update all table name references (`organisations` → `core_organisations`, etc.)
+- [ ] Remove `organisation_id` filters from profile table queries
+- [ ] Update `pace_contact` queries to use `person_id` instead of `member_id`
+- [ ] Update React component code for React 19 compatibility
+- [ ] Configure React Compiler in vite.config.ts
+- [ ] Fix TypeScript errors
+
+### Phase 4: Testing
+- [ ] Run type checking (`npm run type-check`)
+- [ ] Run build (`npm run build`)
+- [ ] Test all database queries
+- [ ] Test authentication flows
+- [ ] Test profile management
+- [ ] Test file uploads
+- [ ] Test navigation and permissions
+- [ ] Test cross-organisation scenarios
+- [ ] Run full test suite
+
+### Phase 5: Deployment
+- [ ] Deploy to staging environment
+- [ ] Perform full regression testing
+- [ ] Deploy to production
+- [ ] Monitor for errors
+
+---
+
+## Breaking Changes
+
+### 1. React 19 Upgrade (BREAKING)
+
+**Impact:** High - All consuming apps must upgrade to React 19
+
+#### What Changed
+
+- **React**: `^18.3.1` → `^19.2.3`
+- **React DOM**: `^18.3.1` → `^19.2.3`
+- **@types/react**: `^18.3.17` → `^19.2.7`
+- **@types/react-dom**: `^18.3.5` → `^19.2.3`
+- **@vitejs/plugin-react**: `^4.5.1` → `^5.1.2`
+- **React Compiler**: Added `babel-plugin-react-compiler@^1.0.0` (optional but recommended)
+
+#### Quick Summary
+
+- All consuming apps must upgrade to React 19.2.3+
+- React Compiler should be configured for optimal performance
+- TypeScript types are stricter, especially for `child.props` access
+- Error handling behavior has changed
+
+**📖 For complete React 19 migration instructions, see:** [React 19 Migration Guide](./V0.6.0_REACT_19_MIGRATION.md)
+
+The dedicated React 19 migration guide includes:
+- Step-by-step dependency updates
+- Vite configuration changes
+- TypeScript type updates
+- React Compiler setup
+- Troubleshooting common issues
+- Testing checklist
+
+---
+
+### 2. Database Schema Changes (BREAKING)
+
+**Impact:** High - All database queries must be updated
+
+There are two major database schema changes that affect consuming applications:
+
+#### 2.1. Table Naming Standardization
+
+**Migration:** `20251206111258_standardize_table_naming_app_entity.sql`  
+**Date:** 2025-12-06
+
+All tables have been renamed to follow the `app_entity` naming convention:
+- **Core infrastructure tables** → `core_*` prefix
+- **Application-specific tables** → `{app}_*` prefix (e.g., `cake_*`, `trac_*`, `medi_*`)
+- **Shared PACE tables** → `core_*` prefix
+
+##### Core Table Renames
+
+| Old Name | New Name |
+|----------|----------|
+| `organisations` | `core_organisations` |
+| `event` | `core_events` |
+| `file_references` | `core_file_references` |
+| `pace_person` | `core_person` |
+| `pace_member` | `core_member` |
+| `pace_contact` | `core_contact` |
+| `pace_address` | `core_address` |
+| `pace_phone` | `core_phone` |
+| `pace_consent` | `core_consent` |
+| `pace_identification` | `core_identification` |
+| `pace_qualification` | `core_qualification` |
+| All other `pace_*` tables | `core_*` |
+
+##### View Changes
+
+| Old Name | New Name | Notes |
+|----------|----------|-------|
+| `organisation_memberships` | **DROPPED** | Merged into `core_organisation_memberships` |
+| `user_organisation_memberships` | **DROPPED** | Merged into `core_organisation_memberships` |
+| - | `core_organisation_memberships` | **NEW** - Unified membership view |
+
+##### Code Updates Required
+
+**Before:**
+```typescript
+// ❌ This will fail - table name changed
+const { data } = await supabase
+  .from('organisations')
+  .select('*');
+```
+
+**After:**
+```typescript
+// ✅ Use new table name
+const { data } = await supabase
+  .from('core_organisations')
+  .select('*');
+```
+
+**Before:**
+```typescript
+// ❌ This will fail - view dropped
+const { data } = await supabase
+  .from('organisation_memberships')
+  .select('*')
+  .eq('organisation_id', orgId);
+```
+
+**After:**
+```typescript
+// ✅ Use new unified view
+const { data } = await supabase
+  .from('core_organisation_memberships')
+  .select('*')
+  .eq('organisation_id', orgId);
+```
+
+**Before:**
+```typescript
+// ❌ This will fail - table names changed
+const { data } = await supabase
+  .from('pace_person')
+  .select('*, pace_member(*), organisations(*)')
+  .eq('id', personId);
+```
+
+**After:**
+```typescript
+// ✅ Use new table names
+const { data } = await supabase
+  .from('core_person')
+  .select('*, core_member(*), core_organisations(*)')
+  .eq('id', personId);
+```
+
+**Before:**
+```typescript
+// ❌ This will fail - table name changed
+const { data } = await supabase
+  .from('file_references')
+  .select('*')
+  .eq('table_name', 'pace_person')
+  .eq('record_id', personId);
+```
+
+**After:**
+```typescript
+// ✅ Use new table names
+const { data } = await supabase
+  .from('core_file_references')
+  .select('*')
+  .eq('table_name', 'core_person')  // Also update table_name values
+  .eq('record_id', personId);
+```
+
+**Important**: The `table_name` column in `core_file_references` has been updated to use new table names. If you're querying by `table_name`, ensure you use the new names:
+- `'pace_person'` → `'core_person'`
+- `'event'` → `'core_events'`
+- `'pace_member'` → `'core_member'`
+- `'pace_contact'` → `'core_contact'`
+- etc.
+
+##### Search and Replace Strategy
+
+Use your IDE's search and replace to update table names:
+
+1. **Search for old table names:**
+   - `'organisations'` → `'core_organisations'`
+   - `'event'` → `'core_events'`
+   - `'pace_person'` → `'core_person'`
+   - `'pace_member'` → `'core_member'`
+   - `'pace_contact'` → `'core_contact'`
+   - etc.
+
+2. **Update view references:**
+   - `'organisation_memberships'` → `'core_organisation_memberships'`
+   - `'user_organisation_memberships'` → `'core_organisation_memberships'`
+
+3. **Update file reference table_name values:**
+   - `'pace_person'` → `'core_person'`
+   - `'event'` → `'core_events'`
+   - etc.
+
+#### 2.2. Person-Scoped Profiles Migration
+
+**Migration:** `20251205211120_migrate_profiles_to_person_scoped.sql` + related migrations  
+**Date:** 2025-12-05
+
+Profiles have been migrated from **organisation-scoped** to **person-scoped**:
+- **One membership profile** (`core_member`) per person (regardless of organisation)
+- **One medical profile** (`medi_profile`) per person
+- **Multiple contact profiles** (`core_contact`) per person
+
+##### Key Changes
+
+1. **Removed `organisation_id`** from:
+   - `core_member` (was `pace_member`)
+   - `medi_profile`
+   - `core_contact` (was `pace_contact`)
+   - Related tables: `medi_condition`, `medi_diet`, `medi_action_plan`, `core_consent`, `core_identification`, `core_qualification`
+
+2. **Removed `member_id`** from `core_contact` (now uses `person_id` directly)
+
+3. **Added unique constraint** on `core_member.person_id` (one membership per person)
+
+##### Code Updates Required
+
+**Before:**
+```typescript
+// ❌ This will fail - organisation_id column no longer exists
+const { data } = await supabase
+  .from('pace_member')
+  .select('*')
+  .eq('person_id', personId)
+  .eq('organisation_id', orgId);
+```
+
+**After:**
+```typescript
+// ✅ No organisation_id needed - one profile per person
+const { data } = await supabase
+  .from('core_member')
+  .select('*')
+  .eq('person_id', personId);
+```
+
+**Before:**
+```typescript
+// ❌ This will fail - member_id column no longer exists
+const { data } = await supabase
+  .from('pace_contact')
+  .select('*')
+  .eq('member_id', memberId);
+```
+
+**After:**
+```typescript
+// ✅ Use person_id instead
+const { data } = await supabase
+  .from('core_contact')
+  .select('*')
+  .eq('person_id', personId);
+```
+
+**Before:**
+```typescript
+// ❌ This will fail - organisation_id required
+await supabase
+  .from('pace_member')
+  .insert({
+    person_id: personId,
+    organisation_id: orgId, // ❌ Column doesn't exist
+    membership_number: '12345'
+  });
+```
+
+**After:**
+```typescript
+// ✅ No organisation_id needed
+await supabase
+  .from('core_member')
+  .insert({
+    person_id: personId,
+    membership_number: '12345'
+  });
+```
+
+##### Getting Organisation Members
+
+**Before:**
+```typescript
+// ❌ This pattern no longer works
+const { data } = await supabase
+  .from('pace_member')
+  .select('*')
+  .eq('organisation_id', orgId);
+```
+
+**After:**
+```typescript
+// ✅ Get members via organisation roles
+const { data: orgMembers } = await supabase
+  .from('rbac_organisation_roles')
+  .select(`
+    organisation_id,
+    user_id,
+    core_person!inner(
+      id,
+      core_member(*)
+    )
+  `)
+  .eq('organisation_id', orgId)
+  .eq('status', 'active');
+```
+
+**For detailed person-scoped profiles migration instructions, see:** [Person-Scoped Profiles Migration Guide](./V0.5.190_person-scoped-profiles-migration-guide.md)
+
+**For detailed database changes, see:** [Database Changes December 2025](./database-changes-december-2025.md)
+
+---
+
+## New Features
+
+### useFormDialog Hook
+
+**New in:** Unreleased (0.6.1)
+
+Generic React hook for managing form dialog state (open/close, form data, reset behavior). Supports both controlled and uncontrolled usage patterns with type-safe form data management.
+
+**Usage:**
+
+```tsx
+import { useFormDialog } from '@jmruthers/pace-core';
+
+function MyComponent() {
+  const formDialog = useFormDialog<FormData>({
+    defaultValues: { name: '', email: '' }
+  });
+
+  return (
+    <>
+      <Button onClick={() => formDialog.open()}>Open Form</Button>
+      <Dialog open={formDialog.isOpen} onOpenChange={formDialog.setOpen}>
+        <DialogContent>
+          <Form form={form} onSubmit={formDialog.handleSubmit}>
+            {/* Form fields */}
+          </Form>
+        </DialogContent>
+      </Dialog>
+    </>
+  );
+}
+```
+
+### DateTimeField Component
+
+**New in:** Unreleased (0.6.1)
+
+Form input component for datetime values with automatic UTC ↔ timezone conversion.
+
+**Features:**
+- Supports both ISO string and Date object values
+- Automatic timezone conversion
+- Prevents unwanted conversions during user editing
+- Shows timezone information when not UTC
+- Accessible form field with proper labels
+
+**Usage:**
+
+```tsx
+import { DateTimeField, Form, useZodForm } from '@jmruthers/pace-core';
+
+function MyForm() {
+  const form = useZodForm({
+    schema: z.object({
+      eventDate: z.string().datetime()
+    })
+  });
+
+  return (
+    <Form form={form}>
+      <FormField
+        control={form.control}
+        name="eventDate"
+        render={({ field }) => (
+          <DateTimeField
+            label="Event Date & Time"
+            value={field.value}
+            onChange={field.onChange}
+            timezone="America/New_York"
+          />
+        )}
+      />
+    </Form>
+  );
+}
+```
+
+### DatePickerWithTimezone Component
+
+**New in:** Unreleased (0.6.1)
+
+Date picker component with timezone information display.
+
+**Features:**
+- Calendar date selection with timezone context
+- Shows "Local" when timezone matches user timezone
+- Optional "Done" button
+- Accessible date selection
+
+**Usage:**
+
+```tsx
+import { DatePickerWithTimezone } from '@jmruthers/pace-core';
+
+function MyComponent() {
+  const [date, setDate] = useState<Date | undefined>();
+
+  return (
+    <DatePickerWithTimezone
+      date={date}
+      onDateChange={setDate}
+      timezone="America/New_York"
+      showDoneButton
+    />
+  );
+}
+```
+
+### Timezone Utilities
+
+**New in:** Unreleased (0.6.1)
+
+Comprehensive timezone conversion and formatting utilities.
+
+**Available Utilities:**
+
+```tsx
+import {
+  formatInTimeZone,
+  getTimezoneAbbreviation,
+  formatTimeInTimeZone,
+  getUserTimeZone,
+  toZonedTime,
+  fromZonedTime,
+  roundToNearestMinutes,
+  getTimeZoneDifference,
+  formatDateTimeForDisplay,
+  formatDateOnlyForDisplay,
+  formatDateTimeForTable,
+  formatDateTimeForMap
+} from '@jmruthers/pace-core/utils/timezone';
+```
+
+**Usage Examples:**
+
+```tsx
+import { formatInTimeZone, getUserTimeZone, toZonedTime } from '@jmruthers/pace-core/utils/timezone';
+
+// Format date in specific timezone
+const formatted = formatInTimeZone(
+  new Date(),
+  'America/New_York',
+  'MMM dd, yyyy HH:mm'
+);
+
+// Get user's timezone
+const userTz = getUserTimeZone(); // e.g., "America/New_York"
+
+// Convert UTC to timezone
+const localTime = toZonedTime(new Date(), 'America/New_York');
+
+// Format for display
+const display = formatDateTimeForDisplay(
+  new Date().toISOString(),
+  'America/New_York'
+);
+```
+
+### Location Utilities
+
+**New in:** Unreleased (0.6.1)
+
+Geographic coordinate handling utilities.
+
+**Available Utilities:**
+
+```tsx
+import {
+  formatCoordinates,
+  hasValidCoordinates,
+  areCoordinatesEqual,
+  getGoogleMapsUrl
+} from '@jmruthers/pace-core/utils/location';
+```
+
+**Usage Examples:**
+
+```tsx
+import { formatCoordinates, getGoogleMapsUrl } from '@jmruthers/pace-core/utils/location';
+
+// Format coordinates
+const formatted = formatCoordinates({ lat: 40.7128, lng: -74.0060 });
+// Returns: "40.712800, -74.006000"
+
+// Generate Google Maps URL
+const mapsUrl = getGoogleMapsUrl({ lat: 40.7128, lng: -74.0060 });
+// Returns: "https://www.google.com/maps/search/?api=1&query=40.712800,-74.006000"
+```
+
+---
+
+## Step-by-Step Migration
+
+### Step 1: Backup Everything
+
+```bash
+# Backup your project
+git commit -am "Pre-migration backup"
+
+# Backup your database (if using Supabase CLI)
+supabase db dump > backup.sql
+```
+
+### Step 2: Update Dependencies
+
+**📖 For React 19 dependency updates, see [React 19 Migration Guide](./V0.6.0_REACT_19_MIGRATION.md#step-1-update-react-dependencies).**
+
+```bash
+# Update React and related dependencies (see React 19 guide for details)
+npm install react@^19.2.3 react-dom@^19.2.3
+npm install -D @types/react@^19.2.7 @types/react-dom@^19.2.3
+npm install -D @vitejs/plugin-react@^5.1.2
+npm install -D babel-plugin-react-compiler@latest
+
+# Update pace-core
+npm install @jmruthers/pace-core@0.6.1
+```
+
+### Step 3: Apply Database Migrations
+
+Apply the following migrations in order:
+
+1. **Person-Scoped Profiles Migration:**
+   ```bash
+   # Apply migration
+   supabase migration up 20251205211120_migrate_profiles_to_person_scoped
+   ```
+
+2. **Table Naming Standardization:**
+   ```bash
+   # Apply migration
+   supabase migration up 20251206111258_standardize_table_naming_app_entity
+   ```
+
+**Note:** If you're using Supabase hosted, apply these migrations through the Supabase dashboard or CLI.
+
+### Step 4: Regenerate TypeScript Types
+
+```bash
+# Regenerate database types
+npx supabase gen types typescript --project-id <your-project-id> > src/types/database.generated.ts
+```
+
+### Step 5: Update Vite Configuration for React 19
+
+**📖 See [React 19 Migration Guide](./V0.6.0_REACT_19_MIGRATION.md#step-4-configure-react-compiler-in-vite) for detailed Vite configuration instructions.**
+
+Quick summary: Update your `vite.config.ts` to include React Compiler configuration. The React 19 migration guide includes complete setup instructions.
+
+### Step 6: Update Code
+
+#### 6.1. Update Table Names
+
+Search and replace all table name references:
+
+```bash
+# Use your IDE's search and replace or:
+# Find: 'organisations'
+# Replace: 'core_organisations'
+
+# Find: 'event'
+# Replace: 'core_events'
+
+# Find: 'pace_person'
+# Replace: 'core_person'
+
+# Find: 'pace_member'
+# Replace: 'core_member'
+
+# Find: 'pace_contact'
+# Replace: 'core_contact'
+
+# Find: 'organisation_memberships'
+# Replace: 'core_organisation_memberships'
+
+# Find: 'user_organisation_memberships'
+# Replace: 'core_organisation_memberships'
+```
+
+#### 6.2. Remove Organisation ID Filters
+
+Search for and remove `organisation_id` filters from profile table queries:
+
+```typescript
+// Find patterns like:
+.eq('organisation_id', orgId)
+
+// In queries to:
+// - core_member
+// - medi_profile
+// - core_contact
+// - core_consent
+// - core_identification
+// - core_qualification
+```
+
+#### 6.3. Update Contact Queries
+
+Update `pace_contact` queries to use `person_id` instead of `member_id`:
+
+```typescript
+// Find:
+.eq('member_id', memberId)
+
+// Replace with:
+.eq('person_id', personId)
+```
+
+#### 6.4. Update React Component Code for React 19
+
+**📖 See [React 19 Migration Guide](./V0.6.0_REACT_19_MIGRATION.md#step-5-update-typescript-types) for detailed React 19 TypeScript updates.**
+
+If you have components that access `child.props`, you'll need to add type assertions. The React 19 migration guide includes complete examples and patterns.
+
+### Step 7: Fix TypeScript Errors
+
+```bash
+# Run type checking
+npm run type-check
+
+# Fix all TypeScript errors
+# Common fixes:
+# - Update table name types
+# - Add type assertions for child.props
+# - Update import paths if needed
+```
+
+### Step 8: Test Your Application
+
+```bash
+# Run build
+npm run build
+
+# Run tests
+npm run test
+
+# Start dev server
+npm run dev
+```
+
+---
+
+## Code Examples
+
+### Example 1: Organisation Query
+
+**Before:**
+```typescript
+const { data: organisations } = await supabase
+  .from('organisations')
+  .select('*')
+  .eq('is_active', true);
+```
+
+**After:**
+```typescript
+const { data: organisations } = await supabase
+  .from('core_organisations')
+  .select('*')
+  .eq('is_active', true);
+```
+
+### Example 2: Event Query with Joins
+
+**Before:**
+```typescript
+const { data: events } = await supabase
+  .from('event')
+  .select(`
+    *,
+    organisations(*)
+  `)
+  .eq('organisation_id', orgId);
+```
+
+**After:**
+```typescript
+const { data: events } = await supabase
+  .from('core_events')
+  .select(`
+    *,
+    core_organisations(*)
+  `)
+  .eq('organisation_id', orgId);
+```
+
+### Example 3: Person with Member Profile
+
+**Before:**
+```typescript
+const { data: person } = await supabase
+  .from('pace_person')
+  .select(`
+    *,
+    pace_member(*)
+  `)
+  .eq('id', personId)
+  .eq('organisation_id', orgId)  // ❌ organisation_id no longer exists
+  .single();
+```
+
+**After:**
+```typescript
+const { data: person } = await supabase
+  .from('core_person')
+  .select(`
+    *,
+    core_member(*)
+  `)
+  .eq('id', personId)
+  .single();  // ✅ No organisation_id needed
+```
+
+### Example 4: Organisation Memberships
+
+**Before:**
+```typescript
+const { data: memberships } = await supabase
+  .from('organisation_memberships')
+  .select('*')
+  .eq('organisation_id', orgId)
+  .eq('user_id', userId);
+```
+
+**After:**
+```typescript
+const { data: memberships } = await supabase
+  .from('core_organisation_memberships')
+  .select('*')
+  .eq('organisation_id', orgId)
+  .eq('user_id', userId);
+```
+
+### Example 5: File References
+
+**Before:**
+```typescript
+const { data: files } = await supabase
+  .from('file_references')
+  .select('*')
+  .eq('table_name', 'pace_person')
+  .eq('record_id', personId);
+```
+
+**After:**
+```typescript
+const { data: files } = await supabase
+  .from('core_file_references')
+  .select('*')
+  .eq('table_name', 'core_person')  // Updated table_name value
+  .eq('record_id', personId);
+```
+
+### Example 6: Getting Member Profile
+
+**Before:**
+```typescript
+async function getMemberProfile(personId: string, orgId: string) {
+  const { data } = await supabase
+    .from('pace_member')
+    .select('*')
+    .eq('person_id', personId)
+    .eq('organisation_id', orgId)  // ❌
+    .single();
+  return data;
+}
+```
+
+**After:**
+```typescript
+async function getMemberProfile(personId: string) {
+  // ✅ No organisation_id needed - one profile per person
+  const { data } = await supabase
+    .from('core_member')
+    .select('*')
+    .eq('person_id', personId)
+    .single();
+  return data;
+}
+```
+
+### Example 7: Getting Contacts
+
+**Before:**
+```typescript
+async function getContacts(memberId: string) {
+  const { data } = await supabase
+    .from('pace_contact')
+    .select('*')
+    .eq('member_id', memberId)  // ❌
+    .eq('organisation_id', orgId);  // ❌
+  return data;
+}
+```
+
+**After:**
+```typescript
+async function getContacts(personId: string) {
+  // ✅ Use person_id directly
+  const { data } = await supabase
+    .from('core_contact')
+    .select('*')
+    .eq('person_id', personId);
+  return data;
+}
+```
+
+### Example 8: React Component with child.props
+
+**Before:**
+```tsx
+React.Children.map(children, (child) => {
+  if (React.isValidElement(child)) {
+    const variant = child.props.variant; // ❌ Type error in React 19
+  }
+});
+```
+
+**After:**
+```tsx
+React.Children.map(children, (child) => {
+  if (React.isValidElement(child)) {
+    const props = child.props as { variant?: string; [key: string]: unknown };
+    const variant = props.variant; // ✅ Type-safe
+  }
+});
+```
+
+---
+
+## Testing Checklist
+
+### Database Queries
+- [ ] Test organisation queries with new table names
+- [ ] Test event queries with new table names
+- [ ] Test person/profile queries (person-scoped)
+- [ ] Test file reference queries
+- [ ] Test organisation membership queries
+- [ ] Test cross-organisation scenarios
+
+### React Components
+- [ ] All components render correctly
+- [ ] No TypeScript errors
+- [ ] Error boundaries work correctly
+- [ ] React Compiler is working (check DevTools)
+
+### Authentication
+- [ ] Login works
+- [ ] Logout works
+- [ ] Session restoration works
+- [ ] Organisation switching works
+
+### Permissions
+- [ ] RBAC permission checks work
+- [ ] Navigation filtering works
+- [ ] Page permission guards work
+
+### Forms
+- [ ] Form validation works
+- [ ] Form submission works
+- [ ] New DateTimeField component works (if using)
+
+### Data Tables
+- [ ] Data tables render correctly
+- [ ] Sorting works
+- [ ] Filtering works
+- [ ] Pagination works
+
+### File Uploads
+- [ ] File uploads work
+- [ ] File references use new table names
+- [ ] File display works
+
+### Performance
+- [ ] No performance regressions
+- [ ] React Compiler optimizations working
+- [ ] No memory leaks
+
+---
+
+## Troubleshooting
+
+### Issue 1: "relation does not exist"
+
+**Error:**
+```
+relation "organisations" does not exist
+```
+
+**Solution:**
+Update table name to `core_organisations`:
+```typescript
+// ❌ Old
+.from('organisations')
+
+// ✅ New
+.from('core_organisations')
+```
+
+### Issue 2: "column does not exist"
+
+**Error:**
+```
+column "organisation_id" does not exist in table "core_member"
+```
+
+**Solution:**
+Remove `organisation_id` filters from profile table queries:
+```typescript
+// ❌ Old
+.from('core_member')
+.eq('organisation_id', orgId)  // ❌ Column doesn't exist
+
+// ✅ New
+.from('core_member')
+.eq('person_id', personId)  // ✅ Person-scoped
+```
+
+### Issue 3: View not found
+
+**Error:**
+```
+relation "organisation_memberships" does not exist
+```
+
+**Solution:**
+Use the new unified view:
+```typescript
+// ❌ Old
+.from('organisation_memberships')
+
+// ✅ New
+.from('core_organisation_memberships')
+```
+
+### Issue 4: File reference table_name mismatch
+
+**Error:**
+```
+No file references found (table_name mismatch)
+```
+
+**Solution:**
+Update `table_name` values to use new table names:
+```typescript
+// ❌ Old
+.eq('table_name', 'pace_person')
+
+// ✅ New
+.eq('table_name', 'core_person')
+```
+
+### Issue 5: TypeScript errors with child.props
+
+**Error:**
+```
+Property 'variant' does not exist on type 'unknown'
+```
+
+**Solution:**
+Add type assertion:
+```typescript
+const props = child.props as { variant?: string; [key: string]: unknown };
+const variant = props.variant;
+```
+
+### Issue 6: React Compiler not working
+
+**Symptoms:**
+- No "Memo ✨" badges in React DevTools
+- Performance not improved
+
+**Solution:**
+1. Verify `babel-plugin-react-compiler` is installed
+2. Check `vite.config.ts` has the compiler configured
+3. Restart your dev server
+4. Check React DevTools for "Memo ✨" badges
+
+### Issue 7: Test failures after React 19 upgrade
+
+**Solution:**
+1. Update `@testing-library/react` to latest version
+2. Check for StrictMode-related test issues
+3. Verify error boundaries still work correctly
+4. Update test mocks if needed
+
+---
+
+## Additional Resources
+
+### Documentation
+- [React 19 Migration Guide](./V0.6.0_REACT_19_MIGRATION.md)
+- [Database Changes December 2025](./database-changes-december-2025.md)
+- [Person-Scoped Profiles Migration Guide](./V0.5.190_person-scoped-profiles-migration-guide.md)
+- [RBAC Migration Guide](./V0.4.0_rbac-migration.md)
+
+### External Resources
+- [React 19 Upgrade Guide](https://react.dev/blog/2024/04/25/react-19-upgrade-guide)
+- [React Compiler Documentation](https://react.dev/learn/react-compiler)
+
+### Support
+
+If you encounter issues migrating:
+
+1. **Check Migration Status**: Verify all migrations are applied
+2. **Verify Types**: Regenerate TypeScript types from current schema
+3. **Review RLS**: Ensure RLS policies are correctly applied
+4. **Check Logs**: Review Supabase logs for errors
+5. **Search Codebase**: Use search to find all references to old table names
+
+---
+
+## Summary
+
+**Key Takeaways:**
+
+1. **React 19 Upgrade:**
+   - Must upgrade to React 19.2.3+
+   - Configure React Compiler for optimal performance
+   - Update TypeScript types for `child.props`
+
+2. **Table Naming:**
+   - All core tables → `core_*` prefix
+   - All PACE tables → `core_*` prefix
+   - Application tables → `{app}_*` prefix
+   - Update all queries to use new table names
+
+3. **Views:**
+   - `organisation_memberships` and `user_organisation_memberships` → `core_organisation_memberships`
+
+4. **Profiles:**
+   - Person-scoped (not organisation-scoped)
+   - Remove `organisation_id` from profile queries
+   - Use `person_id` instead of `member_id` for contacts
+
+5. **File References:**
+   - Update `table_name` values to use new table names
+
+6. **Types:**
+   - Regenerate TypeScript types after migrations
+
+7. **New Features:**
+   - `useFormDialog` hook available
+   - `DateTimeField` and `DatePickerWithTimezone` components available
+   - Timezone and location utilities available
+
+**Migration Order:**
+1. Update dependencies (React 19, pace-core 0.6.1)
+2. Apply person-scoped profiles migrations
+3. Apply table naming standardization migrations
+4. Regenerate TypeScript types
+5. Update code to use new table names
+6. Remove `organisation_id` filters from profile queries
+7. Update React component code for React 19
+8. Configure React Compiler
+9. Test thoroughly
+
+---
+
+**Last Updated:** January 2025  
+**Version:** 0.6.1  
+**Previous Version:** 0.5.190
+