@jmruthers/pace-core 0.5.76 → 0.5.78

package/docs/rbac/quick-start.md

@@ -1,3 +1,9 @@
+---
+lastUpdated: 2025-10-29T22:43:00+11:00
+version: 0.5.76
+reviewedBy: content-audit
+---
+
 # RBAC Quick Start
 
 > **📚 RBAC System** | [← Back to Documentation](../../README.md) | [RBAC Overview](./README.md) | [Examples](./examples.md)
@@ -17,10 +23,11 @@ A simple user management app that demonstrates:
 
 ## 🚨 Critical Rules (Follow These or It Won't Work)
 
-1. **Never make direct database queries** to `rbac_apps`, `rbac_global_roles`, or other RBAC tables
-2. **Always use `PagePermissionGuard`** for page-level permissions (not manual permission checks)
-3. **Always set up providers correctly** in the exact order shown
-4. **Use the exact app name** from your environment variable (must match database exactly)
+1. **ALWAYS call `setupRBAC()` first** - This is MANDATORY and must be called before any RBAC features
+2. **Never make direct database queries** to `rbac_apps`, `rbac_global_roles`, or other RBAC tables
+3. **Always use `PagePermissionGuard`** for page-level permissions (not manual permission checks)
+4. **Always set up providers correctly** in the exact order shown
+5. **Use the exact app name** from your environment variable (must match database exactly)
 
 ## 🚀 Step-by-Step Implementation
 
