@jmruthers/pace-core 0.5.181 → 0.5.182

package/docs/troubleshooting/common-issues.md

@@ -1,7 +1,7 @@
 ---
-lastUpdated: 2025-10-29T22:43:00+11:00
-version: 0.5.76
-reviewedBy: content-audit
+lastUpdated: 2025-11-18T15:00:00+11:00
+version: 0.5.181
+reviewedBy: documentation-standards-audit
 ---
 
 # Common Issues & Solutions
@@ -42,7 +42,6 @@ reviewedBy: content-audit
    <UnifiedAuthProvider 
      supabaseClient={supabase} 
      appName="your-app"
-     enableRBAC={true}
      requireOrganisationContext={true}
    >
      <OrganisationProvider>
@@ -159,6 +158,217 @@ function DebugRBAC() {
 }
 ```
 
+### Issue 5: Network Errors / CORS Issues
+
+**Symptoms:**
+- "CORS request did not succeed" error
+- Network timeout errors
+- Login requests failing
+- Connection refused errors
+
+**Root Cause:** CORS configuration or network connectivity issues
+
+**Solution:**
+
+#### Step 1: Verify CORS Configuration
+
+If pace-cake works fine with the same Supabase instance, then **CORS is already configured correctly**. The "CORS request did not succeed" error message is often misleading - it usually means the request failed for another reason, not necessarily CORS policy.
+
+**Check Network Tab in Browser DevTools:**
+1. Open browser DevTools (F12 or Cmd+Option+I)
+2. Go to **Network** tab
+3. Clear the network log
+4. Try to log in
+5. Look for the failed request to `/auth/v1/token`
+
+**What to check:**
+- **Status code**: What HTTP status code is returned? (200, 401, 500, etc.)
+- **Request headers**: Are the headers correct?
+- **Response**: What does the response say?
+- **Timing**: Does the request timeout or fail immediately?
+
+#### Step 2: Fix CORS in Supabase Dashboard
+
+If CORS is actually the issue:
+
+1. **Log into Supabase Dashboard** → [https://app.supabase.com](https://app.supabase.com)
+2. **Navigate to Settings → API**
+3. **Find "CORS" or "Allowed Origins" section**
+4. **Add your development origin**: `http://localhost:8087` (or your port)
+5. **Save changes** and wait 30-60 seconds for propagation
+6. **Clear browser cache** and test again
+
+**For development, you can use a wildcard** (less secure, but convenient):
+```
+*
+```
+
+⚠️ **Note**: Wildcard (`*`) allows ALL origins. Only use this for development, never in production!
+
+#### Step 3: Check Browser/Network Issues
+
+**Common causes of "CORS request did not succeed":**
+
+1. **Browser extension blocking requests**
+   - Try incognito/private mode
+   - Disable extensions one by one
+
+2. **Network/proxy issues**
+   - Check if corporate proxy is blocking
+   - Try different network (mobile hotspot)
+   - Check firewall settings
+
+3. **DNS issues**
+   - Can you reach your Supabase domain?
+   - Try pinging the domain
+
+4. **SSL/TLS issues**
+   - Check browser console for SSL errors
+   - Verify certificate is valid
+
+#### Step 4: Compare with Working App
+
+If another app (like pace-cake) works with the same Supabase instance:
+
+1. **Compare Supabase client setup** - Should be identical
+2. **Compare request headers** - Are they the same?
+3. **Compare provider setup** - Should match exactly
+4. **Check for code differences** - Something in your setup might be different
+
+**Most Likely Causes:**
+- Different port (but CORS should allow both if configured correctly)
+- Browser session issue (try clearing cache/cookies)
+- Network timing (something interfering with the request)
+- Code difference (something in your setup is different)
+
+### Issue 6: Database View Compatibility
+
+**Symptoms:**
+- Error: "column reference 'user_id' is ambiguous"
+- Queries failing with ambiguous column errors
+
+**Root Cause:** Database uses views instead of base tables, and views join multiple tables with same column names
+
+**Solution:**
+
+#### Apply Compatibility Migration (Recommended)
+
+@jmruthers/pace-core includes a compatibility migration:
+
+```bash
+# Copy the migration to your project
+cp node_modules/@jmruthers/pace-core/supabase/migrations/20250202000001_add_view_compatibility_functions.sql supabase/migrations/
+
+# Apply the migration
+supabase db push
+```
+
+The migration creates these functions:
+- `get_user_organisation_memberships(target_user_id UUID)`
+- `get_user_organisation_roles(target_user_id UUID, org_ids UUID[])`
+
+@jmruthers/pace-core will automatically detect and use these functions when it encounters ambiguous column errors.
+
+#### Alternative: Modify Database Views
+
+If you prefer to modify your views directly, ensure all column references are fully qualified (e.g., `table_name.user_id` instead of just `user_id`).
+
+### Issue 7: React Hooks Errors
+
+**Symptoms:**
+- Error: "Rendered more hooks than during the previous render"
+- Hooks called conditionally or after early returns
+
+**Root Cause:** Violating React hooks rules - hooks must be called in the same order on every render
+
+**Solution:**
+
+#### ❌ WRONG - Early return before hooks
+
+```tsx
+export const MyComponent = ({ isOpen, data }: Props) => {
+  // This early return causes the hooks error
+  if (!isOpen || !data) {
+    return null;
+  }
+
+  const { selectedOrganisation } = useOrganisations(); // Hook called after early return
+  const { items } = useData(data.id);
+  
+  return <DataTable ... />;
+};
+```
+
+#### ✅ CORRECT - Call hooks before any conditional returns
+
+```tsx
+export const MyComponent = ({ isOpen, data }: Props) => {
+  // ALWAYS call hooks first, before any conditional logic
+  const { selectedOrganisation } = useOrganisations();
+  const { items, isLoading } = useData(data?.id);
+
+  // THEN do conditional returns
+  if (!isOpen || !data) {
+    return null;
+  }
+  
+  return <DataTable data={items} ... />;
+};
+```
+
+**Key Rules:**
+1. **Always call hooks at the top level** - Never inside conditionals, loops, or nested functions
+2. **Call hooks in the same order** - Every render must call the same hooks in the same order
+3. **No early returns before hooks** - All hooks must be called before any conditional returns
+
+### Issue 8: PagePermissionGuard UI Issues
+
+**Symptoms:**
+- Access Denied modal persists despite correct permissions
+- Infinite re-render loops
+- UI state not updating despite correct component state
+
+**Root Cause:** Usually an application implementation issue, not a pace-core bug
+
+**Solution:**
+
+#### Verify pace-core is Working
+
+Check console logs - pace-core should show:
+- ✅ `useCan` returns `can: true`
+- ✅ `willShowAccessDenied: false`
+- ✅ `willShowContent: true`
+- ✅ `RENDERING CONTENT STATE` is logged
+
+#### Check Your Implementation
+
+**Common causes:**
+1. **Multiple PagePermissionGuard instances** rendering simultaneously
+2. **Infinite re-render loop** in your component
+3. **CSS/Modal layering conflicts** keeping the modal visible
+4. **React state management issues** preventing UI updates
+
+**Add Diagnostic Code:**
+
+```tsx
+import { useEffect, useRef } from 'react';
+
+export function MyComponent() {
+  const renderCount = useRef(0);
+  
+  useEffect(() => {
+    renderCount.current += 1;
+    console.log(`Component rendered ${renderCount.current} times`);
+    
+    if (renderCount.current > 10) {
+      console.error('Infinite re-render detected!');
+    }
+  });
+  
+  // Your component code...
+}
+```
+
 ## 🆘 **Still Having Issues?**
 
 If you're still experiencing problems after following this guide:
