@jmruthers/pace-core 0.6.2 → 0.6.4

package/docs/components/context-selector.md

@@ -0,0 +1,126 @@
+# Context Selector - Unified Intelligent Selector
+
+## Overview
+
+The `ContextSelector` (formerly `HybridContextSelector`) is the **single unified selector** for all pace-core applications. It intelligently shows all organisations and events a user can access based on their roles and permissions.
+
+## Why Unified Selector?
+
+Previously, apps had to choose between:
+- `OrganisationSelector` - for org-based apps
+- `EventSelector` - for event-based apps  
+- `HybridContextSelector` - for hybrid apps
+
+This created complexity and required apps to know their scope type upfront. With page-level scope, we can now intelligently show **everything** the user can access in one place.
+
+## How It Works
+
+The `ContextSelector` automatically:
+
+1. **Shows all accessible organisations** - Based on user's organisation roles
+2. **Shows all accessible events** - Based on user's event-app roles and organisation membership
+3. **Groups items intelligently** - Organisations and Events in separate sections
+4. **Handles super admins** - Shows all orgs and events
+5. **Respects permissions** - Only shows what user can actually access
+
+## Usage
+
+### Basic Usage
+
+```tsx
+import { ContextSelector } from '@jmruthers/pace-core';
+
+function MyHeader() {
+  const { switchOrganisation } = useOrganisations();
+  const { events, setSelectedEvent } = useEvents();
+
+  return (
+    <ContextSelector
+      onOrganisationSelect={(org) => switchOrganisation(org.id)}
+      onEventSelect={(event) => {
+        const fullEvent = events.find(e => e.event_id === event.event_id);
+        setSelectedEvent(fullEvent || event);
+      }}
+    />
+  );
+}
+```
+
+### In Header Component
+
+The `Header` component now uses `ContextSelector` by default:
+
+```tsx
+<Header
+  logoUrl="/logo.svg"
+  showContextSelector={true} // Default: shows unified selector
+  user={user}
+  onSignOut={handleSignOut}
+/>
+```
+
+### In PaceAppLayout
+
+```tsx
+<PaceAppLayout
+  appName="MINT"
+  showContextSelector={true} // Default: shows unified selector
+  navItems={navItems}
+>
+  {children}
+</PaceAppLayout>
+```
+
+## Migration from Separate Selectors
+
+### Before (Separate Selectors)
+
+```tsx
+<Header
+  showOrgSelector={true}
+  showEventSelector={true}
+  // ...
+/>
+```
+
+### After (Unified Selector)
+
+```tsx
+<Header
+  showContextSelector={true} // Single prop replaces both
+  // ...
+/>
+```
+
+## Benefits
+
+1. **Simpler API** - One selector instead of three
+2. **Better UX** - Users see everything they can access in one place
+3. **Intelligent** - Automatically determines what to show based on permissions
+4. **Future-proof** - Works with any app configuration (org-based, event-based, hybrid)
+5. **No configuration needed** - Just use it, it figures out what to show
+
+## Migration from Separate Selectors
+
+**⚠️ BREAKING CHANGE**: The separate selectors have been removed. You must migrate to `ContextSelector`.
+
+### 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
+
+## Implementation Details
+
+The selector uses:
+- `useOrganisations()` - Gets accessible organisations
+- `useEvents()` - Gets accessible events (already filtered by permissions)
+- `useRBAC()` - Checks super admin status
+
+Both hooks already filter based on user permissions, so the selector automatically shows the correct items.
+

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