@jmruthers/pace-core 0.6.2 → 0.6.4

package/docs/pace-mint-fix-auto-selection.md

@@ -0,0 +1,218 @@
+# Fix for Auto-Selection Issue in pace-mint AppLayout
+
+## Problem
+
+When a user switches from an event to an organisation in the context selector, pace-mint's AppLayout component is auto-selecting the event again, even though the user explicitly cleared it. This causes the selector to show the event instead of the organisation.
+
+## Root Cause
+
+pace-mint's AppLayout has its own auto-selection logic that runs whenever:
+- Events are loaded/refreshed
+- `selectedEvent` becomes `null`
+- There's only one event available
+
+This logic doesn't distinguish between:
+- **Initial load** (should auto-select) 
+- **User explicitly cleared event** (should NOT auto-select)
+
+## Solution
+
+Update pace-mint's AppLayout component to track when the user explicitly clears the event selection, and skip auto-selection in those cases.
+
+## Implementation Steps
+
+### Step 1: Track Previous Event Selection
+
+Add a ref to track the previous `selectedEvent` value to detect when the user explicitly clears it:
+
+```tsx
+import { useRef, useEffect } from 'react';
+import { useEvents } from '@jmruthers/pace-core';
+
+function AppLayout() {
+  const { events, selectedEvent, setSelectedEvent } = useEvents();
+  
+  // Track previous selectedEvent to detect explicit clears
+  const previousSelectedEventRef = useRef<Event | null>(null);
+  const userExplicitlyClearedRef = useRef<boolean>(false);
+  
+  // Detect when user explicitly clears event (was set, now null)
+  useEffect(() => {
+    const wasSet = previousSelectedEventRef.current !== null;
+    const isNowNull = selectedEvent === null;
+    
+    if (wasSet && isNowNull) {
+      // User explicitly cleared the event
+      userExplicitlyClearedRef.current = true;
+    } else if (selectedEvent !== null) {
+      // Event is selected, reset the flag
+      userExplicitlyClearedRef.current = false;
+    }
+    
+    previousSelectedEventRef.current = selectedEvent;
+  }, [selectedEvent]);
+  
+  // ... rest of component
+}
+```
+
+### Step 2: Update Auto-Selection Logic
+
+Modify your auto-selection logic to check the flag before auto-selecting:
+
+```tsx
+// OLD CODE (problematic):
+useEffect(() => {
+  if (!selectedEvent && events.length === 1 && !isLoading) {
+    // Auto-select single event
+    setSelectedEvent(events[0]);
+  }
+}, [selectedEvent, events, isLoading, setSelectedEvent]);
+
+// NEW CODE (fixed):
+useEffect(() => {
+  // Only auto-select if:
+  // 1. No event is currently selected
+  // 2. There's exactly one event available
+  // 3. Events are not loading
+  // 4. User did NOT explicitly clear the event
+  if (
+    !selectedEvent && 
+    events.length === 1 && 
+    !isLoading &&
+    !userExplicitlyClearedRef.current
+  ) {
+    // Auto-select single event
+    setSelectedEvent(events[0]);
+  }
+}, [selectedEvent, events, isLoading, setSelectedEvent]);
+```
+
+### Step 3: Reset Flag on Initial Load (Optional)
+
+If you want to allow auto-selection on initial page load but prevent it after user actions, you can track whether this is the initial load:
+
+```tsx
+const isInitialLoadRef = useRef<boolean>(true);
+
+useEffect(() => {
+  // After first render, mark initial load as complete
+  if (isInitialLoadRef.current && events.length > 0) {
+    isInitialLoadRef.current = false;
+  }
+}, [events]);
+
+// Then in auto-selection logic:
+useEffect(() => {
+  if (
+    !selectedEvent && 
+    events.length === 1 && 
+    !isLoading &&
+    (!userExplicitlyClearedRef.current || isInitialLoadRef.current)
+  ) {
+    setSelectedEvent(events[0]);
+  }
+}, [selectedEvent, events, isLoading, setSelectedEvent]);
+```
+
+## Complete Example
+
+Here's a complete example of the fix:
+
+```tsx
+import { useRef, useEffect } from 'react';
+import { useEvents } from '@jmruthers/pace-core';
+import type { Event } from '@jmruthers/pace-core';
+
+function AppLayout() {
+  const { events, selectedEvent, setSelectedEvent, isLoading } = useEvents();
+  
+  // Track previous selectedEvent to detect explicit clears
+  const previousSelectedEventRef = useRef<Event | null>(null);
+  const userExplicitlyClearedRef = useRef<boolean>(false);
+  const isInitialLoadRef = useRef<boolean>(true);
+  
+  // Detect when user explicitly clears event
+  useEffect(() => {
+    const wasSet = previousSelectedEventRef.current !== null;
+    const isNowNull = selectedEvent === null;
+    
+    if (wasSet && isNowNull) {
+      // User explicitly cleared the event (e.g., switched to organisation)
+      userExplicitlyClearedRef.current = true;
+      console.log('[AppLayout] User explicitly cleared event - preventing auto-selection');
+    } else if (selectedEvent !== null) {
+      // Event is selected, reset the flag
+      userExplicitlyClearedRef.current = false;
+    }
+    
+    previousSelectedEventRef.current = selectedEvent;
+  }, [selectedEvent]);
+  
+  // Mark initial load as complete after events are loaded
+  useEffect(() => {
+    if (isInitialLoadRef.current && events.length > 0 && !isLoading) {
+      isInitialLoadRef.current = false;
+    }
+  }, [events, isLoading]);
+  
+  // Auto-select single event ONLY if:
+  // - No event is selected
+  // - Exactly one event available
+  // - Not loading
+  // - User didn't explicitly clear it (or it's initial load)
+  useEffect(() => {
+    const shouldAutoSelect = 
+      !selectedEvent && 
+      events.length === 1 && 
+      !isLoading &&
+      (!userExplicitlyClearedRef.current || isInitialLoadRef.current);
+    
+    if (shouldAutoSelect) {
+      console.log('[AppLayout] Auto-selecting single available event');
+      setSelectedEvent(events[0]);
+    } else if (!selectedEvent && events.length === 1 && userExplicitlyClearedRef.current) {
+      console.log('[AppLayout] Auto-select skipped - user explicitly cleared event');
+    }
+  }, [selectedEvent, events, isLoading, setSelectedEvent]);
+  
+  // ... rest of your component
+}
+```
+
+## Testing
+
+After implementing the fix, test the following scenarios:
+
+1. **Initial Load**: 
+   - ✅ Should auto-select if only one event is available
+   
+2. **Switch Event to Organisation**:
+   - ✅ Should NOT auto-select event after switching to organisation
+   - ✅ Selector should show the organisation, not the event
+
+3. **Switch Organisation to Event**:
+   - ✅ Should select the event when user explicitly selects it
+   - ✅ Selector should show the event
+
+4. **Manual Event Selection**:
+   - ✅ Should select the event when user clicks on it
+   - ✅ Should not interfere with manual selections
+
+## Additional Notes
+
+- pace-core's EventService already has internal logic to prevent auto-selection when `userClearedEventRef` is set
+- This fix adds an additional layer of protection at the application level
+- The ref-based approach ensures the flag persists across re-renders
+- The initial load flag allows auto-selection on first page load while preventing it after user actions
+
+## Related pace-core Changes
+
+The following changes were made in pace-core to support this fix:
+
+1. **ContextSelector** - Now prioritizes event selection over organisation when both are selected
+2. **Header Component** - Clears event selection when switching to organisation
+3. **EventService** - Preserves `userClearedEventRef` flag when organisation changes
+
+These changes ensure that pace-core respects user intent, but consuming apps (like pace-mint) should also implement the above fix to prevent their own auto-selection logic from interfering.
+

