@jmruthers/pace-core 0.6.1 → 0.6.3

package/docs/migration/RBAC_SCOPE_MIGRATION.md

@@ -0,0 +1,385 @@
+# RBAC Scope Migration Guide
+
+## Overview
+
+This migration moves RBAC scope from app-level (`rbac_apps.requires_event`) to page-level (`rbac_app_pages.scope_type`). This enables hybrid apps like `pace-mint` to have both event-based and organisation-based pages within the same app.
+
+**⚠️ BREAKING CHANGE**: This migration removes app-level scope configuration entirely. All scope is now configured at the page level with no backward compatibility.
+
+## What Changed
+
+**Removed**: App-level scope configuration (`rbac_apps.requires_event`)  
+**Now**: Page-level scope only (`rbac_app_pages.scope_type`)
+
+### Why This Change?
+
+1. **Single Source of Truth**: Scope is stored in one place (page-level), making it easier to understand and maintain
+2. **More Flexible**: Each page can have its own scope, enabling hybrid apps like pace-mint
+3. **Simpler Queries**: No need to join with `rbac_apps` to determine scope
+4. **More Explicit**: No inheritance logic - scope is always clear from the page itself
+5. **No Backward Compatibility Overhead**: Clean break from old patterns
+
+## Breaking Changes
+
+### Removed APIs
+
+1. **`UnifiedAuthProvider.appConfig` prop** - No longer needed
+2. **`useAppConfig().requiresEvent`** - Use `getPageScopeType(pageId)` instead
+3. **`useAppConfig().supportsDirectAccess`** - No longer relevant
+4. **`ContextValidator.validateScope()`** - Use `resolveScopeForPage()` instead
+5. **`ContextValidator.resolveRequiredContext()`** - Use `resolveScopeForPage()` instead
+6. **`ContextValidator.isContextReady()`** - Context readiness checked per page
+7. **`RBACSecurityValidator.validateContextRequirements()`** - No longer needed
+8. **`getAppConfig()`, `getAppConfigByName()`, `getAppConfigWithClient()`** - Use `getPageScopeType()` instead
+
+### Changed APIs
+
+1. **`useRBAC(pageId)`** - Now requires `pageId` parameter for proper scope resolution
+2. **`getPermissionMap()`, `getRoleContext()`, `getAccessLevel()`, `isPermitted()`** - No longer accept `appConfig` parameter
+
+### Removed Components
+
+- `OrganisationSelector` - Use `ContextSelector` instead
+- `EventSelector` - Use `ContextSelector` instead
+- `HybridContextSelector` - Use `ContextSelector` instead
+
+### Removed Props
+
+- `Header.showEventSelector` - Use `showContextSelector` instead
+- `Header.showOrgSelector` - Use `showContextSelector` instead
+- `PaceAppLayout.showEventSelector` - Use `showContextSelector` instead
+- `PaceAppLayout.showOrgSelector` - Use `showContextSelector` instead
+
+## Migration Steps
+
+### Step 1: Run Database Migration
+
+Run the migration to populate `rbac_app_pages.scope_type`:
+
+```bash
+supabase migration up
+```
+
+**Migration 1:** `supabase/migrations/20251231124932_add_page_scope_type_to_rbac_app_pages.sql`
+- Adds `scope_type` column to `rbac_app_pages`
+- Populates `scope_type` for all existing pages based on their app's `requires_event`
+- Makes `scope_type` NOT NULL (required for all pages)
+- Creates `get_page_scope_type()` function
+- **Drops `rbac_apps.requires_event` column** (no longer needed)
+
+**Migration 2:** `supabase/migrations/20251231131610_update_rpc_functions_remove_requires_event.sql`
+- Updates `data_rbac_apps_list` to remove `requires_event` from return type
+- Updates `data_user_events_get` to remove `requires_event` check (always checks event app roles if app_id provided)
+
+### Step 2: Verify Page Scope Types
+
+Check that all pages have `scope_type` set:
+
+```sql
+-- Check for any pages without scope_type (should return 0 rows after migration)
+SELECT 
+  ap.page_name,
+  ap.scope_type,
+  a.name as app_name
+FROM rbac_app_pages ap
+JOIN rbac_apps a ON ap.app_id = a.id
+WHERE ap.scope_type IS NULL;
+```
+
+If any pages have `NULL` scope_type after migration, update them:
+
+```sql
+-- For event-based pages
+UPDATE rbac_app_pages
+SET scope_type = 'event'
+WHERE page_name = 'your-page-name' 
+  AND app_id = (SELECT id FROM rbac_apps WHERE name = 'YOUR_APP');
+
+-- For organisation-based pages
+UPDATE rbac_app_pages
+SET scope_type = 'organisation'
+WHERE page_name = 'your-page-name'
+  AND app_id = (SELECT id FROM rbac_apps WHERE name = 'YOUR_APP');
+```
+
+### Step 3: Update UnifiedAuthProvider
+
+**Before:**
+```tsx
+<UnifiedAuthProvider
+  appConfig={{ requires_event: true }}
+  // ... other props
+>
+  {children}
+</UnifiedAuthProvider>
+```
+
+**After:**
+```tsx
+<UnifiedAuthProvider
+  // appConfig prop removed - scope is now page-level
+  // ... other props
+>
+  {children}
+</UnifiedAuthProvider>
+```
+
+### Step 4: Update useRBAC Calls
+
+**Before:**
+```tsx
+const { permissionMap } = useRBAC(); // No pageId
+```
+
+**After:**
+```tsx
+const { permissionMap } = useRBAC(pageId); // Pass pageId for proper scope resolution
+```
+
+### Step 5: Replace useAppConfig Usage
+
+**Before:**
+```tsx
+const { requiresEvent, supportsDirectAccess } = useAppConfig();
+
+if (requiresEvent) {
+  // Show event selector
+}
+```
+
+**After:**
+```tsx
+import { getPageScopeType } from '@jmruthers/pace-core';
+
+const pageScopeType = await getPageScopeType(pageId, appId, appName);
+
+if (pageScopeType === 'event' || pageScopeType === 'both') {
+  // Show event selector (or use ContextSelector which handles this automatically)
+}
+```
+
+### Step 6: Update ContextValidator Usage
+
+**Before:**
+```tsx
+import { ContextValidator } from '@jmruthers/pace-core';
+
+const validation = await ContextValidator.resolveRequiredContext(
+  scope,
+  appConfig,
+  appName,
+  supabase
+);
+```
+
+**After:**
+```tsx
+import { ContextValidator, getPageScopeType } from '@jmruthers/pace-core';
+
+const pageScopeType = await getPageScopeType(pageId, appId, appName);
+const validation = await ContextValidator.resolveScopeForPage(
+  scope,
+  pageScopeType,
+  appName,
+  supabase
+);
+```
+
+### Step 7: Update Permission Checks
+
+**Before:**
+```tsx
+const permissionMap = await getPermissionMap(
+  { userId, scope },
+  appConfig,
+  appName
+);
+```
+
+**After:**
+```tsx
+const permissionMap = await getPermissionMap(
+  { userId, scope }
+  // appConfig and appName no longer needed
+);
+```
+
+### Step 8: Update Selector Components
+
+**Before:**
+```tsx
+<Header
+  showOrgSelector={true}
+  showEventSelector={true}
+/>
+```
+
+**After:**
+```tsx
+<Header
+  showContextSelector={true} // Single unified selector
+/>
+```
+
+## Page Scope Types
+
+After migration, all pages must have one of these `scope_type` values:
+
+### `'event'`
+Page requires event context. Organisation is derived from event.
+
+### `'organisation'`
+Page requires organisation context. Event is optional.
+
+### `'both'`
+Page can be accessed with either event or organisation context. Permissions are merged (union), with higher permissions taking precedence.
+
+## Creating New Pages
+
+When creating new pages, always set `scope_type` explicitly:
+
+```sql
+-- Create an event-based page
+INSERT INTO rbac_app_pages (app_id, page_name, page_description, scope_type)
+VALUES (
+  (SELECT id FROM rbac_apps WHERE name = 'MINT'),
+  'budget',
+  'Event Budget Management',
+  'event'  -- ✅ Explicit scope type
+);
+
+-- Create an organisation-based page
+INSERT INTO rbac_app_pages (app_id, page_name, page_description, scope_type)
+VALUES (
+  (SELECT id FROM rbac_apps WHERE name = 'MINT'),
+  'dashboard',
+  'Organisation Dashboard',
+  'organisation'  -- ✅ Explicit scope type
+);
+
+-- Create a 'both' page (can use either context)
+INSERT INTO rbac_app_pages (app_id, page_name, page_description, scope_type)
+VALUES (
+  (SELECT id FROM rbac_apps WHERE name = 'MINT'),
+  'reports',
+  'Reports (Event or Organisation)',
+  'both'  -- ✅ Can be accessed with either context
+);
+```
+
+## Hybrid Apps (e.g., pace-mint)
+
+For apps that have both event-based and organisation-based pages:
+
+1. Set `scope_type = 'event'` for event-based pages (e.g., budget pages)
+2. Set `scope_type = 'organisation'` for organisation-based pages (e.g., settings pages)
+3. Set `scope_type = 'both'` for pages that can use either context
+
+Example:
+```sql
+-- Event-based budget page
+UPDATE rbac_app_pages
+SET scope_type = 'event'
+WHERE page_name = 'budget' AND app_id = (SELECT id FROM rbac_apps WHERE name = 'MINT');
+
+-- Organisation-based settings page
+UPDATE rbac_app_pages
+SET scope_type = 'organisation'
+WHERE page_name = 'settings' AND app_id = (SELECT id FROM rbac_apps WHERE name = 'MINT');
+```
+
+## API Changes Summary
+
+### `getPageScopeType()`
+
+**Before**: Could return `null` (inherit from app)
+
+**After**: Always returns a value (`'event'`, `'organisation'`, or `'both'`)
+
+```typescript
+// After migration, this always returns a value
+const scopeType = await getPageScopeType(pageId, appId, appName);
+// scopeType is now: 'event' | 'organisation' | 'both' (never null)
+```
+
+### `resolveScopeForPage()`
+
+**Before**: Accepted `appConfig` parameter and could inherit from app
+
+**After**: `pageScopeType` is required (never null), `appConfig` removed
+
+```typescript
+// After migration
+const validation = await ContextValidator.resolveScopeForPage(
+  scope,
+  pageScopeType,  // Required, never null
+  appName,
+  supabase
+);
+```
+
+## Benefits
+
+1. **Clearer Intent**: Each page explicitly declares its scope requirements
+2. **Easier Debugging**: No need to trace through app-level config to understand page scope
+3. **Better Performance**: Direct lookup from page table, no join needed
+4. **More Flexible**: Hybrid apps can have mixed scopes without special handling
+5. **No Backward Compatibility Overhead**: Clean, maintainable codebase
+
+## Testing Checklist
+
+- [ ] Database migration completed successfully
+- [ ] All pages have `scope_type` set (no NULL values)
+- [ ] `UnifiedAuthProvider` no longer uses `appConfig` prop
+- [ ] All `useRBAC()` calls pass `pageId` parameter
+- [ ] All `useAppConfig().requiresEvent` replaced with `getPageScopeType()`
+- [ ] All deprecated `ContextValidator` methods replaced
+- [ ] All selector components updated to use `ContextSelector`
+- [ ] Permission checks work correctly for all page types
+- [ ] Event-based pages work correctly
+- [ ] Organisation-based pages work correctly
+- [ ] Hybrid pages (scope_type = 'both') work correctly
+
+## Troubleshooting
+
+### Pages Not Showing in Navigation
+
+If pages aren't showing after migration:
+
+1. **Check scope_type is set**:
+   ```sql
+   SELECT page_name, scope_type FROM rbac_app_pages WHERE app_id = 'your-app-id';
+   ```
+
+2. **Verify scope matches context**:
+   - Event-based pages require `eventId` to be selected
+   - Organisation-based pages require `organisationId` to be selected
+   - 'both' pages work with either context
+
+3. **Check permissions**: Ensure user has permissions for the page in the correct scope
+
+### Permission Denied Errors
+
+If you get permission denied errors:
+
+1. **Verify scope_type matches selected context**:
+   - If page is `'event'`, ensure an event is selected
+   - If page is `'organisation'`, ensure an organisation is selected
+
+2. **Check page permissions are configured** for the correct scope type
+
+3. **Verify user's roles are active** (valid_from/valid_to dates)
+
+### ContextSelector Not Showing Items
+
+1. Check user has organisation memberships or event-app roles
+2. Verify organisations/events are active
+3. Check RLS policies allow user to see the items
+4. Ensure super admin status if testing as super admin
+
+## Related Documentation
+
+- [pace-mint RBAC Setup Guide](../pace-mint-rbac-setup.md) - Specific guide for hybrid apps
+- [Context Selector Component](../components/context-selector.md) - Unified selector documentation
+- [RBAC System Overview](../rbac/README.md) - General RBAC documentation
+- [Event-Based Apps](../rbac/event-based-apps.md) - Event-based app patterns