@@ -195,7 +202,50 @@ if (!supabaseUrl || !supabaseAnonKey) {
 export const supabase = createClient(supabaseUrl, supabaseAnonKey)
 ```
 
-### 8. App Setup (CRITICAL)
+### 8. Initialize RBAC (MANDATORY - NEW STEP!)
+
+**CRITICAL**: You MUST call `setupRBAC()` before using any RBAC features. Create `src/lib/rbac-setup.ts`:
+
+```typescript
+// src/lib/rbac-setup.ts
+import { setupRBAC } from '@jmruthers/pace-core/rbac'
+import { supabase } from './supabase'
+
+// ⚠️ REQUIRED: Initialize RBAC before using any RBAC features
+setupRBAC(supabase)
+```
+
+**Then import this in your main entry point:**
+
+```typescript
+// src/main.tsx
+import React from 'react'
+import ReactDOM from 'react-dom/client'
+import './lib/rbac-setup' // ⚠️ Import setup BEFORE App
+import App from './App'
+
+ReactDOM.createRoot(document.getElementById('root')!).render(
+  <React.StrictMode>
+    <App />
+  </React.StrictMode>
+)
+```
+
+**Or in your App.tsx (alternative approach):**
+
+```typescript
+// src/App.tsx
+import React from 'react'
+import { setupRBAC } from '@jmruthers/pace-core/rbac'
+import { supabase } from './lib/supabase'
+
+// ⚠️ REQUIRED: Call setupRBAC before anything else
+setupRBAC(supabase)
+
+// ... rest of your app
+```
+
+### 9. App Setup (CRITICAL)
 
 Create `src/App.tsx` with this EXACT structure:
 
@@ -208,26 +258,23 @@ import {
   OrganisationProvider,
   EventProvider 
 } from '@jmruthers/pace-core/providers'
-import { setRBACAppName } from '@jmruthers/pace-core/utils'
 import { supabase } from './lib/supabase'
 import { Dashboard } from './pages/Dashboard'
 import { Users } from './pages/Users'
 import { Login } from './pages/Login'
 
-// CRITICAL: Set the app name for RBAC resolution
+// CRITICAL: App name for RBAC resolution
 const APP_NAME = import.meta.env.VITE_APP_NAME
 
 if (!APP_NAME) {
   throw new Error('VITE_APP_NAME environment variable is required')
 }
 
-// CRITICAL: Set the app name globally for RBAC
-setRBACAppName(APP_NAME)
-
 function App() {
   return (
     <UnifiedAuthProvider 
       supabaseClient={supabase}
+      appName={APP_NAME}
     >
       <OrganisationProvider>
         <EventProvider>
@@ -247,7 +294,7 @@ function App() {
 export default App
 ```
 
-### 9. Create Login Page
+### 10. Create Login Page
 
 Create `src/pages/Login.tsx`:
 
@@ -343,7 +390,7 @@ export function Login() {
 }
 ```
 
-### 10. Create Dashboard Page
+### 11. Create Dashboard Page
 
 Create `src/pages/Dashboard.tsx`:
 
@@ -417,7 +464,7 @@ export function Dashboard() {
 }
 ```
 
-### 11. Create Users Page
+### 12. Create Users Page
 
 Create `src/pages/Users.tsx`:
 
@@ -522,6 +569,16 @@ Your RBAC setup is working correctly if:
 
 ## 🚨 Troubleshooting
 
+### Issue: "RBACNotInitializedError"
+
+**Cause**: Forgot to call `setupRBAC()`.
+
+**Solution**:
+```typescript
+import { setupRBAC } from '@jmruthers/pace-core/rbac'
+setupRBAC(supabase) // Must be called BEFORE rendering app
+```
+
 ### Issue: "Access Denied" on all pages
 
 **Check these in order:**

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

@@ -1,3 +1,9 @@
+---
+lastUpdated: 2025-10-29T22:43:00+11:00
+version: 0.5.76
+reviewedBy: content-audit
+---
+
 # RBAC-RLS Integration: Dynamic Permission Enforcement
 
 This document explains how to use the new RBAC-RLS integration system that allows dynamic permission enforcement based on configurable RBAC settings instead of hardcoded RLS policies.

package/docs/rbac/super-admin-guide.md

@@ -1,3 +1,9 @@
+---
+lastUpdated: 2025-10-29T22:43:00+11:00
+version: 0.5.76
+reviewedBy: content-audit
+---
+
 # Super Admin Access Guide
 
 This comprehensive guide shows consuming apps how to properly implement super admin access, including practical examples and best practices.

package/docs/rbac/troubleshooting.md

@@ -1,3 +1,9 @@
+---
+lastUpdated: 2025-10-29T22:43:00+11:00
+version: 0.5.76
+reviewedBy: content-audit
+---
+
 # RBAC Troubleshooting Guide
 
 > **📚 Quick Start**: If you're new to RBAC, start with the [Quick Start Guide](./quick-start.md) first.

package/docs/security/README.md

@@ -1,3 +1,9 @@
+---
+lastUpdated: 2025-10-29T22:43:00+11:00
+version: 0.5.76
+reviewedBy: content-audit
+---
+
 # Security Guide
 
 This guide covers security best practices, implementation patterns, and security considerations when using PACE Core.

package/docs/security/checklist.md

@@ -1,3 +1,9 @@
+---
+lastUpdated: 2025-10-29T22:43:00+11:00
+version: 0.5.76
+reviewedBy: content-audit
+---
+
 # Security Checklist
 
 > **🔒 Production Security** | [Security Best Practices](./README.md) | [RBAC Security](../rbac/README.md) | [Authentication Security](../core-concepts/authentication.md)

package/docs/styles/README.md

@@ -1,8 +1,14 @@
+---
+lastUpdated: 2025-10-29T22:43:00+11:00
+version: 0.5.76
+reviewedBy: content-audit
+---
+
 # PACE Core Styling Guide
 
 This guide explains how to properly style PACE Core components using our two-file CSS architecture with Tailwind v4 and native utilities.
 
-> **🎨 New to PACE Core?** Start with the [Quick Start Guide](./getting-started/quick-start.md) to get up and running in 5 minutes.
+> **🎨 New to PACE Core?** Start with the [Getting started roadmap](../getting-started/documentation-index.md) to see the post-install checklist.
 
 ## Overview
 

package/docs/{usage.md → styles/usage.md}

@@ -1,3 +1,9 @@
+---
+lastUpdated: 2025-10-29T22:43:00+11:00
+version: 0.5.76
+reviewedBy: content-audit
+---
+
 # PACE Core Styling Usage Guide
 
 This guide explains how to integrate PACE Core's new styling system into your application.

package/docs/testing/README.md

@@ -1,3 +1,9 @@
+---
+lastUpdated: 2025-10-29T22:43:00+11:00
+version: 0.5.76
+reviewedBy: content-audit
+---
+
 # Testing Guide
 
 This guide covers testing strategies, patterns, and best practices for applications built with PACE Core.

package/docs/{visual-testing.md → testing/visual-testing.md}

@@ -1,3 +1,9 @@
+---
+lastUpdated: 2025-10-29T22:43:00+11:00
+version: 0.5.76
+reviewedBy: content-audit
+---
+
 # Visual Testing Guide
 
 This document outlines the visual testing approach for pace-core components to ensure visual parity after the styling refactor.

package/docs/troubleshooting/README.md

@@ -1,10 +1,14 @@
-# Troubleshooting Guide
+---
+lastUpdated: 2025-10-29T22:43:00+11:00
+version: 0.5.76
+reviewedBy: content-audit
+---
 
-> **🆘 Get Help Fast** | [Common Issues](#common-issues) | [Debugging](#debugging) | [Support](#support)
+# Troubleshooting Guide
 
-[← Back to Documentation](../README.md) | [↑ Table of Contents](#table-of-contents)
+> **🆘 Complete Troubleshooting Reference** | [← Back to Documentation](../README.md) | [Installation Guide](../getting-started/installation-guide.md)
 
-Comprehensive troubleshooting guide for PACE Core applications. Find solutions to common problems and learn debugging techniques.
+Comprehensive troubleshooting guide for PACE Core applications. Find solutions to common problems, learn debugging techniques, and get help when you need it.
 
 ## 📋 Table of Contents
 
@@ -494,4 +498,382 @@ function DebugInfo() {
 5. **Test in incognito mode** to rule out extensions
 6. **Try a minimal reproduction** in a new project
 
-Remember: **Most issues have simple solutions. Take a step back and check the basics first!**
+## 🔍 Advanced Debugging Techniques
+
+### React Developer Tools
+
+```typescript
+// Enable React DevTools in development
+if (process.env.NODE_ENV === 'development') {
+  // React DevTools will automatically connect
+  console.log('React DevTools enabled');
+}
+
+// Custom hook for debugging component renders
+function useDebugRender(componentName: string, props?: any) {
+  useEffect(() => {
+    console.log(`${componentName} rendered with props:`, props);
+  });
+  
+  useEffect(() => {
+    console.log(`${componentName} mounted`);
+    return () => console.log(`${componentName} unmounted`);
+  }, []);
+}
+
+// Usage in components
+function MyComponent({ data, loading }) {
+  useDebugRender('MyComponent', { data, loading });
+  
+  if (loading) return <div>Loading...</div>;
+  return <div>{data}</div>;
+}
+```
+
+### Custom Debug Hooks
+
+```typescript
+// hooks/useDebug.ts
+import { useEffect, useRef } from 'react';
+
+export function useDebugValue<T>(value: T, label: string) {
+  const prevValue = useRef<T>();
+  
+  useEffect(() => {
+    if (prevValue.current !== value) {
+      console.log(`${label} changed:`, {
+        previous: prevValue.current,
+        current: value,
+      });
+      prevValue.current = value;
+    }
+  }, [value, label]);
+}
+
+export function useDebugEffect(effect: () => void, deps: any[], label: string) {
+  useEffect(() => {
+    console.log(`${label} effect triggered with deps:`, deps);
+    effect();
+  }, deps);
+}
+
+export function useDebugCallback<T extends (...args: any[]) => any>(
+  callback: T,
+  deps: any[],
+  label: string
+): T {
+  const prevDeps = useRef<any[]>();
+  
+  useEffect(() => {
+    if (JSON.stringify(prevDeps.current) !== JSON.stringify(deps)) {
+      console.log(`${label} callback dependencies changed:`, deps);
+      prevDeps.current = deps;
+    }
+  }, [deps, label]);
+  
+  return callback;
+}
+
+// Usage
+function MyComponent({ userId }) {
+  useDebugValue(userId, 'userId');
+  
+  const handleClick = useDebugCallback(
+    () => console.log('Button clicked'),
+    [userId],
+    'handleClick'
+  );
+  
+  useDebugEffect(() => {
+    console.log('Effect running for userId:', userId);
+  }, [userId], 'userIdEffect');
+  
+  return <button onClick={handleClick}>Click me</button>;
+}
+```
+
+### Authentication Debugging
+
+```typescript
+// Debug authentication state
+function AuthDebugger() {
+  const { user, session, loading, error } = useUnifiedAuth();
+  
+  useEffect(() => {
+    console.log('Auth Debug Info:', {
+      user: user ? { id: user.id, email: user.email } : null,
+      session: session ? { expires_at: session.expires_at } : null,
+      loading,
+      error: error?.message
+    });
+  }, [user, session, loading, error]);
+  
+  return null;
+}
+
+// Debug RBAC permissions
+function RBACDebugger() {
+  const { hasPermission, isLoading, error } = useCan();
+  
+  useEffect(() => {
+    console.log('RBAC Debug Info:', {
+      isLoading,
+      error: error?.message,
+      permissions: {
+        canReadUsers: hasPermission('read:users'),
+        canWriteUsers: hasPermission('write:users'),
+        canDeleteUsers: hasPermission('delete:users')
+      }
+    });
+  }, [hasPermission, isLoading, error]);
+  
+  return null;
+}
+```
+
+### Component Debugging
+
+```typescript
+// Debug component props and state
+function ComponentDebugger({ children, ...props }) {
+  const [state, setState] = useState({});
+  
+  useEffect(() => {
+    console.log('Component Debug:', {
+      props,
+      state,
+      timestamp: new Date().toISOString()
+    });
+  }, [props, state]);
+  
+  return children;
+}
+
+// Usage
+<ComponentDebugger>
+  <DataTable data={data} columns={columns} />
+</ComponentDebugger>
+```
+
+### Performance Debugging
+
+```typescript
+// Debug performance issues
+function PerformanceDebugger() {
+  useEffect(() => {
+    const observer = new PerformanceObserver((list) => {
+      for (const entry of list.getEntries()) {
+        if (entry.duration > 100) { // Log slow operations
+          console.warn('Slow operation detected:', {
+            name: entry.name,
+            duration: entry.duration,
+            startTime: entry.startTime
+          });
+        }
+      }
+    });
+    
+    observer.observe({ entryTypes: ['measure', 'navigation'] });
+    
+    return () => observer.disconnect();
+  }, []);
+  
+  return null;
+}
+
+// Debug render performance
+function RenderDebugger({ children }) {
+  const renderStart = performance.now();
+  
+  useEffect(() => {
+    const renderEnd = performance.now();
+    const renderTime = renderEnd - renderStart;
+    
+    if (renderTime > 16) { // More than one frame
+      console.warn('Slow render detected:', {
+        renderTime,
+        component: children.type?.name || 'Unknown'
+      });
+    }
+  });
+  
+  return children;
+}
+```
+
+### Network Debugging
+
+```typescript
+// Debug API calls
+function NetworkDebugger() {
+  useEffect(() => {
+    const originalFetch = window.fetch;
+    
+    window.fetch = async (...args) => {
+      const start = performance.now();
+      console.log('API Call Started:', args[0]);
+      
+      try {
+        const response = await originalFetch(...args);
+        const end = performance.now();
+        
+        console.log('API Call Completed:', {
+          url: args[0],
+          status: response.status,
+          duration: end - start
+        });
+        
+        return response;
+      } catch (error) {
+        const end = performance.now();
+        
+        console.error('API Call Failed:', {
+          url: args[0],
+          error: error.message,
+          duration: end - start
+        });
+        
+        throw error;
+      }
+    };
+    
+    return () => {
+      window.fetch = originalFetch;
+    };
+  }, []);
+  
+  return null;
+}
+```
+
+### Error Boundary Debugging
+
+```typescript
+// Enhanced error boundary with debugging
+class DebugErrorBoundary extends React.Component {
+  constructor(props) {
+    super(props);
+    this.state = { hasError: false, error: null, errorInfo: null };
+  }
+  
+  static getDerivedStateFromError(error) {
+    return { hasError: true };
+  }
+  
+  componentDidCatch(error, errorInfo) {
+    console.error('Error Boundary Caught Error:', {
+      error: error.message,
+      stack: error.stack,
+      componentStack: errorInfo.componentStack,
+      timestamp: new Date().toISOString()
+    });
+    
+    this.setState({
+      error,
+      errorInfo
+    });
+  }
+  
+  render() {
+    if (this.state.hasError) {
+      return (
+        <div className="p-4 border border-red-500 bg-red-50">
+          <h2 className="text-red-800 font-bold">Something went wrong</h2>
+          <details className="mt-2">
+            <summary className="cursor-pointer text-red-700">
+              Error Details (Click to expand)
+            </summary>
+            <pre className="mt-2 text-xs text-red-600 whitespace-pre-wrap">
+              {this.state.error && this.state.error.toString()}
+              {this.state.errorInfo.componentStack}
+            </pre>
+          </details>
+        </div>
+      );
+    }
+    
+    return this.props.children;
+  }
+}
+```
+
+### Debug Information Template
+
+```tsx
+// Add this to your app for comprehensive debugging
+function DebugInfo() {
+  const auth = useUnifiedAuth();
+  const org = useOrganisation();
+  const events = useEvents();
+  const { hasPermission } = useCan();
+  
+  return (
+    <div style={{ 
+      position: 'fixed', 
+      top: 0, 
+      right: 0, 
+      background: 'white', 
+      padding: '10px', 
+      border: '1px solid black', 
+      zIndex: 9999,
+      fontSize: '12px',
+      maxWidth: '300px',
+      maxHeight: '400px',
+      overflow: 'auto'
+    }}>
+      <h4>Debug Info</h4>
+      <pre>{JSON.stringify({
+        auth: { 
+          user: auth.user?.id, 
+          loading: auth.loading,
+          error: auth.error?.message 
+        },
+        org: { 
+          current: org.selectedOrganisation?.id, 
+          loading: org.loading,
+          error: org.error?.message 
+        },
+        events: { 
+          current: events.selectedEvent?.id, 
+          loading: events.loading,
+          error: events.error?.message 
+        },
+        permissions: { 
+          canReadUsers: hasPermission('read:users'),
+          canWriteUsers: hasPermission('write:users')
+        }
+      }, null, 2)}</pre>
+    </div>
+  );
+}
+```
+
+### Debugging Checklist
+
+#### Before Debugging
+- [ ] Check browser console for errors
+- [ ] Verify environment variables are set
+- [ ] Confirm all dependencies are installed
+- [ ] Check network connectivity
+- [ ] Verify Supabase configuration
+
+#### During Debugging
+- [ ] Enable debug mode in providers
+- [ ] Add console.log statements strategically
+- [ ] Use React DevTools to inspect components
+- [ ] Check Network tab for failed requests
+- [ ] Monitor performance metrics
+
+#### After Debugging
+- [ ] Remove debug code before production
+- [ ] Document the solution for future reference
+- [ ] Update error handling if needed
+- [ ] Consider adding monitoring for similar issues
+
+## Related Documentation
+
+- [Common Issues](./common-issues.md) - Specific problem solutions
+- [Styling Issues](./styling-issues.md) - Component styling problems
+- [Authentication Guide](../implementation-guides/authentication.md) - Auth troubleshooting
+- [Performance Guide](../best-practices/performance.md) - Performance debugging
+- [API Reference](../api-reference/) - Component documentation

package/docs/troubleshooting/cake-page-permission-guard-issue-summary.md

@@ -1,3 +1,9 @@
+---
+lastUpdated: 2025-10-29T22:43:00+11:00
+version: 0.5.76
+reviewedBy: content-audit
+---
+
 # Cake PagePermissionGuard Issue - Summary & Action Plan
 
 ## 🚨 Issue Status: CAKE APPLICATION BUG (Not pace-core)

package/docs/troubleshooting/common-issues.md

@@ -1,3 +1,9 @@
+---
+lastUpdated: 2025-10-29T22:43:00+11:00
+version: 0.5.76
+reviewedBy: content-audit
+---
+
 # Common Issues & Solutions
 
 > **🆘 Troubleshooting** | [← Back to Documentation](../README.md) | [Styling Issues](./styling-issues.md) | [FAQ](../faq.md)

package/docs/troubleshooting/database-view-compatibility.md

@@ -1,3 +1,9 @@
+---
+lastUpdated: 2025-10-29T22:43:00+11:00
+version: 0.5.76
+reviewedBy: content-audit
+---
+
 # Database View Compatibility
 
 ## Problem: "column reference 'user_id' is ambiguous" Error

package/docs/troubleshooting/organisation-context-setup.md

@@ -1,3 +1,9 @@
+---
+lastUpdated: 2025-10-29T22:43:00+11:00
+version: 0.5.76
+reviewedBy: content-audit
+---
+
 # Organisation Context Setup Troubleshooting
 
 This guide helps you resolve the `unrecognized configuration parameter "app.organisation_id"` error that occurs when using PACE Core with Supabase.