@jmruthers/pace-core 0.5.68 → 0.5.70

package/docs/implementation-guides/event-theming-summary.md

@@ -0,0 +1,220 @@
+# Event Theming Implementation Summary
+
+## What Exists in pace-core
+
+### Database Schema
+Events have an `event_colours` JSONB field that stores theme colors in OKLCH format:
+
+```typescript
+interface Event {
+  event_colours?: Record<string, unknown> | null; // JSONB field for theme colors
+}
+```
+
+The expected format:
+```json
+{
+  "main": {
+    "50": {"L": 0.98, "C": 0.007, "H": 29.203},
+    "100": {"L": 0.96, "C": 0.018, "H": 29.203},
+    // ... all Tailwind shades 50-950
+    "raw": {"L": 0.587, "C": 0.24, "H": 29.203}
+  },
+  "sec": { /* secondary palette */ },
+  "acc": { /* accent palette */ }
+}
+```
+
+### Runtime Theming System
+Located in `packages/core/src/theming/runtime.ts`:
+
+- **`applyPalette(palette)`** - Applies event colors dynamically
+- **`clearPalette()`** - Clears dynamic theming, returns to app defaults
+- **`generateSSRThemeCSS(palette)`** - SSR support
+- **`isDynamicThemingActive()`** - Debug helper
+
+### EventProvider
+`packages/core/src/providers/EventProvider.tsx`:
+- Fetches events from database via RPC `data_user_events_get`
+- Stores `event_colours` in the event object
+- Manages event selection state
+- Auto-selects next upcoming event
+
+## What Was Missing
+
+### Automatic Event Theming Integration
+There was **no automatic connection** between event selection and theming application. Consuming apps would need to manually:
+1. Watch for selectedEvent changes
+2. Extract event_colours
+3. Call applyPalette()
+4. Handle cleanup
+
+## What I Added
+
+### New Hook: `useEventTheme()`
+
+**Location:** `packages/core/src/hooks/useEventTheme.ts`
+
+**What it does:**
+- Automatically watches selectedEvent from EventProvider
+- Applies event colors when an event with `event_colours` is selected
+- Clears theming when no event is selected
+- Handles validation, errors, and cleanup
+- Works consistently across all apps
+
+**Usage:**
+```tsx
+import { useEventTheme } from '@jmruthers/pace-core';
+
+function MyApp() {
+  useEventTheme(); // Just call it!
+  
+  return <div>Your app</div>;
+}
+```
+
+**Exports:**
+- Available from `@jmruthers/pace-core` (main export)
+- Available from `@jmruthers/pace-core/hooks` (hooks export)
+
+## Why This in pace-core?
+
+This follows the pace-core principles:
+
+### 1. **Consistency Across App Suite**
+Every app (CAKE, TRACE, ADMIN, etc.) needs event theming. By having it in pace-core, all apps get the same behavior, UX, and error handling.
+
+### 2. **Maximum Code Reuse**
+Instead of every app implementing this logic, it's once in pace-core:
+- No duplicated `useEffect` logic
+- No duplicated event watching
+- No duplicated error handling
+- Centralized improvements benefit all apps
+
+### 3. **Opt-in Design**
+The hook is opt-in - apps call `useEventTheme()` if they want automatic theming. Apps can still use manual `applyPalette()` if they need custom logic.
+
+## Architecture Decision
+
+### What's in pace-core:
+- ✅ Event theming infrastructure (runtime APIs)
+- ✅ Automatic event theming hook (`useEventTheme`)
+- ✅ Documentation and examples
+- ✅ Type definitions
+
+### What's in consuming apps:
+- ✅ Calling `useEventTheme()` in the app component
+- ✅ ADMIN app: Palette picker UI to set colors
+- ✅ ADMIN app: Save colors to database via `event_colours` field
+
+## How It Works
+
+1. **ADMIN app** sets event colors via a palette picker and saves to `event.event_colours` in the database
+2. **Consuming apps** (CAKE, TRACE) call `useEventTheme()` hook
+3. When user selects an event via `EventSelector`, the hook detects the change
+4. Hook extracts `event_colours` from selected event
+5. Hook calls `applyPalette()` with the colors
+6. CSS variables update dynamically → UI colors change
+7. When event is deselected, hook calls `clearPalette()`
+
+## Database Flow
+
+```
+ADMIN App
+  ↓ (User sets colors in palette picker)
+  ↓ (Save to database)
+event.event_colours = {
+  main: { 50: {...}, 100: {...}, ... },
+  sec: { 50: {...}, 100: {...}, ... },
+  acc: { 50: {...}, 100: {...}, ... }
+}
+  ↓ (RPC fetches events)
+EventProvider loads events
+  ↓ (User selects event)
+useEventTheme() detects change
+  ↓ (Applies colors)
+applyPalette() → CSS variables update
+  ↓
+UI colors change in CAKE/TRACE
+```
+
+## Usage Example
+
+```tsx
+// In your consuming app (e.g., CAKE or TRACE)
+
+import { 
+  UnifiedAuthProvider, 
+  EventProvider, 
+  OrganisationProvider,
+  useEventTheme 
+} from '@jmruthers/pace-core';
+
+function App() {
+  // Enable automatic event theming
+  useEventTheme();
+  
+  return (
+    <div>
+      <EventSelector />
+      {/* Rest of your app */}
+    </div>
+  );
+}
+
+function RootLayout() {
+  return (
+    <UnifiedAuthProvider supabaseClient={supabase} appName="CAKE">
+      <OrganisationProvider>
+        <EventProvider>
+          <App />
+        </EventProvider>
+      </OrganisationProvider>
+    </UnifiedAuthProvider>
+  );
+}
+```
+
+## Migration Guide
+
+If you're already manually applying event colors in your consuming apps:
+
+### Before:
+```tsx
+function App() {
+  const { selectedEvent } = useEvents();
+  
+  useEffect(() => {
+    if (selectedEvent?.event_colours) {
+      applyPalette(selectedEvent.event_colours);
+    } else {
+      clearPalette();
+    }
+  }, [selectedEvent]);
+}
+```
+
+### After:
+```tsx
+function App() {
+  useEventTheme(); // Replaces the above useEffect
+  
+  return <div>Your app</div>;
+}
+```
+
+## Benefits
+
+- **Zero boilerplate** - One line to enable automatic theming
+- **Consistent UX** - All apps behave the same way
+- **Less code** - No duplication across apps
+- **Type safe** - Full TypeScript support
+- **Maintainable** - Centralized improvements
+- **Flexible** - Can still use manual API if needed
+
+## Documentation
+
+Full documentation available at:
+- **Implementation Guide:** `packages/core/docs/implementation-guides/dynamic-colors.md`
+- **Usage Guide:** `packages/core/docs/usage.md`
+- **API Reference:** Available in code docs and type definitions

