@jmruthers/pace-core 0.2.4

package/docs/best-practices/performance.md

@@ -0,0 +1,789 @@
+# Performance Best Practices
+
+Performance is crucial for user experience. This guide provides comprehensive performance optimization techniques for `@jmruthers/pace-core` applications.
+
+## Overview
+
+Performance optimization in `@jmruthers/pace-core` focuses on:
+
+- **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
+
+## 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
+// Lazy load components based on user permissions
+function ConditionalComponent({ permission, children }) {
+  const { hasPermission } = useRBAC();
+  const [shouldLoad, setShouldLoad] = useState(false);
+
+  useEffect(() => {
+    if (hasPermission(permission)) {
+      setShouldLoad(true);
+    }
+  }, [hasPermission, permission]);
+
+  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
+
+### 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}`);
+    }
+  });
+}
+```
+
+For more information about optimizing your application, see the [Security Guide](./security.md) and [Testing Guide](./testing.md).