@jmruthers/pace-core 0.2.4

package/docs/troubleshooting/common-issues.md

@@ -0,0 +1,1563 @@
+# Common Issues
+
+This guide provides solutions to the most common issues you may encounter when using `@jmruthers/pace-core`.
+
+## Navigation Issues
+
+### NavigationMenu Not Receiving Authentication Context
+
+**Problem**: `NavigationMenu` shows `permissions: undefined`, `roles: undefined`, `accessLevel: undefined` in console logs.
+
+**Root Cause**: The `NavigationMenu` component is not properly connected to the authentication context.
+
+**Solution**: Ensure `NavigationMenu` is used within the proper provider hierarchy and enable permission filtering:
+
+```tsx
+// ❌ WRONG - NavigationMenu without proper context
+<NavigationMenu 
+  items={navItems}
+  currentPath={location.pathname}
+  onNavigate={handleNavigate}
+/>
+
+// ✅ CORRECT - NavigationMenu with authentication context
+<UnifiedAuthProvider supabaseClient={supabase} appName="My App">
+  <OrganisationProvider>
+    <EventProvider>
+      <PaceAppLayout 
+        appName="My App" 
+        navItems={navItems}
+        showEventSelector={true}
+      >
+        <Routes>
+          {/* Your routes */}
+        </Routes>
+      </PaceAppLayout>
+    </EventProvider>
+  </OrganisationProvider>
+</UnifiedAuthProvider>
+```
+
+**Alternative Solution**: Use `NavigationMenu` directly with permission filtering:
+
+```tsx
+import { NavigationMenu } from '@jmruthers/pace-core';
+import { useUnifiedAuth } from '@jmruthers/pace-core/providers';
+
+function AuthenticatedNavigation() {
+  const { hasPermission, hasRole } = useUnifiedAuth();
+
+  const navItems = [
+    { 
+      id: 'dashboard', 
+      label: 'Dashboard', 
+      href: '/dashboard',
+      permissions: ['dashboard:read']
+    },
+    { 
+      id: 'admin', 
+      label: 'Admin Panel', 
+      href: '/admin',
+      roles: ['admin']
+    }
+  ];
+
+  return (
+    <NavigationMenu 
+      items={navItems}
+      currentPath={location.pathname}
+      onNavigate={handleNavigate}
+      filterByPermissions={true}
+      auditLog={true}
+    />
+  );
+}
+```
+
+### NavigationMenu Items Not Filtering by Permissions
+
+**Problem**: All navigation items are shown regardless of user permissions.
+
+**Solution**: Enable permission filtering and add permission requirements to navigation items:
+
+```tsx
+// Add permissions to navigation items
+const navItems = [
+  { 
+    id: 'dashboard', 
+    label: 'Dashboard', 
+    href: '/dashboard',
+    permissions: ['dashboard:read'] // Required permission
+  },
+  { 
+    id: 'admin', 
+    label: 'Admin Panel', 
+    href: '/admin',
+    roles: ['admin', 'super_admin'] // Required roles
+  }
+];
+
+// Enable filtering
+<NavigationMenu 
+  items={navItems}
+  filterByPermissions={true}
+  auditLog={true}
+/>
+```
+
+### NavigationMenu Console Errors
+
+**Problem**: Console shows "useUnifiedAuth not available" warnings.
+
+**Solution**: Ensure `NavigationMenu` is used within `UnifiedAuthProvider`:
+
+```tsx
+// ❌ WRONG - Outside of auth provider
+<NavigationMenu items={navItems} />
+
+// ✅ CORRECT - Inside auth provider
+<UnifiedAuthProvider supabaseClient={supabase} appName="My App">
+  <NavigationMenu items={navItems} />
+</UnifiedAuthProvider>
+```
+
+## Authentication Issues
+
+### 1. "User not authenticated" Error
+
+**Problem**: Users are getting "not authenticated" errors even when they should be logged in.
+
+**Solution**:
+
+```typescript
+import { useUnifiedAuth } from '@jmruthers/pace-core';
+
+function App() {
+  const { user, loading, error } = useUnifiedAuth();
+
+  if (loading) {
+    return <div>Loading...</div>;
+  }
+
+  if (error) {
+    console.error('Auth error:', error);
+    return <div>Authentication error: {error.message}</div>;
+  }
+
+  if (!user) {
+    return <LoginForm />;
+  }
+
+  return <AuthenticatedApp />;
+}
+```
+
+**Common Causes**:
+- Session expired
+- Invalid token
+- Network connectivity issues
+- Supabase configuration problems
+
+**Debugging**:
+```typescript
+// Check session status
+const { session } = useUnifiedAuth();
+console.log('Session:', session);
+console.log('Session expires:', new Date(session?.expires_at * 1000));
+```
+
+### 2. Authentication Provider Not Wrapped
+
+**Problem**: Components can't access authentication context.
+
+**Solution**: Ensure your app is wrapped with the authentication provider:
+
+```typescript
+import { UnifiedAuthProvider } from '@jmruthers/pace-core';
+
+function App() {
+  return (
+    <UnifiedAuthProvider>
+      <YourApp />
+    </UnifiedAuthProvider>
+  );
+}
+```
+
+### 3. Session Refresh Issues
+
+**Problem**: Sessions are not refreshing automatically.
+
+**Solution**:
+
+```typescript
+import { useUnifiedAuth } from '@jmruthers/pace-core';
+
+function SessionManager() {
+  const { session, refreshSession } = useUnifiedAuth();
+
+  useEffect(() => {
+    if (session && session.expires_at) {
+      const timeUntilExpiry = session.expires_at * 1000 - Date.now();
+      const refreshTime = Math.max(timeUntilExpiry - 5 * 60 * 1000, 0);
+
+      const timer = setTimeout(() => {
+        refreshSession();
+      }, refreshTime);
+
+      return () => clearTimeout(timer);
+    }
+  }, [session, refreshSession]);
+
+  return null;
+}
+```
+
+## Permission Issues
+
+### 1. "Access denied" Errors
+
+**Problem**: Users are getting access denied even when they should have permissions.
+
+**Solution**:
+
+```typescript
+import { useRBAC } from '@jmruthers/pace-core';
+
+function DebugPermissions() {
+  const { user, roles, permissions, hasPermission } = useRBAC();
+
+  console.log('User:', user);
+  console.log('Roles:', roles);
+  console.log('Permissions:', permissions);
+
+  // Test specific permissions
+  console.log('Can read users:', hasPermission('read:users'));
+  console.log('Can create events:', hasPermission('create:events'));
+
+  return (
+    <div>
+      <h3>Permission Debug Info</h3>
+      <p>User: {user?.email}</p>
+      <p>Roles: {roles.map(r => r.name).join(', ')}</p>
+      <p>Permissions: {permissions.map(p => p.name).join(', ')}</p>
+    </div>
+  );
+}
+```
+
+### 2. Page Permission Not Working
+
+**Problem**: Page-level permissions are not being enforced.
+
+**Solution**:
+
+```typescript
+import { usePagePermission } from '@jmruthers/pace-core';
+
+function ProtectedPage() {
+  const { hasAccess, loading, error } = usePagePermission('admin');
+
+  if (loading) {
+    return <div>Checking permissions...</div>;
+  }
+
+  if (error) {
+    console.error('Permission error:', error);
+    return <div>Error checking permissions</div>;
+  }
+
+  if (!hasAccess) {
+    return <div>Access denied</div>;
+  }
+
+  return <AdminDashboard />;
+}
+```
+
+### 3. Organisation Context Missing
+
+**Problem**: Organisation-based permissions are not working.
+
+**Solution**:
+
+```typescript
+import { useOrganisation } from '@jmruthers/pace-core';
+
+function OrganisationAwareComponent() {
+  const { currentOrganisation, loading, error } = useOrganisation();
+
+  if (loading) {
+    return <div>Loading organisation...</div>;
+  }
+
+  if (error) {
+    console.error('Organisation error:', error);
+    return <div>Error loading organisation</div>;
+  }
+
+  if (!currentOrganisation) {
+    return <div>Please select an organisation</div>;
+  }
+
+  return (
+    <div>
+      <h1>{currentOrganisation.name}</h1>
+      {/* Your component content */}
+    </div>
+  );
+}
+```
+
+### 4. Organisation Context Timing Issue (v0.3.44+ Fixed)
+
+**Problem**: RLS policies failing on first load, super admin permissions returning false, or database queries not filtering by organisation.
+
+**Root Cause**: Race condition where database organisation context wasn't set before other components tried to make queries.
+
+**Solution**: This issue was fixed in v0.3.44+. The `OrganisationProvider` now:
+
+1. **Sets database context before rendering children**
+2. **Shows loading states during context setup**
+3. **Prevents race conditions with database queries**
+
+If you're still experiencing this issue:
+
+```typescript
+// ✅ Ensure proper provider hierarchy
+<UnifiedAuthProvider supabaseClient={supabase} appName="my-app">
+  <OrganisationProvider>  {/* This now handles context timing automatically */}
+    <EventProvider>
+      <YourAppContent />
+    </EventProvider>
+  </OrganisationProvider>
+</UnifiedAuthProvider>
+```
+
+**For v0.3.43 and earlier**: You may need to implement a local workaround:
+
+```typescript
+// Temporary workaround for older versions
+function OrganisationContextGuard({ children }: { children: React.ReactNode }) {
+  const { selectedOrganisation } = useOrganisation();
+  const { supabase } = useUnifiedAuth();
+  const [contextReady, setContextReady] = useState(false);
+
+  useEffect(() => {
+    if (selectedOrganisation && supabase) {
+      setOrganisationContext(supabase, selectedOrganisation.id)
+        .then(() => setContextReady(true))
+        .catch(console.error);
+    }
+  }, [selectedOrganisation, supabase]);
+
+  if (!contextReady) {
+    return <div>Setting up organisation context...</div>;
+  }
+
+  return <>{children}</>;
+}
+```
+
+**Detailed Setup**: If you're getting "unrecognized configuration parameter" errors, see the [Organisation Context Setup Guide](./organisation-context-setup.md) for complete database setup instructions.
+
+## Styling Issues
+
+### 1. App Looks Unstyled (Raw HTML)
+
+**Problem**: App appears with default browser styling only - no colors, fonts, or proper layout.
+
+**Symptoms**:
+- Default browser styling only
+- No colors, fonts, or layout
+- Components look like plain HTML
+- Header is squashed or too wide
+- Main container stretches full width
+- Missing colored background
+
+**Solution**:
+
+**CRITICAL**: Use the `PaceAppLayout` component - don't just import CSS files:
+
+```tsx
+// ❌ Wrong - just CSS imports
+import '@jmruthers/pace-core/styles/core.css';
+
+function App() {
+  return (
+    <div>
+      <h1>My App</h1>
+      {/* This won't be styled properly */}
+    </div>
+  );
+}
+
+// ✅ Correct - use PaceAppLayout
+import { PaceAppLayout } from '@jmruthers/pace-core';
+import './app.css'; // Your app's color palette (must come first)
+import '@jmruthers/pace-core/styles/core.css';
+
+function App() {
+  return (
+    <PaceAppLayout appName="My Application">
+      <div className="container mx-auto px-4 py-6">
+        <h1 className="text-3xl font-bold text-main-900">My App</h1>
+        <p className="text-main-700">This will be properly styled</p>
+      </div>
+    </PaceAppLayout>
+  );
+}
+```
+
+**Common Causes**:
+- Missing CSS imports
+- Wrong build tool configuration (using Tailwind v3 instead of v4)
+- Not using PaceAppLayout component
+- Missing app.css with color palette
+- CSS files not being processed
+
+**Build Tool Configuration**:
+
+**For Vite (Recommended):**
+```js
+// vite.config.js
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+import tailwindcss from '@tailwindcss/vite'
+
+export default defineConfig({
+  plugins: [
+    react(),
+    tailwindcss() // Tailwind v4 - no config file needed!
+  ],
+})
+```
+
+**Dependencies:**
+```bash
+npm install -D @tailwindcss/vite tailwindcss@^4.0.0
+# Remove old Tailwind v3 if installed
+npm uninstall tailwindcss@^3.0.0
+```
+
+**Create app.css with Color Palette:**
+```css
+/* app.css - Your app's color palette */
+@theme static {
+  /* MAIN palette - your primary brand color */
+  --color-main-raw: oklch(0.7 0.057 252.02);
+  --color-main-50: oklch(0.98 0.001 252.02);
+  --color-main-100: oklch(0.96 0.005 252.02);
+  --color-main-200: oklch(0.927 0.012 252.02);
+  --color-main-300: oklch(0.881 0.021 252.02);
+  --color-main-400: oklch(0.822 0.032 252.02);
+  --color-main-500: oklch(0.75 0.047 252.02);
+  --color-main-600: oklch(0.7 0.057 252.02);
+  --color-main-700: oklch(0.567 0.044 252.02);
+  --color-main-800: oklch(0.456 0.034 252.02);
+  --color-main-900: oklch(0.332 0.024 252.02);
+  --color-main-950: oklch(0.195 0.014 252.02);
+
+  /* SEC palette - your secondary brand color */
+  --color-sec-raw: oklch(0.58 0.23 280.75);
+  --color-sec-50: oklch(0.98 0.003 280.75);
+  --color-sec-100: oklch(0.96 0.014 280.75);
+  --color-sec-200: oklch(0.927 0.033 280.75);
+  --color-sec-300: oklch(0.881 0.059 280.75);
+  --color-sec-400: oklch(0.822 0.093 280.75);
+  --color-sec-500: oklch(0.75 0.133 280.75);
+  --color-sec-600: oklch(0.665 0.182 280.75);
+  --color-sec-700: oklch(0.58 0.23 280.75);
+  --color-sec-800: oklch(0.456 0.158 280.75);
+  --color-sec-900: oklch(0.332 0.099 280.75);
+  --color-sec-950: oklch(0.195 0.047 280.75);
+
+  /* ACC palette - your accent brand color */
+  --color-acc-raw: oklch(0.64 0.21 37.76);
+  --color-acc-50: oklch(0.98 0.003 37.76);
+  --color-acc-100: oklch(0.96 0.015 37.76);
+  --color-acc-200: oklch(0.927 0.035 37.76);
+  --color-acc-300: oklch(0.881 0.063 37.76);
+  --color-acc-400: oklch(0.822 0.099 37.76);
+  --color-acc-500: oklch(0.75 0.143 37.76);
+  --color-acc-600: oklch(0.64 0.21 37.76);
+  --color-acc-700: oklch(0.567 0.177 37.76);
+  --color-acc-800: oklch(0.456 0.13 37.76);
+  --color-acc-900: oklch(0.332 0.085 37.76);
+  --color-acc-950: oklch(0.195 0.044 37.76);
+}
+```
+
+**Debugging Steps**:
+1. Check Browser DevTools for CSS import errors
+2. Verify pace-core CSS files are loading in Network tab
+3. Inspect elements to see if Tailwind classes are applied
+4. Ensure Tailwind v4 is installed and configured
+5. Test CSS imports with temporary rule: `body { background-color: red !important; }`
+
+**Quick Checklist**:
+- [ ] CSS files imported in main.tsx/App.tsx
+- [ ] app.css created with color palette
+- [ ] Using PaceAppLayout component
+- [ ] Tailwind v4 configured in build tool
+- [ ] No custom CSS overriding pace-core styles
+- [ ] All required dependencies installed
+- [ ] No build errors in console
+
+### 2. App Looks Different from Demo (v0.3.47+ Fixed)
+
+**Problem**: Your consuming app looks different from the PACE Core demo app
+
+**Symptoms**:
+- Different background colors (gray instead of blue)
+- Different text colors
+- Overall different visual appearance
+
+**Root Cause**: The demo app uses a custom CSS configuration, while consuming apps use our theme file. The theme file was using neutral gray colors instead of the blue-tinted scheme from the demo.
+
+**Solution**: This issue was fixed in v0.3.47+. The theme file now uses the same blue-tinted color scheme as the demo app:
+
+- **Background**: Very light blue (`--color-primary-50`)
+- **Foreground**: Very dark blue (`--color-primary-950`)
+- **Primary**: Blue (`--color-primary-600`)
+- **Borders**: Blue (`--color-primary-500`)
+- **Inputs**: Light purple (`--color-secondary-200`)
+
+**Quick Fix**:
+```bash
+npm install @jmruthers/pace-core@latest
+```
+
+### 2. Header Layout Issues (v0.3.48+ Fixed)
+
+**Problem**: Header elements are stacked vertically instead of being aligned horizontally across the page
+
+**Symptoms**:
+- Logo, navigation, and user menu are stacked vertically
+- Header doesn't use the full width properly
+- Layout looks broken compared to demo app
+
+**Root Cause**: Missing CSS variables that the header component depends on:
+- `--app-width` (for container width)
+- `--color-main-*` (for header background colors)
+- `--color-sec-*` and `--color-acc-*` (for other header elements)
+
+**Solution**: This issue was fixed in v0.3.48+. The theme file now includes all required CSS variables:
+
+- **Layout Variables**: `--app-width: 90rem`
+- **App Color Variables**: `--color-main-*`, `--color-sec-*`, `--color-acc-*`
+- **Complete Color Palette**: All color variants (50, 100, 200, etc.) plus `-raw` variants
+
+**Quick Fix**:
+```bash
+npm install @jmruthers/pace-core@latest
+```
+
+### 3. Missing CSS Variables (v0.3.49+ Fixed)
+
+**Problem**: Components not rendering correctly due to missing CSS variables
+
+**Symptoms**:
+- Components appear unstyled or broken
+- Console errors about undefined CSS variables
+- Inconsistent appearance across different components
+- DataTable examples not working properly
+
+**Root Cause**: The theme file was missing many CSS variables that components depend on:
+- Font variables (--font-sans, --font-serif, --font-mono)
+- Design tokens (--pace-* variables)
+- Event colors (--color-ev-* variables)
+- Radix UI variables (--radix-toast-*)
+
+**Solution**: This issue was fixed in v0.3.49+. The theme file now includes comprehensive variable coverage:
+
+- **Font Variables**: All typography variables for consistent fonts
+- **Design Tokens**: Complete PACE Core design token system
+- **Event Colors**: Full color palette for DataTable examples
+- **Component Variables**: All variables needed for component styling
+- **Radix UI Variables**: Third-party component library compatibility
+
+**Quick Fix**:
+```bash
+npm install @jmruthers/pace-core@latest
+```
+
+### 4. Login Page Styling Issues (v0.4.4+ Fixed)
+
+**Problem**: Login page looks different from the pace-core demo - unstyled button, wrong background, missing shadows.
+
+**Symptoms**:
+- Button appears as plain text instead of styled button
+- Background is white instead of gradient
+- Card has no shadow or wrong styling
+- Input fields are dark instead of white
+- Overall appearance doesn't match the demo
+
+**Root Cause**: Missing theme mappings in `styles/core.css` prevented CSS variables from being processed correctly by Tailwind v4.
+
+**Solution**: This issue was fixed in v0.4.4+. The theme file now includes complete mappings for all color palettes.
+
+**Quick Fix**:
+```bash
+npm install @jmruthers/pace-core@latest
+```
+
+**Required Setup** (must be exactly like this):
+
+1. **CSS Imports** (in your main.tsx):
+```tsx
+import './app.css'; // Your app's palette definitions (must come first)
+import '@jmruthers/pace-core/styles/core.css';
+```
+
+2. **App.css** (complete palette required):
+```css
+@theme static {
+  /* MAIN palette - your primary brand color */
+  --color-main-50: oklch(0.98 0.001 252.02);
+  --color-main-100: oklch(0.96 0.005 252.02);
+  /* ... all shades 50-950 + raw */
+  
+  /* SEC palette - your secondary brand color */
+  --color-sec-50: oklch(0.98 0.003 280.75);
+  /* ... all shades 50-950 + raw */
+  
+  /* ACC palette - your accent brand color */
+  --color-acc-50: oklch(0.98 0.003 37.76);
+  /* ... all shades 50-950 + raw */
+}
+
+@layer base {
+  .appGradient {
+    background: radial-gradient(var(--color-main-200), oklch(from var(--color-main-200) l c h / 0%) 30%), 
+                conic-gradient(var(--color-main-200), var(--color-sec-200), var(--color-acc-200), var(--color-main-200));
+    background-attachment: fixed;
+  }
+}
+```
+
+3. **HTML Structure** (in your index.html):
+```html
+<body class="appGradient">
+  <div id="root" class="grid grid-rows-[auto_1fr_auto] min-h-screen"></div>
+</body>
+```
+
+4. **Vite Configuration** (Tailwind v4 required):
+```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() // Tailwind v4 - no config file needed!
+  ],
+});
+```
+
+**Debugging Steps**:
+1. Check browser dev tools for CSS import errors
+2. Verify `bg-main-600` class resolves to actual color value
+3. Ensure all CSS files are imported in correct order
+4. Confirm Tailwind v4 is installed (not v3)
+5. Test with minimal setup to isolate the issue
+
+### 5. Tailwind v4 Theme File Issues (v0.3.45+ Fixed)
+
+**Problem**: Build failures when using `@import '@jmruthers/pace-core/styles/core.css'`
+
+**Root Cause**: The theme file was missing semantic colors and had circular references in component classes.
+
+**Solution**: This issue was fixed in v0.3.45+. The theme file now includes:
+
+- **Complete semantic colors** (ring, border, background, foreground, etc.)
+- **Fixed component classes** (no circular @apply references)
+- **All required Tailwind v4 colors**
+
+**Quick Fix**:
+```bash
+npm install @jmruthers/pace-core@latest
+```
+
+**Usage**:
+```css
+/* index.css */
+@import '@jmruthers/pace-core/styles/core.css';
+```
+
+**Vite Configuration**:
+```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() // ✅ Simple - theme is in CSS
+  ],
+});
+```
+
+### 2. Missing Semantic Colors
+
+**Problem**: Colors like `ring-ring`, `border`, `background` not working
+
+**Solution**: The theme file now includes all semantic colors:
+
+```css
+/* These are now included in the theme file */
+--color-ring: var(--color-primary-600);
+--color-border: var(--color-neutral-300);
+--color-background: var(--color-neutral-50);
+--color-foreground: var(--color-neutral-950);
+/* ... and more */
+```
+
+### 3. Component Classes Not Working
+
+**Problem**: `.pace-button`, `.pace-input` classes not applying styles
+
+**Solution**: Component classes are now self-contained:
+
+```css
+/* ✅ Fixed - no circular references */
+.pace-button-primary {
+  @apply inline-flex items-center justify-center rounded-md text-sm font-medium transition-colors focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-ring focus-visible:ring-offset-2 disabled:opacity-50 disabled:pointer-events-none ring-offset-background bg-primary-600 text-main-50 hover:bg-primary-700 active:bg-primary-800;
+}
+```
+
+## Event Management Issues
+
+### 1. Events Not Loading
+
+**Problem**: Events are not being fetched or displayed.
+
+**Solution**:
+
+```typescript
+import { useEvents } from '@jmruthers/pace-core';
+
+function EventList() {
+  const { events, loading, error, refreshEvents } = useEvents();
+
+  if (loading) {
+    return <div>Loading events...</div>;
+  }
+
+  if (error) {
+    console.error('Events error:', error);
+    return (
+      <div>
+        <div>Error loading events: {error}</div>
+        <button onClick={refreshEvents}>Retry</button>
+      </div>
+    );
+  }
+
+  if (!events || events.length === 0) {
+    return <div>No events found</div>;
+  }
+
+  return (
+    <div>
+      {events.map(event => (
+        <div key={event.id}>
+          <h3>{event.name}</h3>
+          <p>{event.description}</p>
+        </div>
+      ))}
+    </div>
+  );
+}
+```
+
+### 2. Event Selection Not Working
+
+**Problem**: Users can't select events or the selection is not persisting.
+
+**Solution**:
+
+```typescript
+import { useEvents } from '@jmruthers/pace-core';
+
+function EventSelector() {
+  const { events, selectedEvent, setSelectedEvent, hasAccess } = useEvents();
+
+  const handleEventSelect = (event) => {
+    if (hasAccess(event.id)) {
+      setSelectedEvent(event);
+    } else {
+      console.warn('User does not have access to this event');
+    }
+  };
+
+  return (
+    <div>
+      <h2>Select Event</h2>
+      {events.map(event => (
+        <div key={event.id}>
+          <span>{event.name}</span>
+          {hasAccess(event.id) ? (
+            <button onClick={() => handleEventSelect(event)}>
+              {selectedEvent?.id === event.id ? 'Selected' : 'Select'}
+            </button>
+          ) : (
+            <span>No access</span>
+          )}
+        </div>
+      ))}
+    </div>
+  );
+}
+```
+
+## Form Issues
+
+### 1. Form Validation Not Working
+
+**Problem**: Form validation is not triggering or showing errors.
+
+**Solution**:
+
+```typescript
+import { useZodForm } from '@jmruthers/pace-core';
+import { z } from 'zod';
+
+const schema = z.object({
+  name: z.string().min(1, 'Name is required'),
+  email: z.string().email('Invalid email'),
+});
+
+function UserForm() {
+  const {
+    register,
+    handleSubmit,
+    formState: { errors, isSubmitting },
+    reset,
+  } = useZodForm(schema);
+
+  const onSubmit = async (data) => {
+    try {
+      await createUser(data);
+      reset();
+    } catch (error) {
+      console.error('Form submission error:', error);
+    }
+  };
+
+  return (
+    <form onSubmit={handleSubmit(onSubmit)}>
+      <div>
+        <input {...register('name')} placeholder="Name" />
+        {errors.name && <span className="error">{errors.name.message}</span>}
+      </div>
+      
+      <div>
+        <input type="email" {...register('email')} placeholder="Email" />
+        {errors.email && <span className="error">{errors.email.message}</span>}
+      </div>
+      
+      <button type="submit" disabled={isSubmitting}>
+        {isSubmitting ? 'Submitting...' : 'Submit'}
+      </button>
+    </form>
+  );
+}
+```
+
+### 2. Form Data Not Saving
+
+**Problem**: Form data is not being saved to the database.
+
+**Solution**:
+
+```typescript
+import { useZodForm } from '@jmruthers/pace-core';
+import { useSupabase } from '@jmruthers/pace-core';
+
+function UserForm() {
+  const { supabase } = useSupabase();
+  const { currentOrganisation } = useOrganisation();
+
+  const onSubmit = async (data) => {
+    try {
+      const { error } = await supabase
+        .from('users')
+        .insert({
+          ...data,
+          organisation_id: currentOrganisation.id,
+        });
+
+      if (error) {
+        console.error('Database error:', error);
+        throw error;
+      }
+
+      console.log('User created successfully');
+    } catch (error) {
+      console.error('Form submission error:', error);
+    }
+  };
+
+  // ... rest of form component
+}
+```
+
+## Component Issues
+
+### 1. Components Not Rendering
+
+**Problem**: Components are not rendering or showing blank content.
+
+**Solution**:
+
+```typescript
+import { ErrorBoundary } from '@jmruthers/pace-core';
+
+function App() {
+  return (
+    <ErrorBoundary fallback={<div>Something went wrong</div>}>
+      <YourComponents />
+    </ErrorBoundary>
+  );
+}
+```
+
+### 2. Styling Issues
+
+**Problem**: Components are not styled correctly or styles are missing.
+
+**Solution**:
+
+```typescript
+// Ensure Tailwind CSS is imported
+// Import the core CSS file
+import './app.css'; // Your app's color palette (must come first)
+import '@jmruthers/pace-core/styles/core.css';
+
+// Check if your app is properly set up
+function App() {
+  return (
+    <div>
+      <YourApp />
+    </div>
+  );
+}
+```
+
+### 3. Component Props Issues
+
+**Problem**: Components are not receiving the correct props or props are undefined.
+
+**Solution**:
+
+```typescript
+import { Button } from '@jmruthers/pace-core';
+
+function MyComponent() {
+  // Always provide required props
+  return (
+    <Button 
+      variant="primary"
+      onClick={() => console.log('clicked')}
+    >
+      Click me
+    </Button>
+  );
+}
+```
+
+## Database Issues
+
+### 1. Database Connection Errors
+
+**Problem**: Cannot connect to Supabase database.
+
+**Solution**:
+
+```typescript
+import { createSupabaseClient } from '@jmruthers/pace-core';
+
+// Check environment variables
+const supabaseUrl = process.env.SUPABASE_URL;
+const supabaseKey = process.env.SUPABASE_ANON_KEY;
+
+if (!supabaseUrl || !supabaseKey) {
+  console.error('Missing Supabase environment variables');
+  throw new Error('Supabase configuration missing');
+}
+
+const supabase = createSupabaseClient(supabaseUrl, supabaseKey);
+
+// Test connection
+supabase.from('users').select('count').single()
+  .then(() => console.log('Database connected'))
+  .catch(error => console.error('Database connection failed:', error));
+```
+
+### 2. RLS Policy Issues
+
+**Problem**: Row Level Security policies are blocking legitimate access.
+
+**Solution**:
+
+```sql
+-- Check if RLS is enabled
+SELECT schemaname, tablename, rowsecurity 
+FROM pg_tables 
+WHERE tablename = 'your_table_name';
+
+-- Check policies
+SELECT * FROM pg_policies WHERE tablename = 'your_table_name';
+
+-- Test policy
+SELECT * FROM your_table_name WHERE organisation_id = 'your_org_id';
+```
+
+### 3. Data Not Filtered by Organisation
+
+**Problem**: Data is not being filtered by the current organisation.
+
+**Solution**:
+
+```typescript
+import { useOrganisation } from '@jmruthers/pace-core';
+import { useSupabase } from '@jmruthers/pace-core';
+
+function DataComponent() {
+  const { supabase } = useSupabase();
+  const { currentOrganisation } = useOrganisation();
+
+  const fetchData = async () => {
+    if (!currentOrganisation) {
+      console.warn('No organisation selected');
+      return;
+    }
+
+    const { data, error } = await supabase
+      .from('your_table')
+      .select('*')
+      .eq('organisation_id', currentOrganisation.id);
+
+    if (error) {
+      console.error('Database error:', error);
+      return;
+    }
+
+    console.log('Filtered data:', data);
+  };
+
+  return (
+    <div>
+      <button onClick={fetchData}>Load Data</button>
+    </div>
+  );
+}
+```
+
+## Performance Issues
+
+### 1. Slow Loading Times
+
+**Problem**: Components are taking too long to load.
+
+**Solution**:
+
+```typescript
+import { useMemo } from 'react';
+import { useEvents } from '@jmruthers/pace-core';
+
+function OptimizedEventList() {
+  const { events, loading } = useEvents();
+
+  // Memoize expensive calculations
+  const sortedEvents = useMemo(() => {
+    return events?.sort((a, b) => 
+      new Date(a.start_date).getTime() - new Date(b.start_date).getTime()
+    ) || [];
+  }, [events]);
+
+  if (loading) {
+    return <div>Loading events...</div>;
+  }
+
+  return (
+    <div>
+      {sortedEvents.map(event => (
+        <EventCard key={event.id} event={event} />
+      ))}
+    </div>
+  );
+}
+```
+
+### 2. Memory Leaks
+
+**Problem**: Memory usage is increasing over time.
+
+**Solution**:
+
+```typescript
+import { useEffect, useCallback } from 'react';
+import { useEvents } from '@jmruthers/pace-core';
+
+function EventManager() {
+  const { events, refreshEvents } = useEvents();
+
+  // Clean up on unmount
+  useEffect(() => {
+    return () => {
+      // Cleanup function
+      console.log('Component unmounting');
+    };
+  }, []);
+
+  // Memoize callbacks
+  const handleRefresh = useCallback(() => {
+    refreshEvents();
+  }, [refreshEvents]);
+
+  return (
+    <div>
+      <button onClick={handleRefresh}>Refresh Events</button>
+      {/* Event list */}
+    </div>
+  );
+}
+```
+
+## Network Issues
+
+### 1. API Request Failures
+
+**Problem**: API requests are failing with network errors.
+
+**Solution**:
+
+```typescript
+import { useUnifiedAuth } from '@jmruthers/pace-core';
+
+function NetworkAwareComponent() {
+  const { error } = useUnifiedAuth();
+
+  useEffect(() => {
+    if (error) {
+      console.error('Network error:', error);
+      
+      // Check if it's a network issue
+      if (error.message.includes('network') || error.message.includes('fetch')) {
+        console.log('Network connectivity issue detected');
+        // Implement retry logic or show offline message
+      }
+    }
+  }, [error]);
+
+  return (
+    <div>
+      {error && (
+        <div className="error">
+          <p>Connection error: {error.message}</p>
+          <button onClick={() => window.location.reload()}>
+            Retry
+          </button>
+        </div>
+      )}
+    </div>
+  );
+}
+```
+
+### 2. CORS Issues
+
+**Problem**: Getting CORS errors when making requests.
+
+**Solution**:
+
+```typescript
+// Check Supabase configuration
+const supabase = createSupabaseClient(
+  process.env.SUPABASE_URL!,
+  process.env.SUPABASE_ANON_KEY!,
+  {
+    auth: {
+      autoRefreshToken: true,
+      persistSession: true,
+      detectSessionInUrl: true,
+    },
+  }
+);
+```
+
+## Environment Issues
+
+### 1. Environment Variables Missing
+
+**Problem**: Application is failing due to missing environment variables.
+
+**Solution**:
+
+```typescript
+// Validate environment variables
+const requiredEnvVars = [
+  'SUPABASE_URL',
+  'SUPABASE_ANON_KEY',
+  'NODE_ENV',
+];
+
+requiredEnvVars.forEach(varName => {
+  if (!process.env[varName]) {
+    console.error(`Missing environment variable: ${varName}`);
+    throw new Error(`Missing required environment variable: ${varName}`);
+  }
+});
+
+console.log('Environment variables validated');
+```
+
+### 2. Development vs Production Issues
+
+**Problem**: Application works in development but not in production.
+
+**Solution**:
+
+```typescript
+// Environment-specific configuration
+const config = {
+  development: {
+    supabaseUrl: process.env.SUPABASE_URL,
+    supabaseKey: process.env.SUPABASE_ANON_KEY,
+    debug: true,
+  },
+  production: {
+    supabaseUrl: process.env.SUPABASE_URL,
+    supabaseKey: process.env.SUPABASE_ANON_KEY,
+    debug: false,
+  },
+};
+
+const currentConfig = config[process.env.NODE_ENV || 'development'];
+```
+
+## Debugging Tools
+
+### 1. Debug Component
+
+```typescript
+function DebugPanel() {
+  const { user, session } = useUnifiedAuth();
+  const { currentOrganisation } = useOrganisation();
+  const { events, selectedEvent } = useEvents();
+
+  return (
+    <div className="debug-panel">
+      <h3>Debug Information</h3>
+      <pre>
+        {JSON.stringify({
+          user: user?.email,
+          session: session?.expires_at,
+          organisation: currentOrganisation?.name,
+          events: events?.length,
+          selectedEvent: selectedEvent?.name,
+        }, null, 2)}
+      </pre>
+    </div>
+  );
+}
+```
+
+### 2. Error Boundary with Logging
+
+```typescript
+import { ErrorBoundary } from '@jmruthers/pace-core';
+
+function LoggingErrorBoundary({ children }) {
+  return (
+    <ErrorBoundary
+      fallback={<div>Something went wrong</div>}
+      onError={(error, errorInfo) => {
+        console.error('Error caught by boundary:', error);
+        console.error('Error info:', errorInfo);
+        
+        // Send to error reporting service
+        // reportError(error, errorInfo);
+      }}
+    >
+      {children}
+    </ErrorBoundary>
+  );
+}
+```
+
+## 🌐 Public Pages Issues
+
+### Public Pages Not Working
+
+**Problem**: Public pages show authentication errors or don't load properly
+
+**Root Cause**: Public pages are being rendered inside the authentication context
+
+**Solution**: Public pages MUST be completely separate from your main app
+
+```tsx
+// ❌ WRONG - This will break
+<UnifiedAuthProvider>
+  <Routes>
+    <Route path="/events/:eventCode" element={<PublicPage />} />
+  </Routes>
+</UnifiedAuthProvider>
+
+// ✅ CORRECT - Separate applications
+<BrowserRouter>
+  <Routes>
+    <Route path="/events/*" element={<PublicPageApp />} />
+    <Route path="/*" element={
+      <UnifiedAuthProvider>
+        <AuthenticatedApp />
+      </UnifiedAuthProvider>
+    } />
+  </Routes>
+</BrowserRouter>
+```
+
+**Complete Setup:**
+```tsx
+// PublicPageApp.tsx
+import { PublicPageProvider } from '@jmruthers/pace-core';
+
+export function PublicPageApp() {
+  return (
+    <PublicPageProvider>
+      <Routes>
+        <Route path="/events/:eventCode" element={<PublicEventPage />} />
+      </Routes>
+    </PublicPageProvider>
+  );
+}
+```
+
+### Public Page Hooks Not Working
+
+**Problem**: `usePublicEvent` or `usePublicRouteParams` return null/undefined
+
+**Root Cause**: Not using the hooks inside `PublicPageProvider`
+
+**Solution**: Ensure all public page components are wrapped in `PublicPageProvider`
+
+```tsx
+// ❌ WRONG - Hooks won't work
+function PublicPage() {
+  const { eventCode } = usePublicRouteParams(); // Returns null
+  // ...
+}
+
+// ✅ CORRECT - Hooks work properly
+<PublicPageProvider>
+  <PublicPage /> {/* Hooks work here */}
+</PublicPageProvider>
+```
+
+### Public Page Loading Forever
+
+**Problem**: Public pages show loading spinner indefinitely
+
+**Root Cause**: Event data not found or API errors
+
+**Solution**: Add proper error handling and fallbacks
+
+```tsx
+function PublicEventPage() {
+  const { eventCode } = usePublicRouteParams({ fetchEventData: false });
+  const { event, isLoading, error, refetch } = usePublicEvent(eventCode || '');
+  
+  // Handle loading
+  if (isLoading) {
+    return <PublicLoadingSpinner message="Loading event..." />;
+  }
+  
+  // Handle error
+  if (error) {
+    return (
+      <div className="min-h-screen bg-white flex items-center justify-center">
+        <div className="text-center">
+          <h1 className="text-2xl font-bold text-gray-900 mb-4">
+            Event Not Found
+          </h1>
+          <p className="text-gray-600 mb-6">
+            The event code "{eventCode}" is invalid or not available for public viewing.
+          </p>
+          <button
+            onClick={refetch}
+            className="px-4 py-2 bg-blue-600 text-white rounded-md hover:bg-blue-700"
+          >
+            Try Again
+          </button>
+        </div>
+      </div>
+    );
+  }
+  
+  // Handle missing event
+  if (!event) {
+    return <div>Event not found</div>;
+  }
+  
+  // Render the page
+  return (
+    <PublicPageLayout eventCode={eventCode || ''} event={event}>
+      {/* Your content */}
+    </PublicPageLayout>
+  );
+}
+```
+
+### Public Page Styling Issues
+
+**Problem**: Public pages appear unstyled or broken
+
+**Root Cause**: Missing CSS import or Tailwind configuration
+
+**Solution**: Ensure CSS is imported and Tailwind is configured
+
+```tsx
+// Make sure to import CSS
+import '@jmruthers/pace-core/styles/core.css';
+
+// And configure Tailwind properly
+// 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}'
+      ]
+    })
+  ],
+})
+```
+
+### Public Page Environment Variables
+
+**Problem**: Public pages can't access Supabase or environment variables
+
+**Root Cause**: Missing environment variables or incorrect configuration
+
+**Solution**: Set up environment variables and pass them to `PublicPageProvider`
+
+```tsx
+// .env.local
+VITE_SUPABASE_URL=your_supabase_url
+VITE_SUPABASE_ANON_KEY=your_supabase_anon_key
+VITE_APP_NAME=Your App Name
+
+// PublicPageApp.tsx
+import { PublicPageProvider } from '@jmruthers/pace-core';
+
+export function PublicPageApp() {
+  return (
+    <PublicPageProvider
+      environment={{
+        supabaseUrl: import.meta.env.VITE_SUPABASE_URL,
+        supabaseKey: import.meta.env.VITE_SUPABASE_ANON_KEY,
+      }}
+    >
+      <Routes>
+        <Route path="/events/:eventCode" element={<PublicEventPage />} />
+      </Routes>
+    </PublicPageProvider>
+  );
+}
+```
+
+### Public Page "process is not defined" Error
+
+**Problem**: `ReferenceError: process is not defined` when using `PublicPageProvider` in Vite-based applications
+
+**Root Cause**: The component is trying to access Node.js globals (`process`) that aren't available in browser environments
+
+**Solution**: This has been fixed in pace-core v0.4.61+. The `PublicPageProvider` now safely handles both browser and Node.js environments.
+
+**If you're still seeing this error:**
+
+1. **Update pace-core** to the latest version:
+   ```bash
+   npm update @jmruthers/pace-core
+   ```
+
+2. **Verify your Vite configuration** includes environment variable support:
+   ```ts
+   // vite.config.ts
+   export default defineConfig({
+     plugins: [react(), tailwindcss()],
+     envDir: '.', // Look for .env files in root
+     envPrefix: 'VITE_', // Only load VITE_ prefixed variables
+   })
+   ```
+
+3. **Set up environment variables** in your `.env` file:
+   ```bash
+   # .env.local
+   VITE_SUPABASE_URL=your_supabase_url
+   VITE_SUPABASE_ANON_KEY=your_supabase_anon_key
+   ```
+
+4. **Use the correct environment variable names**:
+   - ✅ `VITE_SUPABASE_URL` (Vite)
+   - ✅ `NEXT_PUBLIC_SUPABASE_URL` (Next.js)
+   - ❌ `SUPABASE_URL` (not prefixed for Vite)
+
+**The fix ensures:**
+- ✅ Safe access to `import.meta.env` (Vite/browser)
+- ✅ Safe access to `process.env` (Node.js/server)
+- ✅ Proper fallback handling
+- ✅ No "process is not defined" errors
+
+### Public Page Database Access
+
+**Problem**: Public pages can't access event data from database
+
+**Root Cause**: Missing RLS policies or incorrect database setup
+
+**Solution**: Set up proper RLS policies for public access
+
+```sql
+-- Enable RLS on events table
+ALTER TABLE events ENABLE ROW LEVEL SECURITY;
+
+-- Create policy for public events
+CREATE POLICY "Public events are viewable by anyone" ON events
+  FOR SELECT USING (is_public = true);
+
+-- Or allow specific event codes
+CREATE POLICY "Specific event codes are public" ON events
+  FOR SELECT USING (event_code IN ('EVENT123', 'EVENT456'));
+```
+
+## Getting Help
+
+If you're still experiencing issues:
+
+1. **Check the console** for error messages
+2. **Verify your configuration** (environment variables, Supabase setup)
+3. **Test with minimal setup** to isolate the issue
+4. **Check the documentation** for specific component usage
+5. **Search existing issues** in the GitHub repository
+6. **Create a new issue** with detailed information about your problem
+
+When reporting an issue, include:
+
+- **Environment**: Node.js version, package versions
+- **Steps to reproduce**: Clear steps to recreate the issue
+- **Expected behavior**: What you expected to happen
+- **Actual behavior**: What actually happened
+- **Error messages**: Full error messages from console
+- **Code example**: Minimal code that reproduces the issue
+
+For more specific troubleshooting, see the [Debugging Guide](./debugging.md).