@jmruthers/pace-core 0.5.76 → 0.5.78

package/docs/best-practices/performance-expansion.md

@@ -1,473 +0,0 @@
-# Performance Optimization - Advanced Topics
-
-> **📚 Best Practices**: Advanced Performance | [← Back](./README.md) | [Basic Performance](./performance.md)
-
-Advanced performance optimization strategies for building high-performance PACE Core applications.
-
----
-
-**Last Updated**: 2025-02-08 | **Version**: v0.5.65+
-
-## Table of Contents
-
-1. [Bundle Optimization](#bundle-optimization)
-2. [React Rendering Optimization](#react-rendering-optimization)
-3. [Memory Management](#memory-management)
-4. [Network Optimization](#network-optimization)
-5. [Code Splitting Strategies](#code-splitting-strategies)
-
----
-
-## 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
-```
-
----
-
-## React Rendering Optimization
-
-### Component Memoization Strategies
-
-#### 1. 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>
-      <h3>{user.name}</h3>
-      <p>{user.email}</p>
-      <button onClick={() => onEdit(user.id)}>Edit</button>
-    </Card>
-  );
-}, (prevProps, nextProps) => {
-  // Custom comparison function
-  return prevProps.user.id === nextProps.user.id &&
-         prevProps.user.name === nextProps.user.name;
-});
-```
-
-#### 2. useMemo for Expensive Calculations
-
-```tsx
-import { useMemo } from 'react';
-
-function EventCalendar({ events }) {
-  const eventsByDate = useMemo(() => {
-    return events.reduce((groups, event) => {
-      const date = event.date.split('T')[0];
-      if (!groups[date]) groups[date] = [];
-      groups[date].push(event);
-      return groups;
-    }, {});
-  }, [events]);
-
-  return (
-    <div>
-      {Object.entries(eventsByDate).map(([date, eventsList]) => (
-        <DateGroup key={date} date={date} events={eventsList} />
-      ))}
-    </div>
-  );
-}
-```
-
-#### 3. useCallback for Event Handlers
-
-```tsx
-import { useCallback } from 'react';
-
-function EventManager({ events, setSelectedEvent }) {
-  const handleEventClick = useCallback((eventId: string) => {
-    const event = events.find(e => e.id === eventId);
-    setSelectedEvent(event);
-  }, [events, setSelectedEvent]);
-
-  return (
-    <div>
-      {events.map(event => (
-        <EventCard
-          key={event.id}
-          event={event}
-          onClick={() => handleEventClick(event.id)}
-        />
-      ))}
-    </div>
-  );
-}
-```
-
----
-
-## Memory Management
-
-### Preventing Memory Leaks
-
-#### 1. Clean Up Effects
-
-```tsx
-import { useEffect, useRef } from 'react';
-
-function DataFetcher({ userId }) {
-  const abortController = useRef(new AbortController());
-
-  useEffect(() => {
-    const fetchData = async () => {
-      try {
-        const response = await fetch(`/api/users/${userId}`, {
-          signal: abortController.current.signal
-        });
-        // Handle response
-      } catch (error) {
-        if (error.name !== 'AbortError') {
-          console.error('Failed to fetch data:', error);
-        }
-      }
-    };
-
-    fetchData();
-
-    return () => {
-      // Clean up on unmount
-      abortController.current.abort();
-    };
-  }, [userId]);
-}
-```
-
-#### 2. Remove Event Listeners
-
-```tsx
-import { useEffect, useRef } from 'react';
-
-function ResizableComponent() {
-  const containerRef = useRef<HTMLDivElement>(null);
-
-  useEffect(() => {
-    const handleResize = () => {
-      // Handle resize
-    };
-
-    const container = containerRef.current;
-    window.addEventListener('resize', handleResize);
-
-    return () => {
-      // Clean up event listener
-      window.removeEventListener('resize', handleResize);
-    };
-  }, []);
-
-  return <div ref={containerRef}>Content</div>;
-}
-```
-
-### Memory Monitoring
-
-```tsx
-function useMemoryMonitor() {
-  useEffect(() => {
-    if (!('memory' in performance)) return;
-
-    const monitor = setInterval(() => {
-      const memory = (performance as any).memory;
-      console.log({
-        used: `${(memory.usedJSHeapSize / 1048576).toFixed(2)} MB`,
-        total: `${(memory.totalJSHeapSize / 1048576).toFixed(2)} MB`,
-        limit: `${(memory.jsHeapSizeLimit / 1048576).toFixed(2)} MB`,
-      });
-    }, 5000);
-
-    return () => clearInterval(monitor);
-  }, []);
-}
-```
-
----
-
-## Network Optimization
-
-### 1. Request Debouncing
-
-```tsx
-import { useState, useEffect } from 'react';
-import { useDebounce } from '@jmruthers/pace-core';
-
-function SearchableDataTable({ data }) {
-  const [searchQuery, setSearchQuery] = useState('');
-  const debouncedQuery = useDebounce(searchQuery, 300);
-
-  useEffect(() => {
-    if (debouncedQuery) {
-      // Perform search
-      const results = data.filter(item => 
-        item.name.toLowerCase().includes(debouncedQuery.toLowerCase())
-      );
-      setFilteredData(results);
-    }
-  }, [debouncedQuery, data]);
-}
-```
-
-### 2. Request Caching
-
-```tsx
-import { useState, useEffect, useRef } from 'react';
-
-function useCachedFetch<T>(url: string, cacheKey: string) {
-  const cache = useRef(new Map<string, T>());
-  const [data, setData] = useState<T | null>(null);
-  const [loading, setLoading] = useState(false);
-
-  useEffect(() => {
-    if (cache.current.has(cacheKey)) {
-      setData(cache.current.get(cacheKey)!);
-      return;
-    }
-
-    setLoading(true);
-    fetch(url)
-      .then(res => res.json())
-      .then(data => {
-        cache.current.set(cacheKey, data);
-        setData(data);
-      })
-      .finally(() => setLoading(false));
-  }, [url, cacheKey]);
-
-  return { data, loading };
-}
-```
-
-### 3. Batch API Requests
-
-```tsx
-async function batchFetchUsers(userIds: string[]) {
-  const chunks = [];
-  const chunkSize = 50;
-
-  for (let i = 0; i < userIds.length; i += chunkSize) {
-    chunks.push(userIds.slice(i, i + chunkSize));
-  }
-
-  const promises = chunks.map(chunk =>
-    fetch('/api/users/batch', {
-      method: 'POST',
-      headers: { 'Content-Type': 'application/json' },
-      body: JSON.stringify({ userIds: chunk })
-    }).then(res => res.json())
-  );
-
-  const results = await Promise.all(promises);
-  return results.flat();
-}
-```
-
----
-
-## Code Splitting Strategies
-
-### 1. Route-Based Code Splitting
-
-```tsx
-import { lazy, Suspense } from 'react';
-import { BrowserRouter, Routes, Route } from 'react-router-dom';
-
-// Lazy load route components
-const Dashboard = lazy(() => import('./pages/Dashboard'));
-const Users = lazy(() => import('./pages/Users'));
-const Events = lazy(() => import('./pages/Events'));
-
-function App() {
-  return (
-    <BrowserRouter>
-      <Suspense fallback={<LoadingSpinner />}>
-        <Routes>
-          <Route path="/" element={<Dashboard />} />
-          <Route path="/users" element={<Users />} />
-          <Route path="/events" element={<Events />} />
-        </Routes>
-      </Suspense>
-    </BrowserRouter>
-  );
-}
-```
-
-### 2. Component-Based Code Splitting
-
-```tsx
-import { lazy, Suspense } from 'react';
-import { Card } from '@jmruthers/pace-core';
-
-// Lazy load heavy components
-const DataTable = lazy(() => import('@jmruthers/pace-core').then(m => ({ default: m.DataTable })));
-const ChartEditor = lazy(() => import('./components/ChartEditor'));
-
-function AnalyticsPage() {
-  return (
-    <div>
-      <Card>
-        <Suspense fallback={<div>Loading table...</div>}>
-          <DataTable data={data} columns={columns} />
-        </Suspense>
-      </Card>
-      <Card>
-        <Suspense fallback={<div>Loading chart...</div>}>
-          <ChartEditor />
-        </Suspense>
-      </Card>
-    </div>
-  );
-}
-```
-
-### 3. Feature-Based Code Splitting
-
-```tsx
-// Split by feature
-const AdminTools = lazy(() => import('./features/AdminTools'));
-const UserManagement = lazy(() => import('./features/UserManagement'));
-
-function App() {
-  const { hasPermission } = useCan();
-  
-  return (
-    <div>
-      {hasPermission('admin:access') && (
-        <Suspense fallback={<LoadingSpinner />}>
-          <AdminTools />
-        </Suspense>
-      )}
-      
-      <Suspense fallback={<LoadingSpinner />}>
-        <UserManagement />
-      </Suspense>
-    </div>
-  );
-}
-```
-
----
-
-## Performance Monitoring
-
-### Real-Time Metrics
-
-```tsx
-import { useEffect } from 'react';
-
-function usePerformanceMetrics() {
-  useEffect(() => {
-    // Track Core Web Vitals
-    const observer = new PerformanceObserver((list) => {
-      for (const entry of list.getEntries()) {
-        console.log({
-          name: entry.name,
-          value: entry.value,
-          type: entry.entryType
-        });
-      }
-    });
-
-    // Observe paint timing
-    observer.observe({ entryTypes: ['paint'] });
-    
-    // Observe navigation timing
-    observer.observe({ entryTypes: ['navigation'] });
-
-    return () => observer.disconnect();
-  }, []);
-}
-```
-
-### Custom Metrics
-
-```tsx
-function trackCustomMetric(name: string, duration: number) {
-  if (typeof window !== 'undefined' && 'performance' in window) {
-    const metric = {
-      name,
-      duration,
-      timestamp: Date.now()
-    };
-
-    // Store in localStorage for analysis
-    const metrics = JSON.parse(localStorage.getItem('metrics') || '[]');
-    metrics.push(metric);
-    localStorage.setItem('metrics', JSON.stringify(metrics.slice(-100)));
-
-    // Or send to analytics
-    // analytics.track('performance', metric);
-  }
-}
-```
-
----
-
-## Related Documentation
-
-- [Performance Best Practices](./performance.md) - Basic performance guidelines
-- [DataTable Performance](./implementation-guides/performance.md) - DataTable-specific optimizations
-- [Security Best Practices](./security.md) - Security considerations
-- [Deployment Best Practices](./deployment.md) - Production deployment
-
----
-
-**Next Steps**: Review your application's performance, identify bottlenecks, and implement these optimizations.

package/docs/breaking-changes.md

@@ -1,179 +0,0 @@
-# PACE Core Breaking Changes
-
-> **📢 Important**: This document tracks all breaking changes in PACE Core.  
-> **Check this file** before upgrading to a new major version.
-
-## Recent Breaking Changes
-
-### v0.5.65+ - Mandatory Inactivity Timeouts
-
-**Status**: ⚠️ **BREAKING CHANGE**  
-**Date**: January 2025  
-**Impact**: High - Affects all apps using `UnifiedAuthProvider`
-
-#### What Changed
-
-The `UnifiedAuthProvider` now requires mandatory inactivity timeout configuration. These props were previously optional but are now required for security and TypeScript compliance.
-
-#### Before (Old Code)
-
-```tsx
-// ❌ This will now cause TypeScript errors
-<UnifiedAuthProvider supabaseClient={supabase} appName="my-app">
-  <App />
-</UnifiedAuthProvider>
-```
-
-#### After (New Code)
-
-```tsx
-// ✅ Required configuration
-<UnifiedAuthProvider 
-  supabaseClient={supabase} 
-  appName="my-app"
-  idleTimeoutMs={30 * 60 * 1000}  // Required: 30 minutes
-  warnBeforeMs={5 * 60 * 1000}    // Required: 5 minutes warning
-  onIdleLogout={() => window.location.href = '/login'}  // Required
->
-  <App />
-</UnifiedAuthProvider>
-```
-
-#### Required Props
-
-| Prop | Type | Required | Description |
-|------|------|----------|-------------|
-| `idleTimeoutMs` | `number` | ✅ Yes | Idle timeout in milliseconds |
-| `warnBeforeMs` | `number` | ✅ Yes | Warning before logout in milliseconds |
-| `onIdleLogout` | `() => void` | ✅ Yes | Callback when user is logged out |
-
-#### Migration Steps
-
-1. **Identify all UnifiedAuthProvider instances** in your codebase
-2. **Add the three required props** to each instance
-3. **Choose appropriate timeout values** for your application
-4. **Test the inactivity warning and logout flow**
-
-#### Migration Guide
-
-See the complete [Migration Guide](./migration-guides/unified-auth-provider-mandatory-timeouts.md) for detailed instructions.
-
-#### Why This Change
-
-This breaking change was made for security reasons:
-- Ensures all apps have automatic logout functionality
-- Prevents security vulnerabilities from idle sessions
-- Provides consistent user experience across all apps
-- Improves overall security posture
-
----
-
-### v2.0.0 - Service Architecture Changes
-
-**Status**: ⚠️ **BREAKING CHANGE**  
-**Date**: December 2024  
-**Impact**: Medium - Affects apps using service architecture
-
-#### What Changed
-
-The library now uses a service-based architecture with pure TypeScript service classes and React integration through providers and hooks.
-
-#### Key Changes
-
-- ✅ **New Service Layer**: Pure TypeScript classes for business logic
-- ✅ **Provider Layer**: React context integration for services
-- ✅ **Hook Layer**: Reactive hooks for component integration
-- ✅ **Backward Compatible**: `UnifiedAuthProvider` maintained for compatibility
-
-#### Migration
-
-The service architecture is now the default. Existing code continues to work without changes:
-
-```tsx
-// Works out of the box - uses service architecture internally
-import { UnifiedAuthProvider } from '@jmruthers/pace-core';
-```
-
-See [Service Architecture Guide](./architecture/services.md) for details.
-
----
-
-## Version History
-
-### v0.5.65+
-- ⚠️ Mandatory inactivity timeouts in UnifiedAuthProvider
-- ⚠️ Breaking TypeScript interface changes
-
-### v2.0.0
-- ⚠️ Service architecture introduced (backward compatible)
-- ⚠️ New provider patterns available
-
-### v0.4.17
-- ⚠️ Source path fixes for Tailwind scanning
-- Migration guide: [v0.4.17 Source Path Fix](./migration/v0.4.17-source-path-fix.md)
-
-### v0.4.16
-- ⚠️ CSS-first approach for Tailwind v4
-- Migration guide: [CSS-First Migration](./migration/v0.4.16-css-first-approach.md)
-
-### v0.4.15
-- ⚠️ Tailwind content scanning requirements
-- Migration guide: [Tailwind Scanning](./migration/v0.4.15-tailwind-scanning.md)
-
-## Checking for Breaking Changes
-
-### Before Upgrading
-
-1. **Check this file** for breaking changes in your target version
-2. **Review migration guides** for each breaking change
-3. **Test in development environment** before production
-4. **Update TypeScript** to catch type errors early
-
-### Finding Your Current Version
-
-```bash
-npm list @jmruthers/pace-core
-```
-
-Or check your `package.json`:
-```json
-{
-  "dependencies": {
-    "@jmruthers/pace-core": "^0.5.65"
-  }
-}
-```
-
-## Migration Resources
-
-- [Unified Migration Guide](./migration/MIGRATION_GUIDE.md)
-- [Service Architecture Migration](./migration/service-architecture.md)
-- [RBAC Migration](./migration/rbac-migration.md)
-- [All Migration Guides](./migration/)
-
-## Getting Help
-
-If you encounter issues during migration:
-
-1. Check the specific migration guide for your breaking change
-2. Review [Troubleshooting](./troubleshooting/common-issues.md)
-3. See [Common Issues](./troubleshooting/common-issues.md)
-4. File an issue with version and error details
-
-## Staying Updated
-
-To stay informed about breaking changes:
-
-- 📢 **Check this file** before each upgrade
-- 📢 **Review release notes** on GitHub
-- 📢 **Subscribe to notifications** for major versions
-- 📢 **Follow migration guides** step-by-step
-
----
-
-**Remember**: Always test breaking changes in a development environment before deploying to production.
-
-**Last Updated**: January 2025  
-**Current Stable Version**: v0.5.65+  
-**Next Major Version**: v1.0.0 (TBD)
-