@jmruthers/pace-core 0.5.76 → 0.5.78

package/docs/best-practices/performance.md

@@ -1,16 +1,25 @@
+---
+lastUpdated: 2025-10-29T22:43:00+11:00
+version: 0.5.76
+reviewedBy: content-audit
+---
+
 # Performance Best Practices
 
-Performance is crucial for user experience. This guide provides comprehensive performance optimization techniques for `@jmruthers/pace-core` applications.
+> **📚 Complete Performance Guide** | [← Back to Documentation](./README.md) | [Installation Guide](../getting-started/installation-guide.md)
+
+Performance is crucial for user experience. This comprehensive guide provides all performance optimization techniques for `@jmruthers/pace-core` applications, from basic strategies to advanced optimization.
 
 ## Overview
 
-Performance optimization in `@jmruthers/pace-core` focuses on:
+Performance optimization in `@jmruthers/pace-core` covers:
 
 - **Component Rendering**: Minimizing unnecessary re-renders
 - **Data Fetching**: Efficient data loading and caching
 - **Bundle Size**: Optimizing package size and tree shaking
 - **Memory Management**: Preventing memory leaks
 - **Network Optimization**: Reducing API calls and payload size
+- **Advanced Techniques**: Code splitting, lazy loading, and optimization tools
 
 ## Component Performance
 
