@jmruthers/pace-core 0.5.17 → 0.5.18

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

@@ -0,0 +1,187 @@
+# Cake PagePermissionGuard Issue - Summary & Action Plan
+
+## 🚨 Issue Status: CAKE APPLICATION BUG (Not pace-core)
+
+**Date**: January 16, 2025  
+**Priority**: Critical  
+**Status**: Requires Cake team action  
+
+## Problem Summary
+
+The `PagePermissionGuard` component from pace-core is working correctly, but Cake's implementation has a UI layering issue causing the Access Denied modal to persist despite correct permissions.
+
+### Evidence from Console Logs
+
+✅ **pace-core is working correctly**:
+- `useCan` returns `can: true`
+- `willShowAccessDenied: false`
+- `willShowContent: true`
+- `RENDERING CONTENT STATE` is logged
+
+❌ **Cake has implementation issues**:
+- Access Denied modal remains visible
+- Infinite re-render loop detected (same instance ID `14bp0efg9`)
+- UI state not updating despite correct component state
+
+## Root Cause Analysis
+
+Based on the console logs, this is **definitely a Cake application issue**, not a pace-core bug. The most likely causes are:
+
+1. **Multiple PagePermissionGuard instances** rendering simultaneously
+2. **Infinite re-render loop** in the Meals component
+3. **CSS/Modal layering conflicts** keeping the modal visible
+4. **React state management issues** preventing UI updates
+
+## Immediate Action Required
+
+### Step 1: Add Diagnostic Code
+
+Add this to your Meals component to identify the exact issue:
+
+```tsx
+import { useEffect, useRef } from 'react';
+
+export function Meals() {
+  const renderCount = useRef(0);
+  renderCount.current += 1;
+  
+  useEffect(() => {
+    // Check for infinite re-renders
+    if (renderCount.current > 10) {
+      console.error('🚨 INFINITE RE-RENDER DETECTED!', {
+        renderCount: renderCount.current,
+        component: 'Meals'
+      });
+    }
+    
+    // Check for multiple PagePermissionGuard instances
+    const guards = document.querySelectorAll('[data-testid*="page-permission-guard"]');
+    console.log('[Meals] PagePermissionGuard instances:', guards.length);
+    
+    // Check for multiple modals
+    const modals = document.querySelectorAll('[role="dialog"], .modal, [data-testid*="modal"]');
+    console.log('[Meals] Modal elements:', modals.length);
+    
+  }, []);
+  
+  console.log('[Meals] Component render count:', renderCount.current);
+  
+  return (
+    <div>
+      <PagePermissionGuard pageName="meals" operation="read">
+        <DataTable ... />
+      </PagePermissionGuard>
+    </div>
+  );
+}
+```
+
+### Step 2: Check for Common Issues
+
+1. **Multiple PagePermissionGuard wrappers**:
+   ```tsx
+   // ❌ WRONG - Don't do this
+   <PagePermissionGuard>
+     <PagePermissionGuard>
+       <DataTable />
+     </PagePermissionGuard>
+   </PagePermissionGuard>
+   ```
+
+2. **Conditional rendering**:
+   ```tsx
+   // ❌ WRONG - Don't conditionally render the guard
+   {someCondition && (
+     <PagePermissionGuard>
+       <DataTable />
+     </PagePermissionGuard>
+   )}
+   ```
+
+3. **State management causing re-renders**:
+   ```tsx
+   // ❌ WRONG - This can cause infinite loops
+   const [loading, setLoading] = useState(true);
+   useEffect(() => {
+     setLoading(false);
+   }, [loading]); // This dependency causes infinite loop
+   ```
+
+### Step 3: Simplify the Implementation
+
+Use this minimal implementation to test:
+
+```tsx
+import React from 'react';
+import { PagePermissionGuard, DataTable } from '@jmruthers/pace-core';
+
+export function Meals() {
+  console.log('[Meals] Rendering Meals component');
+  
+  return (
+    <div>
+      <h1>Meals</h1>
+      <p>Manage the meals available for AJ2025...</p>
+      
+      <PagePermissionGuard 
+        pageName="meals" 
+        operation="read"
+        fallback={
+          <div className="min-h-screen flex items-center justify-center">
+            <div className="text-center">
+              <div className="animate-spin rounded-full h-8 w-8 border-b-2 border-gray-900 mx-auto mb-4"></div>
+              <p>Loading permissions...</p>
+            </div>
+          </div>
+        }
+      >
+        <DataTable
+          data={processedMeals || []}
+          columns={columns}
+          rbac={{
+            resource: 'meals',
+            pageId: 'meals'
+          }}
+          // ... other props
+        />
+      </PagePermissionGuard>
+    </div>
+  );
+}
+```
+
+## Expected Results After Fix
+
+After implementing the fix, you should see:
+
+1. ✅ Only one `PagePermissionGuard` instance in console
+2. ✅ No infinite re-render warnings
+3. ✅ `RENDERING CONTENT STATE` appears once
+4. ✅ Access Denied modal disappears
+5. ✅ DataTable content becomes visible
+
+## Files to Check
+
+1. **Meals component** - Look for multiple PagePermissionGuard wrappers
+2. **Parent components** - Check for conditional rendering
+3. **State management** - Look for infinite re-render causes
+4. **CSS files** - Check for modal z-index conflicts
+
+## Debugging Tools
+
+1. **React DevTools** - Check component tree for multiple instances
+2. **Browser DevTools** - Check for multiple modal elements
+3. **Console logs** - Look for infinite re-render warnings
+
+## Contact Information
+
+If you need further assistance after implementing these fixes, please provide:
+
+1. The complete Meals component code
+2. Console logs after adding the diagnostic code
+3. Screenshots of React DevTools component tree
+4. Any parent component that renders the Meals component
+
+---
+
+**Note**: This is confirmed to be a Cake application issue, not a pace-core bug. The pace-core component is working correctly as evidenced by the console logs showing proper permission resolution and state management.