@@ -168,4 +378,60 @@ If you're still experiencing problems after following this guide:
 3. **Ensure you're using the correct API key** (anon, not service role)
 4. **Test with a minimal setup** to isolate the issue
 
-The most common issue is using the **service role key** instead of the **anon key**. The service role key bypasses RLS policies and can cause unexpected behavior with RPC calls.
+The most common issue is using the **service role key** instead of the **anon key**. The service role key bypasses RLS policies and can cause unexpected behavior with RPC calls.
+
+## ♿ Accessibility
+
+When troubleshooting issues, consider accessibility implications:
+
+- **WCAG 2.1 AA compliance** - Ensure fixes maintain accessibility standards
+- **Screen Reader Support** - Verify solutions don't break screen reader functionality
+- **Keyboard Navigation** - Ensure fixes don't affect keyboard accessibility
+- **Error Announcements** - Ensure error messages are accessible to assistive technologies
+- **Focus Management** - Verify focus handling remains correct after fixes
+
+### Accessibility Best Practices
+
+1. **Test with screen readers** - Verify fixes work with assistive technologies
+2. **Check error announcements** - Ensure error messages are properly announced
+3. **Maintain keyboard access** - Verify all interactive elements remain keyboard accessible
+4. **Preserve semantic structure** - Don't break semantic HTML with workarounds
+5. **Test focus management** - Ensure focus handling remains correct
+
+## ⚠️ Edge Cases
+
+### Multiple Issues Occurring Simultaneously
+
+When multiple issues occur at once:
+- Address setup issues first (RBAC, providers, environment)
+- Fix authentication before permission issues
+- Resolve network/CORS before data fetching issues
+- Test each fix independently
+- Use systematic debugging approach
+
+### Issues That Only Occur in Production
+
+When issues only appear in production:
+- Verify environment variables are set correctly
+- Check build configuration matches development
+- Ensure all dependencies are included in build
+- Verify API endpoints are accessible from production
+- Check for environment-specific configuration differences
+
+### Intermittent Issues
+
+When issues occur intermittently:
+- Check for race conditions in async operations
+- Verify cache invalidation is working correctly
+- Check for timing issues in provider setup
+- Monitor network conditions
+- Review error logs for patterns
+
+### Issues After Updates
+
+When issues occur after updating pace-core:
+- Review migration guides for breaking changes
+- Check for deprecated API usage
+- Verify all dependencies are compatible
+- Review changelog for known issues
+- Test with previous version to confirm regression

