@jmruthers/pace-core 0.5.193 → 0.6.2

package/docs/migration/quick-migration-guide.md

@@ -1,356 +0,0 @@
----
-lastUpdated: 2025-11-18T21:00:00+11:00
-version: 0.5.181
-reviewedBy: documentation-standards-audit
----
-
-# Quick Migration Guide
-
-> **🚀 Fast Track Migration** | [Full Migration Guide](./MIGRATION_GUIDE.md) | [Complete Migration Reference](./README.md)
-
-Quick migration guide for common PACE Core upgrade scenarios. For detailed migration instructions, see the [Complete Migration Guide](./MIGRATION_GUIDE.md).
-
-## 🎯 Quick Migration Checklist
-
-### Before You Start
-- [ ] **Backup your project** - Always backup before major updates
-- [ ] **Check current version** - `npm list @jmruthers/pace-core`
-- [ ] **Review changelog** - Check for breaking changes
-- [ ] **Test in development** - Never migrate directly in production
-
-### Common Migration Scenarios
-
-## 📦 Package Updates
-
-### Minor Version Updates (e.g., v0.4.16 → v0.4.17)
-
-**Usually safe, but check for:**
-- New features
-- Bug fixes
-- Performance improvements
-
-```bash
-# Update to latest
-npm update @jmruthers/pace-core
-
-# Or specific version
-npm install @jmruthers/pace-core@0.4.17
-```
-
-**What to check:**
-- [ ] App still builds successfully
-- [ ] No console errors
-- [ ] Components render correctly
-- [ ] Authentication still works
-
-### Major Version Updates (e.g., v0.x → v1.x)
-
-**Requires more attention:**
-- Breaking API changes
-- New required props
-- Deprecated features
-- Configuration changes
-
-```bash
-# Check what's new
-npm info @jmruthers/pace-core versions --json
-
-# Update to latest
-npm install @jmruthers/pace-core@latest
-```
-
-**What to check:**
-- [ ] Review [Breaking Changes](./breaking-changes.md)
-- [ ] Update import statements
-- [ ] Fix deprecated API usage
-- [ ] Update configuration files
-- [ ] Test all functionality
-
-## 🔧 Configuration Updates
-
-### Tailwind v4 Migration
-
-**From v0.4.15 to v0.4.16+ (CSS-First Approach):**
-
-```bash
-# Remove old dependencies
-npm uninstall tailwindcss postcss autoprefixer
-
-# Install new dependencies
-npm install @tailwindcss/vite tailwindcss@^4.0.0
-```
-
-**Update vite.config.ts:**
-```ts
-// Before (v0.4.15)
-import tailwindcss from '@tailwindcss/vite'
-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+)
-import tailwindcss from '@tailwindcss/vite'
-export default defineConfig({
-  plugins: [
-    react(),
-    tailwindcss({
-      content: [
-        './src/**/*.{js,ts,jsx,tsx}' // Only app files, pace-core scanned via @source
-      ]
-    })
-  ],
-})
-```
-
-**Update CSS imports:**
-```tsx
-// Before
-import '@jmruthers/pace-core/src/styles/core.css';
-
-// After
-import '@jmruthers/pace-core/src/styles/core.css';
-```
-
-### Source Path Fix (v0.4.17+)
-
-**Critical fix for @source directive paths:**
-
-```ts
-// vite.config.ts
-import tailwindcss from '@tailwindcss/vite'
-export default defineConfig({
-  plugins: [
-    react(),
-    tailwindcss({
-      content: [
-        './src/**/*.{js,ts,jsx,tsx}',
-        './node_modules/@jmruthers/pace-core/**/*.{js,ts,jsx,tsx}'
-      ]
-    })
-  ],
-})
-```
-
-## 🔄 API Changes
-
-### Component Props
-
-**Common prop changes:**
-
-```tsx
-// Before (v0.x)
-<DataTable
-  data={data}
-  columns={columns}
-  enableSearch={true}
-  enablePagination={true}
-/>
-
-// After (v1.x)
-<DataTable
-  data={data}
-  columns={columns}
-  features={{
-    search: true,
-    pagination: true,
-    sorting: true,
-    filtering: true
-  }}
-/>
-```
-
-### Hook Changes
-
-**RBAC hooks moved to separate module:**
-
-```tsx
-// Before
-import { useCan, usePermissions } from '@jmruthers/pace-core';
-
-// After
-import { useCan, usePermissions } from '@jmruthers/pace-core/rbac';
-```
-
-### Import Changes
-
-**Consolidated imports:**
-
-```tsx
-// Before
-import { Button } from '@jmruthers/pace-core/components';
-import { useUnifiedAuth } from '@jmruthers/pace-core/hooks';
-
-// After
-import { Button, useUnifiedAuth } from '@jmruthers/pace-core';
-```
-
-## 🐛 Common Migration Issues
-
-### Styling Issues
-
-**Problem**: Components appear unstyled after update
-
-**Solution**:
-```tsx
-// Ensure CSS import is first
-import '@jmruthers/pace-core/src/styles/core.css';
-import { Button } from '@jmruthers/pace-core';
-```
-
-### Build Errors
-
-**Problem**: Build fails with Tailwind errors
-
-**Solution**:
-```bash
-# Clear all caches
-rm -rf node_modules package-lock.json
-npm install
-
-# Check Tailwind config
-npm run build -- --debug
-```
-
-### TypeScript Errors
-
-**Problem**: Type errors after update
-
-**Solution**:
-```bash
-# Update TypeScript types
-npm install @types/react@latest @types/react-dom@latest
-
-# Regenerate types
-npm run type-check
-```
-
-### Authentication Issues
-
-**Problem**: Login not working after update
-
-**Solution**:
-```tsx
-// Check provider hierarchy
-<UnifiedAuthProvider supabaseClient={supabase} appName="my-app">
-  <OrganisationProvider>
-    <EventProvider>
-      <YourApp />
-    </EventProvider>
-  </OrganisationProvider>
-</UnifiedAuthProvider>
-```
-
-## ✅ Post-Migration Testing
-
-### Essential Tests
-- [ ] **Build succeeds** - `npm run build`
-- [ ] **App starts** - `npm run dev`
-- [ ] **Authentication works** - Login/logout
-- [ ] **Components render** - All UI components display
-- [ ] **Permissions work** - RBAC functions correctly
-- [ ] **Forms work** - Form validation and submission
-- [ ] **Data tables work** - CRUD operations
-- [ ] **Styling correct** - No visual regressions
-
-### Performance Tests
-- [ ] **Bundle size** - Check for size increases
-- [ ] **Load time** - Measure initial load
-- [ ] **Runtime performance** - Check for slowdowns
-- [ ] **Memory usage** - Monitor for leaks
-
-### Browser Tests
-- [ ] **Chrome** - Latest version
-- [ ] **Firefox** - Latest version
-- [ ] **Safari** - Latest version
-- [ ] **Mobile browsers** - iOS Safari, Chrome Mobile
-
-## 🆘 Getting Help
-
-### If Migration Fails
-
-1. **Check the logs** - Look for specific error messages
-2. **Revert changes** - Go back to working version
-3. **Check documentation** - Look for migration guides
-4. **Search issues** - Check GitHub issues
-5. **Ask for help** - Create detailed issue report
-
-### Debug Information
-
-When asking for help, include:
-
-```bash
-# Version information
-npm list @jmruthers/pace-core
-node --version
-npm --version
-
-# Build output
-npm run build 2>&1 | tee build.log
-
-# Error details
-# Include full error messages and stack traces
-```
-
-### Emergency Rollback
-
-```bash
-# Rollback to previous version
-npm install @jmruthers/pace-core@0.4.16
-
-# Or specific working version
-npm install @jmruthers/pace-core@0.4.15
-
-# Clear caches
-rm -rf node_modules package-lock.json
-npm install
-```
-
-## 📚 Additional Resources
-
-- **[Complete Migration Guide](./MIGRATION_GUIDE.md)** - Detailed migration instructions
-- **[Migration Overview](./README.md)** - Migration guide index
-- **[Troubleshooting](../troubleshooting/README.md)** - Common issues and solutions
-- **[GitHub Issues](https://github.com/jmruthers/pace-core/issues)** - Report bugs and get help
-
----
-
-**Remember**: Always test migrations in a development environment first!
-
-## ♿ Accessibility
-
-Migration processes should maintain accessibility:
-
-- **Accessibility testing after migration** - Verify all components remain accessible after migration
-- **Screen reader compatibility** - Test with assistive technologies after migration
-- **Keyboard navigation** - Ensure keyboard navigation still works after migration
-
-### Accessibility Best Practices
-
-1. **Test accessibility after migration** - Run accessibility tests after each migration step
-2. **Verify keyboard navigation** - Ensure all interactive elements remain keyboard accessible
-3. **Test with screen readers** - Verify components work with assistive technologies
-
-## ⚠️ Edge Cases
-
-### Migration Failures
-
-When migrations fail:
-- Review error messages carefully
-- Check version compatibility
-- Verify all dependencies are updated
-- Test with minimal configuration
-
-### Partial Migrations
-
-When only partial migration is possible:
-- Document what was migrated and what wasn't
-- Create remediation plan for remaining items
-- Test partially migrated code thoroughly

package/docs/migration/service-architecture.md

@@ -1,281 +0,0 @@
----
-lastUpdated: 2025-11-18T21:00:00+11:00
-version: 0.5.181
-reviewedBy: documentation-standards-audit
----
-
-# Provider Architecture: Service-Based Design
-
-## Overview
-
-pace-core now uses a **service-based architecture** for all providers. This provides better testability, maintainability, and follows SOLID principles by separating business logic (services) from React context (providers).
-
-## Architecture Benefits
-
-- **Separation of Concerns**: Business logic in pure TypeScript services
-- **Better Testability**: Services can be tested without React
-- **Improved Performance**: Services instantiated once and reused
-- **Type Safety**: Full TypeScript support with clear interfaces
-
-## Quick Start
-
-### Basic Usage
-
-```tsx
-import { UnifiedAuthProvider, useUnifiedAuth } from '@jmruthers/pace-core';
-
-function App() {
-  return (
-    <UnifiedAuthProvider
-      supabaseClient={supabase}
-      appName="MY_APP"
-      idleTimeoutMs={30 * 60 * 1000} // 30 minutes
-      warnBeforeMs={60 * 1000} // 60 seconds
-      onIdleLogout={() => {
-        // Handle idle logout - redirect to login
-        window.location.href = '/login';
-      }}
-    >
-      <YourAppContent />
-    </UnifiedAuthProvider>
-  );
-}
-```
-
-### Using Hooks
-
-```tsx
-import { useUnifiedAuth, useEvents, useOrganisations } from '@jmruthers/pace-core';
-
-function MyComponent() {
-  const { user, isAuthenticated, signOut } = useUnifiedAuth();
-  const { events, selectedEvent, setSelectedEvent } = useEvents();
-  const { selectedOrganisation, organisations } = useOrganisations();
-  
-  // Use the hooks as needed
-}
-```
-
-## Service Architecture Overview
-
-### Three-Layer Architecture
-
-The service architecture follows a clear three-layer pattern:
-
-1. **Service Layer** (`src/services/`) - Pure TypeScript classes containing business logic
-   - No React dependencies
-   - Observable pattern for state changes
-   - Easy to unit test
-
-2. **Provider Layer** (`src/providers/services/`) - React context providers that create service instances
-   - Creates and manages service instances (singleton pattern)
-   - Provides services via React context
-   - Handles service lifecycle
-   - **Note**: Providers do NOT export hooks
-
-3. **Hook Layer** (`src/hooks/services/`) - React hooks for reactive component integration
-   - Access services from context
-   - Subscribe to service state changes
-   - Trigger React re-renders when state changes
-   - **⚠️ Always import hooks from here, not from providers**
-
-### Service Layer
-
-Each service is a pure TypeScript class:
-
-```typescript
-class AuthService extends BaseService {
-  signIn(email: string, password: string): Promise<AuthResult> { /* ... */ }
-  signOut(): Promise<AuthResult> { /* ... */ }
-  // ... other methods
-}
-```
-
-### Provider Layer
-
-Service providers create and manage service instances:
-
-```tsx
-function AuthServiceProvider({ children, supabaseClient }) {
-  const authService = useMemo(() => new AuthService(supabaseClient), [supabaseClient]);
-  // Initialize and manage service lifecycle
-  return <AuthServiceContext.Provider value={{ authService }}>{children}</AuthServiceContext.Provider>;
-}
-```
-
-### Hook Layer
-
-Convenience hooks provide easy access to services:
-
-```tsx
-function useAuth() {
-  const context = useContext(AuthServiceContext);
-  return context.authService;
-}
-```
-
-## Available Hooks
-
-### Unified Hook (Recommended for Most Use Cases)
-
-```tsx
-import { useUnifiedAuth } from '@jmruthers/pace-core';
-
-function MyComponent() {
-  const { 
-    user, 
-    isAuthenticated, 
-    signOut,
-    selectedOrganisation,
-    events,
-    selectedEvent,
-    permissions,
-    hasRole,
-    hasPermission
-  } = useUnifiedAuth();
-  
-  // Access all features from one hook
-}
-```
-
-### Individual Service Hooks (For Performance)
-
-For better performance, use individual service hooks:
-
-```tsx
-import { 
-  useEvents, 
-  useOrganisations, 
-  useAuthService,
-  useEventService,
-  useOrganisationService
-} from '@jmruthers/pace-core';
-
-function MyComponent() {
-  const events = useEvents();              // Convenience hook
-  const orgs = useOrganisations();         // Convenience hook
-  const authService = useAuthService();    // Direct service hook
-  const eventService = useEventService();   // Direct service hook
-  
-  // Only re-renders when relevant service state changes
-}
-```
-
-**Important**: Service hooks (like `useAuthService`, `useEventService`) are exported from `hooks/services/` and include state subscription logic. Always import them from the main package or `hooks/services/`, never from `providers/services/`.
-
-## Testing
-
-### Testing Services
-
-Services are pure TypeScript classes, making them easy to unit test:
-
-```typescript
-describe('AuthService', () => {
-  let authService: AuthService;
-  
-  beforeEach(() => {
-    authService = new AuthService(mockSupabase);
-  });
-  
-  it('should sign in user', async () => {
-    const result = await authService.signIn('test@example.com', 'password');
-    expect(result.user).toBeDefined();
-  });
-});
-```
-
-### Testing Providers
-
-Providers can be tested with React Testing Library:
-
-```typescript
-render(
-  <UnifiedAuthProvider
-    supabaseClient={mockSupabase}
-    appName="TEST_APP"
-    idleTimeoutMs={30000}
-    warnBeforeMs={5000}
-    onIdleLogout={() => {}}
-  >
-    <TestComponent />
-  </UnifiedAuthProvider>
-);
-```
-
-## Common Issues
-
-### Missing Required Props
-
-**Error**: `Missing required prop: idleTimeoutMs`
-
-Add the required inactivity management props:
-
-```tsx
-<UnifiedAuthProvider
-  supabaseClient={supabase}
-  appName="MY_APP"
-  idleTimeoutMs={30 * 60 * 1000}
-  warnBeforeMs={60 * 1000}
-  onIdleLogout={() => window.location.href = '/login'}
->
-  <YourAppContent />
-</UnifiedAuthProvider>
-```
-
-## Performance Tips
-
-1. **Use individual hooks** when you only need specific data
-2. **Avoid unnecessary re-renders** by selecting only what you need
-3. **Memoize expensive computations** in components
-4. **Test services in isolation** for better unit tests
-
-## Additional Resources
-
-- [API Reference](../../api-reference/providers.md)
-- [Architecture Documentation](../../architecture/services.md)
-- [Example Apps](../../getting-started/examples/)
-
-## ♿ Accessibility
-
-Service architecture migration should maintain accessibility:
-
-- **Accessibility testing after migration** - Verify all components remain accessible after migration
-- **Screen reader compatibility** - Test with assistive technologies after migration
-- **Keyboard navigation** - Ensure keyboard navigation still works after migration
-- **Focus management** - Verify focus management is correct after migration
-
-### Accessibility Best Practices
-
-1. **Test accessibility after migration** - Run accessibility tests after each migration step
-2. **Verify keyboard navigation** - Ensure all interactive elements remain keyboard accessible
-3. **Test with screen readers** - Verify components work with assistive technologies
-4. **Check focus indicators** - Ensure focus indicators are visible and correct
-
-## ⚠️ Edge Cases
-
-### Service Initialization Failures
-
-When services fail to initialize:
-- Verify all required props are provided
-- Check Supabase client is properly configured
-- Review service dependencies
-- Test with minimal configuration
-- Verify environment variables are set correctly
-
-### Service Context Not Available
-
-When service context is not available:
-- Verify service provider is properly mounted
-- Check provider order and hierarchy
-- Review service provider composition
-- Test with service provider examples
-- Verify hooks are called within provider context
-
-### Performance Issues After Migration
-
-When performance degrades after migration:
-- Check for unnecessary re-renders
-- Review service instance creation
-- Verify memoization is working correctly
-- Test with performance profiling tools
-- Consider using individual hooks instead of unified hook