package/docs/troubleshooting/page-permission-guard-diagnostic.js

@@ -0,0 +1,129 @@
+/**
+ * PagePermissionGuard Diagnostic Script
+ * 
+ * Add this to your Cake application's Meals component to diagnose the UI issue.
+ * Copy and paste this code into your Meals component temporarily.
+ */
+
+// Add this to your Meals component
+export function usePagePermissionGuardDiagnostic() {
+  const renderCount = useRef(0);
+  const instanceIds = useRef(new Set());
+  
+  renderCount.current += 1;
+  
+  useEffect(() => {
+    // Check for infinite re-renders
+    if (renderCount.current > 10) {
+      console.error('🚨 INFINITE RE-RENDER DETECTED!', {
+        renderCount: renderCount.current,
+        timestamp: new Date().toISOString(),
+        component: 'Meals'
+      });
+    }
+    
+    // Check for multiple PagePermissionGuard instances
+    const guards = document.querySelectorAll('[data-testid*="page-permission-guard"]');
+    if (guards.length > 1) {
+      console.error('🚨 MULTIPLE PagePermissionGuard INSTANCES!', {
+        count: guards.length,
+        elements: Array.from(guards).map(g => ({
+          element: g,
+          visible: g.offsetParent !== null,
+          zIndex: window.getComputedStyle(g).zIndex
+        }))
+      });
+    }
+    
+    // Check for multiple modals
+    const modals = document.querySelectorAll('[role="dialog"], .modal, [data-testid*="modal"], [data-testid*="access-denied"]');
+    if (modals.length > 1) {
+      console.error('🚨 MULTIPLE MODALS DETECTED!', {
+        count: modals.length,
+        modals: Array.from(modals).map(m => ({
+          element: m,
+          visible: m.offsetParent !== null,
+          zIndex: window.getComputedStyle(m).zIndex,
+          display: window.getComputedStyle(m).display
+        }))
+      });
+    }
+    
+    // Check for CSS conflicts
+    const elements = document.querySelectorAll('*');
+    const zIndexes = Array.from(elements)
+      .map(el => ({ 
+        element: el, 
+        zIndex: window.getComputedStyle(el).zIndex,
+        position: window.getComputedStyle(el).position
+      }))
+      .filter(item => item.zIndex !== 'auto' && item.zIndex !== '0' && item.position === 'fixed')
+      .sort((a, b) => parseInt(b.zIndex) - parseInt(a.zIndex));
+    
+    if (zIndexes.length > 0) {
+      console.log('🔍 Fixed positioned elements with z-index:', zIndexes.slice(0, 5));
+    }
+    
+    // Check for React Strict Mode
+    const isStrictMode = process.env.NODE_ENV === 'development' && 
+      document.querySelector('[data-reactroot]')?.__reactInternalInstance;
+    
+    if (isStrictMode) {
+      console.log('⚠️ React Strict Mode detected - this can cause double rendering in development');
+    }
+    
+  }, []);
+  
+  // Track PagePermissionGuard instance IDs
+  useEffect(() => {
+    const interval = setInterval(() => {
+      const logs = Array.from(document.querySelectorAll('*'))
+        .map(el => el.textContent)
+        .join(' ')
+        .match(/\[PagePermissionGuard\].*?\(instance: ([a-z0-9]+)\)/g);
+      
+      if (logs) {
+        logs.forEach(log => {
+          const match = log.match(/instance: ([a-z0-9]+)/);
+          if (match) {
+            instanceIds.current.add(match[1]);
+          }
+        });
+        
+        if (instanceIds.current.size > 1) {
+          console.error('🚨 MULTIPLE PagePermissionGuard INSTANCE IDS!', {
+            instanceIds: Array.from(instanceIds.current),
+            count: instanceIds.current.size
+          });
+        }
+      }
+    }, 1000);
+    
+    return () => clearInterval(interval);
+  }, []);
+  
+  return {
+    renderCount: renderCount.current,
+    instanceCount: instanceIds.current.size
+  };
+}
+
+/**
+ * Usage in your Meals component:
+ * 
+ * import { usePagePermissionGuardDiagnostic } from './path/to/this/file';
+ * 
+ * export function Meals() {
+ *   const diagnostic = usePagePermissionGuardDiagnostic();
+ *   
+ *   console.log('[Meals] Diagnostic info:', diagnostic);
+ *   
+ *   return (
+ *     <div>
+ *       <PagePermissionGuard pageName="meals" operation="read">
+ *         <DataTable ... />
+ *       </PagePermissionGuard>
+ *     </div>
+ *   );
+ * }
+ */

