@jmruthers/pace-core 0.5.19 → 0.5.21

package/docs/troubleshooting/cake-infinite-rerender-debugging.md

@@ -0,0 +1,284 @@
+# Cake Infinite Re-render Debugging Guide
+
+## 🚨 Issue: Infinite Re-renders in Meals Component
+
+The Cake team is experiencing infinite re-renders in their Meals component, causing the `PagePermissionGuard` to re-render continuously. The diagnostic logs show:
+
+```
+[Meals] Diagnostic info: 
+Object { renderCount: 1, instanceCount: 0 }
+[Meals] Diagnostic info: 
+Object { renderCount: 2, instanceCount: 0 }
+[Meals] Diagnostic info: 
+Object { renderCount: 3, instanceCount: 0 }
+...
+```
+
+## 🔍 Root Cause Analysis
+
+The issue is **NOT** in `PagePermissionGuard` - it's working correctly:
+- ✅ App ID resolution: `Successfully resolved app ID: a0865252-b745-4639-8028-a53ee6128000`
+- ✅ Permissions granted: `Final decision: { hasPermission: true }`
+- ✅ No multiple instances: `instanceCount: 0`
+
+The problem is in the **parent Meals component** that's re-rendering infinitely.
+
+## 🛠️ Debugging Steps
+
+### Step 1: Add Comprehensive Debugging to Meals Component
+
+Add this debugging code to your Meals component:
+
+```typescript
+import React, { useMemo, useCallback, useEffect, useRef } from 'react';
+
+const Meals = React.memo(() => {
+  const renderCountRef = useRef(0);
+  renderCountRef.current += 1;
+  
+  // Track what's causing re-renders
+  const [debugInfo, setDebugInfo] = useState({
+    renderCount: renderCountRef.current,
+    lastRenderTime: Date.now(),
+    reRenderReasons: []
+  });
+
+  // Get all your hooks
+  const eventsData = useEvents();
+  const authData = useUnifiedAuth();
+  const orgData = useOrganisations();
+  const configData = useAppConfig();
+
+  // Track changes in each hook
+  const prevEventsRef = useRef(eventsData);
+  const prevAuthRef = useRef(authData);
+  const prevOrgRef = useRef(orgData);
+  const prevConfigRef = useRef(configData);
+
+  useEffect(() => {
+    const reasons = [];
+    
+    // Check if events data changed
+    if (prevEventsRef.current !== eventsData) {
+      reasons.push('eventsData changed');
+      prevEventsRef.current = eventsData;
+    }
+    
+    // Check if auth data changed
+    if (prevAuthRef.current !== authData) {
+      reasons.push('authData changed');
+      prevAuthRef.current = authData;
+    }
+    
+    // Check if org data changed
+    if (prevOrgRef.current !== orgData) {
+      reasons.push('orgData changed');
+      prevOrgRef.current = orgData;
+    }
+    
+    // Check if config data changed
+    if (prevConfigRef.current !== configData) {
+      reasons.push('configData changed');
+      prevConfigRef.current = configData;
+    }
+
+    console.log('[Meals] Re-render reasons:', reasons);
+    console.log('[Meals] Current data:', {
+      eventsData: eventsData?.selectedEvent?.id,
+      authData: authData?.user?.id,
+      orgData: orgData?.selectedOrganisation?.id,
+      configData: configData?.requiresEvent
+    });
+  });
+
+  // Your existing component logic...
+  
+  return (
+    <PagePermissionGuard
+      pageName="meals"
+      operation="read"
+      fallback={<div>Loading permissions...</div>}
+    >
+      {/* Your DataTable content */}
+    </PagePermissionGuard>
+  );
+}, (prevProps, nextProps) => {
+  // This should never re-render since there are no props
+  console.log('[Meals] React.memo comparison called - this should not happen!');
+  return true;
+});
+```
+
+### Step 2: Check Hook Dependencies
+
+Look for these common causes of infinite re-renders:
+
+#### A. Unstable Object References
+```typescript
+// ❌ BAD - Creates new object on every render
+const data = { events: eventsData, auth: authData };
+
+// ✅ GOOD - Memoize the object
+const data = useMemo(() => ({ 
+  events: eventsData, 
+  auth: authData 
+}), [eventsData, authData]);
+```
+
+#### B. Unstable Function References
+```typescript
+// ❌ BAD - Creates new function on every render
+const handleClick = () => { /* ... */ };
+
+// ✅ GOOD - Memoize the function
+const handleClick = useCallback(() => { /* ... */ }, []);
+```
+
+#### C. useEffect Dependencies
+```typescript
+// ❌ BAD - Missing dependencies or unstable dependencies
+useEffect(() => {
+  // ...
+}, []); // Missing dependencies
+
+// ❌ BAD - Unstable dependency
+useEffect(() => {
+  // ...
+}, [someObject]); // someObject changes every render
+
+// ✅ GOOD - Stable dependencies
+useEffect(() => {
+  // ...
+}, [userId, eventId]); // Primitive values
+```
+
+### Step 3: Check Parent Components
+
+The infinite re-render might be coming from a parent component. Check:
+
+1. **Parent component re-renders**: Add debugging to parent components
+2. **Context providers**: Check if any context providers are re-rendering
+3. **State updates**: Look for state updates that trigger re-renders
+
+### Step 4: Use React DevTools Profiler
+
+1. Open React DevTools
+2. Go to Profiler tab
+3. Start recording
+4. Interact with the component
+5. Stop recording
+6. Look for components that re-render frequently
+
+### Step 5: Check for State Updates in Render
+
+Look for state updates that happen during render:
+
+```typescript
+// ❌ BAD - State update during render
+const Meals = () => {
+  const [count, setCount] = useState(0);
+  
+  // This will cause infinite re-renders!
+  setCount(count + 1);
+  
+  return <div>{count}</div>;
+};
+```
+
+## 🔧 Common Fixes
+
+### Fix 1: Memoize Expensive Calculations
+```typescript
+const Meals = React.memo(() => {
+  const eventsData = useEvents();
+  const authData = useUnifiedAuth();
+  
+  // Memoize expensive calculations
+  const processedData = useMemo(() => {
+    return processEventsData(eventsData);
+  }, [eventsData]);
+  
+  // Memoize callbacks
+  const handleEventChange = useCallback((eventId) => {
+    // Handle event change
+  }, []);
+  
+  return (
+    <PagePermissionGuard pageName="meals" operation="read">
+      {/* Your content */}
+    </PagePermissionGuard>
+  );
+});
+```
+
+### Fix 2: Stabilize Hook Dependencies
+```typescript
+const Meals = React.memo(() => {
+  const eventsData = useEvents();
+  const authData = useUnifiedAuth();
+  
+  // Extract only the values you need
+  const selectedEventId = eventsData?.selectedEvent?.id;
+  const userId = authData?.user?.id;
+  
+  // Use primitive values in dependencies
+  useEffect(() => {
+    // Your effect logic
+  }, [selectedEventId, userId]);
+  
+  return (
+    <PagePermissionGuard pageName="meals" operation="read">
+      {/* Your content */}
+    </PagePermissionGuard>
+  );
+});
+```
+
+### Fix 3: Check Context Providers
+Make sure context providers are not re-rendering:
+
+```typescript
+// ❌ BAD - Creates new object every render
+const AppProvider = ({ children }) => {
+  const [state, setState] = useState({});
+  
+  return (
+    <AppContext.Provider value={{ state, setState }}>
+      {children}
+    </AppContext.Provider>
+  );
+};
+
+// ✅ GOOD - Memoize the context value
+const AppProvider = ({ children }) => {
+  const [state, setState] = useState({});
+  
+  const contextValue = useMemo(() => ({
+    state,
+    setState
+  }), [state]);
+  
+  return (
+    <AppContext.Provider value={contextValue}>
+      {children}
+    </AppContext.Provider>
+  );
+};
+```
+
+## 🎯 Next Steps
+
+1. **Add the debugging code** to your Meals component
+2. **Run the app** and check the console logs
+3. **Identify the re-render reasons** from the logs
+4. **Apply the appropriate fix** based on what's causing the re-renders
+5. **Test the fix** to ensure the infinite re-renders stop
+
+## 📞 Need Help?
+
+If you're still experiencing issues after following these steps, please share:
+1. The console logs from the debugging code
+2. The Meals component code
+3. Any parent component code that might be relevant
+
+The issue is definitely in the Cake application code, not in pace-core, so we need to identify what's causing the parent component to re-render infinitely.