@@ -786,4 +795,468 @@ function checkPerformanceBudget(metrics) {
 }
 ```
 
+## Advanced Performance Techniques
+
+### Bundle Optimization
+
+#### Tree Shaking
+
+**Goal**: Minimize bundle size by eliminating unused code.
+
+**Implementation**:
+```typescript
+// ✅ Good - Named exports for tree shaking
+export { Button } from './Button';
+export { Card } from './Card';
+export { DataTable } from './DataTable';
+
+// ❌ Bad - Default exports reduce tree shaking
+export default { Button, Card, DataTable };
+```
+
+**Verify Tree Shaking**:
+```bash
+# Check bundle size
+npm run build
+npx vite-bundle-visualizer
+```
+
+#### Dynamic Imports
+
+**Use Case**: Load components only when needed.
+
+```tsx
+import React, { Suspense, lazy } from 'react';
+
+// Lazy load heavy components
+const DataTable = lazy(() => import('@jmruthers/pace-core').then(m => ({ default: m.DataTable })));
+const ChartEditor = lazy(() => import('./components/ChartEditor'));
+
+function App() {
+  return (
+    <Suspense fallback={<LoadingSpinner />}>
+      <DataTable data={data} columns={columns} />
+    </Suspense>
+  );
+}
+```
+
+#### Analysis Tools
+
+```bash
+# Install analyzer
+npm install -D vite-bundle-visualizer
+
+# Analyze bundle
+npx vite-bundle-visualizer dist/stats.html
+```
+
+### Advanced Component Memoization
+
+#### React.memo for Expensive Components
+
+```tsx
+import React from 'react';
+import { Card } from '@jmruthers/pace-core';
+
+interface UserCardProps {
+  user: User;
+  onEdit: (userId: string) => void;
+}
+
+// Memoize expensive components
+const UserCard = React.memo(({ user, onEdit }: UserCardProps) => {
+  return (
+    <Card className="p-4">
+      <h3>{user.name}</h3>
+      <p>{user.email}</p>
+      <button onClick={() => onEdit(user.id)}>Edit</button>
+    </Card>
+  );
+});
+
+// Custom comparison function for complex props
+const ComplexComponent = React.memo(
+  ({ data, config }: { data: any[]; config: any }) => {
+    return <DataTable data={data} columns={config.columns} />;
+  },
+  (prevProps, nextProps) => {
+    // Only re-render if data length or config changed
+    return (
+      prevProps.data.length === nextProps.data.length &&
+      JSON.stringify(prevProps.config) === JSON.stringify(nextProps.config)
+    );
+  }
+);
+```
+
+#### useMemo for Expensive Calculations
+
+```tsx
+import { useMemo } from 'react';
+import { DataTable } from '@jmruthers/pace-core';
+
+function ExpensiveDataProcessor({ rawData }: { rawData: any[] }) {
+  // Memoize expensive data processing
+  const processedData = useMemo(() => {
+    return rawData.map(item => ({
+      ...item,
+      // Expensive calculations
+      score: calculateComplexScore(item),
+      category: categorizeItem(item),
+      processed: true
+    }));
+  }, [rawData]);
+
+  // Memoize column configuration
+  const columns = useMemo(() => [
+    { accessorKey: 'name', header: 'Name' },
+    { accessorKey: 'score', header: 'Score' },
+    { accessorKey: 'category', header: 'Category' }
+  ], []);
+
+  return <DataTable data={processedData} columns={columns} />;
+}
+```
+
+### Memory Management
+
+#### Preventing Memory Leaks
+
+```tsx
+import { useEffect, useRef } from 'react';
+
+function DataFetcher() {
+  const isMountedRef = useRef(true);
+
+  useEffect(() => {
+    const fetchData = async () => {
+      try {
+        const data = await api.getData();
+        if (isMountedRef.current) {
+          setData(data);
+        }
+      } catch (error) {
+        if (isMountedRef.current) {
+          setError(error);
+        }
+      }
+    };
+
+    fetchData();
+
+    return () => {
+      isMountedRef.current = false;
+    };
+  }, []);
+
+  // Cleanup subscriptions
+  useEffect(() => {
+    const subscription = eventBus.subscribe('dataUpdate', handleUpdate);
+    
+    return () => {
+      subscription.unsubscribe();
+    };
+  }, []);
+}
+```
+
+#### Efficient State Updates
+
+```tsx
+import { useCallback, useReducer } from 'react';
+
+// Use reducer for complex state
+function dataReducer(state: any, action: any) {
+  switch (action.type) {
+    case 'SET_DATA':
+      return { ...state, data: action.payload };
+    case 'UPDATE_ITEM':
+      return {
+        ...state,
+        data: state.data.map(item =>
+          item.id === action.id ? { ...item, ...action.updates } : item
+        )
+      };
+    case 'DELETE_ITEM':
+      return {
+        ...state,
+        data: state.data.filter(item => item.id !== action.id)
+      };
+    default:
+      return state;
+  }
+}
+
+function OptimizedDataManager() {
+  const [state, dispatch] = useReducer(dataReducer, { data: [], loading: false });
+
+  // Memoize dispatch functions
+  const updateItem = useCallback((id: string, updates: any) => {
+    dispatch({ type: 'UPDATE_ITEM', id, updates });
+  }, []);
+
+  const deleteItem = useCallback((id: string) => {
+    dispatch({ type: 'DELETE_ITEM', id });
+  }, []);
+
+  return (
+    <DataTable
+      data={state.data}
+      onUpdate={updateItem}
+      onDelete={deleteItem}
+    />
+  );
+}
+```
+
+### Network Optimization
+
+#### Request Deduplication
+
+```tsx
+import { useMemo } from 'react';
+
+// Deduplicate identical requests
+const requestCache = new Map();
+
+function useOptimizedFetch(url: string, options: any) {
+  const cacheKey = useMemo(() => 
+    `${url}-${JSON.stringify(options)}`, 
+    [url, options]
+  );
+
+  const fetchData = useCallback(async () => {
+    if (requestCache.has(cacheKey)) {
+      return requestCache.get(cacheKey);
+    }
+
+    const promise = fetch(url, options).then(res => res.json());
+    requestCache.set(cacheKey, promise);
+
+    // Clear cache after 5 minutes
+    setTimeout(() => {
+      requestCache.delete(cacheKey);
+    }, 5 * 60 * 1000);
+
+    return promise;
+  }, [cacheKey]);
+
+  return fetchData;
+}
+```
+
+#### Batch API Calls
+
+```tsx
+import { useCallback } from 'react';
+
+function useBatchRequests() {
+  const batchRequests = useCallback(async (requests: any[]) => {
+    // Group requests by endpoint
+    const groupedRequests = requests.reduce((groups, request) => {
+      const key = request.endpoint;
+      if (!groups[key]) groups[key] = [];
+      groups[key].push(request);
+      return groups;
+    }, {});
+
+    // Execute batches in parallel
+    const results = await Promise.all(
+      Object.entries(groupedRequests).map(([endpoint, batch]) =>
+        api.batchRequest(endpoint, batch)
+      )
+    );
+
+    return results.flat();
+  }, []);
+
+  return batchRequests;
+}
+```
+
+### Code Splitting Strategies
+
+#### Route-Based Splitting
+
+```tsx
+import { lazy, Suspense } from 'react';
+import { Routes, Route } from 'react-router-dom';
+
+// Lazy load route components
+const Dashboard = lazy(() => import('./pages/Dashboard'));
+const Users = lazy(() => import('./pages/Users'));
+const Settings = lazy(() => import('./pages/Settings'));
+
+function App() {
+  return (
+    <Suspense fallback={<LoadingSpinner />}>
+      <Routes>
+        <Route path="/" element={<Dashboard />} />
+        <Route path="/users" element={<Users />} />
+        <Route path="/settings" element={<Settings />} />
+      </Routes>
+    </Suspense>
+  );
+}
+```
+
+#### Feature-Based Splitting
+
+```tsx
+import { lazy, Suspense } from 'react';
+import { useCan } from '@jmruthers/pace-core';
+
+// Lazy load admin features
+const AdminPanel = lazy(() => import('./AdminPanel'));
+const UserManagement = lazy(() => import('./UserManagement'));
+
+function App() {
+  const { hasPermission } = useCan();
+
+  return (
+    <div>
+      <MainContent />
+      
+      {hasPermission('admin:access') && (
+        <Suspense fallback={<div>Loading admin features...</div>}>
+          <AdminPanel />
+        </Suspense>
+      )}
+      
+      {hasPermission('users:manage') && (
+        <Suspense fallback={<div>Loading user management...</div>}>
+          <UserManagement />
+        </Suspense>
+      )}
+    </div>
+  );
+}
+```
+
+### Performance Monitoring
+
+#### Real-Time Performance Tracking
+
+```tsx
+import { useEffect } from 'react';
+
+function usePerformanceMonitor() {
+  useEffect(() => {
+    // Monitor Core Web Vitals
+    const observer = new PerformanceObserver((list) => {
+      for (const entry of list.getEntries()) {
+        console.log('Performance metric:', {
+          name: entry.name,
+          value: entry.value,
+          startTime: entry.startTime
+        });
+      }
+    });
+
+    observer.observe({ entryTypes: ['measure', 'navigation'] });
+
+    return () => observer.disconnect();
+  }, []);
+}
+
+// Usage in components
+function MyComponent() {
+  usePerformanceMonitor();
+  
+  return <div>Component content</div>;
+}
+```
+
+#### Bundle Size Monitoring
+
+```bash
+# Add to package.json scripts
+{
+  "scripts": {
+    "analyze": "npm run build && npx vite-bundle-visualizer",
+    "size-check": "npm run build && npx bundlesize"
+  }
+}
+
+# Monitor bundle size
+npm run analyze
+```
+
+### Performance Testing
+
+#### Automated Performance Tests
+
+```typescript
+// performance.test.ts
+import { render, screen } from '@testing-library/react';
+import { performance } from 'perf_hooks';
+
+describe('Performance Tests', () => {
+  test('DataTable renders within performance budget', async () => {
+    const start = performance.now();
+    
+    render(<DataTable data={largeDataset} columns={columns} />);
+    
+    await screen.findByRole('table');
+    
+    const end = performance.now();
+    const renderTime = end - start;
+    
+    // Should render within 100ms
+    expect(renderTime).toBeLessThan(100);
+  });
+
+  test('Component re-renders are optimized', () => {
+    let renderCount = 0;
+    
+    const TestComponent = () => {
+      renderCount++;
+      return <div>Test</div>;
+    };
+    
+    const { rerender } = render(<TestComponent />);
+    
+    // Re-render with same props
+    rerender(<TestComponent />);
+    
+    // Should not cause unnecessary re-renders
+    expect(renderCount).toBe(1);
+  });
+});
+```
+
+## Performance Checklist
+
+### Development Phase
+- [ ] Use React.memo for expensive components
+- [ ] Implement useCallback for event handlers
+- [ ] Use useMemo for expensive calculations
+- [ ] Implement proper cleanup in useEffect
+- [ ] Use dynamic imports for large components
+- [ ] Optimize bundle with tree shaking
+
+### Production Phase
+- [ ] Enable production optimizations
+- [ ] Monitor Core Web Vitals
+- [ ] Implement performance budgets
+- [ ] Set up performance monitoring
+- [ ] Test with real data volumes
+- [ ] Optimize images and assets
+
+### Monitoring Phase
+- [ ] Track bundle size over time
+- [ ] Monitor render performance
+- [ ] Watch for memory leaks
+- [ ] Analyze user experience metrics
+- [ ] Set up performance alerts
+- [ ] Regular performance audits
+
+## Related Documentation
+
+- [Data Tables Performance](../implementation-guides/data-tables.md#performance-optimization) - DataTable-specific optimizations
+- [Authentication Performance](../implementation-guides/authentication.md#performance) - Auth-related performance
+- [Best Practices Overview](./README.md) - General best practices
+- [Troubleshooting Performance Issues](../troubleshooting/README.md#performance-issues) - Performance debugging
+
 For more information about optimizing your application, see the [Security Guide](./security.md) and [Testing Guide](./testing.md). 

package/docs/best-practices/security.md

@@ -1,3 +1,9 @@
+---
+lastUpdated: 2025-10-29T22:43:00+11:00
+version: 0.5.76
+reviewedBy: content-audit
+---
+
 # Security Best Practices
 
 Security is a critical aspect of any application. This guide provides comprehensive security best practices for using `@jmruthers/pace-core` in your applications.

package/docs/best-practices/testing.md

@@ -1,3 +1,9 @@
+---
+lastUpdated: 2025-10-29T22:43:00+11:00
+version: 0.5.76
+reviewedBy: content-audit
+---
+
 # Testing Best Practices
 
 Comprehensive testing is essential for maintaining code quality and preventing regressions. This guide provides testing strategies and patterns for `@jmruthers/pace-core` applications.

package/docs/core-concepts/authentication.md

@@ -1,3 +1,9 @@
+---
+lastUpdated: 2025-10-29T22:43:00+11:00
+version: 0.5.76
+reviewedBy: content-audit
+---
+
 # Authentication
 
 > **📚 Core Concepts** | [← Back to Documentation](../README.md) | [Quick Start](../getting-started/quick-start.md) | [RBAC](../rbac/README.md)

package/docs/core-concepts/events.md

@@ -1,3 +1,9 @@
+---
+lastUpdated: 2025-10-29T22:43:00+11:00
+version: 0.5.76
+reviewedBy: content-audit
+---
+
 # Events
 
 > **📚 Core Concepts** | [← Back to Documentation](../README.md) | [Organisations](./organisations.md) | [Permissions](./permissions.md)

package/docs/core-concepts/organisations.md

@@ -1,3 +1,9 @@
+---
+lastUpdated: 2025-10-29T22:43:00+11:00
+version: 0.5.76
+reviewedBy: content-audit
+---
+
 # Organisations
 
 > **📚 Core Concepts** | [← Back to Documentation](../README.md) | [Permissions](./permissions.md) | [Events](./events.md)

package/docs/core-concepts/permissions.md

@@ -1,3 +1,9 @@
+---
+lastUpdated: 2025-10-29T22:43:00+11:00
+version: 0.5.76
+reviewedBy: content-audit
+---
+
 # Permissions
 
 > **📚 Core Concepts** | [← Back to Documentation](../README.md) | [RBAC](../rbac/README.md) | [Organisations](./organisations.md)

package/docs/core-concepts/rbac-system.md

@@ -1,3 +1,9 @@
+---
+lastUpdated: 2025-10-29T22:43:00+11:00
+version: 0.5.76
+reviewedBy: content-audit
+---
+
 # RBAC System
 
 > **📚 New Developer?** Start with the [Installation](../getting-started/installation.md) guide, then [Quick Start](../getting-started/quick-start.md) to build your first app.
@@ -6,6 +12,8 @@ PACE Core provides a comprehensive Role-Based Access Control (RBAC) system that
 
 > **🔄 Migrating?** If you're upgrading from the legacy RBAC system, see the [Migration Guide](../migration/rbac-migration.md) for step-by-step instructions.
 
+> **⚠️ IMPORTANT**: You **must** call `setupRBAC()` before using any RBAC features. See the [Quick Start Guide](../rbac/quick-start.md) for setup instructions.
+
 ## Overview
 
 The RBAC system provides: