@jmruthers/pace-core 0.5.76 → 0.5.78

package/docs/performance/README.md

@@ -1,551 +0,0 @@
-# Performance Best Practices
-
-> **⚡ Optimize Your App** | [Bundle Optimization](#bundle-optimization) | [Runtime Performance](#runtime-performance) | [Monitoring](#monitoring)
-
-[← Back to Documentation](../README.md) | [↑ Table of Contents](#table-of-contents) | [Next: Security Checklist →](../security/checklist.md)
-
-Complete guide to optimizing PACE Core applications for maximum performance.
-
-## 📋 Table of Contents
-
-- [Performance Overview](#-performance-overview)
-- [Quick Performance Checklist](#-quick-performance-checklist)
-- [Bundle Optimization](#-bundle-optimization)
-- [Runtime Performance](#-runtime-performance)
-- [Caching Strategies](#-caching-strategies)
-- [Monitoring](#-monitoring)
-- [Performance Best Practices](#-performance-best-practices)
-- [Performance Tools](#-performance-tools)
-- [Additional Resources](#-additional-resources)
-- [Troubleshooting](#-troubleshooting)
-
-## 📊 Performance Overview
-
-This guide covers:
-- **Bundle Optimization** - Reducing bundle size and load time
-- **Runtime Performance** - Optimizing component rendering and state management
-- **Caching Strategies** - Implementing effective caching
-- **Monitoring** - Measuring and tracking performance
-
-## 🚀 Quick Performance Checklist
-
-### Before You Start
-- [ ] **Measure baseline** - Use React DevTools Profiler
-- [ ] **Check bundle size** - Use webpack-bundle-analyzer
-- [ ] **Audit dependencies** - Remove unused packages
-- [ ] **Enable production mode** - Ensure optimizations are enabled
-
-### Performance Targets
-- [ ] **Bundle size** - < 500KB gzipped
-- [ ] **First Contentful Paint** - < 1.5s
-- [ ] **Time to Interactive** - < 3s
-- [ ] **Largest Contentful Paint** - < 2.5s
-
-## 📦 Bundle Optimization
-
-### Tree Shaking
-
-**Enable Tree Shaking**
-```js
-// webpack.config.js
-module.exports = {
-  mode: 'production',
-  optimization: {
-    usedExports: true,
-    sideEffects: false,
-  },
-};
-```
-
-**Import Only What You Need**
-```tsx
-// ❌ Bad - imports entire library
-import * as PACE from '@jmruthers/pace-core';
-
-// ✅ Good - imports only what you need
-import { Button, DataTable } from '@jmruthers/pace-core';
-```
-
-**Use Dynamic Imports**
-```tsx
-// Lazy load heavy components
-const HeavyComponent = React.lazy(() => import('./HeavyComponent'));
-
-function App() {
-  return (
-    <Suspense fallback={<div>Loading...</div>}>
-      <HeavyComponent />
-    </Suspense>
-  );
-}
-```
-
-### Code Splitting
-
-**Route-based Code Splitting**
-```tsx
-import { lazy, Suspense } from 'react';
-import { BrowserRouter, Routes, Route } from 'react-router-dom';
-
-const Dashboard = lazy(() => import('./pages/Dashboard'));
-const Users = lazy(() => import('./pages/Users'));
-const Settings = lazy(() => import('./pages/Settings'));
-
-function App() {
-  return (
-    <BrowserRouter>
-      <Suspense fallback={<div>Loading...</div>}>
-        <Routes>
-          <Route path="/" element={<Dashboard />} />
-          <Route path="/users" element={<Users />} />
-          <Route path="/settings" element={<Settings />} />
-        </Routes>
-      </Suspense>
-    </BrowserRouter>
-  );
-}
-```
-
-**Component-based Code Splitting**
-```tsx
-import { lazy, Suspense } from 'react';
-
-const DataTable = lazy(() => import('@jmruthers/pace-core').then(module => ({ 
-  default: module.DataTable 
-})));
-
-function MyComponent() {
-  return (
-    <Suspense fallback={<div>Loading table...</div>}>
-      <DataTable data={data} columns={columns} />
-    </Suspense>
-  );
-}
-```
-
-### Bundle Analysis
-
-**Analyze Bundle Size**
-```bash
-# Install analyzer
-npm install -D webpack-bundle-analyzer
-
-# Add to package.json
-{
-  "scripts": {
-    "analyze": "webpack-bundle-analyzer build/static/js/*.js"
-  }
-}
-
-# Run analysis
-npm run build
-npm run analyze
-```
-
-**Optimize Dependencies**
-```bash
-# Check for duplicate dependencies
-npm ls --depth=0
-
-# Check bundle size
-npx bundlephobia @jmruthers/pace-core
-
-# Find unused dependencies
-npx depcheck
-```
-
-## ⚡ Runtime Performance
-
-### Component Optimization
-
-**Use React.memo for Expensive Components**
-```tsx
-import React, { memo } from 'react';
-import { DataTable } from '@jmruthers/pace-core';
-
-const ExpensiveTable = memo(({ data, columns }) => {
-  return <DataTable data={data} columns={columns} />;
-});
-
-// Only re-renders when data or columns change
-function App() {
-  const [data, setData] = useState([]);
-  const [otherState, setOtherState] = useState('');
-
-  return (
-    <div>
-      <ExpensiveTable data={data} columns={columns} />
-      <button onClick={() => setOtherState('new value')}>
-        Update Other State
-      </button>
-    </div>
-  );
-}
-```
-
-**Optimize Callbacks with useCallback**
-```tsx
-import { useCallback, useState } from 'react';
-import { DataTable } from '@jmruthers/pace-core';
-
-function MyComponent() {
-  const [data, setData] = useState([]);
-
-  // Memoize expensive callbacks
-  const handleDataChange = useCallback((newData) => {
-    setData(newData);
-  }, []);
-
-  const handleSort = useCallback((column, direction) => {
-    // Expensive sorting logic
-    const sorted = [...data].sort((a, b) => {
-      // Sorting logic
-    });
-    setData(sorted);
-  }, [data]);
-
-  return (
-    <DataTable
-      data={data}
-      columns={columns}
-      onDataChange={handleDataChange}
-      onSort={handleSort}
-    />
-  );
-}
-```
-
-**Optimize Expensive Calculations with useMemo**
-```tsx
-import { useMemo } from 'react';
-import { DataTable } from '@jmruthers/pace-core';
-
-function MyComponent() {
-  const [data, setData] = useState([]);
-  const [filter, setFilter] = useState('');
-
-  // Memoize expensive calculations
-  const filteredData = useMemo(() => {
-    return data.filter(item => 
-      item.name.toLowerCase().includes(filter.toLowerCase())
-    );
-  }, [data, filter]);
-
-  const sortedData = useMemo(() => {
-    return [...filteredData].sort((a, b) => a.name.localeCompare(b.name));
-  }, [filteredData]);
-
-  return (
-    <DataTable data={sortedData} columns={columns} />
-  );
-}
-```
-
-### State Management Optimization
-
-**Avoid Unnecessary Re-renders**
-```tsx
-// ❌ Bad - causes re-render on every state change
-function App() {
-  const [user, setUser] = useState(null);
-  const [theme, setTheme] = useState('light');
-
-  return (
-    <div>
-      <UserProfile user={user} />
-      <ThemeToggle theme={theme} onThemeChange={setTheme} />
-    </div>
-  );
-}
-
-// ✅ Good - separate concerns
-function App() {
-  return (
-    <UserProvider>
-      <UserProfile />
-    </UserProvider>
-  );
-}
-```
-
-**Use Context Selectors**
-```tsx
-import { useContext, useMemo } from 'react';
-import { UserContext } from '@jmruthers/pace-core';
-
-function UserProfile() {
-  // Only re-renders when user changes, not when other context values change
-  const user = useContext(UserContext, (state) => state.user);
-  
-  return <div>{user?.name}</div>;
-}
-```
-
-### Data Table Performance
-
-**Optimize Large Datasets**
-```tsx
-import { DataTable, useVirtualization } from '@jmruthers/pace-core';
-
-function LargeDataTable() {
-  const [data, setData] = useState([]);
-
-  return (
-    <DataTable
-      data={data}
-      columns={columns}
-      // Enable virtualization for large datasets
-      enableVirtualization
-      // Set reasonable page size
-      pageSize={50}
-      // Enable server-side pagination
-      serverSidePagination
-      // Optimize rendering
-      enableRowSelection={false}
-      enableColumnResizing={false}
-    />
-  );
-}
-```
-
-**Implement Pagination**
-```tsx
-import { DataTable } from '@jmruthers/pace-core';
-
-function PaginatedTable() {
-  const [data, setData] = useState([]);
-  const [currentPage, setCurrentPage] = useState(1);
-  const [pageSize, setPageSize] = useState(50);
-
-  const paginatedData = useMemo(() => {
-    const start = (currentPage - 1) * pageSize;
-    const end = start + pageSize;
-    return data.slice(start, end);
-  }, [data, currentPage, pageSize]);
-
-  return (
-    <DataTable
-      data={paginatedData}
-      columns={columns}
-      pagination={{
-        currentPage,
-        pageSize,
-        totalItems: data.length,
-        onPageChange: setCurrentPage,
-        onPageSizeChange: setPageSize,
-      }}
-    />
-  );
-}
-```
-
-## 💾 Caching Strategies
-
-### API Response Caching
-
-**Implement React Query**
-```tsx
-import { useQuery } from '@tanstack/react-query';
-import { DataTable } from '@jmruthers/pace-core';
-
-function UsersTable() {
-  const { data, isLoading, error } = useQuery({
-    queryKey: ['users'],
-    queryFn: fetchUsers,
-    staleTime: 5 * 60 * 1000, // 5 minutes
-    cacheTime: 10 * 60 * 1000, // 10 minutes
-  });
-
-  if (isLoading) return <div>Loading...</div>;
-  if (error) return <div>Error: {error.message}</div>;
-
-  return <DataTable data={data} columns={columns} />;
-}
-```
-
-**Implement SWR**
-```tsx
-import useSWR from 'swr';
-import { DataTable } from '@jmruthers/pace-core';
-
-function UsersTable() {
-  const { data, error } = useSWR('/api/users', fetcher, {
-    revalidateOnFocus: false,
-    revalidateOnReconnect: true,
-    dedupingInterval: 60000, // 1 minute
-  });
-
-  if (error) return <div>Error: {error.message}</div>;
-  if (!data) return <div>Loading...</div>;
-
-  return <DataTable data={data} columns={columns} />;
-}
-```
-
-### Component Caching
-
-**Cache Expensive Components**
-```tsx
-import { memo, useMemo } from 'react';
-import { DataTable } from '@jmruthers/pace-core';
-
-const CachedDataTable = memo(({ data, columns, filters }) => {
-  const filteredData = useMemo(() => {
-    return data.filter(item => 
-      filters.every(filter => filter.predicate(item))
-    );
-  }, [data, filters]);
-
-  return <DataTable data={filteredData} columns={columns} />;
-});
-```
-
-## 📊 Monitoring
-
-### Performance Monitoring
-
-**Use React DevTools Profiler**
-```tsx
-import { Profiler } from 'react';
-
-function onRenderCallback(id, phase, actualDuration) {
-  console.log('Render:', { id, phase, actualDuration });
-}
-
-function App() {
-  return (
-    <Profiler id="App" onRender={onRenderCallback}>
-      <YourApp />
-    </Profiler>
-  );
-}
-```
-
-**Implement Performance Metrics**
-```tsx
-import { useEffect } from 'react';
-
-function usePerformanceMetrics() {
-  useEffect(() => {
-    // Measure First Contentful Paint
-    const observer = new PerformanceObserver((list) => {
-      for (const entry of list.getEntries()) {
-        if (entry.name === 'first-contentful-paint') {
-          console.log('FCP:', entry.startTime);
-        }
-      }
-    });
-    observer.observe({ entryTypes: ['paint'] });
-
-    return () => observer.disconnect();
-  }, []);
-}
-```
-
-**Monitor Bundle Size**
-```tsx
-// Add to your build process
-const BundleAnalyzerPlugin = require('webpack-bundle-analyzer').BundleAnalyzerPlugin;
-
-module.exports = {
-  plugins: [
-    new BundleAnalyzerPlugin({
-      analyzerMode: 'static',
-      openAnalyzer: false,
-    }),
-  ],
-};
-```
-
-### Real User Monitoring
-
-**Implement RUM**
-```tsx
-import { useEffect } from 'react';
-
-function useRUM() {
-  useEffect(() => {
-    // Send performance data to your analytics
-    const sendMetrics = () => {
-      const navigation = performance.getEntriesByType('navigation')[0];
-      const metrics = {
-        loadTime: navigation.loadEventEnd - navigation.loadEventStart,
-        domContentLoaded: navigation.domContentLoadedEventEnd - navigation.domContentLoadedEventStart,
-        firstPaint: performance.getEntriesByName('first-paint')[0]?.startTime,
-        firstContentfulPaint: performance.getEntriesByName('first-contentful-paint')[0]?.startTime,
-      };
-      
-      // Send to your analytics service
-      analytics.track('performance', metrics);
-    };
-
-    window.addEventListener('load', sendMetrics);
-    return () => window.removeEventListener('load', sendMetrics);
-  }, []);
-}
-```
-
-## 🎯 Performance Best Practices
-
-### General Guidelines
-
-1. **Measure First** - Always measure before optimizing
-2. **Optimize Bottlenecks** - Focus on the biggest performance issues
-3. **Test on Real Devices** - Use actual devices, not just desktop
-4. **Monitor Continuously** - Set up performance monitoring
-5. **Keep Dependencies Updated** - Regular updates often include performance improvements
-
-### PACE Core Specific
-
-1. **Use Design Tokens** - Import only the tokens you need
-2. **Lazy Load Components** - Use dynamic imports for heavy components
-3. **Optimize Data Tables** - Use virtualization for large datasets
-4. **Cache API Responses** - Implement proper caching strategies
-5. **Minimize Re-renders** - Use React.memo and useCallback appropriately
-
-## 🛠️ Performance Tools
-
-### Development Tools
-- **React DevTools Profiler** - Component performance analysis
-- **Chrome DevTools** - Network and performance analysis
-- **webpack-bundle-analyzer** - Bundle size analysis
-- **Lighthouse** - Performance auditing
-
-### Production Tools
-- **Web Vitals** - Core web vitals monitoring
-- **Sentry** - Error and performance monitoring
-- **DataDog** - Application performance monitoring
-- **New Relic** - Full-stack performance monitoring
-
-## 📚 Additional Resources
-
-- **[Bundle Optimization Guide](./bundle-optimization.md)** - Detailed bundle optimization
-- **[Runtime Performance Guide](./runtime-performance.md)** - Component optimization
-- **[Caching Strategies](./caching-strategies.md)** - Advanced caching techniques
-- **[Monitoring Guide](./monitoring.md)** - Performance monitoring setup
-
-## 🆘 Troubleshooting
-
-### Common Performance Issues
-
-**Issue 1: Large Bundle Size**
-- Use tree shaking
-- Implement code splitting
-- Remove unused dependencies
-
-**Issue 2: Slow Rendering**
-- Use React.memo
-- Optimize callbacks with useCallback
-- Implement virtualization
-
-**Issue 3: Memory Leaks**
-- Clean up event listeners
-- Cancel API requests
-- Clear timers and intervals
-
-**Issue 4: Slow API Responses**
-- Implement caching
-- Use pagination
-- Optimize database queries
-
-Remember: **Performance is a feature, not an afterthought!**