package/docs/troubleshooting/cake-infinite-rerender-summary.md

@@ -0,0 +1,117 @@
+# Cake Infinite Re-render Issue - Summary & Action Plan
+
+## 🚨 Current Status
+
+The Cake team is experiencing **infinite re-renders** in their Meals component, causing the `PagePermissionGuard` to re-render continuously. This is **NOT** a pace-core issue - it's a Cake application issue.
+
+## 📊 Evidence from Console Logs
+
+```
+[Meals] Diagnostic info: 
+Object { renderCount: 1, instanceCount: 0 }
+[Meals] Diagnostic info: 
+Object { renderCount: 2, instanceCount: 0 }
+[Meals] Diagnostic info: 
+Object { renderCount: 3, instanceCount: 0 }
+...
+[Meals] Diagnostic info: 
+Object { renderCount: 19, instanceCount: 0 }
+```
+
+**Key Observations:**
+- ✅ `PagePermissionGuard` is working correctly (permissions granted, app ID resolved)
+- ✅ No multiple instances (`instanceCount: 0`)
+- ❌ Parent Meals component is re-rendering infinitely (`renderCount: 1, 2, 3...`)
+
+## 🔍 Root Cause
+
+The infinite re-renders are caused by the **parent Meals component**, not by `PagePermissionGuard`. The parent component is re-rendering continuously, which triggers `PagePermissionGuard` to re-render as well.
+
+## 🛠️ Immediate Action Plan
+
+### Step 1: Add Debugging Code
+Use the diagnostic script provided in `cake-rerender-diagnostic.js` to identify what's causing the re-renders.
+
+### Step 2: Common Causes to Check
+
+1. **Unstable Object References**
+   ```typescript
+   // ❌ BAD - Creates new object every render
+   const data = { events: eventsData, auth: authData };
+   
+   // ✅ GOOD - Memoize
+   const data = useMemo(() => ({ events: eventsData, auth: authData }), [eventsData, authData]);
+   ```
+
+2. **Unstable Function References**
+   ```typescript
+   // ❌ BAD - Creates new function every render
+   const handleClick = () => { /* ... */ };
+   
+   // ✅ GOOD - Memoize
+   const handleClick = useCallback(() => { /* ... */ }, []);
+   ```
+
+3. **useEffect Dependencies**
+   ```typescript
+   // ❌ BAD - Missing or unstable dependencies
+   useEffect(() => { /* ... */ }, []);
+   useEffect(() => { /* ... */ }, [someObject]);
+   
+   // ✅ GOOD - Stable dependencies
+   useEffect(() => { /* ... */ }, [userId, eventId]);
+   ```
+
+4. **State Updates During Render**
+   ```typescript
+   // ❌ BAD - Causes infinite re-renders
+   const [count, setCount] = useState(0);
+   setCount(count + 1); // Don't do this!
+   ```
+
+5. **Context Provider Re-renders**
+   ```typescript
+   // ❌ BAD - Creates new value every render
+   <Context.Provider value={{ state, setState }}>
+   
+   // ✅ GOOD - Memoize the value
+   const value = useMemo(() => ({ state, setState }), [state]);
+   <Context.Provider value={value}>
+   ```
+
+### Step 3: Use React DevTools
+1. Open React DevTools Profiler
+2. Record a session
+3. Look for components that re-render frequently
+4. Identify the root cause
+
+## 📁 Files to Check
+
+1. **Meals component** - Add the debugging code
+2. **Parent components** - Check for re-render causes
+3. **Context providers** - Ensure they're not re-rendering
+4. **Custom hooks** - Check for unstable dependencies
+
+## 🎯 Expected Outcome
+
+After applying the fixes:
+- Render count should stabilize at 1-2 renders
+- No more infinite re-renders
+- `PagePermissionGuard` should work correctly
+- DataTable should display properly
+
+## 📞 Next Steps
+
+1. **Immediate**: Add the debugging code to identify the cause
+2. **Short-term**: Apply the appropriate fixes based on the debugging output
+3. **Long-term**: Review the entire component tree for similar issues
+
+## 🔗 Resources
+
+- **Debugging Guide**: `cake-infinite-rerender-debugging.md`
+- **Diagnostic Script**: `cake-rerender-diagnostic.js`
+- **React DevTools**: https://react.dev/learn/react-developer-tools
+
+---
+
+**Remember**: This is a Cake application issue, not a pace-core issue. The `PagePermissionGuard` is working correctly - the problem is in the parent component that's re-rendering infinitely.

