@jmruthers/pace-core 0.2.4

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

@@ -0,0 +1,277 @@
+# Organisation Context Setup Troubleshooting
+
+This guide helps you resolve the `unrecognized configuration parameter "app.organisation_id"` error that occurs when using PACE Core with Supabase.
+
+## 🚨 The Error
+
+```
+Error loading units: unrecognized configuration parameter "app.organisation_id"
+```
+
+**Console Error:**
+```
+Supabase error fetching units: Object { 
+  code: "42704", 
+  details: null, 
+  hint: null, 
+  message: 'unrecognized configuration parameter "app.organisation_id"' 
+}
+```
+
+## 🔍 Root Cause
+
+This error occurs when:
+1. The Supabase database doesn't have the `set_organisation_context` function
+2. The `app.organisation_id` configuration parameter isn't available
+3. The organisation context isn't being set before making database queries
+
+## ✅ Solution: Database Setup
+
+### Step 1: Create the Organisation Context Functions
+
+Run this SQL in your Supabase SQL Editor:
+
+```sql
+-- Create the organisation context functions
+CREATE OR REPLACE FUNCTION set_organisation_context(organisation_id UUID)
+RETURNS void
+LANGUAGE plpgsql
+SECURITY DEFINER
+AS $$
+BEGIN
+  -- Set the organisation context for the current session
+  PERFORM set_config('app.organisation_id', organisation_id::text, true);
+END;
+$$;
+
+CREATE OR REPLACE FUNCTION clear_organisation_context()
+RETURNS void
+LANGUAGE plpgsql
+SECURITY DEFINER
+AS $$
+BEGIN
+  -- Clear the organisation context
+  PERFORM set_config('app.organisation_id', NULL, true);
+END;
+$$;
+
+CREATE OR REPLACE FUNCTION get_organisation_context()
+RETURNS UUID
+LANGUAGE plpgsql
+SECURITY DEFINER
+AS $$
+BEGIN
+  -- Get the current organisation context
+  RETURN COALESCE(current_setting('app.organisation_id', true)::UUID, NULL);
+END;
+$$;
+
+CREATE OR REPLACE FUNCTION check_organisation_access(organisation_id UUID)
+RETURNS BOOLEAN
+LANGUAGE plpgsql
+SECURITY DEFINER
+AS $$
+DECLARE
+  current_org_id UUID;
+  user_id UUID;
+BEGIN
+  -- Get current user and organisation context
+  user_id := auth.uid();
+  current_org_id := get_organisation_context();
+  
+  -- Super admin check (if you have a super_admin role)
+  IF EXISTS (
+    SELECT 1 FROM user_profiles 
+    WHERE id = user_id AND role = 'super_admin'
+  ) THEN
+    RETURN TRUE;
+  END IF;
+  
+  -- Check if user has access to the organisation
+  RETURN EXISTS (
+    SELECT 1 FROM user_profiles 
+    WHERE id = user_id 
+    AND (organisation_id = current_org_id OR current_org_id IS NULL)
+  );
+END;
+$$;
+```
+
+### Step 2: Update Your RLS Policies
+
+Make sure your RLS policies use the organisation context:
+
+```sql
+-- Example: Update your units table RLS policy
+CREATE POLICY "Users can view units for their organisation" ON units
+FOR SELECT USING (
+  check_organisation_access(organisation_id)
+);
+
+-- Example: Update your events table RLS policy  
+CREATE POLICY "Users can view events for their organisation" ON events
+FOR SELECT USING (
+  check_organisation_access(organisation_id)
+);
+```
+
+### Step 3: Verify the Functions Work
+
+Test the functions in your Supabase SQL Editor:
+
+```sql
+-- Test setting organisation context
+SELECT set_organisation_context('your-organisation-id-here');
+
+-- Test getting organisation context
+SELECT get_organisation_context();
+
+-- Test organisation access check
+SELECT check_organisation_access('your-organisation-id-here');
+```
+
+## 🔧 Application Setup
+
+### Step 1: Ensure Proper Provider Setup
+
+Make sure your app is wrapped with the required providers:
+
+```tsx
+// App.tsx
+import { UnifiedAuthProvider, OrganisationProvider } from '@jmruthers/pace-core';
+
+function App() {
+  return (
+    <UnifiedAuthProvider supabaseClient={supabase} appName="my-app">
+      <OrganisationProvider>
+        <YourAppContent />
+      </OrganisationProvider>
+    </UnifiedAuthProvider>
+  );
+}
+```
+
+### Step 2: Check Organisation Selection
+
+Make sure users can select an organisation:
+
+```tsx
+// components/OrganisationSelector.tsx
+import { useOrganisation } from '@jmruthers/pace-core';
+
+function OrganisationSelector() {
+  const { organisation, switchOrganisation, organisations } = useOrganisation();
+
+  return (
+    <select 
+      value={organisation?.id || ''} 
+      onChange={(e) => switchOrganisation(e.target.value)}
+    >
+      <option value="">Select Organisation</option>
+      {organisations.map(org => (
+        <option key={org.id} value={org.id}>
+          {org.name}
+        </option>
+      ))}
+    </select>
+  );
+}
+```
+
+### Step 3: Verify Database Context is Set
+
+Add debugging to see if the context is being set:
+
+```tsx
+// components/DebugOrganisationContext.tsx
+import { useOrganisation } from '@jmruthers/pace-core';
+import { useEffect } from 'react';
+
+function DebugOrganisationContext() {
+  const { organisation } = useOrganisation();
+
+  useEffect(() => {
+    if (organisation) {
+      console.log('Current organisation:', organisation);
+      // The OrganisationProvider should automatically call set_organisation_context
+    }
+  }, [organisation]);
+
+  return null;
+}
+```
+
+## 🧪 Testing the Fix
+
+### Step 1: Check Database Functions
+
+Run this query in Supabase to verify the functions exist:
+
+```sql
+SELECT routine_name 
+FROM information_schema.routines 
+WHERE routine_name IN (
+  'set_organisation_context', 
+  'get_organisation_context', 
+  'check_organisation_access'
+);
+```
+
+### Step 2: Test Organisation Context
+
+```sql
+-- Set context
+SELECT set_organisation_context('your-org-id');
+
+-- Check if it's set
+SELECT current_setting('app.organisation_id', true);
+
+-- Test access check
+SELECT check_organisation_access('your-org-id');
+```
+
+### Step 3: Check RLS Policies
+
+```sql
+-- Check if your tables have RLS enabled
+SELECT schemaname, tablename, rowsecurity 
+FROM pg_tables 
+WHERE tablename IN ('units', 'events', 'user_profiles');
+
+-- Check RLS policies
+SELECT schemaname, tablename, policyname, permissive, roles, cmd, qual
+FROM pg_policies 
+WHERE tablename IN ('units', 'events');
+```
+
+## 🚨 Common Issues
+
+### Issue 1: Functions Don't Exist
+**Solution**: Run the SQL functions creation script above.
+
+### Issue 2: RLS Policies Not Updated
+**Solution**: Update your RLS policies to use `check_organisation_access(organisation_id)`.
+
+### Issue 3: Organisation Not Selected
+**Solution**: Make sure users can select an organisation before making queries.
+
+### Issue 4: Super Admin Not Working
+**Solution**: Make sure your `user_profiles` table has a `role` column with `super_admin` values.
+
+## 📚 Related Documentation
+
+- **[RBAC Setup Guide](../rbac/getting-started.md)** - Complete RBAC setup
+- **[Organisation Management](../core-concepts/organisations.md)** - Organisation concepts
+- **[Common Issues](./common-issues.md)** - Other troubleshooting topics
+
+## 🆘 Still Having Issues?
+
+If you're still experiencing problems:
+
+1. **Check the Supabase logs** in your project dashboard
+2. **Verify your database schema** matches the expected structure
+3. **Test the functions individually** in the SQL editor
+4. **Check your RLS policies** are correctly configured
+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.