package/docs/migration/README.md

@@ -6,12 +6,25 @@ reviewedBy: documentation-standards-audit
 
 # Migration Guide
 
-> **🔄 Upgrade and Migration** | [Unified Migration Guide](./MIGRATION_GUIDE.md) | [RBAC Migration](./rbac-migration.md)
+> **🔄 Upgrade and Migration** | [Unified Migration Guide](./MIGRATION_GUIDE.md) | [RBAC Migration](./V0.4.0_rbac-migration.md)
 
 [← Back to Documentation](../README.md) | [↑ Table of Contents](#table-of-contents) | [Next: Unified Migration Guide →](./MIGRATION_GUIDE.md)
 
 Complete migration guides for upgrading to and between versions of `@jmruthers/pace-core`.
 
+## 📖 Documentation Structure
+
+This migration documentation follows a clear structure to help you find the information you need:
+
+- **CHANGELOG.md**: High-level announcements and summaries with links to detailed guides
+- **Migration Guides**: Step-by-step instructions, code examples, and troubleshooting
+  - **Version-Specific**: `V0.5.190_TO_V0.6.1_MIGRATION.md` - Complete migration for specific versions
+  - **Feature-Specific**: `V0.6.0_REACT_19_MIGRATION.md`, `V0.4.0_rbac-migration.md` - Focused guides for specific features (with version stamps at start)
+  - **Database-Specific**: `database-changes-december-2025.md` - Database schema changes
+  - **General**: `MIGRATION_GUIDE.md` - General migration patterns and best practices
+
+**For documentation structure guidelines, see:** [Documentation Structure](./DOCUMENTATION_STRUCTURE.md)
+
 ## 📚 Start Here: Unified Migration Guide
 
 **For all migrations, start with:** [Complete Migration Guide](./MIGRATION_GUIDE.md)
@@ -29,6 +42,8 @@ The unified guide provides:
 - [Quick Migration Checklist](#-quick-migration-checklist)
 - [Version Migrations](#-version-migrations)
 - [Critical Fixes](#-critical-fixes)
+  - [v0.5.190 → v0.6.1 Comprehensive Migration Guide](#v05190--v061-comprehensive-migration-guide)
+  - [Person-Scoped Profiles Migration](#person-scoped-profiles-migration-v05190)
 - [From Other Libraries](#-from-other-libraries)
 - [RBAC Migration](#-rbac-migration)
 - [Migration Tools](#-migration-tools)
@@ -64,6 +79,25 @@ This guide covers:
 
 ## 🚨 Critical Fixes
 
+### v0.5.190 → v0.6.1 Comprehensive Migration Guide
+
+**NEW**: Complete migration guide for upgrading from v0.5.190 to v0.6.1.
+
+**Breaking Changes:**
+- React 19 upgrade (all apps must upgrade)
+- Database schema changes (table naming standardization)
+- Person-scoped profiles migration
+
+**Migration Guide**: [v0.5.190 → v0.6.1 Migration Guide](./V0.5.190_TO_V0.6.1_MIGRATION.md)
+
+**Quick Summary**:
+- Upgrade React to 19.2.3+
+- Apply database migrations
+- Update all table name references
+- Remove `organisation_id` filters from profile queries
+- Configure React Compiler
+- See full guide for detailed instructions
+
 ### Person-Scoped Profiles Migration (v0.5.190+)
 
 **BREAKING CHANGE**: Profiles (membership, medical, and contact) have been migrated from organisation-scoped to person-scoped.
@@ -74,7 +108,7 @@ This guide covers:
 - One membership per person (enforced by unique constraint)
 - Related tables (`pace_consent`, `pace_identification`, `pace_qualification`, etc.) also no longer have `organisation_id`
 
-**Migration Guide**: [Person-Scoped Profiles Migration Guide](./person-scoped-profiles-migration-guide.md)
+**Migration Guide**: [Person-Scoped Profiles Migration Guide](./V0.5.190_person-scoped-profiles-migration-guide.md)
 
 **Quick Summary**:
 - Remove all `organisation_id` filters/queries for profile tables
@@ -91,7 +125,7 @@ This guide covers:
 - Super admin permissions returning false
 - Potential data leakage between organisations
 
-**Migration**: [Organisation Context Timing Fix](./organisation-context-timing-fix.md)
+**Migration**: [Organisation Context Timing Fix](./V0.3.44_organisation-context-timing-fix.md)
 
 **Quick Fix**:
 ```bash
@@ -393,7 +427,7 @@ function MyComponent() {
 
 ## 🔐 RBAC Migration
 
-For detailed RBAC migration, see the [RBAC Migration Guide](./rbac-migration.md).
+For detailed RBAC migration, see the [RBAC Migration Guide](./V0.4.0_rbac-migration.md).
 
 ### Quick RBAC Migration
 
@@ -487,8 +521,20 @@ import '@jmruthers/pace-core/src/styles/core.css';
 
 ## 📚 Additional Resources
 
-- **[RBAC Migration Guide](./rbac-migration.md)** - Detailed RBAC migration
-- **[Migration Guide](./MIGRATION_GUIDE.md)** - Complete migration reference
+### Migration Guides
+
+- **[Complete Migration Guide](./MIGRATION_GUIDE.md)** - General migration patterns and best practices
+- **[v0.5.190 → v0.6.1 Migration Guide](./V0.5.190_TO_V0.6.1_MIGRATION.md)** - Comprehensive migration for v0.6.1
+- **[React 19 Migration Guide](./V0.6.0_REACT_19_MIGRATION.md)** - React 19 upgrade instructions (v0.6.0)
+- **[RBAC Migration Guide](./V0.4.0_rbac-migration.md)** - RBAC system migration (v0.4.0+)
+- **[Person-Scoped Profiles Migration](./V0.5.190_person-scoped-profiles-migration-guide.md)** - Profile migration guide (v0.5.190+)
+- **[Database Changes December 2025](./database-changes-december-2025.md)** - Database schema changes
+- **[Migration Guide](./MIGRATION_GUIDE.md)** - Comprehensive migration guide with quick reference table
+
+### Documentation
+
+- **[Documentation Structure](./DOCUMENTATION_STRUCTURE.md)** - Guidelines for CHANGELOG and migration docs
+- **[CHANGELOG.md](../../CHANGELOG.md)** - Version history and change announcements
 - **[Common Issues](../troubleshooting/common-issues.md)** - Troubleshooting migration issues
 - **[API Reference](../api-reference/)** - Complete API documentation