@jmruthers/pace-core 0.2.4

package/docs/migration/README.md

@@ -0,0 +1,493 @@
+# Migration Guide
+
+> **🔄 Upgrade and Migration** | [RBAC Migration](./rbac-migration.md) | [Version Migration](../troubleshooting/migration.md)
+
+[← Back to Documentation](../README.md) | [↑ Table of Contents](#table-of-contents) | [Next: RBAC Migration →](./rbac-migration.md)
+
+Complete migration guides for upgrading to and between versions of `@jmruthers/pace-core`.
+
+## 📋 Table of Contents
+
+- [Migration Overview](#-migration-overview)
+- [Quick Migration Checklist](#-quick-migration-checklist)
+- [Version Migrations](#-version-migrations)
+- [Critical Fixes](#-critical-fixes)
+- [From Other Libraries](#-from-other-libraries)
+- [RBAC Migration](#-rbac-migration)
+- [Migration Tools](#-migration-tools)
+- [Common Migration Issues](#-common-migration-issues)
+- [Additional Resources](#-additional-resources)
+- [Migration Timeline](#-migration-timeline)
+
+## 📋 Migration Overview
+
+This guide covers:
+- **From v0.x to v1.x** - Major version upgrades
+- **From Other Libraries** - Migrating from Supabase Auth, custom RBAC, etc.
+- **RBAC Migration** - Upgrading RBAC systems
+- **Breaking Changes** - What changed and how to fix it
+
+## 🚀 Quick Migration Checklist
+
+### Before You Start
+- [ ] **Backup your project** - Create a git commit or backup
+- [ ] **Check current version** - `npm list @jmruthers/pace-core`
+- [ ] **Review breaking changes** - Check the changelog
+- [ ] **Test in development** - Never migrate directly in production
+
+### Migration Steps
+- [ ] **Update package** - `npm install @jmruthers/pace-core@latest`
+- [ ] **Update imports** - Fix any changed import paths
+- [ ] **Update API calls** - Fix any changed function signatures
+- [ ] **Update configuration** - Fix any changed config options
+- [ ] **Test thoroughly** - Run all tests and manual testing
+- [ ] **Deploy to staging** - Test in staging environment first
+
+## 📦 Version Migrations
+
+## 🚨 Critical Fixes
+
+### Organisation Context Timing Fix (v0.3.44+)
+
+**CRITICAL**: Fixed race condition where database organisation context wasn't set before other components tried to make queries.
+
+**Impact**: 
+- RLS policies failing on first load
+- Super admin permissions returning false
+- Potential data leakage between organisations
+
+**Migration**: [Organisation Context Timing Fix](./organisation-context-timing-fix.md)
+
+**Quick Fix**:
+```bash
+npm install @jmruthers/pace-core@latest
+```
+
+### Tailwind v4 Theme File Fix (v0.3.45+)
+
+**CRITICAL**: Fixed Tailwind v4 theme file with missing semantic colors and circular @apply references.
+
+**Impact**:
+- Build failures when importing `@jmruthers/pace-core/styles/core.css`
+- Missing semantic colors (ring, border, background, foreground, etc.)
+- Component classes not working due to circular references
+
+**Solution**: Theme file now includes all required semantic colors and fixed component classes.
+
+### Tailwind v4 Basic Colors Fix (v0.3.46+)
+
+**CRITICAL**: Fixed missing basic colors in Tailwind v4 theme file.
+
+**Impact**:
+- Component styles failing due to missing basic color references
+- Build errors when using white, black, transparent, or current colors
+
+**Solution**: Added complete basic color definitions (white, black, transparent, current).
+
+**Quick Fix**:
+```bash
+npm install @jmruthers/pace-core@latest
+```
+
+**Usage** (now works out-of-the-box):
+```tsx
+/* main.tsx */
+import '@jmruthers/pace-core/styles/core.css';
+```
+
+```ts
+// vite.config.ts
+export default defineConfig({
+  plugins: [
+    react(),
+    tailwindcss() // ✅ Simple - theme is included in CSS
+  ],
+});
+```
+
+### Tailwind CSS v4 Migration
+
+PACE Core now supports Tailwind CSS v4 with modern CSS-first configuration.
+
+#### Quick Migration Steps
+
+1. **Update Dependencies**
+   ```bash
+   npm uninstall tailwindcss postcss autoprefixer
+   npm install @tailwindcss/vite tailwindcss@^4.0.0
+   ```
+
+2. **Remove Tailwind Config**
+   Delete your `tailwind.config.js` file - not needed in v4.
+
+3. **Update Vite Config**
+   ```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 included in CSS (v0.3.45+)
+     ],
+   });
+   ```
+
+4. **Update CSS Imports**
+   ```css
+   /* Before (v3) */
+   @tailwind base;
+   @tailwind components;
+   @tailwind utilities;
+
+   /* After (v4) */
+   @import '@jmruthers/pace-core/styles/core.css';
+   ```
+
+For complete Tailwind v4 setup instructions, see the [Styling Guide](../styles/README.md#tailwind-css-v4-setup).
+
+### From v0.x to v1.x
+
+#### Breaking Changes
+
+**1. Package Name Change**
+```diff
+- import { Button } from '@jmruthers/pace-core';
++ import { Button } from '@jmruthers/pace-core';
+```
+
+**2. Auth Provider API Changes**
+```diff
+- <AuthProvider supabaseUrl={url} supabaseKey={key}>
++ <UnifiedAuthProvider supabaseUrl={url} supabaseKey={key}>
+```
+
+**3. Hook Name Changes**
+```diff
+- import { useAuth } from '@jmruthers/pace-core';
++ import { useUnifiedAuth } from '@jmruthers/pace-core';
+```
+
+**4. Component Prop Changes**
+```diff
+- <Button variant="primary">
++ <Button variant="default">
+```
+
+#### Migration Steps
+
+**Step 1: Update Package**
+```bash
+npm uninstall @jmruthers/pace-core
+npm install @jmruthers/pace-core
+```
+
+**Step 2: Update Imports**
+```bash
+# Find and replace all imports
+find src -name "*.tsx" -o -name "*.ts" | xargs sed -i 's/from "@jmruthers/pace-core"/from "@jmruthers\/@jmruthers/pace-core"/g'
+```
+
+**Step 3: Update Auth Provider**
+```tsx
+// Before
+import { AuthProvider } from '@jmruthers/pace-core';
+
+function App() {
+  return (
+    <AuthProvider supabaseUrl={url} supabaseKey={key}>
+      <YourApp />
+    </AuthProvider>
+  );
+}
+
+// After
+import { UnifiedAuthProvider } from '@jmruthers/pace-core';
+
+function App() {
+  return (
+    <UnifiedAuthProvider supabaseUrl={url} supabaseKey={key}>
+      <YourApp />
+    </UnifiedAuthProvider>
+  );
+}
+```
+
+**Step 4: Update Hooks**
+```tsx
+// Before
+import { useAuth, useCan } from '@jmruthers/pace-core';
+
+function MyComponent() {
+  const { user, signIn, signOut } = useAuth();
+  const canEdit = useCan('edit', 'users');
+}
+
+// After
+import { useUnifiedAuth, useCan } from '@jmruthers/pace-core';
+
+function MyComponent() {
+  const { user, signIn, signOut } = useUnifiedAuth();
+  const canEdit = useCan('edit', 'users');
+}
+```
+
+**Step 5: Update Component Props**
+```tsx
+// Before
+<Button variant="primary" size="large">
+  Click me
+</Button>
+
+// After
+<Button variant="default" size="lg">
+  Click me
+</Button>
+```
+
+## 🔄 From Other Libraries
+
+### From Supabase Auth
+
+**Before (Supabase Auth)**
+```tsx
+import { createClient } from '@supabase/supabase-js';
+import { AuthProvider } from '@supabase/auth-ui-react';
+
+const supabase = createClient(url, key);
+
+function App() {
+  return (
+    <AuthProvider supabaseClient={supabase}>
+      <YourApp />
+    </AuthProvider>
+  );
+}
+```
+
+**After (PACE Core)**
+```tsx
+import { UnifiedAuthProvider } from '@jmruthers/pace-core';
+
+// Import the core CSS file - app.css must come first for proper @theme processing
+import './app.css'; // Your app's color palette
+import '@jmruthers/pace-core/styles/core.css';
+
+function App() {
+  return (
+    <UnifiedAuthProvider supabaseUrl={url} supabaseKey={key}>
+      <YourApp />
+    </UnifiedAuthProvider>
+  );
+}
+```
+
+### From Custom RBAC
+
+**Before (Custom RBAC)**
+```tsx
+import { useAuth } from './hooks/useAuth';
+import { usePermissions } from './hooks/usePermissions';
+
+function MyComponent() {
+  const { user } = useAuth();
+  const { hasPermission } = usePermissions();
+  
+  if (!hasPermission('edit', 'users')) {
+    return null;
+  }
+  
+  return <button>Edit User</button>;
+}
+```
+
+**After (PACE Core RBAC)**
+```tsx
+import { useUnifiedAuth, useCan } from '@jmruthers/pace-core';
+
+function MyComponent() {
+  const { user } = useUnifiedAuth();
+  const canEdit = useCan('edit', 'users');
+  
+  if (!canEdit) {
+    return null;
+  }
+  
+  return <button>Edit User</button>;
+}
+```
+
+### From Custom UI Components
+
+**Before (Custom Components)**
+```tsx
+import { Button } from './components/Button';
+import { Modal } from './components/Modal';
+
+function MyComponent() {
+  return (
+    <Modal>
+      <Button onClick={handleClick}>
+        Click me
+      </Button>
+    </Modal>
+  );
+}
+```
+
+**After (PACE Core Components)**
+```tsx
+import { Button, Modal } from '@jmruthers/pace-core';
+
+// Import the core CSS file (in your app's entry point)
+import './app.css'; // Your app's color palette (must come first)
+import '@jmruthers/pace-core/styles/core.css';
+
+function MyComponent() {
+  return (
+    <Modal>
+      <Button onClick={handleClick}>
+        Click me
+      </Button>
+    </Modal>
+  );
+}
+```
+
+## 🔐 RBAC Migration
+
+For detailed RBAC migration, see the [RBAC Migration Guide](./rbac-migration.md).
+
+### Quick RBAC Migration
+
+**1. Install PACE Core**
+```bash
+npm install @jmruthers/pace-core
+```
+
+**2. Set up RBAC Provider**
+```tsx
+import { RBACProvider } from '@jmruthers/pace-core';
+
+function App() {
+  return (
+    <RBACProvider>
+      <YourApp />
+    </RBACProvider>
+  );
+}
+```
+
+**3. Update Permission Checks**
+```tsx
+// Before
+const canEdit = checkPermission('edit', 'users');
+
+// After
+const canEdit = useCan('edit', 'users');
+```
+
+## 🛠️ Migration Tools
+
+### Automated Migration Script
+
+Create a migration script to help with common changes:
+
+```bash
+#!/bin/bash
+# migrate-to-@jmruthers/pace-core.sh
+
+echo "Starting PACE Core migration..."
+
+# Update package.json
+echo "Updating package.json..."
+sed -i 's/"@jmruthers/pace-core"/"@jmruthers\/@jmruthers/pace-core"/g' package.json
+
+# Update imports
+echo "Updating imports..."
+find src -name "*.tsx" -o -name "*.ts" | xargs sed -i 's/from "@jmruthers/pace-core"/from "@jmruthers\/@jmruthers/pace-core"/g'
+
+# Update component props
+echo "Updating component props..."
+find src -name "*.tsx" | xargs sed -i 's/variant="primary"/variant="default"/g'
+find src -name "*.tsx" | xargs sed -i 's/size="large"/size="lg"/g'
+
+echo "Migration complete! Please review changes and test thoroughly."
+```
+
+### Migration Checklist
+
+- [ ] **Package updated** - `@jmruthers/pace-core` installed
+- [ ] **Imports updated** - All import statements fixed
+- [ ] **Auth provider updated** - Using `UnifiedAuthProvider`
+- [ ] **Hooks updated** - Using new hook names
+- [ ] **Component props updated** - Using new prop values
+- [ ] **Styling updated** - Importing design tokens
+- [ ] **Tests updated** - All tests passing
+- [ ] **Documentation updated** - README and docs updated
+
+## 🚨 Common Migration Issues
+
+### Issue 1: Import Errors
+**Problem**: `Module not found: Can't resolve '@jmruthers/pace-core'`
+**Solution**: Update all imports to use `@jmruthers/pace-core`
+
+### Issue 2: Auth Provider Not Working
+**Problem**: Authentication not working after migration
+**Solution**: Ensure you're using `UnifiedAuthProvider` and have the correct props
+
+### Issue 3: Styling Not Applied
+**Problem**: Components look unstyled
+**Solution**: Import the CSS files in your app's entry point:
+```tsx
+import './app.css'; // Your app's color palette (must come first)
+import '@jmruthers/pace-core/styles/core.css';
+```
+
+### Issue 4: TypeScript Errors
+**Problem**: TypeScript errors after migration
+**Solution**: Update type imports and ensure all types are imported from the new package
+
+## 📚 Additional Resources
+
+- **[RBAC Migration Guide](./rbac-migration.md)** - Detailed RBAC migration
+- **[Version Migration](../troubleshooting/migration.md)** - Version-specific migration
+- **[Common Issues](../troubleshooting/common-issues.md)** - Troubleshooting migration issues
+- **[API Reference](../api-reference/)** - Complete API documentation
+
+## 🆘 Need Help?
+
+If you encounter issues during migration:
+
+1. **Check the troubleshooting guide** - [Common Issues](../troubleshooting/common-issues.md)
+2. **Review the API reference** - [API Documentation](../api-reference/)
+3. **Test in a new project** - Create a fresh project to test the new version
+4. **Check the changelog** - Review what changed in the new version
+
+## 🔄 Migration Timeline
+
+### Recommended Migration Schedule
+
+**Week 1: Preparation**
+- [ ] Review breaking changes
+- [ ] Create migration branch
+- [ ] Set up test environment
+
+**Week 2: Development Migration**
+- [ ] Update package
+- [ ] Fix imports and API calls
+- [ ] Update tests
+
+**Week 3: Testing**
+- [ ] Run all tests
+- [ ] Manual testing
+- [ ] Performance testing
+
+**Week 4: Deployment**
+- [ ] Deploy to staging
+- [ ] User acceptance testing
+- [ ] Production deployment
+
+Remember: **Always test thoroughly before deploying to production!**

package/docs/migration/organisation-context-timing-fix.md

@@ -0,0 +1,217 @@
+# Organisation Context Timing Fix Migration
+
+## Overview
+
+This migration guide covers the critical fix for organisation context timing issues in PACE Core v0.3.44+. This fix resolves race conditions where database organisation context wasn't set before other components tried to make queries.
+
+## What Was Fixed
+
+### The Problem (v0.3.43 and earlier)
+
+- **Race Condition**: Database organisation context wasn't set before child components rendered
+- **RLS Policy Failures**: Row Level Security policies failed on first load
+- **Super Admin Issues**: Super admin permissions returned false due to missing context
+- **Data Leakage Risk**: Potential for queries to run without proper organisation filtering
+
+### The Solution (v0.3.44+)
+
+- **Automatic Context Setting**: `OrganisationProvider` now sets database context before rendering children
+- **Context Readiness State**: Added `isContextReady` state to ensure proper timing
+- **Loading States**: Shows appropriate loading messages during context setup
+- **Race Condition Prevention**: Children only render after context is fully established
+
+## Migration Steps
+
+### For New Projects
+
+No action required - the fix is automatic in v0.3.44+.
+
+### For Existing Projects
+
+#### 1. Update PACE Core
+
+```bash
+npm install @jmruthers/pace-core@latest
+```
+
+#### 2. Remove Local Workarounds
+
+If you implemented a local `OrganisationContextGuard` or similar workaround, you can now remove it:
+
+```tsx
+// ❌ Remove this - no longer needed
+function OrganisationContextGuard({ children }) {
+  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}</>;
+}
+
+// ✅ Use this instead - automatic in v0.3.44+
+<UnifiedAuthProvider supabaseClient={supabase} appName="my-app">
+  <OrganisationProvider>  {/* Handles context timing automatically */}
+    <YourApp />
+  </OrganisationProvider>
+</UnifiedAuthProvider>
+```
+
+#### 3. Update Provider Hierarchy
+
+Ensure your provider hierarchy is correct:
+
+```tsx
+// ✅ Correct hierarchy
+<UnifiedAuthProvider supabaseClient={supabase} appName="my-app">
+  <OrganisationProvider>  {/* Sets database context automatically */}
+    <EventProvider>        {/* Can safely make queries */}
+      <YourApp />
+    </EventProvider>
+  </OrganisationProvider>
+</UnifiedAuthProvider>
+```
+
+#### 4. Test the Fix
+
+1. **Clear browser cache/localStorage**
+2. **Reload your application**
+3. **Check console for organisation context messages**:
+   ```
+   [OrganisationProvider] Database organisation context set to: Your Organisation
+   ```
+4. **Verify RLS policies work on first load**
+5. **Test super admin permissions**
+
+## What Changed
+
+### OrganisationProvider Changes
+
+```typescript
+// New state for context readiness
+const [isContextReady, setIsContextReady] = useState(false);
+
+// Updated context setting with proper async handling
+const setDatabaseOrganisationContext = useCallback(async (organisation: Organisation): Promise<void> => {
+  if (!supabase) {
+    setIsContextReady(false);
+    return;
+  }
+
+  try {
+    await setOrganisationContext(supabase, organisation.id);
+    console.log('[OrganisationProvider] Database organisation context set to:', organisation.display_name);
+    setIsContextReady(true); // Only set ready after context is actually set
+  } catch (error) {
+    console.error('[OrganisationProvider] Failed to set database organisation context:', error);
+    setIsContextReady(false);
+  }
+}, [supabase]);
+
+// Updated validation to include context readiness
+const hasValidOrganisationContext = useMemo(() => {
+  return !!(selectedOrganisation && !isLoading && !error && isContextReady);
+}, [selectedOrganisation, isLoading, error, isContextReady]);
+
+// Updated loading condition
+if (isLoading || (selectedOrganisation && !isContextReady)) {
+  return (
+    <div className="organisation-loading">
+      <div className="text-center">
+        <div className="animate-spin rounded-full h-8 w-8 border-b-2 border-primary mx-auto mb-4"></div>
+        <p className="text-muted-foreground">
+          {isLoading ? 'Loading organisation context...' : 'Setting up organisation context...'}
+        </p>
+      </div>
+    </div>
+  );
+}
+```
+
+## Benefits
+
+### For Developers
+
+- **No Manual Setup**: Organisation context is set automatically
+- **No Race Conditions**: Proper timing ensures context is always available
+- **Better Loading States**: Clear feedback during context setup
+- **Simplified Code**: No need for local workarounds
+
+### For Users
+
+- **Faster Loading**: No delays from manual context setting
+- **Reliable Permissions**: Super admin and RBAC work correctly from first load
+- **Data Security**: RLS policies work correctly, preventing data leakage
+- **Better UX**: Clear loading states and no permission errors
+
+## Troubleshooting
+
+### Still Having Issues?
+
+1. **Check PACE Core Version**:
+   ```bash
+   npm list @jmruthers/pace-core
+   ```
+   Should be v0.3.44 or later.
+
+2. **Clear All Caches**:
+   ```bash
+   # Clear npm cache
+   npm cache clean --force
+   
+   # Clear browser cache and localStorage
+   # Then reload your application
+   ```
+
+3. **Check Console Logs**:
+   Look for these messages:
+   ```
+   [OrganisationProvider] Database organisation context set to: [Organisation Name]
+   ```
+
+4. **Verify Provider Hierarchy**:
+   Ensure `OrganisationProvider` wraps your app content.
+
+### Common Issues
+
+#### Issue: "Organisation context is required but not available"
+
+**Solution**: Ensure `OrganisationProvider` is wrapping your app and user has organisation memberships.
+
+#### Issue: RLS policies still failing
+
+**Solution**: Check that the `set_organisation_context` function exists in your database and is working correctly.
+
+#### Issue: Super admin permissions returning false
+
+**Solution**: This should be fixed automatically. If not, check that the user has the `super_admin` role and the `get_user_app_permissions` function is working correctly.
+
+## Support
+
+If you're still experiencing issues after following this migration guide:
+
+1. Check the [Troubleshooting Guide](../troubleshooting/common-issues.md)
+2. Review the [Organisation Context Timing Issue](../troubleshooting/common-issues.md#4-organisation-context-timing-issue-v0344-fixed) section
+3. Open an issue with:
+   - PACE Core version
+   - Console logs
+   - Provider hierarchy
+   - Steps to reproduce
+
+## Related Documentation
+
+- [OrganisationProvider API Reference](../api-reference/providers.md#organisationprovider)
+- [Organisations Core Concepts](../core-concepts/organisations.md)
+- [Troubleshooting Common Issues](../troubleshooting/common-issues.md)
+- [RLS Policy Guide](../troubleshooting/database-view-compatibility.md)