package/docs/troubleshooting/react-hooks-issue-analysis.md

@@ -0,0 +1,166 @@
+# React Hooks Issue Analysis - pace-cake Team
+
+## 🐛 Issue Summary
+**Error**: "Rendered more hooks than during the previous render" in MenuModal component when using DataTable from pace-core.
+
+## 🔍 Root Cause Analysis
+
+### ✅ **pace-core DataTable is Clean**
+After thorough analysis of the pace-core DataTable component and related hooks, I can confirm that **this is NOT a bug in pace-core**. The DataTable component follows proper React hooks rules:
+
+- **No early returns** before hooks
+- **No conditional hooks** - all hooks are called unconditionally  
+- **Consistent hook order** - hooks are always called in the same sequence
+- **Proper hook dependencies** - all hooks have stable dependencies
+
+### ❌ **The Problem is in pace-cake's Pattern**
+
+The consuming app is using this **problematic pattern**:
+
+```typescript
+// ❌ WRONG - Early return before hooks
+export const MenuModal = ({ isOpen, onClose, unit, eventId }: MenuModalProps) => {
+  // This early return causes the hooks error
+  if (!isOpen || !unit?.unit_id || !eventId) {
+    return null;
+  }
+
+  const { selectedOrganisation } = useOrganisations(); // Hook called after early return
+  const { mealplans, isLoading, ... } = useMealplanData(unit.unit_id, eventId);
+  
+  return <DataTable ... />;
+};
+```
+
+## 🚨 **Why This Causes the Error**
+
+1. **First render**: `isOpen = false` → early return → **0 hooks called**
+2. **Second render**: `isOpen = true` → no early return → **2+ hooks called**  
+3. **React detects**: "Rendered more hooks than during the previous render" ❌
+
+This violates the fundamental React hooks rule: **hooks must always be called in the same order on every render**.
+
+## ✅ **The Correct Pattern**
+
+```typescript
+// ✅ CORRECT - Hooks before any conditional logic
+export const MenuModal = ({ isOpen, onClose, unit, eventId }: MenuModalProps) => {
+  // Always call hooks first, regardless of conditions
+  const { selectedOrganisation } = useOrganisations();
+  const { mealplans, isLoading, ... } = useMealplanData(unit?.unit_id, eventId);
+  
+  // Then do conditional rendering
+  if (!isOpen || !unit?.unit_id || !eventId) {
+    return null;
+  }
+  
+  return (
+    <Dialog open={isOpen} onOpenChange={onClose}>
+      <DialogContent>
+        <DataTable
+          data={mealplans}
+          columns={columns}
+          // ... other props
+        />
+      </DialogContent>
+    </Dialog>
+  );
+};
+```
+
+## 🛠️ **Alternative Solutions**
+
+### **Option 1: Conditional Hook Parameters**
+```typescript
+// Pass safe defaults to hooks
+const { mealplans, isLoading } = useMealplanData(
+  unit?.unit_id || '', 
+  eventId || ''
+);
+
+// Handle empty data in the hook or component
+if (!unit?.unit_id || !eventId) {
+  return null;
+}
+```
+
+### **Option 2: Wrapper Component Pattern**
+```typescript
+const MenuModalContent = ({ unit, eventId, onClose }) => {
+  // All hooks here - no early returns
+  const { selectedOrganisation } = useOrganisations();
+  const { mealplans, isLoading } = useMealplanData(unit.unit_id, eventId);
+  
+  return (
+    <DialogContent>
+      <DataTable data={mealplans} columns={columns} />
+    </DialogContent>
+  );
+};
+
+export const MenuModal = ({ isOpen, onClose, unit, eventId }) => {
+  if (!isOpen || !unit?.unit_id || !eventId) {
+    return null;
+  }
+  
+  return (
+    <Dialog open={isOpen} onOpenChange={onClose}>
+      <MenuModalContent unit={unit} eventId={eventId} onClose={onClose} />
+    </Dialog>
+  );
+};
+```
+
+## 📋 **Recommended Fix for pace-cake**
+
+**Update the MenuModal component by moving all hooks before any conditional logic:**
+
+```typescript
+export const MenuModal = ({ isOpen, onClose, unit, eventId }: MenuModalProps) => {
+  // ✅ Move hooks to the top - before any early returns
+  const { selectedOrganisation } = useOrganisations();
+  const { mealplans, isLoading, ... } = useMealplanData(unit?.unit_id, eventId);
+  
+  // ✅ Then do conditional rendering
+  if (!isOpen || !unit?.unit_id || !eventId) {
+    return null;
+  }
+
+  return (
+    <Dialog open={isOpen} onOpenChange={onClose}>
+      <DialogContent>
+        <DataTable
+          data={mealplans}
+          columns={columns}
+          // ... other props
+        />
+      </DialogContent>
+    </Dialog>
+  );
+};
+```
+
+## 🎯 **Key Points**
+
+- **Not a pace-core bug** - DataTable follows proper React hooks rules
+- **Consuming app issue** - early return before hooks violates React rules  
+- **Simple fix** - move hooks before conditional logic
+- **This is a common React pattern mistake** - not specific to DataTable
+
+## 📚 **React Hooks Rules Reference**
+
+1. **Only call hooks at the top level** - Don't call hooks inside loops, conditions, or nested functions
+2. **Only call hooks from React functions** - Don't call hooks from regular JavaScript functions
+3. **Call hooks in the same order every time** - This is what's being violated in the current code
+
+## 🔗 **Additional Resources**
+
+- [React Hooks Rules](https://reactjs.org/docs/hooks-rules.html)
+- [React Hooks FAQ](https://reactjs.org/docs/hooks-faq.html)
+- [Common Hooks Mistakes](https://reactjs.org/docs/hooks-faq.html#what-can-i-do-if-my-effect-dependencies-change-too-often)
+
+---
+
+**Status**: ✅ **Resolved** - This is a consuming app pattern issue, not a pace-core bug.  
+**Action Required**: Update MenuModal component to call hooks before conditional logic.  
+**Priority**: High - This is blocking feature implementation.

package/docs/troubleshooting/styling-issues.md

@@ -0,0 +1,219 @@
+# 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