package/docs/troubleshooting/page-permission-guard-ui-debugging.md

@@ -0,0 +1,353 @@
+# PagePermissionGuard UI Debugging Guide
+
+## Issue: Access Denied Modal Persists Despite Correct Permissions
+
+### Problem Description
+The `PagePermissionGuard` component is correctly determining permissions (`can: true`, `willShowAccessDenied: false`, `willShowContent: true`) and logging `RENDERING CONTENT STATE`, but the Access Denied modal remains visible, obscuring the content.
+
+### Root Cause Analysis
+Based on the console logs, this is **NOT** a pace-core bug. The issue is in the Cake application's implementation. The logs show:
+
+1. ✅ **Permission Check Works**: `useCan` returns `can: true`
+2. ✅ **State Resolution Works**: `willShowAccessDenied: false`, `willShowContent: true`
+3. ✅ **Component Logic Works**: `RENDERING CONTENT STATE` is logged
+4. ❌ **UI Issue**: Access Denied modal remains visible
+5. ❌ **Infinite Loop**: Same instance ID (`14bp0efg9`) renders repeatedly
+
+## Debugging Steps for Cake Team
+
+### Step 1: Check for Multiple PagePermissionGuard Instances
+
+**Problem**: Multiple `PagePermissionGuard` components may be rendering simultaneously.
+
+**Debug Code**:
+```tsx
+// Add this to your Meals component
+console.log('[Meals] PagePermissionGuard instances:', document.querySelectorAll('[data-testid*="page-permission-guard"]').length);
+console.log('[Meals] Access Denied modals:', document.querySelectorAll('[data-testid*="access-denied"]').length);
+```
+
+**Fix**: Ensure only one `PagePermissionGuard` wraps your content.
+
+### Step 2: Check for CSS/Modal Layering Issues
+
+**Problem**: The Access Denied modal might be rendered by a different component or have CSS that keeps it visible.
+
+**Debug Code**:
+```tsx
+// Add this to your Meals component
+useEffect(() => {
+  const modals = document.querySelectorAll('[role="dialog"], .modal, [data-testid*="modal"]');
+  console.log('[Meals] Found modals:', modals.length);
+  modals.forEach((modal, index) => {
+    console.log(`[Meals] Modal ${index}:`, {
+      element: modal,
+      visible: modal.offsetParent !== null,
+      zIndex: window.getComputedStyle(modal).zIndex,
+      display: window.getComputedStyle(modal).display
+    });
+  });
+}, []);
+```
+
+**Fix**: Check if there are multiple modals or CSS conflicts.
+
+### Step 3: Check for State Management Issues
+
+**Problem**: React state might not be updating correctly, causing stale UI.
+
+**Debug Code**:
+```tsx
+// Add this to your Meals component
+const [debugState, setDebugState] = useState({});
+useEffect(() => {
+  setDebugState({
+    timestamp: new Date().toISOString(),
+    renderCount: (debugState.renderCount || 0) + 1
+  });
+}, []);
+
+console.log('[Meals] Component render state:', debugState);
+```
+
+**Fix**: Look for infinite re-renders or state update issues.
+
+### Step 4: Check for Conditional Rendering Issues
+
+**Problem**: The `PagePermissionGuard` might be conditionally rendered, causing React to unmount/remount.
+
+**Debug Code**:
+```tsx
+// Add this to your Meals component
+const [showGuard, setShowGuard] = useState(true);
+console.log('[Meals] PagePermissionGuard should render:', showGuard);
+
+// If you have conditional rendering, log it
+if (someCondition) {
+  console.log('[Meals] Conditional rendering condition:', someCondition);
+}
+```
+
+**Fix**: Ensure `PagePermissionGuard` is not conditionally rendered.
+
+### Step 5: Check for Parent Component Re-renders
+
+**Problem**: The parent component might be re-rendering and causing issues.
+
+**Debug Code**:
+```tsx
+// Add this to your Meals component
+const renderCount = useRef(0);
+renderCount.current += 1;
+console.log('[Meals] Component render count:', renderCount.current);
+
+// Check if props are changing
+useEffect(() => {
+  console.log('[Meals] Props changed:', { selectedEvent, otherProps });
+}, [selectedEvent, otherProps]);
+```
+
+**Fix**: Memoize expensive operations and prevent unnecessary re-renders.
+
+### Step 6: Check for React Strict Mode Issues
+
+**Problem**: React Strict Mode can cause double rendering in development.
+
+**Debug Code**:
+```tsx
+// Check if you're in strict mode
+console.log('[Meals] React Strict Mode:', process.env.NODE_ENV === 'development' && React.StrictMode);
+```
+
+**Fix**: Test in production build to see if issue persists.
+
+### Step 7: Check for CSS-in-JS or Styled Components Issues
+
+**Problem**: CSS-in-JS libraries might be causing style conflicts.
+
+**Debug Code**:
+```tsx
+// Check for style conflicts
+useEffect(() => {
+  const styles = document.querySelectorAll('style');
+  console.log('[Meals] Style elements:', styles.length);
+  
+  // Check for conflicting z-index values
+  const elements = document.querySelectorAll('*');
+  const zIndexes = Array.from(elements)
+    .map(el => ({ 
+      element: el, 
+      zIndex: window.getComputedStyle(el).zIndex 
+    }))
+    .filter(item => item.zIndex !== 'auto' && item.zIndex !== '0')
+    .sort((a, b) => parseInt(b.zIndex) - parseInt(a.zIndex));
+  
+  console.log('[Meals] Z-index conflicts:', zIndexes.slice(0, 10));
+}, []);
+```
+
+**Fix**: Check for CSS conflicts and z-index issues.
+
+## Common Cake Implementation Issues
+
+### Issue 1: Multiple PagePermissionGuard Wrappers
+
+```tsx
+// ❌ WRONG: Multiple guards
+<PagePermissionGuard pageName="meals" operation="read">
+  <PagePermissionGuard pageName="meals" operation="read">
+    <DataTable ... />
+  </PagePermissionGuard>
+</PagePermissionGuard>
+
+// ✅ CORRECT: Single guard
+<PagePermissionGuard pageName="meals" operation="read">
+  <DataTable ... />
+</PagePermissionGuard>
+```
+
+### Issue 2: Conditional Rendering
+
+```tsx
+// ❌ WRONG: Conditional guard
+{someCondition && (
+  <PagePermissionGuard pageName="meals" operation="read">
+    <DataTable ... />
+  </PagePermissionGuard>
+)}
+
+// ✅ CORRECT: Always render guard
+<PagePermissionGuard pageName="meals" operation="read">
+  {someCondition && <DataTable ... />}
+</PagePermissionGuard>
+```
+
+### Issue 3: State Management in Parent
+
+```tsx
+// ❌ WRONG: State changes causing re-renders
+const [loading, setLoading] = useState(true);
+useEffect(() => {
+  // This might cause infinite re-renders
+  setLoading(false);
+}, [loading]);
+
+// ✅ CORRECT: Stable state management
+const [loading, setLoading] = useState(true);
+useEffect(() => {
+  setLoading(false);
+}, []); // Empty dependency array
+```
+
+### Issue 4: CSS Conflicts
+
+```tsx
+// ❌ WRONG: CSS that might conflict
+.modal {
+  z-index: 9999 !important;
+  position: fixed !important;
+}
+
+// ✅ CORRECT: Use pace-core's built-in styling
+// Let pace-core handle the modal styling
+```
+
+## Recommended Fix for Cake
+
+### 1. Simplify the Meals Component
+
+```tsx
+// Meals.tsx - Simplified version
+import React from 'react';
+import { PagePermissionGuard } from '@jmruthers/pace-core';
+import { DataTable } from '@jmruthers/pace-core';
+
+export function Meals() {
+  console.log('[Meals] Rendering Meals component');
+  
+  return (
+    <div>
+      <h1>Meals</h1>
+      <p>Manage the meals available for AJ2025...</p>
+      
+      <PagePermissionGuard 
+        pageName="meals" 
+        operation="read"
+        fallback={
+          <div className="min-h-screen flex items-center justify-center">
+            <div className="text-center">
+              <div className="animate-spin rounded-full h-8 w-8 border-b-2 border-gray-900 mx-auto mb-4"></div>
+              <p>Loading permissions...</p>
+            </div>
+          </div>
+        }
+      >
+        <DataTable
+          data={processedMeals || []}
+          columns={columns}
+          rbac={{
+            resource: 'meals',
+            pageId: 'meals'
+          }}
+          // ... other props
+        />
+      </PagePermissionGuard>
+    </div>
+  );
+}
+```
+
+### 2. Check for Infinite Re-renders
+
+Add this to your Meals component to detect infinite re-renders:
+
+```tsx
+import { useEffect, useRef } from 'react';
+
+export function Meals() {
+  const renderCount = useRef(0);
+  renderCount.current += 1;
+  
+  useEffect(() => {
+    if (renderCount.current > 10) {
+      console.error('[Meals] INFINITE RE-RENDER DETECTED!', {
+        renderCount: renderCount.current,
+        timestamp: new Date().toISOString()
+      });
+    }
+  });
+  
+  // ... rest of component
+}
+```
+
+### 3. Check for Multiple Modals
+
+Add this to detect multiple modals:
+
+```tsx
+useEffect(() => {
+  const checkModals = () => {
+    const modals = document.querySelectorAll('[role="dialog"], .modal, [data-testid*="modal"], [data-testid*="access-denied"]');
+    if (modals.length > 1) {
+      console.error('[Meals] MULTIPLE MODALS DETECTED!', {
+        count: modals.length,
+        modals: Array.from(modals).map(m => ({
+          element: m,
+          visible: m.offsetParent !== null,
+          zIndex: window.getComputedStyle(m).zIndex
+        }))
+      });
+    }
+  };
+  
+  checkModals();
+  const interval = setInterval(checkModals, 1000);
+  return () => clearInterval(interval);
+}, []);
+```
+
+## Testing the Fix
+
+### 1. Test in Production Build
+
+```bash
+npm run build
+npm run preview
+```
+
+### 2. Test with React DevTools
+
+1. Install React DevTools browser extension
+2. Open the Components tab
+3. Look for multiple `PagePermissionGuard` instances
+4. Check for infinite re-renders
+
+### 3. Test with Network Tab
+
+1. Open DevTools Network tab
+2. Look for repeated API calls
+3. Check if permission checks are being called repeatedly
+
+## Expected Behavior
+
+After fixing the issues, you should see:
+
+1. ✅ Only one `PagePermissionGuard` instance
+2. ✅ No infinite re-renders
+3. ✅ `RENDERING CONTENT STATE` log appears once
+4. ✅ Access Denied modal disappears
+5. ✅ DataTable content is visible
+
+## Contact Information
+
+If you need further assistance, please provide:
+
+1. The complete Meals component code
+2. Any parent component that renders Meals
+3. The console logs after implementing the debugging code
+4. Screenshots of React DevTools showing component tree
+
+---
+
+**Note**: This issue is in the Cake application's implementation, not in pace-core. The `PagePermissionGuard` component is working correctly as evidenced by the console logs.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jmruthers/pace-core",
-  "version": "0.5.17",
+  "version": "0.5.18",
   "description": "Clean, modern React component library with Tailwind v4 styling and native utilities",
   "private": false,
   "publishConfig": {