package/docs/troubleshooting/debugging.md

@@ -1,3 +1,9 @@
+---
+lastUpdated: 2025-11-18T15:00:00+11:00
+version: 0.5.181
+reviewedBy: documentation-standards-audit
+---
+
 # Debugging Guide
 
 Effective debugging is essential for maintaining and troubleshooting `@jmruthers/pace-core` applications. This guide provides comprehensive debugging techniques and tools.
@@ -1114,4 +1120,51 @@ function debugAPI() {
 }
 ```
 
-For more information about debugging your application, see the [Common Issues Guide](./common-issues.md) and [Migration Guide](./migration.md). 
+For more information about debugging your application, see the [Common Issues Guide](./common-issues.md) and [Migration Guide](./migration.md).
+
+## ♿ Accessibility
+
+When debugging, ensure accessibility is maintained:
+
+- **Screen Reader Testing** - Test fixes with screen readers to verify accessibility
+- **Keyboard Navigation** - Verify keyboard accessibility is preserved during debugging
+- **Error Announcements** - Ensure error messages are accessible to assistive technologies
+- **Focus Management** - Verify focus handling remains correct after fixes
+- **ARIA Labels** - Check that ARIA labels are not removed during debugging
+
+### Accessibility Best Practices
+
+1. **Test with assistive technologies** - Verify fixes work with screen readers and keyboard navigation
+2. **Preserve semantic structure** - Don't break semantic HTML during debugging
+3. **Maintain focus visibility** - Ensure focus indicators remain visible
+4. **Check error announcements** - Verify error messages are properly announced
+5. **Test keyboard shortcuts** - Ensure keyboard shortcuts still work after fixes
+
+## ⚠️ Edge Cases
+
+### Debugging Tools Not Working
+
+When debugging tools don't work:
+- Verify development mode is enabled
+- Check browser console for errors
+- Ensure debugging tools are properly installed
+- Clear browser cache and restart dev server
+- Check for conflicts with browser extensions
+
+### Performance Impact of Debugging
+
+When debugging impacts performance:
+- Use conditional debugging (only in development)
+- Remove debug code before production
+- Use performance monitoring tools
+- Profile memory usage during debugging
+- Optimize debug logging
+
+### Debugging in Production
+
+When debugging production issues:
+- Use remote logging services
+- Implement error tracking
+- Use feature flags for debugging
+- Monitor performance metrics
+- Collect user feedback 

package/docs/troubleshooting/migration.md

@@ -1,3 +1,9 @@
+---
+lastUpdated: 2025-11-18T15:00:00+11:00
+version: 0.5.181
+reviewedBy: documentation-standards-audit
+---
+
 # Migration Guide
 
 This guide provides comprehensive migration strategies for upgrading `@jmruthers/pace-core` applications between versions and handling breaking changes.
@@ -915,4 +921,51 @@ export class RollbackStrategy {
 }
 ```
 
