@jmruthers/pace-core 0.4.1 → 0.5.1

package/docs/troubleshooting/README.md

@@ -0,0 +1,497 @@
+# Troubleshooting Guide
+
+> **🆘 Get Help Fast** | [Common Issues](#common-issues) | [Debugging](#debugging) | [Support](#support)
+
+[← Back to Documentation](../README.md) | [↑ Table of Contents](#table-of-contents)
+
+Comprehensive troubleshooting guide for PACE Core applications. Find solutions to common problems and learn debugging techniques.
+
+## 📋 Table of Contents
+
+- [Common Issues](#-common-issues)
+- [Debugging Techniques](#-debugging-techniques)
+- [Performance Issues](#-performance-issues)
+- [Authentication Problems](#-authentication-problems)
+- [Styling Issues](#-styling-issues)
+- [Build & Deployment](#-build--deployment)
+- [Getting Help](#-getting-help)
+
+## 🐛 Common Issues
+
+### Quick Fixes
+
+**Most common issues and their solutions:**
+
+| Issue | Quick Fix | Full Guide |
+|-------|-----------|------------|
+| Components not styled | Import `core.css` | [Styling Issues](#styling-issues) |
+| Authentication not working | Check provider setup | [Authentication Problems](#authentication-problems) |
+| Permissions returning false | Verify RBAC setup | [RBAC Issues](#rbac-issues) |
+| Build failing | Check Tailwind config | [Build Issues](#build-issues) |
+| DataTable not rendering | Check features prop | [Component Issues](#component-issues) |
+
+### Styling Issues
+
+**Problem**: Components appear unstyled or broken
+
+**Quick Fix:**
+```tsx
+// ✅ Make sure you import the CSS
+import '@jmruthers/pace-core/styles/core.css';
+```
+
+**Common Causes:**
+- Missing CSS import
+- Incorrect Tailwind configuration
+- CSS conflicts with existing styles
+- Missing Vite content scanning
+
+**Full Solution**: See [Common Issues - Styling](./common-issues.md#styling-issues)
+
+### Authentication Problems
+
+**Problem**: Login not working or user state not updating
+
+**Quick Fix:**
+```tsx
+// ✅ Ensure proper provider hierarchy
+<UnifiedAuthProvider supabaseClient={supabase} appName="my-app">
+  <OrganisationProvider>
+    <EventProvider>
+      <YourApp />
+    </EventProvider>
+  </OrganisationProvider>
+</UnifiedAuthProvider>
+```
+
+**Common Causes:**
+- Missing provider setup
+- Incorrect Supabase configuration
+- Provider hierarchy issues
+- Session management problems
+
+**Full Solution**: See [Common Issues - Authentication](./common-issues.md#authentication-issues)
+
+### RBAC Issues
+
+**Problem**: Permissions always return false or incorrect
+
+**Quick Fix:**
+```tsx
+// ✅ Check if user has proper context
+const { hasPermission, isLoading } = useCan();
+if (isLoading) return <div>Loading permissions...</div>;
+
+// ✅ Ensure proper scope
+<PermissionGuard
+  userId={user.id}
+  scope={{ organisationId: currentOrg.id }}
+  permission="read:users"
+>
+  <UserList />
+</PermissionGuard>
+```
+
+**Common Causes:**
+- Missing organisation context
+- Incorrect permission strings
+- RBAC not properly initialized
+- Database RLS policies
+
+**Full Solution**: See [Common Issues - RBAC](./common-issues.md#rbac-issues)
+
+## 🔍 Debugging Techniques
+
+### Enable Debug Mode
+
+**PACE Core Debug Mode:**
+```tsx
+// Enable debug logging
+<UnifiedAuthProvider 
+  supabaseClient={supabase} 
+  appName="my-app"
+  debug={true} // Enable debug mode
+>
+  <YourApp />
+</UnifiedAuthProvider>
+```
+
+**RBAC Debug Mode:**
+```tsx
+// Debug permission checks
+const { hasPermission, debugInfo } = useCan();
+
+console.log('Permission debug info:', debugInfo);
+```
+
+### Browser DevTools
+
+**React DevTools:**
+1. Install React DevTools browser extension
+2. Check component props and state
+3. Use Profiler to identify performance issues
+4. Inspect context providers
+
+**Network Tab:**
+1. Check API requests to Supabase
+2. Verify authentication headers
+3. Look for failed requests
+4. Check response data
+
+**Console Logging:**
+```tsx
+// Add temporary logging
+useEffect(() => {
+  console.log('User:', user);
+  console.log('Session:', session);
+  console.log('Organisation:', currentOrg);
+}, [user, session, currentOrg]);
+```
+
+### Common Debug Patterns
+
+**Check Provider Hierarchy:**
+```tsx
+// Add debug components
+function DebugProviders() {
+  const auth = useUnifiedAuth();
+  const org = useOrganisation();
+  const events = useEvents();
+  
+  console.log('Auth:', auth);
+  console.log('Organisation:', org);
+  console.log('Events:', events);
+  
+  return null;
+}
+
+// Add to your app
+<DebugProviders />
+```
+
+**Check Permission State:**
+```tsx
+function PermissionDebugger() {
+  const { hasPermission, isLoading, error } = useCan();
+  
+  console.log('Permission state:', {
+    hasPermission: hasPermission('read', 'users'),
+    isLoading,
+    error
+  });
+  
+  return null;
+}
+```
+
+## ⚡ Performance Issues
+
+### Slow Rendering
+
+**Symptoms:**
+- Components take long to render
+- UI feels sluggish
+- High CPU usage
+
+**Solutions:**
+```tsx
+// ✅ Use React.memo for expensive components
+const ExpensiveComponent = React.memo(({ data }) => {
+  return <DataTable data={data} columns={columns} />;
+});
+
+// ✅ Use useCallback for event handlers
+const handleClick = useCallback((id: string) => {
+  // Handle click
+}, []);
+
+// ✅ Use useMemo for expensive calculations
+const processedData = useMemo(() => {
+  return data.map(item => expensiveTransform(item));
+}, [data]);
+```
+
+### Large Bundle Size
+
+**Symptoms:**
+- Slow initial load
+- Large JavaScript bundles
+- Long build times
+
+**Solutions:**
+```tsx
+// ✅ Use dynamic imports
+const HeavyComponent = React.lazy(() => import('./HeavyComponent'));
+
+// ✅ Import only what you need
+import { Button, Card } from '@jmruthers/pace-core';
+// Instead of: import * as PACE from '@jmruthers/pace-core';
+
+// ✅ Use code splitting
+const AdminPanel = React.lazy(() => import('./AdminPanel'));
+```
+
+### Memory Leaks
+
+**Symptoms:**
+- Memory usage increases over time
+- Browser becomes slow
+- Crashes after extended use
+
+**Solutions:**
+```tsx
+// ✅ Clean up event listeners
+useEffect(() => {
+  const handleResize = () => setWidth(window.innerWidth);
+  window.addEventListener('resize', handleResize);
+  
+  return () => window.removeEventListener('resize', handleResize);
+}, []);
+
+// ✅ Cancel API requests
+useEffect(() => {
+  const controller = new AbortController();
+  
+  fetchData({ signal: controller.signal });
+  
+  return () => controller.abort();
+}, []);
+```
+
+## 🔐 Authentication Problems
+
+### Login Not Working
+
+**Checklist:**
+- [ ] Supabase client properly configured
+- [ ] Correct environment variables
+- [ ] Provider hierarchy correct
+- [ ] User credentials valid
+- [ ] Network connectivity
+
+**Debug Steps:**
+```tsx
+// 1. Check Supabase connection
+const { data, error } = await supabase.auth.getSession();
+console.log('Session:', data, error);
+
+// 2. Check login attempt
+const { data, error } = await supabase.auth.signInWithPassword({
+  email: 'user@example.com',
+  password: 'password'
+});
+console.log('Login result:', data, error);
+```
+
+### Session Management Issues
+
+**Common Problems:**
+- Session not persisting
+- Automatic logout
+- Token refresh failures
+
+**Solutions:**
+```tsx
+// ✅ Check session persistence
+useEffect(() => {
+  const { data: { subscription } } = supabase.auth.onAuthStateChange(
+    (event, session) => {
+      console.log('Auth state change:', event, session);
+      if (event === 'SIGNED_OUT') {
+        // Handle logout
+      }
+    }
+  );
+  
+  return () => subscription.unsubscribe();
+}, []);
+```
+
+### Permission Issues
+
+**Checklist:**
+- [ ] User has proper roles
+- [ ] Organisation context set
+- [ ] RLS policies correct
+- [ ] Permission strings match
+
+**Debug:**
+```tsx
+// Check user roles
+const { data: userRoles } = await supabase
+  .from('user_roles')
+  .select('*')
+  .eq('user_id', user.id);
+
+console.log('User roles:', userRoles);
+```
+
+## 🎨 Styling Issues
+
+### Components Not Styled
+
+**Quick Fix:**
+```tsx
+// ✅ Import CSS first
+import '@jmruthers/pace-core/styles/core.css';
+import { Button } from '@jmruthers/pace-core';
+```
+
+**Vite Configuration:**
+```ts
+// vite.config.ts
+import tailwindcss from '@tailwindcss/vite'
+export default defineConfig({
+  plugins: [
+    react(),
+    tailwindcss({
+      content: [
+        './src/**/*.{js,ts,jsx,tsx}',
+        './node_modules/@jmruthers/pace-core/**/*.{js,ts,jsx,tsx}'
+      ]
+    })
+  ],
+})
+```
+
+### CSS Conflicts
+
+**Problem**: PACE Core styles conflict with existing styles
+
+**Solution:**
+```css
+/* Use CSS layers to control specificity */
+@layer pace-core, your-app;
+
+@layer your-app {
+  /* Your custom styles */
+  .my-button {
+    /* Will override PACE Core styles */
+  }
+}
+```
+
+### Theme Not Working
+
+**Check:**
+- [ ] CSS import order
+- [ ] Tailwind configuration
+- [ ] Content scanning paths
+- [ ] CSS variables defined
+
+## 🏗️ Build & Deployment
+
+### Build Failures
+
+**Common Causes:**
+- Missing dependencies
+- TypeScript errors
+- Tailwind configuration issues
+- Environment variables missing
+
+**Solutions:**
+```bash
+# Clear cache and reinstall
+rm -rf node_modules package-lock.json
+npm install
+
+# Check for TypeScript errors
+npm run type-check
+
+# Verify Tailwind config
+npm run build -- --debug
+```
+
+### Environment Variables
+
+**Check:**
+```tsx
+// Verify environment variables
+console.log('Environment:', {
+  supabaseUrl: import.meta.env.VITE_SUPABASE_URL,
+  supabaseKey: import.meta.env.VITE_SUPABASE_ANON_KEY,
+  appName: import.meta.env.VITE_APP_NAME,
+});
+```
+
+### Deployment Issues
+
+**Common Problems:**
+- Missing environment variables
+- Build artifacts not found
+- CORS issues
+- CDN configuration
+
+**Solutions:**
+```yaml
+# Example deployment config
+env:
+  VITE_SUPABASE_URL: ${{ secrets.SUPABASE_URL }}
+  VITE_SUPABASE_ANON_KEY: ${{ secrets.SUPABASE_ANON_KEY }}
+  VITE_APP_NAME: "My App"
+```
+
+## 🆘 Getting Help
+
+### Before Asking for Help
+
+1. **Check this guide** - Your issue might already be covered
+2. **Search existing issues** - Look for similar problems
+3. **Gather information** - Error messages, browser console, steps to reproduce
+4. **Try debugging** - Use the debugging techniques above
+
+### Information to Include
+
+When asking for help, include:
+
+- **PACE Core version**: `npm list @jmruthers/pace-core`
+- **Node.js version**: `node --version`
+- **Browser and version**
+- **Error messages** (full stack trace)
+- **Steps to reproduce**
+- **Expected vs actual behavior**
+- **Code snippets** (minimal reproduction)
+
+### Debug Information Template
+
+```tsx
+// Add this to your app for 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 }}>
+      <h4>Debug Info</h4>
+      <pre>{JSON.stringify({
+        auth: { user: auth.user?.id, loading: auth.loading },
+        org: { current: org.selectedOrganisation?.id, loading: org.loading },
+        events: { current: events.selectedEvent?.id, loading: events.loading },
+        permissions: { canReadUsers: hasPermission('read', 'users') }
+      }, null, 2)}</pre>
+    </div>
+  );
+}
+```
+
+### Support Channels
+
+- **GitHub Issues**: For bug reports and feature requests
+- **Documentation**: Check the full documentation
+- **Community**: Join our community discussions
+- **Email**: For security issues or private support
+
+### Common Solutions
+
+**Still having issues? Try these:**
+
+1. **Update to latest version**
+2. **Clear all caches** (browser, npm, build)
+3. **Check browser console** for errors
+4. **Verify all dependencies** are installed
+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!**