@jmruthers/pace-core 0.6.6 → 0.6.7

package/docs/best-practices/performance.md

@@ -1,1328 +0,0 @@
----
-lastUpdated: 2025-11-18T17:00:00+11:00
-version: 0.5.181
-reviewedBy: documentation-standards-audit
----
-
-# Performance Best Practices
-
-> **📚 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` 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
-
-### 1. Memoization Strategies
-
-```typescript
-import { useMemo, useCallback } from 'react';
-import { useEvents } from '@jmruthers/pace-core';
-
-function OptimizedEventList() {
-  const { events, loading } = useEvents();
-
-  // Memoize expensive calculations
-  const sortedEvents = useMemo(() => {
-    return events?.sort((a, b) => 
-      new Date(a.start_date).getTime() - new Date(b.start_date).getTime()
-    ) || [];
-  }, [events]);
-
-  // Memoize filtered data
-  const upcomingEvents = useMemo(() => {
-    const now = new Date();
-    return sortedEvents.filter(event => 
-      new Date(event.start_date) > now
-    );
-  }, [sortedEvents]);
-
-  // Memoize event groups
-  const eventsByDate = useMemo(() => {
-    return upcomingEvents.reduce((groups, event) => {
-      const date = event.start_date.split('T')[0];
-      if (!groups[date]) groups[date] = [];
-      groups[date].push(event);
-      return groups;
-    }, {});
-  }, [upcomingEvents]);
-
-  if (loading) return <div>Loading...</div>;
-
-  return (
-    <div>
-      {Object.entries(eventsByDate).map(([date, events]) => (
-        <div key={date}>
-          <h3>{date}</h3>
-          {events.map(event => (
-            <EventCard key={event.id} event={event} />
-          ))}
-        </div>
-      ))}
-    </div>
-  );
-}
-```
-
-### 2. Callback Optimization
-
-```typescript
-import { useCallback } from 'react';
-import { useEvents } from '@jmruthers/pace-core';
-
-function EventManager() {
-  const { events, setSelectedEvent, refreshEvents } = useEvents();
-
-  // Memoize event handlers
-  const handleEventSelect = useCallback((event) => {
-    setSelectedEvent(event);
-  }, [setSelectedEvent]);
-
-  const handleRefresh = useCallback(() => {
-    refreshEvents();
-  }, [refreshEvents]);
-
-  const handleEventDelete = useCallback(async (eventId) => {
-    try {
-      await deleteEvent(eventId);
-      refreshEvents();
-    } catch (error) {
-      console.error('Failed to delete event:', error);
-    }
-  }, [refreshEvents]);
-
-  return (
-    <div>
-      <button onClick={handleRefresh}>Refresh</button>
-      {events.map(event => (
-        <EventCard
-          key={event.id}
-          event={event}
-          onSelect={handleEventSelect}
-          onDelete={handleEventDelete}
-        />
-      ))}
-    </div>
-  );
-}
-```
-
-### 3. Component Splitting
-
-```typescript
-// Split large components into smaller, focused components
-function EventDashboard() {
-  const { events, loading } = useEvents();
-
-  if (loading) return <LoadingSpinner />;
-
-  return (
-    <div className="dashboard">
-      <EventSummary events={events} />
-      <EventCalendar events={events} />
-      <EventList events={events} />
-    </div>
-  );
-}
-
-// Separate components for better performance
-const EventSummary = React.memo(({ events }) => {
-  const stats = useMemo(() => ({
-    total: events.length,
-    upcoming: events.filter(e => new Date(e.start_date) > new Date()).length,
-    past: events.filter(e => new Date(e.start_date) < new Date()).length,
-  }), [events]);
-
-  return (
-    <div className="summary">
-      <div>Total: {stats.total}</div>
-      <div>Upcoming: {stats.upcoming}</div>
-      <div>Past: {stats.past}</div>
-    </div>
-  );
-});
-
-const EventCalendar = React.memo(({ events }) => {
-  // Calendar implementation
-  return <div className="calendar">...</div>;
-});
-
-const EventList = React.memo(({ events }) => {
-  // List implementation
-  return <div className="list">...</div>;
-});
-```
-
-## Data Fetching Optimization
-
-### 1. Efficient Data Loading
-
-```typescript
-import { useEvents } from '@jmruthers/pace-core';
-
-function OptimizedEventLoader() {
-  const { events, loading, error, refreshEvents } = useEvents();
-
-  // Implement pagination for large datasets
-  const [page, setPage] = useState(1);
-  const [pageSize, setPageSize] = useState(20);
-
-  const paginatedEvents = useMemo(() => {
-    const start = (page - 1) * pageSize;
-    const end = start + pageSize;
-    return events.slice(start, end);
-  }, [events, page, pageSize]);
-
-  // Implement virtual scrolling for very large lists
-  const VirtualizedEventList = useMemo(() => {
-    return React.memo(({ events }) => {
-      return (
-        <div className="virtual-list">
-          {events.map((event, index) => (
-            <EventRow key={event.id} event={event} index={index} />
-          ))}
-        </div>
-      );
-    });
-  }, []);
-
-  return (
-    <div>
-      <VirtualizedEventList events={paginatedEvents} />
-      <Pagination
-        currentPage={page}
-        totalPages={Math.ceil(events.length / pageSize)}
-        onPageChange={setPage}
-      />
-    </div>
-  );
-}
-```
-
-### 2. Caching Strategies
-
-```typescript
-import { useMemoizedCallback } from '@jmruthers/pace-core';
-
-function CachedDataComponent() {
-  const { events, refreshEvents } = useEvents();
-
-  // Cache expensive operations
-  const eventStats = useMemo(() => {
-    return events.reduce((stats, event) => {
-      const month = new Date(event.start_date).getMonth();
-      stats[month] = (stats[month] || 0) + 1;
-      return stats;
-    }, {});
-  }, [events]);
-
-  // Cache filtered results
-  const [filter, setFilter] = useState('');
-  const filteredEvents = useMemo(() => {
-    if (!filter) return events;
-    return events.filter(event => 
-      event.name.toLowerCase().includes(filter.toLowerCase())
-    );
-  }, [events, filter]);
-
-  // Debounced search
-  const debouncedSetFilter = useMemoizedCallback(
-    (value) => setFilter(value),
-    [],
-    300
-  );
-
-  return (
-    <div>
-      <input
-        type="text"
-        placeholder="Search events..."
-        onChange={(e) => debouncedSetFilter(e.target.value)}
-      />
-      <EventList events={filteredEvents} />
-      <EventStats stats={eventStats} />
-    </div>
-  );
-}
-```
-
-### 3. Background Data Updates
-
-```typescript
-import { useEffect, useRef } from 'react';
-import { useEvents } from '@jmruthers/pace-core';
-
-function AutoRefreshingEventList() {
-  const { events, refreshEvents } = useEvents();
-  const intervalRef = useRef(null);
-
-  // Auto-refresh data in background
-  useEffect(() => {
-    intervalRef.current = setInterval(() => {
-      refreshEvents();
-    }, 30000); // Refresh every 30 seconds
-
-    return () => {
-      if (intervalRef.current) {
-        clearInterval(intervalRef.current);
-      }
-    };
-  }, [refreshEvents]);
-
-  // Pause refresh when tab is not visible
-  useEffect(() => {
-    const handleVisibilityChange = () => {
-      if (document.hidden) {
-        if (intervalRef.current) {
-          clearInterval(intervalRef.current);
-        }
-      } else {
-        intervalRef.current = setInterval(() => {
-          refreshEvents();
-        }, 30000);
-      }
-    };
-
-    document.addEventListener('visibilitychange', handleVisibilityChange);
-    return () => {
-      document.removeEventListener('visibilitychange', handleVisibilityChange);
-    };
-  }, [refreshEvents]);
-
-  return <EventList events={events} />;
-}
-```
-
-## Bundle Size Optimization
-
-### 1. Tree Shaking
-
-```typescript
-// Import only what you need
-import { Button, DataTable } from '@jmruthers/pace-core';
-// Instead of: import * from '@jmruthers/pace-core';
-
-// Use dynamic imports for large components
-const HeavyComponent = React.lazy(() => import('./HeavyComponent'));
-
-function App() {
-  return (
-    <Suspense fallback={<div>Loading...</div>}>
-      <HeavyComponent />
-    </Suspense>
-  );
-}
-```
-
-### 2. Code Splitting
-
-```typescript
-// Split routes by feature
-const AdminDashboard = React.lazy(() => import('./AdminDashboard'));
-const UserDashboard = React.lazy(() => import('./UserDashboard'));
-
-function App() {
-  const { user } = useUnifiedAuth();
-
-  return (
-    <Suspense fallback={<div>Loading dashboard...</div>}>
-      {user?.role === 'admin' ? <AdminDashboard /> : <UserDashboard />}
-    </Suspense>
-  );
-}
-```
-
-### 3. Component Lazy Loading
-
-```typescript
-import { useCan } from '@jmruthers/pace-core/rbac';
-import { useUnifiedAuth } from '@jmruthers/pace-core/providers';
-
-// Lazy load components based on user permissions
-function ConditionalComponent({ permission, children }) {
-  const { user, selectedOrganisationId } = useUnifiedAuth();
-  const { can, isLoading } = useCan(
-    user?.id || '',
-    { organisationId: selectedOrganisationId || '', eventId: undefined, appId: undefined },
-    permission
-  );
-  const [shouldLoad, setShouldLoad] = useState(false);
-
-  useEffect(() => {
-    if (!isLoading && can) {
-      setShouldLoad(true);
-    }
-  }, [can, isLoading]);
-
-  if (!shouldLoad) return null;
-
-  return <Suspense fallback={<div>Loading...</div>}>{children}</Suspense>;
-}
-
-// Usage
-<ConditionalComponent permission="admin:analytics">
-  <AnalyticsDashboard />
-</ConditionalComponent>
-```
-
-## Memory Management
-
-### 1. Cleanup on Unmount
-
-```typescript
-import { useEffect, useRef } from 'react';
-import { useEvents } from '@jmruthers/pace-core';
-
-function EventMonitor() {
-  const { events } = useEvents();
-  const mountedRef = useRef(true);
-
-  useEffect(() => {
-    return () => {
-      mountedRef.current = false;
-    };
-  }, []);
-
-  useEffect(() => {
-    if (!mountedRef.current) return;
-
-    const timer = setInterval(() => {
-      if (mountedRef.current) {
-        // Update logic here
-        console.log('Events updated:', events.length);
-      }
-    }, 5000);
-
-    return () => {
-      clearInterval(timer);
-    };
-  }, [events]);
-
-  return <div>Monitoring {events.length} events</div>;
-}
-```
-
-### 2. Event Listener Cleanup
-
-```typescript
-import { useEffect } from 'react';
-import { useUnifiedAuth } from '@jmruthers/pace-core';
-
-function AuthListener() {
-  const { user, signOut } = useUnifiedAuth();
-
-  useEffect(() => {
-    const handleStorageChange = (e) => {
-      if (e.key === 'supabase.auth.token' && !e.newValue) {
-        // Token was removed, sign out
-        signOut();
-      }
-    };
-
-    window.addEventListener('storage', handleStorageChange);
-    return () => {
-      window.removeEventListener('storage', handleStorageChange);
-    };
-  }, [signOut]);
-
-  return null;
-}
-```
-
-### 3. Large List Optimization
-
-```typescript
-import { useVirtualizer } from '@tanstack/react-virtual';
-import { useEvents } from '@jmruthers/pace-core';
-
-function VirtualizedEventList() {
-  const { events } = useEvents();
-  const parentRef = useRef();
-
-  const rowVirtualizer = useVirtualizer({
-    count: events.length,
-    getScrollElement: () => parentRef.current,
-    estimateSize: () => 100,
-  });
-
-  return (
-    <div ref={parentRef} style={{ height: '400px', overflow: 'auto' }}>
-      <div
-        style={{
-          height: `${rowVirtualizer.getTotalSize()}px`,
-          width: '100%',
-          position: 'relative',
-        }}
-      >
-        {rowVirtualizer.getVirtualItems().map((virtualRow) => {
-          const event = events[virtualRow.index];
-          return (
-            <div
-              key={event.id}
-              style={{
-                position: 'absolute',
-                top: 0,
-                left: 0,
-                width: '100%',
-                height: `${virtualRow.size}px`,
-                transform: `translateY(${virtualRow.start}px)`,
-              }}
-            >
-              <EventCard event={event} />
-            </div>
-          );
-        })}
-      </div>
-    </div>
-  );
-}
-```
-
-## Network Optimization
-
-### RBAC Performance Optimizations
-
-The RBAC system includes built-in performance optimizations that significantly reduce network requests:
-
-- **Request Deduplication**: Multiple components checking the same permission share network requests
-- **Enhanced Caching**: Two-tier caching (60s short-term + 5min session cache)
-- **Batched Audit Logging**: Audit events are batched to reduce network requests
-- **Memoization**: Components are memoized to prevent unnecessary re-renders
-
-See the [RBAC Performance Guide](../rbac/performance.md) for detailed information.
-
-### 1. Request Deduplication
-
-```typescript
-import { useMemoizedCallback } from '@jmruthers/pace-core';
-
-function OptimizedDataFetcher() {
-  const { supabase } = useSupabase();
-  const requestCache = useRef(new Map());
-
-  const fetchEventData = useMemoizedCallback(async (eventId) => {
-    // Check cache first
-    if (requestCache.current.has(eventId)) {
-      return requestCache.current.get(eventId);
-    }
-
-    // Make request
-    const { data, error } = await supabase
-      .from('events')
-      .select('*')
-      .eq('id', eventId)
-      .single();
-
-    if (error) throw error;
-
-    // Cache result
-    requestCache.current.set(eventId, data);
-    return data;
-  }, [supabase]);
-
-  return (
-    <div>
-      {eventIds.map(id => (
-        <EventDetails key={id} eventId={id} onFetch={fetchEventData} />
-      ))}
-    </div>
-  );
-}
-```
-
-### 2. Batch Requests
-
-```typescript
-import { useSupabase } from '@jmruthers/pace-core';
-
-function BatchDataFetcher() {
-  const { supabase } = useSupabase();
-  const [events, setEvents] = useState([]);
-  const [loading, setLoading] = useState(false);
-
-  const fetchEventsBatch = async (eventIds) => {
-    setLoading(true);
-    try {
-      const { data, error } = await supabase
-        .from('events')
-        .select('*')
-        .in('id', eventIds);
-
-      if (error) throw error;
-      setEvents(data);
-    } catch (error) {
-      console.error('Failed to fetch events:', error);
-    } finally {
-      setLoading(false);
-    }
-  };
-
-  return (
-    <div>
-      {loading && <div>Loading...</div>}
-      <EventList events={events} />
-    </div>
-  );
-}
-```
-
-### 3. Progressive Loading
-
-```typescript
-import { useState, useEffect } from 'react';
-import { useEvents } from '@jmruthers/pace-core';
-
-function ProgressiveEventList() {
-  const { events } = useEvents();
-  const [visibleEvents, setVisibleEvents] = useState([]);
-  const [page, setPage] = useState(1);
-  const pageSize = 10;
-
-  useEffect(() => {
-    const start = 0;
-    const end = page * pageSize;
-    setVisibleEvents(events.slice(start, end));
-  }, [events, page]);
-
-  const loadMore = () => {
-    setPage(prev => prev + 1);
-  };
-
-  const hasMore = visibleEvents.length < events.length;
-
-  return (
-    <div>
-      {visibleEvents.map(event => (
-        <EventCard key={event.id} event={event} />
-      ))}
-      {hasMore && (
-        <button onClick={loadMore}>
-          Load More ({events.length - visibleEvents.length} remaining)
-        </button>
-      )}
-    </div>
-  );
-}
-```
-
-## Performance Monitoring
-
-### 1. Component Performance Tracking
-
-```typescript
-import { useComponentPerformance } from '@jmruthers/pace-core';
-
-function PerformanceMonitor() {
-  const { renderCount, averageRenderTime, lastRenderTime } = useComponentPerformance();
-
-  useEffect(() => {
-    if (averageRenderTime > 16) { // 60fps threshold
-      console.warn('Component rendering slowly:', averageRenderTime);
-    }
-  }, [averageRenderTime]);
-
-  return (
-    <div className="performance-monitor">
-      <div>Renders: {renderCount}</div>
-      <div>Avg Time: {averageRenderTime.toFixed(2)}ms</div>
-      <div>Last Render: {lastRenderTime.toFixed(2)}ms</div>
-    </div>
-  );
-}
-```
-
-### 2. Network Performance
-
-```typescript
-import { useUnifiedAuth } from '@jmruthers/pace-core';
-
-function NetworkMonitor() {
-  const { error } = useUnifiedAuth();
-  const [networkStats, setNetworkStats] = useState({
-    requests: 0,
-    errors: 0,
-    avgResponseTime: 0,
-  });
-
-  useEffect(() => {
-    const startTime = performance.now();
-    
-    return () => {
-      const endTime = performance.now();
-      const responseTime = endTime - startTime;
-      
-      setNetworkStats(prev => ({
-        ...prev,
-        requests: prev.requests + 1,
-        avgResponseTime: (prev.avgResponseTime + responseTime) / 2,
-      }));
-    };
-  }, []);
-
-  return (
-    <div className="network-monitor">
-      <div>Requests: {networkStats.requests}</div>
-      <div>Errors: {networkStats.errors}</div>
-      <div>Avg Response: {networkStats.avgResponseTime.toFixed(2)}ms</div>
-    </div>
-  );
-}
-```
-
-### 3. Memory Usage Monitoring
-
-```typescript
-function MemoryMonitor() {
-  const [memoryInfo, setMemoryInfo] = useState(null);
-
-  useEffect(() => {
-    const updateMemoryInfo = () => {
-      if ('memory' in performance) {
-        setMemoryInfo({
-          used: performance.memory.usedJSHeapSize,
-          total: performance.memory.totalJSHeapSize,
-          limit: performance.memory.jsHeapSizeLimit,
-        });
-      }
-    };
-
-    const interval = setInterval(updateMemoryInfo, 5000);
-    updateMemoryInfo();
-
-    return () => clearInterval(interval);
-  }, []);
-
-  if (!memoryInfo) return null;
-
-  const usagePercent = (memoryInfo.used / memoryInfo.limit) * 100;
-
-  return (
-    <div className="memory-monitor">
-      <div>Memory Usage: {usagePercent.toFixed(1)}%</div>
-      <div>Used: {(memoryInfo.used / 1024 / 1024).toFixed(1)}MB</div>
-      <div>Total: {(memoryInfo.total / 1024 / 1024).toFixed(1)}MB</div>
-    </div>
-  );
-}
-```
-
-## Performance Best Practices Checklist
-
-### Development Checklist
-
-- [ ] Use React.memo for expensive components
-- [ ] Memoize expensive calculations with useMemo
-- [ ] Memoize event handlers with useCallback
-- [ ] Implement proper cleanup in useEffect
-- [ ] Use lazy loading for large components
-- [ ] Implement virtual scrolling for large lists
-- [ ] Cache expensive API calls
-- [ ] Debounce user input
-- [ ] Optimize bundle size with tree shaking
-- [ ] Monitor component render performance
-
-### Production Checklist
-
-- [ ] Enable production builds
-- [ ] Implement proper error boundaries
-- [ ] Set up performance monitoring
-- [ ] Optimize images and assets
-- [ ] Configure proper caching headers
-- [ ] Implement service workers for offline support
-- [ ] Monitor Core Web Vitals
-- [ ] Set up automated performance testing
-- [ ] Configure CDN for static assets
-- [ ] Implement progressive loading
-
-### Monitoring Checklist
-
-- [ ] Track component render times
-- [ ] Monitor API response times
-- [ ] Track memory usage
-- [ ] Monitor bundle size
-- [ ] Set up performance alerts
-- [ ] Track user experience metrics
-- [ ] Monitor error rates
-- [ ] Track loading times
-- [ ] Monitor Core Web Vitals
-- [ ] Set up automated performance reports
-
-## Performance Tools
-
-### 1. React DevTools Profiler
-
-```typescript
-import { Profiler } from 'react';
-
-function ProfiledComponent() {
-  const onRenderCallback = (id, phase, actualDuration) => {
-    console.log(`Component ${id} took ${actualDuration}ms to ${phase}`);
-  };
-
-  return (
-    <Profiler id="EventList" onRender={onRenderCallback}>
-      <EventList />
-    </Profiler>
-  );
-}
-```
-
-### 2. Custom Performance Hooks
-
-```typescript
-function usePerformanceMonitor(componentName) {
-  const renderCount = useRef(0);
-  const startTime = useRef(performance.now());
-
-  useEffect(() => {
-    renderCount.current += 1;
-    const renderTime = performance.now() - startTime.current;
-    
-    console.log(`${componentName} rendered in ${renderTime.toFixed(2)}ms`);
-    startTime.current = performance.now();
-  });
-}
-```
-
-### 3. Performance Budgets
-
-```typescript
-// Set performance budgets
-const PERFORMANCE_BUDGETS = {
-  firstContentfulPaint: 1500, // 1.5s
-  largestContentfulPaint: 2500, // 2.5s
-  firstInputDelay: 100, // 100ms
-  cumulativeLayoutShift: 0.1, // 0.1
-};
-
-function checkPerformanceBudget(metrics) {
-  Object.entries(PERFORMANCE_BUDGETS).forEach(([metric, budget]) => {
-    if (metrics[metric] > budget) {
-      console.warn(`${metric} exceeded budget: ${metrics[metric]} > ${budget}`);
-    }
-  });
-}
-```
-
-## 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
-
-## ♿ Accessibility
-
-Performance optimizations should maintain accessibility:
-
-- **Lazy loading doesn't break screen readers** - Ensure lazy-loaded content is accessible
-- **Code splitting maintains keyboard navigation** - Verify keyboard navigation works after code splitting
-- **Memoization doesn't affect focus management** - Ensure focus handling remains correct
-- **Performance optimizations are tested with assistive technologies** - Verify optimizations don't break accessibility
-- **Loading states are announced** - Screen readers should announce performance-related loading states
-
-### Accessibility Best Practices
-
-1. **Test optimizations with screen readers** - Verify performance improvements don't break accessibility
-2. **Ensure keyboard navigation** - All optimized components should remain keyboard accessible
-3. **Maintain focus visibility** - Focus indicators should remain visible after optimizations
-4. **Test with assistive technologies** - Verify performance optimizations work with screen readers
-5. **Balance performance and accessibility** - Don't sacrifice accessibility for performance gains
-
-## ⚠️ Edge Cases
-
-### Performance vs Accessibility Trade-offs
-
-When performance optimizations impact accessibility:
-- Find balance between performance and accessibility
-- Test optimizations with assistive technologies
-- Ensure lazy loading doesn't break screen reader navigation
-- Verify code splitting maintains keyboard navigation
-- Document trade-offs when necessary
-
-### Over-Optimization Issues
-
-When over-optimization causes problems:
-- Monitor for premature optimization
-- Test optimizations in real-world scenarios
-- Profile before and after optimizations
-- Verify optimizations provide measurable benefits
-- Consider maintainability when optimizing
-
-### Performance Regression
-
-When performance degrades after optimizations:
-- Profile to identify bottlenecks
-- Test with realistic data volumes
-- Monitor performance metrics
-- Rollback optimizations if needed
-- Document performance regression causes
-
-For more information about optimizing your application, see the [Security Guide](./security.md) and [Testing Guide](./testing.md).