-For more information about migrating your application, see the [Common Issues Guide](./common-issues.md) and [Debugging Guide](./debugging.md). 
+For more information about migrating your application, see the [Common Issues Guide](./common-issues.md) and [Debugging Guide](./debugging.md).
+
+## ♿ Accessibility
+
+During migration, ensure accessibility is maintained:
+
+- **Screen Reader Testing** - Test migrated components with screen readers
+- **Keyboard Navigation** - Verify keyboard accessibility is preserved
+- **ARIA Labels** - Ensure ARIA labels are updated if component APIs change
+- **Focus Management** - Verify focus handling remains correct after migration
+- **Color Contrast** - Check that color changes meet WCAG contrast requirements
+
+### Accessibility Best Practices
+
+1. **Test with assistive technologies** - Verify migrated code works with screen readers
+2. **Preserve semantic structure** - Don't break semantic HTML during migration
+3. **Update ARIA labels** - Ensure ARIA labels match new component APIs
+4. **Maintain focus visibility** - Ensure focus indicators remain visible
+5. **Test keyboard shortcuts** - Verify keyboard shortcuts still work after migration
+
+## ⚠️ Edge Cases
+
+### Partial Migration Issues
+
+When only part of the application is migrated:
+- Verify compatibility between old and new code
+- Test integration points carefully
+- Check for API mismatches
+- Ensure data formats are compatible
+- Test all user flows that span old and new code
+
+### Rollback Scenarios
+
+When migration needs to be rolled back:
+- Have a rollback plan ready
+- Test rollback procedures before migration
+- Ensure database migrations can be reversed
+- Keep backups of all configurations
+- Document rollback steps clearly
+
+### Migration Breaking Existing Features
+
+When migration breaks existing features:
+- Identify all breaking changes
+- Update all affected components
+- Test all user flows thoroughly
+- Provide migration guides for each breaking change
+- Consider gradual migration approach 

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

@@ -1,7 +1,7 @@
 ---
-lastUpdated: 2025-10-29T22:43:00+11:00
-version: 0.5.76
-reviewedBy: content-audit
+lastUpdated: 2025-11-18T15:00:00+11:00
+version: 0.5.181
+reviewedBy: documentation-standards-audit
 ---
 
 # Organisation Context Setup Troubleshooting
@@ -281,3 +281,29 @@ If you're still experiencing problems:
 5. **Ensure your app is using the latest PACE Core version**
 
 The key is making sure the database has the organisation context functions and your RLS policies use them correctly.
+
+## ♿ Accessibility
+
+Organisation context setup doesn't directly impact accessibility, but ensure:
+
+- **Error messages are accessible** - Database errors should be clearly communicated
+- **Loading states are announced** - Screen readers should announce context loading
+- **Focus management** - Ensure focus is properly managed during context setup
+
+## ⚠️ Edge Cases
+
+### Context Not Persisting Across Sessions
+
+When organisation context doesn't persist:
+- Verify session configuration is correct
+- Check that context is set on every request
+- Ensure RLS policies use the context correctly
+- Review session timeout settings
+
+### Multiple Organisation Context Issues
+
+When working with multiple organisations:
+- Verify context switching is working correctly
+- Check that RLS policies handle context changes
+- Ensure context is cleared when switching organisations
+- Test with users who have access to multiple organisations