package/docs/pace-mint-rbac-setup.md

@@ -0,0 +1,391 @@
+---
+lastUpdated: 2025-12-31T00:00:00+11:00
+version: 0.6.4
+reviewedBy: pace-mint-implementation-guide
+---
+
+# pace-mint RBAC Setup Guide
+
+This guide explains how to configure pace-mint to support both organisation-based and event-based pages using pace-core's RBAC system.
+
+## Overview
+
+pace-mint is a **hybrid app** that supports both:
+- **Organisation-based pages**: Financial management at the organisation level
+- **Event-based pages**: Budget and budget variables for specific events
+
+Users can have:
+- Organisation roles (org_admin, leader, member, etc.) for organisation-based pages
+- Event-app roles (planner, participant, etc.) for event-based pages
+- Both types of roles simultaneously
+
+## Architecture
+
+### Two-Stream Navigation
+
+pace-mint uses a **two-stream architecture**:
+
+1. **Landing/Dashboard Page**: User selects their mode
+   - "Organisation Financial Management" → Organisation stream
+   - "Event Financial Management" → Event stream
+
+2. **Each Stream**: Has its own navigation showing only relevant pages
+   - Organisation stream: Shows only organisation-scoped pages
+   - Event stream: Shows only event-scoped pages
+
+### Page Scoping
+
+Each page in pace-mint is marked with a `scope_type`:
+
+- `'event'`: Page requires event context (e.g., "budget", "budget-variables")
+- `'organisation'`: Page requires organisation context (e.g., "dashboard", "reports")
+- `'both'`: Page can be accessed in either context (rare, but possible)
+
+**Note**: All pages must have `scope_type` set explicitly. There is no inheritance from app-level configuration.
+
+## Database Setup
+
+### 1. Ensure pace-mint App Configuration
+
+```sql
+-- Verify pace-mint app exists and is configured correctly
+SELECT id, name, display_name, is_active 
+FROM rbac_apps 
+WHERE name = 'MINT';
+
+-- Note: App-level scope configuration (requires_event) has been removed.
+-- All scope is now configured at the page level via scope_type.
+```
+
+### 2. Create/Update Pages with scope_type
+
+For each page in pace-mint, set the `scope_type`:
+
+```sql
+-- Example: Budget page is event-based
+UPDATE rbac_app_pages
+SET scope_type = 'event'
+WHERE app_id = (SELECT id FROM rbac_apps WHERE name = 'MINT')
+  AND page_name = 'budget';
+
+-- Example: Dashboard page is organisation-based (or NULL to inherit)
+UPDATE rbac_app_pages
+SET scope_type = 'organisation'
+WHERE app_id = (SELECT id FROM rbac_apps WHERE name = 'MINT')
+  AND page_name = 'dashboard';
+
+-- Example: Budget variables page is event-based
+UPDATE rbac_app_pages
+SET scope_type = 'event'
+WHERE app_id = (SELECT id FROM rbac_apps WHERE name = 'MINT')
+  AND page_name = 'budget-variables';
+```
+
+**Important**: 
+- All pages must have `scope_type` set explicitly (no NULL values allowed)
+- Set `scope_type` to match the page's context requirements
+- There is no inheritance - each page declares its own scope
+
+### 3. Configure Page Permissions
+
+Set up permissions for each page based on its scope:
+
+#### Event-Based Pages (e.g., "budget")
+
+```sql
+-- Get the page ID
+WITH mint_app AS (
+  SELECT id FROM rbac_apps WHERE name = 'MINT'
+),
+budget_page AS (
+  SELECT ap.id as page_id
+  FROM rbac_app_pages ap
+  JOIN mint_app ma ON ap.app_id = ma.id
+  WHERE ap.page_name = 'budget'
+)
+-- Insert permissions for event-based roles
+INSERT INTO rbac_page_permissions (app_page_id, operation, role_name, allowed, organisation_id)
+SELECT 
+  bp.page_id,
+  op.operation,
+  role.role_name,
+  CASE 
+    WHEN role.role_name = 'planner' THEN true
+    WHEN role.role_name = 'participant' AND op.operation = 'read' THEN true
+    ELSE false
+  END,
+  '00000000-0000-0000-0000-000000000000'::uuid -- ⚠️ REPLACE with actual organisation ID
+FROM budget_page bp
+CROSS JOIN (SELECT unnest(ARRAY['read', 'create', 'update', 'delete']) as operation) op
+CROSS JOIN (SELECT unnest(ARRAY['planner', 'participant', 'viewer']) as role_name) role;
+```
+
+#### Organisation-Based Pages (e.g., "dashboard")
+
+```sql
+-- Get the page ID
+WITH mint_app AS (
+  SELECT id FROM rbac_apps WHERE name = 'MINT'
+),
+dashboard_page AS (
+  SELECT ap.id as page_id
+  FROM rbac_app_pages ap
+  JOIN mint_app ma ON ap.app_id = ma.id
+  WHERE ap.page_name = 'dashboard'
+)
+-- Insert permissions for organisation-based roles
+INSERT INTO rbac_page_permissions (app_page_id, operation, role_name, allowed, organisation_id)
+SELECT 
+  dp.page_id,
+  op.operation,
+  role.role_name,
+  CASE 
+    WHEN role.role_name = 'org_admin' THEN true
+    WHEN role.role_name = 'leader' AND op.operation != 'delete' THEN true
+    WHEN role.role_name = 'member' AND op.operation = 'read' THEN true
+    ELSE false
+  END,
+  '00000000-0000-0000-0000-000000000000'::uuid -- ⚠️ REPLACE with actual organisation ID
+FROM dashboard_page dp
+CROSS JOIN (SELECT unnest(ARRAY['read', 'create', 'update', 'delete']) as operation) op
+CROSS JOIN (SELECT unnest(ARRAY['org_admin', 'leader', 'member', 'supporter']) as role_name) role;
+```
+
+## pace-core Components
+
+### 1. Context Selector Component
+
+pace-core provides a unified `ContextSelector` component that intelligently shows all organisations and events a user can access:
+
+```tsx
+import { ContextSelector } from '@jmruthers/pace-core';
+
+<ContextSelector
+  onOrganisationSelect={(org) => {
+    // Switch to organisation stream
+    setSelectedOrganisation(org);
+    setSelectedEvent(null);
+    navigate('/dashboard'); // Navigate to org-based dashboard
+  }}
+  onEventSelect={(event) => {
+    // Switch to event stream
+    setSelectedEvent(event);
+    setSelectedOrganisation(null);
+    navigate('/budget'); // Navigate to event-based budget page
+  }}
+/>
+```
+
+The `ContextSelector` automatically shows:
+- All organisations the user has access to (via organisation roles)
+- All events the user has access to (via event-app roles or organisation membership)
+- Everything for super admins
+
+### 2. Navigation Filtering
+
+pace-core's navigation automatically filters pages based on:
+- Current context (event selected vs organisation selected)
+- Page `scope_type`
+- User's permissions
+
+You don't need to manually filter - pace-core handles this automatically.
+
+### 3. Permission Checking
+
+pace-core automatically handles permission checking based on page scope:
+
+- **Event-based pages**: Checks event-app roles for the selected event
+- **Organisation-based pages**: Checks organisation roles for the selected organisation
+- **'both' pages**: Checks both scopes and returns the union (higher permissions win)
+
+## Implementation Steps
+
+### Step 1: Database Configuration
+
+1. Run the pace-core migration that adds `scope_type` to `rbac_app_pages`
+2. Update all pace-mint pages with appropriate `scope_type` values
+3. Configure page permissions for each scope type
+
+### Step 2: Landing Page
+
+Create a landing page where users choose their mode:
+
+```tsx
+function MintLandingPage() {
+  const { selectedOrganisation, selectedEvent } = useUnifiedAuth();
+  const navigate = useNavigate();
+  
+  const handleOrgMode = () => {
+    // Ensure organisation is selected
+    if (!selectedOrganisation) {
+      // Show organisation selector
+      return;
+    }
+    navigate('/dashboard');
+  };
+  
+  const handleEventMode = () => {
+    // Ensure event is selected
+    if (!selectedEvent) {
+      // Show event selector
+      return;
+    }
+    navigate('/budget');
+  };
+  
+  return (
+    <main>
+      <section>
+        <h1>pace-mint</h1>
+        <button onClick={handleOrgMode}>
+          Organisation Financial Management
+        </button>
+        <button onClick={handleEventMode}>
+          Event Financial Management
+        </button>
+      </section>
+    </main>
+  );
+}
+```
+
+### Step 3: Navigation Configuration
+
+Configure navigation items with proper page names:
+
+```tsx
+const orgNavItems = [
+  { label: 'Dashboard', pageName: 'dashboard', href: '/dashboard' },
+  { label: 'Reports', pageName: 'reports', href: '/reports' },
+  // ... other org-based pages
+];
+
+const eventNavItems = [
+  { label: 'Budget', pageName: 'budget', href: '/budget' },
+  { label: 'Budget Variables', pageName: 'budget-variables', href: '/budget-variables' },
+  // ... other event-based pages
+];
+```
+
+### Step 4: Use Context Selector in Header
+
+The `PaceAppLayout` component includes the unified `ContextSelector` by default:
+
+```tsx
+import { PaceAppLayout } from '@jmruthers/pace-core';
+
+function App() {
+  const { selectedOrganisation, selectedEvent, setSelectedOrganisation, setSelectedEvent } = useUnifiedAuth();
+  const navigate = useNavigate();
+  
+  return (
+    <PaceAppLayout
+      appName="MINT"
+      navItems={/* your nav items */}
+      showContextSelector={true} // Default: shows unified selector
+    />
+  );
+}
+```
+
+The `ContextSelector` is automatically integrated into the header and handles organisation/event selection. You can also use it directly if you need custom behavior:
+
+```tsx
+import { ContextSelector } from '@jmruthers/pace-core';
+
+<ContextSelector
+  onOrganisationSelect={(org) => {
+    setSelectedOrganisation(org);
+    setSelectedEvent(null);
+    navigate('/dashboard');
+  }}
+  onEventSelect={(event) => {
+    setSelectedEvent(event);
+    setSelectedOrganisation(null);
+    navigate('/budget');
+  }}
+/>
+```
+
+### Step 5: Page Protection
+
+Use `PagePermissionGuard` for all pages:
+
+```tsx
+import { PagePermissionGuard } from '@jmruthers/pace-core/rbac';
+
+function BudgetPage() {
+  return (
+    <PagePermissionGuard pageName="budget" operation="read">
+      {/* Budget page content */}
+    </PagePermissionGuard>
+  );
+}
+```
+
+## Permission Precedence
+
+When a user has both organisation and event permissions for a 'both' page:
+
+1. **Union of permissions**: User gets permissions from both scopes
+2. **Higher order wins**: More permissive permission takes precedence
+   - Access levels: `super` > `admin` > `user` > `none`
+   - Permission values: `true` > `false`
+
+Example:
+- User has `read:budget` at org level (org_admin)
+- User has `write:budget` at event level (planner)
+- Result: User gets `write:budget` (higher permission wins)
+
+## Super Admin Behavior
+
+Super admins:
+- See **all events** in the hybrid selector
+- See **all organisations** in the hybrid selector
+- Can access **all pages** regardless of scope
+- Bypass all permission checks
+
+## Testing Checklist
+
+- [ ] All pages have correct `scope_type` set in database
+- [ ] Event-based pages only accessible when event is selected
+- [ ] Organisation-based pages only accessible when organisation is selected
+- [ ] Navigation filters correctly based on current context
+- [ ] Context selector shows all accessible orgs and events
+- [ ] Permission checks work correctly for each scope type
+- [ ] 'both' pages return union of permissions
+- [ ] Super admins can access all pages
+- [ ] Users with both org and event roles see appropriate pages
+
+## Troubleshooting
+
+### Pages not showing in navigation
+
+1. Check page `scope_type` matches current context
+2. Verify user has permissions for the page
+3. Ensure page exists in `rbac_app_pages` table
+4. Check page permissions are configured in `rbac_page_permissions`
+
+### Permission denied errors
+
+1. Verify user has the required role for the page
+2. Check page `scope_type` matches selected context
+3. Ensure permissions are configured for the correct organisation/event
+4. Verify user's roles are active (valid_from/valid_to dates)
+
+### Context selector 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
+
+- [RBAC Scope Migration Guide](../migration/RBAC_SCOPE_MIGRATION.md) - Complete migration guide
+- [Context Selector Component](../components/context-selector.md) - Unified selector documentation
+- [RBAC System Overview](../rbac/README.md)
+- [Event-Based Apps](../rbac/event-based-apps.md)
+- [Navigation Filtering](../components/NavigationMenu.md)
+- [Page Permission Guard](../rbac/components/PagePermissionGuard.md)
+