package/docs/implementation-guides/forms.md

@@ -1,4 +1,6 @@
-# Forms Implementation Guide
+# Forms
+
+> **📚 Implementation Guides** | [← Back to Documentation](../README.md) | [Data Tables](./data-tables.md) | [Validation](./forms.md) Implementation Guide
 
 This guide covers how to implement forms using PACE Core's form components and validation system.
 
@@ -175,7 +177,7 @@ const conditionalSchema = z.object({
   }
   return true;
 }, {
-  message: "Organization details are required for organization accounts",
+  message: "Organisation details are required for organization accounts",
   path: ["organizationName"]
 });
 
@@ -191,7 +193,7 @@ function ConditionalForm() {
         type="select" 
         options={[
           { value: 'individual', label: 'Individual' },
-          { value: 'organization', label: 'Organization' }
+          { value: 'organization', label: 'Organisation' }
         ]} 
       />
       
@@ -200,11 +202,11 @@ function ConditionalForm() {
       
       {userType === 'organization' && (
         <Card className="p-4 space-y-4">
-          <h3 className="text-lg font-semibold">Organization Details</h3>
-          <FormField name="organizationName" label="Organization Name" />
+          <h3 className="text-lg font-semibold">Organisation Details</h3>
+          <FormField name="organizationName" label="Organisation Name" />
           <FormField 
             name="organizationSize" 
-            label="Organization Size" 
+            label="Organisation Size" 
             type="select" 
             options={[
               { value: 'small', label: 'Small (1-50 employees)' },
@@ -361,7 +363,7 @@ function CustomFormField({ name, label, ...props }) {
 
 ## Best Practices
 
-### 1. Schema Organization
+### 1. Schema Organisation
 
 ```typescript
 // schemas/user.ts

package/docs/implementation-guides/navigation.md

@@ -1,5 +1,7 @@
 # Navigation Implementation Guide
 
+> **📚 Implementation Guides** | [← Back to Documentation](../README.md) | [App Layout](./app-layout.md) | [Permission Enforcement](./permission-enforcement.md)
+
 This guide covers how to implement navigation systems using PACE Core's navigation components with permission-based filtering and RBAC integration.
 
 ## Overview

package/docs/migration/service-architecture.md

@@ -0,0 +1,351 @@
+# Migration Guide: Service Architecture
+
+## Overview
+
+This guide helps you migrate from the old provider architecture to the new service-based architecture. The new architecture provides better testability, maintainability, and follows SOLID principles.
+
+## Quick Start
+
+### 1. Update Provider Import
+
+Replace the old provider with the new one:
+
+```tsx
+// Old way
+import { UnifiedAuthProvider } from '@core/providers';
+
+// New way
+import { NewUnifiedAuthProvider } from '@core/providers/services/NewUnifiedAuthProvider';
+```
+
+### 2. Update Provider Usage
+
+The new provider has the same API but requires additional configuration:
+
+```tsx
+// Old way
+<UnifiedAuthProvider supabaseClient={supabase} appName="MY_APP">
+  <YourAppContent />
+</UnifiedAuthProvider>
+
+// New way
+<NewUnifiedAuthProvider
+  supabaseClient={supabase}
+  appName="MY_APP"
+  idleTimeoutMs={30 * 60 * 1000} // 30 minutes
+  warnBeforeMs={60 * 1000} // 60 seconds
+  onIdleLogout={() => {
+    // Handle idle logout - redirect to login
+    window.location.href = '/login';
+  }}
+>
+  <YourAppContent />
+</NewUnifiedAuthProvider>
+```
+
+### 3. Update Hook Imports
+
+Replace the old hook with the new one:
+
+```tsx
+// Old way
+import { useUnifiedAuth } from '@core/providers';
+
+// New way
+import { useNewUnifiedAuth } from '@core/providers/services/NewUnifiedAuthProvider';
+```
+
+## Detailed Migration Steps
+
+### Step 1: Update Main App Setup
+
+Update your main app file (usually `main.tsx` or `App.tsx`):
+
+```tsx
+// Before
+import { UnifiedAuthProvider, OrganisationProvider, EventProvider } from '@core/providers';
+
+function App() {
+  return (
+    <UnifiedAuthProvider supabaseClient={supabase} appName="MY_APP">
+      <OrganisationProvider>
+        <EventProvider>
+          <YourAppContent />
+        </EventProvider>
+      </OrganisationProvider>
+    </UnifiedAuthProvider>
+  );
+}
+
+// After
+import { NewUnifiedAuthProvider } from '@core/providers/services/NewUnifiedAuthProvider';
+
+function App() {
+  return (
+    <NewUnifiedAuthProvider
+      supabaseClient={supabase}
+      appName="MY_APP"
+      idleTimeoutMs={30 * 60 * 1000}
+      warnBeforeMs={60 * 1000}
+      onIdleLogout={() => window.location.href = '/login'}
+    >
+      <YourAppContent />
+    </NewUnifiedAuthProvider>
+  );
+}
+```
+
+### Step 2: Update Component Hooks
+
+Update components that use the old hooks:
+
+```tsx
+// Before
+import { useUnifiedAuth } from '@core/providers';
+
+function MyComponent() {
+  const { user, isAuthenticated, signOut } = useUnifiedAuth();
+  // ... component logic
+}
+
+// After
+import { useNewUnifiedAuth } from '@core/providers/services/NewUnifiedAuthProvider';
+
+function MyComponent() {
+  const { user, isAuthenticated, signOut } = useNewUnifiedAuth();
+  // ... component logic (same API)
+}
+```
+
+### Step 3: Update Individual Provider Usage
+
+If you were using individual providers, you can now use individual service hooks:
+
+```tsx
+// Before
+import { useAuth } from '@core/providers';
+import { useOrganisations } from '@core/providers';
+import { useEvents } from '@core/providers';
+
+function MyComponent() {
+  const auth = useAuth();
+  const orgs = useOrganisations();
+  const events = useEvents();
+  // ... component logic
+}
+
+// After - Option 1: Use unified hook (same API)
+import { useNewUnifiedAuth } from '@core/providers/services/NewUnifiedAuthProvider';
+
+function MyComponent() {
+  const auth = useNewUnifiedAuth();
+  // ... component logic (same API)
+}
+
+// After - Option 2: Use individual service hooks (better performance)
+import { useAuth } from '@core/hooks/services/useAuth';
+import { useCurrentOrganisation } from '@core/hooks/services/useCurrentOrganisation';
+import { useCurrentEvent } from '@core/hooks/services/useCurrentEvent';
+
+function MyComponent() {
+  const auth = useAuth();
+  const orgs = useCurrentOrganisation();
+  const events = useCurrentEvent();
+  // ... component logic
+}
+```
+
+## API Changes
+
+### New Required Props
+
+The new provider requires additional props for inactivity management:
+
+```tsx
+interface NewUnifiedAuthProviderProps {
+  // ... existing props
+  idleTimeoutMs: number; // REQUIRED: Inactivity timeout in milliseconds
+  warnBeforeMs: number; // REQUIRED: Warning time before logout in milliseconds
+  onIdleLogout: (reason: 'inactivity') => void; // REQUIRED: App handles redirect/navigation
+}
+```
+
+### Backward Compatibility
+
+The new provider maintains the same API as the old one, so existing components should work without changes:
+
+```tsx
+// This still works exactly the same
+const { user, isAuthenticated, signOut, hasRole, hasPermission } = useNewUnifiedAuth();
+```
+
+## Performance Optimizations
+
+### Use Individual Service Hooks
+
+For better performance, use individual service hooks instead of the unified hook:
+
+```tsx
+// Less efficient - re-renders on any state change
+const auth = useNewUnifiedAuth();
+
+// More efficient - only re-renders when auth state changes
+const auth = useAuth();
+const permissions = usePermissions();
+const organisation = useCurrentOrganisation();
+const events = useCurrentEvent();
+```
+
+### Service Subscription
+
+Services use an observable pattern for efficient updates:
+
+```tsx
+// Services automatically notify subscribers of state changes
+// No need to manually manage subscriptions
+const auth = useAuth(); // Automatically subscribes to auth service changes
+```
+
+## Testing Updates
+
+### Update Test Imports
+
+Update your test files to use the new providers:
+
+```tsx
+// Before
+import { UnifiedAuthProvider } from '@core/providers';
+
+// After
+import { NewUnifiedAuthProvider } from '@core/providers/services/NewUnifiedAuthProvider';
+```
+
+### Update Test Setup
+
+Update your test setup to use the new provider:
+
+```tsx
+// Before
+render(
+  <UnifiedAuthProvider supabaseClient={mockSupabase} appName="TEST_APP">
+    <TestComponent />
+  </UnifiedAuthProvider>
+);
+
+// After
+render(
+  <NewUnifiedAuthProvider
+    supabaseClient={mockSupabase}
+    appName="TEST_APP"
+    idleTimeoutMs={30000}
+    warnBeforeMs={5000}
+    onIdleLogout={() => {}}
+  >
+    <TestComponent />
+  </NewUnifiedAuthProvider>
+);
+```
+
+### Service Testing
+
+You can now test services directly:
+
+```tsx
+// Test services in isolation
+describe('AuthService', () => {
+  let authService: AuthService;
+  
+  beforeEach(() => {
+    authService = new AuthService(mockSupabase);
+  });
+  
+  it('should sign in user', async () => {
+    const result = await authService.signIn('test@example.com', 'password');
+    expect(result.user).toBeDefined();
+  });
+});
+```
+
+## Common Issues and Solutions
+
+### Issue 1: Missing Required Props
+
+**Error**: `Missing required prop: idleTimeoutMs`
+
+**Solution**: Add the required inactivity management props:
+
+```tsx
+<NewUnifiedAuthProvider
+  supabaseClient={supabase}
+  appName="MY_APP"
+  idleTimeoutMs={30 * 60 * 1000} // Add this
+  warnBeforeMs={60 * 1000} // Add this
+  onIdleLogout={() => window.location.href = '/login'} // Add this
+>
+  <YourAppContent />
+</NewUnifiedAuthProvider>
+```
+
+### Issue 2: Hook Not Found
+
+**Error**: `useUnifiedAuth must be used within a UnifiedAuthProvider`
+
+**Solution**: Update the hook import:
+
+```tsx
+// Change this
+import { useUnifiedAuth } from '@core/providers';
+
+// To this
+import { useNewUnifiedAuth } from '@core/providers/services/NewUnifiedAuthProvider';
+```
+
+### Issue 3: Provider Not Found
+
+**Error**: `useNewUnifiedAuth must be used within a NewUnifiedAuthProvider`
+
+**Solution**: Ensure the component is wrapped in the new provider:
+
+```tsx
+// Make sure your app is wrapped in NewUnifiedAuthProvider
+<NewUnifiedAuthProvider {...props}>
+  <YourAppContent />
+</NewUnifiedAuthProvider>
+```
+
+## Migration Checklist
+
+- [ ] Update provider import from `UnifiedAuthProvider` to `NewUnifiedAuthProvider`
+- [ ] Add required inactivity management props (`idleTimeoutMs`, `warnBeforeMs`, `onIdleLogout`)
+- [ ] Update hook import from `useUnifiedAuth` to `useNewUnifiedAuth`
+- [ ] Update test imports and setup
+- [ ] Test the application to ensure everything works
+- [ ] Consider using individual service hooks for better performance
+- [ ] Remove old provider imports once migration is complete
+
+## Rollback Plan
+
+If you need to rollback:
+
+1. **Revert imports**: Change back to old provider imports
+2. **Revert provider usage**: Remove the new required props
+3. **Revert hook usage**: Change back to old hook imports
+4. **Test**: Ensure the application works with the old architecture
+
+## Support
+
+If you encounter issues during migration:
+
+1. **Check the documentation**: Review the service architecture documentation
+2. **Check the examples**: Look at the updated example app
+3. **Check the tests**: Review the test files for usage examples
+4. **Open an issue**: Report bugs or ask questions
+
+## Next Steps
+
+After migration:
+
+1. **Explore individual services**: Consider using individual service hooks for better performance
+2. **Write service tests**: Add unit tests for your custom services
+3. **Optimize performance**: Use individual hooks instead of the unified hook where appropriate
+4. **Contribute**: Help improve the service architecture

package/docs/rbac/README-rbac-rls-integration.md

@@ -6,7 +6,7 @@
 
 The RBAC-RLS integration provides dynamic permission enforcement that automatically respects RBAC configuration changes. This solves the critical issue where:
 
-- **RBAC permissions are configurable** - Organizations can set which roles have which CRUD permissions for each page ✅
+- **RBAC permissions are configurable** - Organisations can set which roles have which CRUD permissions for each page ✅
 - **RLS policies were hardcoded** - Database-level security policies were static and didn't respect the dynamic RBAC configuration ❌
 - **Result:** Users with valid RBAC permissions were blocked by RLS policies, breaking core functionality
 
@@ -346,7 +346,7 @@ When reporting issues, please include:
 
 The RBAC-RLS integration provides a robust, scalable solution for dynamic permission enforcement. It solves the critical architectural issue where RBAC configuration and RLS policies were disconnected, ensuring that:
 
-1. **Organizations have true control** over their permission systems
+1. **Organisations have true control** over their permission systems
 2. **Developers can rely on consistent behavior** across all operations
 3. **Users get the functionality they expect** based on their assigned roles
 4. **The system is maintainable and auditable** with clear change tracking

package/docs/rbac/README.md

@@ -1,6 +1,6 @@
 # RBAC System
 
-> **📚 New to RBAC?** Start with the [Quick Start Guide](./quick-start.md) to get up and running in 10 minutes.
+> **📚 RBAC System** | [← Back to Documentation](../README.md) | [Quick Start](./quick-start.md) | [Permissions](../core-concepts/permissions.md)
 
 The PACE Core RBAC (Role-Based Access Control) system provides comprehensive permission management with organisation context enforcement, caching, and audit logging.
 

package/docs/rbac/examples/rbac-rls-integration-example.md

@@ -6,7 +6,7 @@ This example demonstrates how to use the new RBAC-RLS integration system to solv
 
 Before the RBAC-RLS integration, you had this situation:
 
-1. **RBAC Configuration**: Organization grants `planner` role `delete:page.meals` permission ✅
+1. **RBAC Configuration**: Organisation grants `planner` role `delete:page.meals` permission ✅
 2. **RLS Policy**: Only allows `event_admin` role to delete meals ❌
 3. **Result**: Delete operations fail silently, appearing to succeed but not actually deleting records
 
@@ -223,7 +223,7 @@ USING (
 ## Benefits
 
 ### 1. True Permission Control
-- Organizations can configure permissions without code changes
+- Organisations can configure permissions without code changes
 - RBAC settings actually control what users can do
 - No more disconnect between frontend and database permissions
 
@@ -322,7 +322,7 @@ CREATE TRIGGER permission_change_notification
 
 The RBAC-RLS integration provides a robust, scalable solution for dynamic permission enforcement. It solves the critical architectural issue where RBAC configuration and RLS policies were disconnected, ensuring that:
 
-1. **Organizations have true control** over their permission systems
+1. **Organisations have true control** over their permission systems
 2. **Developers can rely on consistent behavior** across all operations  
 3. **Users get the functionality they expect** based on their assigned roles
 4. **The system is maintainable and auditable** with clear change tracking

package/docs/rbac/quick-start.md

@@ -1,5 +1,7 @@
 # RBAC Quick Start
 
+> **📚 RBAC System** | [← Back to Documentation](../../README.md) | [RBAC Overview](./README.md) | [Examples](./examples.md)
+
 > **⚠️ CRITICAL**: This guide is designed to be impossible to get wrong. Follow every step exactly as written, and your RBAC system will work perfectly.
 
 Build your first RBAC-enabled application in under 10 minutes.