@jmruthers/pace-core 0.2.7 → 0.4.1

package/docs/troubleshooting/README.md

@@ -1,497 +0,0 @@
-# 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!**

package/docs/troubleshooting/styling-issues.md

@@ -1,219 +0,0 @@
-# Styling Issues Troubleshooting
-
-This guide helps you diagnose and fix common styling issues when using pace-core components.
-
-## 🚨 Most Common Issue: Unstyled Components
-
-### Symptoms
-- Components render but appear unstyled (no colors, spacing, or typography)
-- Buttons look like plain HTML buttons
-- Cards appear as plain divs
-- Colors like `text-main-900`, `bg-sec-500` don't work
-
-### Root Cause
-**Pace-core components are not being scanned for Tailwind classes during the build process.**
-
-### Solution
-Update your `vite.config.ts` to include pace-core in content scanning:
-
-```ts
-// vite.config.ts
-import { defineConfig } from 'vite'
-import react from '@vitejs/plugin-react'
-import tailwindcss from '@tailwindcss/vite'
-
-export default defineConfig({
-  plugins: [
-    react(),
-    tailwindcss({
-      // CRITICAL: Include pace-core components for scanning
-      content: [
-        './src/**/*.{js,ts,jsx,tsx}',
-        './node_modules/@jmruthers/pace-core/**/*.{js,ts,jsx,tsx}'
-      ]
-    })
-  ],
-})
-```
-
-### Verification Steps
-1. **Check your Vite config** - Ensure pace-core is included in content array
-2. **Restart dev server** - Configuration changes require a restart
-3. **Test with a simple component**:
-   ```tsx
-   import { Button } from '@jmruthers/pace-core';
-   
-   function Test() {
-     return <Button variant="primary">Test</Button>;
-   }
-   ```
-4. **Check browser dev tools** - Look for missing CSS classes in the computed styles
-
-## 🔍 Other Common Issues
-
-### Issue: CSS file not imported
-
-**Symptoms**: No styles at all, components look completely unstyled
-
-**Solution**: Import the CSS file in your main entry point:
-```tsx
-// src/main.tsx or src/index.tsx
-import '@jmruthers/pace-core/styles/core.css';
-```
-
-### Issue: Colors not working
-
-**Symptoms**: Components render but colors like `text-main-900`, `bg-sec-500` don't apply
-
-**Possible Causes**:
-1. CSS file not imported
-2. Pace-core not included in content scanning
-3. Tailwind v3 instead of v4
-
-**Solution**:
-1. Ensure CSS file is imported
-2. Check Vite configuration includes pace-core
-3. Verify you're using Tailwind v4: `npm list tailwindcss`
-
-### Issue: Styles work in dev but not production
-
-**Symptoms**: Components look good in development but unstyled in production build
-
-**Solution**: Ensure your build configuration also includes content scanning:
-```ts
-// vite.config.ts
-export default defineConfig({
-  plugins: [
-    react(),
-    tailwindcss({
-      content: [
-        './src/**/*.{js,ts,jsx,tsx}',
-        './node_modules/@jmruthers/pace-core/**/*.{js,ts,jsx,tsx}'
-      ]
-    })
-  ],
-  build: {
-    // Your build config
-  }
-})
-```
-
-### Issue: Build errors about missing classes
-
-**Symptoms**: Build fails with errors about missing Tailwind classes
-
-**Solution**: Check that your content paths are correct and include both source files and pace-core:
-```ts
-content: [
-  './src/**/*.{js,ts,jsx,tsx}',
-  './node_modules/@jmruthers/pace-core/**/*.{js,ts,jsx,tsx}'
-]
-```
-
-### Issue: Some components work, others don't
-
-**Symptoms**: Some pace-core components are styled, others are not
-
-**Possible Causes**:
-1. Partial content scanning
-2. Different import paths
-3. Component-specific issues
-
-**Solution**:
-1. Check that all pace-core paths are included in content scanning
-2. Try the alternative configuration:
-   ```ts
-   tailwindcss({
-     content: {
-       files: [
-         './src/**/*.{js,ts,jsx,tsx}',
-         './node_modules/@jmruthers/pace-core/**/*.{js,ts,jsx,tsx}',
-         './node_modules/@jmruthers/pace-core/dist/**/*.{js,ts,jsx,tsx}'
-       ]
-     }
-   })
-   ```
-
-## 🔧 Advanced Troubleshooting
-
-### Check if Tailwind is scanning pace-core
-
-1. **Enable Tailwind debug mode**:
-   ```ts
-   // vite.config.ts
-   tailwindcss({
-     content: [
-       './src/**/*.{js,ts,jsx,tsx}',
-       './node_modules/@jmruthers/pace-core/**/*.{js,ts,jsx,tsx}'
-     ],
-     debug: true // Add this for debugging
-   })
-   ```
-
-2. **Check the generated CSS** - Look for pace-core specific classes in your build output
-
-3. **Use browser dev tools** - Inspect elements to see which classes are missing
-
-### Verify Tailwind v4 installation
-
-```bash
-# Check Tailwind version
-npm list tailwindcss
-
-# Should show version 4.x.x, not 3.x.x
-```
-
-### Check file paths
-
-Ensure your content paths are correct:
-- `./src/**/*.{js,ts,jsx,tsx}` - Your source files
-- `./node_modules/@jmruthers/pace-core/**/*.{js,ts,jsx,tsx}` - Pace-core components
-
-### Alternative content configuration
-
-If the standard configuration doesn't work, try this more explicit approach:
-
-```ts
-// vite.config.ts
-export default defineConfig({
-  plugins: [
-    react(),
-    tailwindcss({
-      content: {
-        files: [
-          './src/**/*.{js,ts,jsx,tsx}',
-          './node_modules/@jmruthers/pace-core/**/*.{js,ts,jsx,tsx}',
-          './node_modules/@jmruthers/pace-core/dist/**/*.{js,ts,jsx,tsx}'
-        ]
-      }
-    })
-  ],
-})
-```
-
-## ✅ Quick Checklist
-
-Before asking for help, verify:
-
-- [ ] CSS file is imported: `import '@jmruthers/pace-core/styles/core.css'`
-- [ ] Vite config includes pace-core in content scanning
-- [ ] Using Tailwind v4 (not v3)
-- [ ] Dev server restarted after config changes
-- [ ] All required peer dependencies installed
-- [ ] Test component renders with proper styling
-
-## 🆘 Still Having Issues?
-
-If you've tried all the above and still have problems:
-
-1. **Check the console** for any error messages
-2. **Verify your setup** matches the [installation guide](../getting-started/installation.md)
-3. **Test with a minimal example** to isolate the issue
-4. **Check your package versions** for compatibility issues
-
-## 📚 Related Documentation
-
-- [Installation Guide](../getting-started/installation.md) - Complete setup instructions
-- [Vite Configuration](../consuming-app-vite-config.md) - Detailed Vite setup
-- [Quick Start Guide](../getting-started/quick-start.md) - Step-by-step tutorial
-- [Styles Guide](../styles/README.md) - Understanding the styling system