@jmruthers/pace-core 0.5.53 → 0.5.55

package/docs/migration/MIGRATION_GUIDE.md

@@ -0,0 +1,684 @@
+# PACE Core Migration Guide
+
+> **🔄 Complete Migration Reference** | [← Back to Documentation](../README.md) | [↑ Table of Contents](#table-of-contents)
+
+Comprehensive migration guide for upgrading PACE Core across all versions with detailed instructions, breaking changes, and troubleshooting.
+
+## Overview
+
+This guide covers all PACE Core migrations from version 0.1.0 to the latest version. Use the version-specific sections to find the exact migration steps for your upgrade path.
+
+## Quick Reference
+
+| From Version | To Version | Breaking Changes | Migration Time | Key Changes |
+|--------------|------------|------------------|----------------|-------------|
+| v0.4.14 | v0.4.15 | ⚠️ Minor | 5-10 min | Tailwind scanning fix |
+| v0.4.15 | v0.4.16 | ⚠️ Minor | 5-10 min | CSS-first approach |
+| v0.4.16 | v0.4.17 | ⚠️ Minor | 5-10 min | Source path fix |
+| v0.4.x | v0.5.x | ⚠️ Minor | 10-15 min | File reference system |
+| v0.3.x | v0.5.x | ⚠️ Major | 30-45 min | RBAC system, providers |
+| v0.2.x | v0.5.x | ⚠️ Major | 45-60 min | Complete restructure |
+
+## Current Version Migration (v0.5.x)
+
+### Latest Changes in v0.5.x
+
+**New Features:**
+- File Upload & Storage System
+- Inactivity Tracking
+- Public Pages System
+- Organisation Security
+- Enhanced RBAC
+
+**Breaking Changes:**
+- None in v0.5.x series
+- All changes are additive
+
+### Recommended Upgrade Path
+
+```bash
+# Update to latest version
+npm install @jmruthers/pace-core@latest
+
+# Update peer dependencies if needed
+npm install @tanstack/react-table@^8.0.0 @radix-ui/react-checkbox@^1.0.0
+```
+
+### New Features Usage
+
+**File Upload System:**
+```tsx
+// New in v0.5.x
+import { FileUpload, FileDisplay, useFileReference } from '@jmruthers/pace-core';
+
+function MyComponent() {
+  const { uploadFile } = useFileReference(supabase);
+  // Use new file upload features
+}
+```
+
+**Inactivity Tracking:**
+```tsx
+// New in v0.5.x
+import { useInactivityTracker, InactivityWarningModal } from '@jmruthers/pace-core';
+
+function MyApp() {
+  const { isIdle, showWarning, resetActivity } = useInactivityTracker({
+    idleTimeoutMs: 30 * 60 * 1000
+  });
+  // Use inactivity tracking
+}
+```
+
+## Version History
+
+### v0.5.54 (Latest)
+
+**Changes:**
+- File reference system improvements
+- Enhanced error handling
+- Performance optimizations
+
+**Migration:** No action required - fully backward compatible.
+
+### v0.5.0 - v0.5.53
+
+**New Features:**
+- File Upload & Storage System
+- Inactivity Tracking
+- Public Pages System
+- Organisation Security
+
+**Migration:** No breaking changes - all features are additive.
+
+### v0.4.17 - Source Path Fix
+
+**Issue Fixed:** @source directive paths in core.css were incorrect, preventing Tailwind v4 from scanning pace-core source files.
+
+**Before (v0.4.16):**
+```css
+@source "./src/**/*.{js,ts,jsx,tsx}";
+```
+
+**After (v0.4.17):**
+```css
+@source "../src/**/*.{js,ts,jsx,tsx}";
+```
+
+**Migration Steps:**
+
+1. **Update pace-core:**
+```bash
+npm install @jmruthers/pace-core@^0.4.17
+```
+
+2. **Verify CSS file size:**
+```bash
+# Should be 50-100+ KB (not 20-30 KB)
+ls -la dist/assets/*.css
+```
+
+3. **Test component styling:**
+```tsx
+import { Button, Card } from '@jmruthers/pace-core';
+
+function TestComponent() {
+  return (
+    <div className="p-8 space-y-4">
+      <h1 className="text-2xl font-bold text-main-900">Path Fix Test</h1>
+      <Card className="p-4 border border-main-300">
+        <Button variant="primary" className="bg-main-600 text-main-50">
+          Primary Button
+        </Button>
+      </Card>
+    </div>
+  );
+}
+```
+
+**Expected Result:** Components should render with proper PACE Core styling.
+
+### v0.4.16 - CSS-First Approach
+
+**Change:** Simplified Tailwind v4 configuration using CSS-first approach with @source directives.
+
+**Before (v0.4.15):**
+```typescript
+// vite.config.ts
+export default defineConfig({
+  plugins: [
+    react(),
+    tailwindcss({
+      content: [
+        './src/**/*.{js,ts,jsx,tsx}',
+        './node_modules/@jmruthers/pace-core/src/**/*.{js,ts,jsx,tsx}'
+      ]
+    })
+  ],
+})
+```
+
+**After (v0.4.16):**
+```typescript
+// vite.config.ts
+export default defineConfig({
+  plugins: [
+    react(),
+    tailwindcss({
+      content: [
+        './src/**/*.{js,ts,jsx,tsx}'
+        // pace-core source files are automatically scanned via @source directives
+      ]
+    })
+  ],
+})
+```
+
+**Migration Steps:**
+
+1. **Update pace-core:**
+```bash
+npm install @jmruthers/pace-core@^0.4.16
+```
+
+2. **Simplify Vite configuration:**
+```typescript
+// vite.config.ts
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+import tailwindcss from '@tailwindcss/vite'
+
+export default defineConfig({
+  plugins: [
+    react(),
+    tailwindcss({
+      content: [
+        './src/**/*.{js,ts,jsx,tsx}'
+      ]
+    })
+  ],
+})
+```
+
+3. **Test the configuration:**
+```tsx
+// Test component
+import { Button } from '@jmruthers/pace-core';
+
+function TestComponent() {
+  return (
+    <Button className="bg-main-600 text-main-50">
+      Test Button
+    </Button>
+  );
+}
+```
+
+### v0.4.15 - Tailwind Scanning Fix
+
+**Issue Fixed:** Components appeared unstyled due to missing Tailwind class scanning.
+
+**Root Cause:** Tailwind v4 needs to scan source files, not compiled JavaScript.
+
+**Migration Steps:**
+
+1. **Update pace-core:**
+```bash
+npm install @jmruthers/pace-core@^0.4.15
+```
+
+2. **Update Vite configuration:**
+```typescript
+// vite.config.ts
+export default defineConfig({
+  plugins: [
+    react(),
+    tailwindcss({
+      content: [
+        './src/**/*.{js,ts,jsx,tsx}',
+        './node_modules/@jmruthers/pace-core/src/**/*.{js,ts,jsx,tsx}'
+      ]
+    })
+  ],
+})
+```
+
+3. **Clear build cache:**
+```bash
+rm -rf dist .vite node_modules
+npm install
+```
+
+4. **Verify CSS generation:**
+```bash
+# Should generate 800+ CSS rules (not 292)
+npm run build
+```
+
+### v0.4.14 and Earlier
+
+**Legacy Configuration:**
+```typescript
+// Old configuration (v0.4.14 and below)
+export default defineConfig({
+  plugins: [
+    react(),
+    tailwindcss({
+      content: [
+        './src/**/*.{js,ts,jsx,tsx}',
+        './node_modules/@jmruthers/pace-core/**/*.{js,ts,jsx,tsx}'
+      ]
+    })
+  ],
+})
+```
+
+## Major Version Migrations
+
+### v0.3.x to v0.5.x
+
+**Breaking Changes:**
+- Provider hierarchy changes
+- RBAC system updates
+- New authentication patterns
+
+**Migration Steps:**
+
+1. **Update dependencies:**
+```bash
+npm install @jmruthers/pace-core@^0.5.0
+```
+
+2. **Update provider hierarchy:**
+```tsx
+// Before (v0.3.x)
+<AuthProvider>
+  <OrganisationProvider>
+    <EventProvider>
+      <App />
+    </EventProvider>
+  </OrganisationProvider>
+</AuthProvider>
+
+// After (v0.5.x)
+<UnifiedAuthProvider supabaseClient={supabase} appName="my-app">
+  <OrganisationProvider>
+    <EventProvider>
+      <App />
+    </EventProvider>
+  </OrganisationProvider>
+</UnifiedAuthProvider>
+```
+
+3. **Update authentication hooks:**
+```tsx
+// Before
+import { useAuth } from '@jmruthers/pace-core';
+
+// After
+import { useUnifiedAuth } from '@jmruthers/pace-core';
+```
+
+4. **Update RBAC usage:**
+```tsx
+// Before
+import { useRBAC } from '@jmruthers/pace-core';
+
+// After
+import { useCan } from '@jmruthers/pace-core/rbac';
+```
+
+### v0.2.x to v0.5.x
+
+**Breaking Changes:**
+- Complete component restructure
+- New import paths
+- Updated prop interfaces
+
+**Migration Steps:**
+
+1. **Update all imports:**
+```tsx
+// Before (v0.2.x)
+import { Button, Card, useAuth } from '@jmruthers/pace-core/components';
+
+// After (v0.5.x)
+import { Button, Card, useUnifiedAuth } from '@jmruthers/pace-core';
+```
+
+2. **Update component props:**
+```tsx
+// Check component documentation for prop changes
+// Most components maintain backward compatibility
+```
+
+3. **Update authentication:**
+```tsx
+// Follow v0.3.x to v0.5.x migration steps
+```
+
+## Breaking Changes Reference
+
+### Authentication Changes
+
+| Version | Change | Before | After |
+|---------|--------|--------|-------|
+| v0.4.0 | Provider consolidation | `AuthProvider` | `UnifiedAuthProvider` |
+| v0.4.0 | Hook consolidation | `useAuth` | `useUnifiedAuth` |
+| v0.3.0 | Provider hierarchy | Individual providers | Nested providers |
+
+### RBAC Changes
+
+| Version | Change | Before | After |
+|---------|--------|--------|-------|
+| v0.5.0 | Hook location | `useRBAC` | `useCan` from `/rbac` |
+| v0.4.0 | Permission format | `"read users"` | `"read:users"` |
+| v0.3.0 | Scope format | `{ userId, orgId }` | `{ organisationId }` |
+
+### Component Changes
+
+| Version | Change | Before | After |
+|---------|--------|--------|-------|
+| v0.4.0 | Import paths | `/components` | Main export |
+| v0.3.0 | Prop interfaces | Legacy props | Updated interfaces |
+| v0.2.0 | Component names | Old names | New naming convention |
+
+## RBAC System Migration
+
+### Legacy to New RBAC
+
+**Database Schema Changes:**
+```sql
+-- New RBAC tables (v0.4.0+)
+CREATE TABLE rbac_apps (
+  id UUID PRIMARY KEY,
+  name TEXT NOT NULL,
+  requires_event BOOLEAN DEFAULT false
+);
+
+CREATE TABLE rbac_page_permissions (
+  id UUID PRIMARY KEY,
+  app_id UUID REFERENCES rbac_apps(id),
+  page_name TEXT NOT NULL,
+  operation TEXT NOT NULL,
+  required_permissions TEXT[] NOT NULL
+);
+
+-- Migration from old system
+INSERT INTO rbac_apps (id, name, requires_event)
+VALUES ('your-app-id', 'Your App Name', false);
+```
+
+**Code Migration:**
+```tsx
+// Before (Legacy RBAC)
+import { useRBAC } from '@jmruthers/pace-core';
+
+function MyComponent() {
+  const { hasPermission } = useRBAC();
+  const canEdit = hasPermission('edit', 'users');
+}
+
+// After (New RBAC)
+import { useCan } from '@jmruthers/pace-core/rbac';
+
+function MyComponent() {
+  const { hasPermission } = useCan();
+  const canEdit = await hasPermission('update:users', { organisationId });
+}
+```
+
+### Permission Format Changes
+
+**Old Format:**
+```tsx
+// v0.3.x and earlier
+hasPermission('read', 'users')
+hasPermission('edit', 'organisations')
+```
+
+**New Format:**
+```tsx
+// v0.4.x and later
+hasPermission('read:users', { organisationId })
+hasPermission('update:organisations', { organisationId })
+```
+
+## Organisation Context Changes
+
+### Provider Hierarchy Updates
+
+**Timing Fix (v0.4.0):**
+```tsx
+// Before - Race condition possible
+<AuthProvider>
+  <OrganisationProvider>
+    <EventProvider>
+      <App />
+    </EventProvider>
+  </OrganisationProvider>
+</AuthProvider>
+
+// After - Proper timing
+<UnifiedAuthProvider supabaseClient={supabase} appName="my-app">
+  <OrganisationProvider>
+    <EventProvider>
+      <App />
+    </EventProvider>
+  </OrganisationProvider>
+</UnifiedAuthProvider>
+```
+
+### Context Resolution
+
+**Automatic Database Context:**
+```tsx
+// The OrganisationProvider now automatically sets database context
+// No manual setup required
+<OrganisationProvider>
+  <YourApp />
+</OrganisationProvider>
+
+// Database context is automatically set via:
+// SELECT set_organisation_context(organisation_id);
+```
+
+## Troubleshooting Common Migration Issues
+
+### Styling Issues After Upgrade
+
+**Problem:** Components appear unstyled after upgrade.
+
+**Solutions:**
+1. **Check Vite configuration:**
+```typescript
+// Ensure pace-core source files are included
+export default defineConfig({
+  plugins: [
+    react(),
+    tailwindcss({
+      content: [
+        './src/**/*.{js,ts,jsx,tsx}',
+        './node_modules/@jmruthers/pace-core/src/**/*.{js,ts,jsx,tsx}'
+      ]
+    })
+  ],
+})
+```
+
+2. **Clear build cache:**
+```bash
+rm -rf dist .vite node_modules
+npm install
+npm run build
+```
+
+3. **Verify CSS file size:**
+```bash
+# Should be 50-100+ KB
+ls -la dist/assets/*.css
+```
+
+### Import Path Changes
+
+**Problem:** Import errors after upgrade.
+
+**Solutions:**
+1. **Update import paths:**
+```tsx
+// Old
+import { Button } from '@jmruthers/pace-core/components';
+
+// New
+import { Button } from '@jmruthers/pace-core';
+```
+
+2. **Check for moved exports:**
+```tsx
+// RBAC hooks moved
+import { useCan } from '@jmruthers/pace-core/rbac';
+
+// Storage hooks
+import { useStorage } from '@jmruthers/pace-core';
+```
+
+### Authentication Issues
+
+**Problem:** Authentication not working after upgrade.
+
+**Solutions:**
+1. **Update provider hierarchy:**
+```tsx
+// Use UnifiedAuthProvider
+<UnifiedAuthProvider supabaseClient={supabase} appName="my-app">
+  <OrganisationProvider>
+    <EventProvider>
+      <App />
+    </EventProvider>
+  </OrganisationProvider>
+</UnifiedAuthProvider>
+```
+
+2. **Update hook usage:**
+```tsx
+// Use useUnifiedAuth
+const { user, signIn, signOut } = useUnifiedAuth();
+```
+
+### RBAC Permission Issues
+
+**Problem:** Permissions not working after RBAC migration.
+
+**Solutions:**
+1. **Update permission format:**
+```tsx
+// Old format
+hasPermission('read', 'users')
+
+// New format
+hasPermission('read:users', { organisationId })
+```
+
+2. **Check scope requirements:**
+```tsx
+// Always include organisation context
+const canEdit = await hasPermission('update:users', { 
+  organisationId: currentOrg.id 
+});
+```
+
+3. **Verify database setup:**
+```sql
+-- Ensure RBAC tables exist
+SELECT * FROM rbac_apps;
+SELECT * FROM rbac_page_permissions;
+```
+
+### Build Errors
+
+**Problem:** Build fails after upgrade.
+
+**Solutions:**
+1. **Update peer dependencies:**
+```bash
+npm install @tanstack/react-table@^8.0.0
+npm install @radix-ui/react-checkbox@^1.0.0
+npm install @radix-ui/react-dialog@^1.0.0
+```
+
+2. **Check TypeScript errors:**
+```bash
+npm run type-check
+```
+
+3. **Update tsconfig.json:**
+```json
+{
+  "compilerOptions": {
+    "skipLibCheck": true,
+    "moduleResolution": "node"
+  }
+}
+```
+
+## Migration Checklist
+
+### Pre-Migration
+
+- [ ] Backup current codebase
+- [ ] Document current version
+- [ ] Test current functionality
+- [ ] Check for custom configurations
+
+### During Migration
+
+- [ ] Update package.json
+- [ ] Update import statements
+- [ ] Update component usage
+- [ ] Update configuration files
+- [ ] Run type checking
+- [ ] Test build process
+
+### Post-Migration
+
+- [ ] Test all functionality
+- [ ] Verify styling
+- [ ] Check authentication
+- [ ] Test RBAC permissions
+- [ ] Performance testing
+- [ ] Update documentation
+
+## Getting Help
+
+### Common Resources
+
+- **[Troubleshooting Guide](../troubleshooting/README.md)** - Detailed problem solving
+- **[API Reference](../api-reference/)** - Complete API documentation
+- **[Examples](../getting-started/examples/)** - Working code examples
+- **[GitHub Issues](https://github.com/jmruthers/pace-core/issues)** - Bug reports
+
+### Migration Support
+
+If you encounter issues during migration:
+
+1. **Check this guide** for your specific version
+2. **Review troubleshooting section** for common issues
+3. **Test with minimal example** to isolate problems
+4. **Check GitHub issues** for similar problems
+5. **Create new issue** with detailed information
+
+### Version-Specific Help
+
+- **v0.4.17+**: [Source Path Fix Guide](./v0.4.17-source-path-fix.md)
+- **v0.4.16**: [CSS-First Migration Guide](./v0.4.16-css-first-approach.md)
+- **v0.4.15**: [Tailwind Scanning Guide](./v0.4.15-tailwind-scanning.md)
+- **RBAC**: [RBAC Migration Guide](./rbac-migration.md)
+
+## Next Steps
+
+After successful migration:
+
+- **[Getting Started](../getting-started/quick-start.md)** - Learn new features
+- **[Implementation Guides](../implementation-guides/)** - Advanced patterns
+- **[Best Practices](../best-practices/)** - Production guidelines
+- **[API Reference](../api-reference/)** - Complete documentation

package/docs/migration/README.md

@@ -1,11 +1,22 @@
 # Migration Guide
 
-> **🔄 Upgrade and Migration** | [RBAC Migration](./rbac-migration.md) | [Version Migration](../troubleshooting/migration.md)
+> **🔄 Upgrade and Migration** | [Unified Migration Guide](./MIGRATION_GUIDE.md) | [RBAC Migration](./rbac-migration.md)
 
-[← Back to Documentation](../README.md) | [↑ Table of Contents](#table-of-contents) | [Next: RBAC Migration →](./rbac-migration.md)
+[← Back to Documentation](../README.md) | [↑ Table of Contents](#table-of-contents) | [Next: Unified Migration Guide →](./MIGRATION_GUIDE.md)
 
 Complete migration guides for upgrading to and between versions of `@jmruthers/pace-core`.
 
+## 📚 Start Here: Unified Migration Guide
+
+**For all migrations, start with:** [Complete Migration Guide](./MIGRATION_GUIDE.md)
+
+The unified guide provides:
+- Quick reference table for all versions
+- Step-by-step migration instructions
+- Breaking changes reference
+- Troubleshooting common issues
+- Complete migration checklist
+
 ## 📋 Table of Contents
 
 - [Migration Overview](#-migration-overview)