package/docs/troubleshooting/cake-rerender-diagnostic.js

@@ -0,0 +1,162 @@
+// Cake Infinite Re-render Diagnostic Script
+// Add this to your Meals component to identify the cause of infinite re-renders
+
+import React, { useMemo, useCallback, useEffect, useRef, useState } from 'react';
+
+// Add this hook to track re-render causes
+const useRenderTracker = (componentName) => {
+  const renderCountRef = useRef(0);
+  const prevPropsRef = useRef({});
+  const prevStateRef = useRef({});
+  
+  renderCountRef.current += 1;
+  
+  const [debugInfo, setDebugInfo] = useState({
+    renderCount: renderCountRef.current,
+    lastRenderTime: Date.now(),
+    reRenderReasons: []
+  });
+
+  const trackRender = (currentProps, currentState) => {
+    const reasons = [];
+    
+    // Check if props changed
+    if (prevPropsRef.current !== currentProps) {
+      reasons.push('props changed');
+      prevPropsRef.current = currentProps;
+    }
+    
+    // Check if state changed
+    if (prevStateRef.current !== currentState) {
+      reasons.push('state changed');
+      prevStateRef.current = currentState;
+    }
+    
+    // If no obvious reason, it might be parent re-render
+    if (reasons.length === 0) {
+      reasons.push('parent re-render');
+    }
+    
+    console.log(`[${componentName}] Re-render #${renderCountRef.current}:`, {
+      reasons,
+      timestamp: new Date().toISOString(),
+      props: currentProps,
+      state: currentState
+    });
+    
+    setDebugInfo({
+      renderCount: renderCountRef.current,
+      lastRenderTime: Date.now(),
+      reRenderReasons: reasons
+    });
+  };
+
+  return { trackRender, debugInfo };
+};
+
+// Enhanced Meals component with debugging
+const MealsWithDebugging = React.memo(() => {
+  const { trackRender, debugInfo } = useRenderTracker('Meals');
+  
+  // Get all your hooks
+  const eventsData = useEvents();
+  const authData = useUnifiedAuth();
+  const orgData = useOrganisations();
+  const configData = useAppConfig();
+  
+  // Track hook changes
+  const prevEventsRef = useRef(eventsData);
+  const prevAuthRef = useRef(authData);
+  const prevOrgRef = useRef(orgData);
+  const prevConfigRef = useRef(configData);
+  
+  // Check what's changing
+  useEffect(() => {
+    const hookChanges = [];
+    
+    if (prevEventsRef.current !== eventsData) {
+      hookChanges.push('eventsData changed');
+      console.log('[Meals] eventsData changed:', {
+        old: prevEventsRef.current,
+        new: eventsData
+      });
+      prevEventsRef.current = eventsData;
+    }
+    
+    if (prevAuthRef.current !== authData) {
+      hookChanges.push('authData changed');
+      console.log('[Meals] authData changed:', {
+        old: prevAuthRef.current,
+        new: authData
+      });
+      prevAuthRef.current = authData;
+    }
+    
+    if (prevOrgRef.current !== orgData) {
+      hookChanges.push('orgData changed');
+      console.log('[Meals] orgData changed:', {
+        old: prevOrgRef.current,
+        new: orgData
+      });
+      prevOrgRef.current = orgData;
+    }
+    
+    if (prevConfigRef.current !== configData) {
+      hookChanges.push('configData changed');
+      console.log('[Meals] configData changed:', {
+        old: prevConfigRef.current,
+        new: configData
+      });
+      prevConfigRef.current = configData;
+    }
+    
+    if (hookChanges.length > 0) {
+      console.log('[Meals] Hook changes detected:', hookChanges);
+    }
+  });
+  
+  // Track render
+  trackRender({}, {});
+  
+  // Your existing component logic...
+  const selectedEvent = useMemo(() => eventsData.selectedEvent, [eventsData.selectedEvent?.event_id, eventsData.selectedEvent?.id]);
+  const user = useMemo(() => authData.user, [authData.user?.id]);
+  const selectedOrganisation = useMemo(() => orgData.selectedOrganisation, [orgData.selectedOrganisation?.id]);
+  const requiresEvent = useMemo(() => configData.requiresEvent, [configData.requiresEvent]);
+  
+  const eventId = useMemo(() => {
+    return selectedEvent?.event_id || selectedEvent?.id;
+  }, [selectedEvent?.event_id, selectedEvent?.id]);
+  
+  // Log diagnostic info
+  console.log('[Meals] Diagnostic info:', {
+    renderCount: debugInfo.renderCount,
+    reRenderReasons: debugInfo.reRenderReasons,
+    hookValues: {
+      selectedEventId: selectedEvent?.id,
+      userId: user?.id,
+      organisationId: selectedOrganisation?.id,
+      requiresEvent
+    }
+  });
+  
+  return (
+    <PagePermissionGuard
+      pageName="meals"
+      operation="read"
+      fallback={<div>Loading permissions...</div>}
+    >
+      <h1>Meals</h1>
+      <p>Manage the meals available for {selectedEvent?.event_name}</p>
+      {/* Your DataTable content */}
+    </PagePermissionGuard>
+  );
+}, (prevProps, nextProps) => {
+  // This should never be called since there are no props
+  console.log('[Meals] React.memo comparison called - this indicates a problem!');
+  console.log('[Meals] prevProps:', prevProps);
+  console.log('[Meals] nextProps:', nextProps);
+  return true;
+});
+
+export default MealsWithDebugging;