@jmruthers/pace-core 0.5.54 → 0.5.55

package/docs/implementation-guides/inactivity-tracking.md

@@ -0,0 +1,779 @@
+# Inactivity Tracking
+
+> **⏰ User Session Management** | [← Back to Documentation](../README.md) | [↑ Table of Contents](#table-of-contents)
+
+Complete guide to implementing user inactivity tracking with automatic warnings and session management.
+
+## Overview
+
+PACE Core provides comprehensive inactivity tracking with:
+- **Cross-tab Synchronization** - Activity tracked across all browser tabs
+- **Configurable Timeouts** - Customizable idle and warning periods
+- **Automatic Warnings** - User-friendly inactivity warnings
+- **Session Management** - Integration with authentication systems
+- **Accessibility Support** - Screen reader friendly warnings
+- **Performance Optimized** - Throttled event handling
+
+## Architecture
+
+```mermaid
+graph TD
+    A[User Activity] --> B[useInactivityTracker Hook]
+    B --> C[BroadcastChannel]
+    C --> D[Cross-tab Sync]
+    B --> E[Local Storage]
+    E --> F[Persistence]
+    B --> G[InactivityWarningModal]
+    G --> H[User Action]
+    H --> I[Reset Timer]
+    B --> J[onIdle Callback]
+    J --> K[Sign Out]
+```
+
+## Quick Start
+
+### 1. Basic Inactivity Tracking
+
+```tsx
+import { useInactivityTracker, InactivityWarningModal } from '@jmruthers/pace-core';
+
+function App() {
+  const { isIdle, timeRemaining, showWarning, resetActivity } = useInactivityTracker({
+    idleTimeoutMs: 30 * 60 * 1000, // 30 minutes
+    warnBeforeMs: 5 * 60 * 1000,   // 5 minutes warning
+    onIdle: () => {
+      console.log('User is idle - signing out');
+      signOut();
+    },
+    onWarning: () => {
+      console.log('Showing inactivity warning');
+    }
+  });
+
+  return (
+    <div>
+      <h1>My App</h1>
+      <p>Idle: {isIdle ? 'Yes' : 'No'}</p>
+      <p>Time remaining: {Math.floor(timeRemaining / 1000)}s</p>
+      
+      <InactivityWarningModal
+        isOpen={showWarning}
+        timeRemaining={timeRemaining}
+        onStayActive={resetActivity}
+        onSignOut={() => signOut()}
+      />
+    </div>
+  );
+}
+```
+
+### 2. Integration with Authentication
+
+```tsx
+import { useInactivityTracker, InactivityWarningModal } from '@jmruthers/pace-core';
+import { useUnifiedAuth } from '@jmruthers/pace-core';
+
+function AuthenticatedApp() {
+  const { signOut } = useUnifiedAuth();
+  
+  const {
+    isIdle,
+    timeRemaining,
+    showWarning,
+    resetActivity,
+    startTracking,
+    stopTracking
+  } = useInactivityTracker({
+    idleTimeoutMs: 15 * 60 * 1000, // 15 minutes
+    warnBeforeMs: 2 * 60 * 1000,   // 2 minutes warning
+    onIdle: () => {
+      console.log('User inactive - signing out');
+      signOut();
+    },
+    onWarning: () => {
+      console.log('Inactivity warning triggered');
+    },
+    onActivity: () => {
+      console.log('User activity detected');
+    }
+  });
+
+  // Start tracking when component mounts
+  useEffect(() => {
+    startTracking();
+    return () => stopTracking();
+  }, [startTracking, stopTracking]);
+
+  return (
+    <div>
+      <h1>Dashboard</h1>
+      <p>Status: {isIdle ? 'Idle' : 'Active'}</p>
+      
+      <InactivityWarningModal
+        isOpen={showWarning}
+        timeRemaining={timeRemaining}
+        onStayActive={resetActivity}
+        onSignOut={signOut}
+        title="Session Timeout Warning"
+        message="You will be signed out due to inactivity."
+        stayActiveText="Stay Active"
+        signOutText="Sign Out Now"
+      />
+    </div>
+  );
+}
+```
+
+## Components
+
+### InactivityWarningModal
+
+A modal component that displays inactivity warnings with countdown timer and action buttons.
+
+#### Props
+
+```typescript
+interface InactivityWarningModalProps {
+  isOpen: boolean;
+  timeRemaining: number;
+  onStayActive: () => void;
+  onSignOut: () => void;
+  title?: string;
+  message?: string;
+  stayActiveText?: string;
+  signOutText?: string;
+  className?: string;
+}
+```
+
+#### Usage Examples
+
+**Basic Warning Modal:**
+```tsx
+<InactivityWarningModal
+  isOpen={showWarning}
+  timeRemaining={timeRemaining}
+  onStayActive={resetActivity}
+  onSignOut={signOut}
+/>
+```
+
+**Customized Warning Modal:**
+```tsx
+<InactivityWarningModal
+  isOpen={showWarning}
+  timeRemaining={timeRemaining}
+  onStayActive={resetActivity}
+  onSignOut={signOut}
+  title="Session Expiring Soon"
+  message="Your session will expire in {time} seconds due to inactivity."
+  stayActiveText="Continue Working"
+  signOutText="End Session"
+  className="custom-warning-modal"
+/>
+```
+
+**Custom Styling:**
+```tsx
+<InactivityWarningModal
+  isOpen={showWarning}
+  timeRemaining={timeRemaining}
+  onStayActive={resetActivity}
+  onSignOut={signOut}
+  className="bg-main-50 border-main-300"
+/>
+```
+
+## Hooks
+
+### useInactivityTracker
+
+Primary hook for tracking user inactivity with comprehensive configuration options.
+
+#### Interface
+
+```typescript
+interface UseInactivityTrackerOptions {
+  /** Timeout in milliseconds before user is considered idle (default: 30 minutes) */
+  idleTimeoutMs?: number;
+  
+  /** Time in milliseconds before idle to show warning (default: 5 minutes) */
+  warnBeforeMs?: number;
+  
+  /** Callback when user becomes idle */
+  onIdle?: () => void;
+  
+  /** Callback when warning should be shown */
+  onWarning?: () => void;
+  
+  /** Callback when user activity is detected */
+  onActivity?: () => void;
+  
+  /** Events to track for activity (default: all) */
+  events?: string[];
+  
+  /** Throttle interval for event handling (default: 100ms) */
+  throttleMs?: number;
+  
+  /** Enable cross-tab synchronization (default: true) */
+  enableCrossTabSync?: boolean;
+  
+  /** Storage key for persistence (default: 'pace-inactivity') */
+  storageKey?: string;
+  
+  /** Enable debug logging (default: false) */
+  debug?: boolean;
+}
+
+interface UseInactivityTrackerReturn {
+  /** Whether user is currently idle */
+  isIdle: boolean;
+  
+  /** Time remaining before idle (in milliseconds) */
+  timeRemaining: number;
+  
+  /** Whether warning should be shown */
+  showWarning: boolean;
+  
+  /** Reset the inactivity timer */
+  resetActivity: () => void;
+  
+  /** Start tracking activity */
+  startTracking: () => void;
+  
+  /** Stop tracking activity */
+  stopTracking: () => void;
+  
+  /** Get current activity status */
+  getActivityStatus: () => {
+    isIdle: boolean;
+    timeRemaining: number;
+    lastActivity: number;
+  };
+}
+```
+
+#### Usage Examples
+
+**Basic Configuration:**
+```tsx
+import { useInactivityTracker } from '@jmruthers/pace-core';
+
+function MyComponent() {
+  const { isIdle, timeRemaining, showWarning, resetActivity } = useInactivityTracker({
+    idleTimeoutMs: 20 * 60 * 1000, // 20 minutes
+    warnBeforeMs: 3 * 60 * 1000,   // 3 minutes warning
+    onIdle: () => {
+      console.log('User is idle');
+      // Handle idle state
+    }
+  });
+
+  return (
+    <div>
+      <p>Idle: {isIdle ? 'Yes' : 'No'}</p>
+      <p>Time remaining: {Math.floor(timeRemaining / 1000)}s</p>
+    </div>
+  );
+}
+```
+
+**Advanced Configuration:**
+```tsx
+import { useInactivityTracker } from '@jmruthers/pace-core';
+
+function AdvancedComponent() {
+  const {
+    isIdle,
+    timeRemaining,
+    showWarning,
+    resetActivity,
+    startTracking,
+    stopTracking,
+    getActivityStatus
+  } = useInactivityTracker({
+    idleTimeoutMs: 45 * 60 * 1000, // 45 minutes
+    warnBeforeMs: 10 * 60 * 1000,  // 10 minutes warning
+    events: ['mousedown', 'keydown', 'scroll', 'touchstart'], // Custom events
+    throttleMs: 200, // Throttle to 200ms
+    enableCrossTabSync: true,
+    storageKey: 'my-app-inactivity',
+    debug: process.env.NODE_ENV === 'development',
+    onIdle: () => {
+      console.log('User idle - performing cleanup');
+      // Save work, clear sensitive data, etc.
+    },
+    onWarning: () => {
+      console.log('Warning: User will be idle soon');
+      // Show notification, play sound, etc.
+    },
+    onActivity: () => {
+      console.log('User activity detected');
+      // Hide warnings, reset notifications, etc.
+    }
+  });
+
+  // Manual control
+  const handlePauseTracking = () => {
+    stopTracking();
+  };
+
+  const handleResumeTracking = () => {
+    startTracking();
+  };
+
+  const handleCheckStatus = () => {
+    const status = getActivityStatus();
+    console.log('Current status:', status);
+  };
+
+  return (
+    <div>
+      <div className="space-y-2">
+        <p>Status: {isIdle ? 'Idle' : 'Active'}</p>
+        <p>Time remaining: {Math.floor(timeRemaining / 1000)}s</p>
+        <p>Warning: {showWarning ? 'Yes' : 'No'}</p>
+      </div>
+      
+      <div className="space-x-2">
+        <Button onClick={resetActivity}>Reset Timer</Button>
+        <Button onClick={handlePauseTracking}>Pause Tracking</Button>
+        <Button onClick={handleResumeTracking}>Resume Tracking</Button>
+        <Button onClick={handleCheckStatus}>Check Status</Button>
+      </div>
+    </div>
+  );
+}
+```
+
+## Configuration Options
+
+### Timeout Configuration
+
+```tsx
+// Short session (5 minutes idle, 1 minute warning)
+const shortSession = useInactivityTracker({
+  idleTimeoutMs: 5 * 60 * 1000,
+  warnBeforeMs: 1 * 60 * 1000
+});
+
+// Long session (2 hours idle, 15 minutes warning)
+const longSession = useInactivityTracker({
+  idleTimeoutMs: 2 * 60 * 60 * 1000,
+  warnBeforeMs: 15 * 60 * 1000
+});
+
+// No warning (immediate idle)
+const immediateIdle = useInactivityTracker({
+  idleTimeoutMs: 10 * 60 * 1000,
+  warnBeforeMs: 0
+});
+```
+
+### Event Tracking
+
+```tsx
+// Track only mouse and keyboard events
+const basicTracking = useInactivityTracker({
+  events: ['mousedown', 'keydown']
+});
+
+// Track all user interactions
+const fullTracking = useInactivityTracker({
+  events: [
+    'mousedown',
+    'mousemove',
+    'keydown',
+    'keyup',
+    'scroll',
+    'touchstart',
+    'touchmove',
+    'focus',
+    'blur'
+  ]
+});
+
+// Custom event tracking
+const customTracking = useInactivityTracker({
+  events: ['click', 'input', 'change', 'submit']
+});
+```
+
+### Cross-Tab Synchronization
+
+```tsx
+// Enable cross-tab sync (default)
+const syncedTracking = useInactivityTracker({
+  enableCrossTabSync: true
+});
+
+// Disable cross-tab sync
+const localTracking = useInactivityTracker({
+  enableCrossTabSync: false
+});
+```
+
+## Integration Patterns
+
+### Authentication Integration
+
+```tsx
+import { useInactivityTracker, InactivityWarningModal } from '@jmruthers/pace-core';
+import { useUnifiedAuth } from '@jmruthers/pace-core';
+
+function AuthenticatedApp() {
+  const { user, signOut, loading } = useUnifiedAuth();
+  
+  const {
+    isIdle,
+    timeRemaining,
+    showWarning,
+    resetActivity
+  } = useInactivityTracker({
+    idleTimeoutMs: 30 * 60 * 1000,
+    warnBeforeMs: 5 * 60 * 1000,
+    onIdle: () => {
+      console.log('User idle - signing out');
+      signOut();
+    },
+    onWarning: () => {
+      console.log('Inactivity warning');
+    }
+  });
+
+  // Don't track inactivity if not authenticated
+  if (loading || !user) {
+    return <div>Loading...</div>;
+  }
+
+  return (
+    <div>
+      <h1>Welcome, {user.email}</h1>
+      
+      <InactivityWarningModal
+        isOpen={showWarning}
+        timeRemaining={timeRemaining}
+        onStayActive={resetActivity}
+        onSignOut={signOut}
+      />
+    </div>
+  );
+}
+```
+
+### Form Integration
+
+```tsx
+import { useInactivityTracker } from '@jmruthers/pace-core';
+import { useForm } from 'react-hook-form';
+
+function LongForm() {
+  const { formState: { isDirty } } = useForm();
+  
+  const { isIdle, showWarning, resetActivity } = useInactivityTracker({
+    idleTimeoutMs: 10 * 60 * 1000, // 10 minutes
+    warnBeforeMs: 2 * 60 * 1000,   // 2 minutes warning
+    onIdle: () => {
+      if (isDirty) {
+        // Save draft before signing out
+        saveDraft();
+      }
+      signOut();
+    }
+  });
+
+  return (
+    <form>
+      {/* Form fields */}
+      
+      {showWarning && isDirty && (
+        <div className="bg-acc-100 border border-acc-300 rounded p-4">
+          <p>You have unsaved changes. Your session will expire soon.</p>
+          <Button onClick={resetActivity}>Continue Editing</Button>
+        </div>
+      )}
+    </form>
+  );
+}
+```
+
+### Multi-Step Process Integration
+
+```tsx
+import { useInactivityTracker } from '@jmruthers/pace-core';
+
+function MultiStepProcess() {
+  const [currentStep, setCurrentStep] = useState(0);
+  const [formData, setFormData] = useState({});
+  
+  const { isIdle, showWarning, resetActivity } = useInactivityTracker({
+    idleTimeoutMs: 15 * 60 * 1000,
+    warnBeforeMs: 3 * 60 * 1000,
+    onIdle: () => {
+      // Save progress before signing out
+      saveProgress(formData, currentStep);
+      signOut();
+    }
+  });
+
+  return (
+    <div>
+      <h2>Step {currentStep + 1} of 5</h2>
+      
+      {/* Step content */}
+      
+      {showWarning && (
+        <div className="fixed bottom-4 right-4 bg-main-600 text-main-50 p-4 rounded">
+          <p>Your session will expire soon. Save your progress?</p>
+          <Button onClick={resetActivity}>Continue</Button>
+        </div>
+      )}
+    </div>
+  );
+}
+```
+
+## Accessibility
+
+### Screen Reader Support
+
+The `InactivityWarningModal` includes proper ARIA attributes and announcements:
+
+```tsx
+<InactivityWarningModal
+  isOpen={showWarning}
+  timeRemaining={timeRemaining}
+  onStayActive={resetActivity}
+  onSignOut={signOut}
+  // Automatically includes:
+  // - role="alertdialog"
+  // - aria-labelledby
+  // - aria-describedby
+  // - Live region for countdown updates
+/>
+```
+
+### Keyboard Navigation
+
+The modal supports full keyboard navigation:
+- **Tab** - Navigate between buttons
+- **Enter/Space** - Activate focused button
+- **Escape** - Close modal (if configured)
+
+### Focus Management
+
+```tsx
+import { useInactivityTracker } from '@jmruthers/pace-core';
+
+function AccessibleApp() {
+  const { showWarning, resetActivity } = useInactivityTracker({
+    // ... configuration
+  });
+
+  // Focus management for accessibility
+  useEffect(() => {
+    if (showWarning) {
+      // Focus will be automatically managed by the modal
+      // The modal will trap focus and return it when closed
+    }
+  }, [showWarning]);
+
+  return (
+    <div>
+      {/* App content */}
+      
+      <InactivityWarningModal
+        isOpen={showWarning}
+        timeRemaining={timeRemaining}
+        onStayActive={resetActivity}
+        onSignOut={signOut}
+        // Focus management is handled automatically
+      />
+    </div>
+  );
+}
+```
+
+## Performance Considerations
+
+### Throttling
+
+The hook uses throttling to prevent excessive event handling:
+
+```tsx
+// Default throttling (100ms)
+const defaultThrottling = useInactivityTracker({
+  // Events are throttled to 100ms by default
+});
+
+// Custom throttling
+const customThrottling = useInactivityTracker({
+  throttleMs: 500 // Throttle to 500ms
+});
+
+// No throttling (not recommended for performance)
+const noThrottling = useInactivityTracker({
+  throttleMs: 0
+});
+```
+
+### Memory Management
+
+The hook automatically cleans up event listeners and timers:
+
+```tsx
+function MyComponent() {
+  const inactivityTracker = useInactivityTracker({
+    // ... configuration
+  });
+
+  // Cleanup is automatic when component unmounts
+  // No manual cleanup required
+}
+```
+
+### Cross-Tab Optimization
+
+Cross-tab synchronization is optimized to minimize performance impact:
+
+```tsx
+// Optimized cross-tab sync
+const optimizedSync = useInactivityTracker({
+  enableCrossTabSync: true,
+  // Uses BroadcastChannel API for efficient communication
+  // Minimal memory footprint
+  // Automatic cleanup
+});
+```
+
+## Troubleshooting
+
+### Common Issues
+
+**Issue: Timer not resetting on activity**
+- Check that events are being tracked correctly
+- Verify throttle settings aren't too high
+- Ensure event listeners are properly attached
+
+**Issue: Cross-tab sync not working**
+- Check browser support for BroadcastChannel API
+- Verify storage permissions
+- Check for conflicting storage keys
+
+**Issue: Modal not showing**
+- Verify `showWarning` state is true
+- Check that `timeRemaining` is greater than 0
+- Ensure modal is rendered in the component tree
+
+### Debug Mode
+
+Enable debug logging to troubleshoot issues:
+
+```tsx
+const { isIdle, timeRemaining, showWarning } = useInactivityTracker({
+  debug: true, // Enable debug logging
+  // ... other options
+});
+
+// Debug output will show:
+// - Event tracking
+// - Timer updates
+// - Cross-tab communication
+// - State changes
+```
+
+### Manual Testing
+
+```tsx
+function DebugComponent() {
+  const {
+    isIdle,
+    timeRemaining,
+    showWarning,
+    resetActivity,
+    getActivityStatus
+  } = useInactivityTracker({
+    idleTimeoutMs: 10 * 1000, // 10 seconds for testing
+    warnBeforeMs: 5 * 1000,   // 5 seconds warning
+    debug: true
+  });
+
+  const status = getActivityStatus();
+
+  return (
+    <div>
+      <h3>Debug Information</h3>
+      <p>Is Idle: {isIdle ? 'Yes' : 'No'}</p>
+      <p>Time Remaining: {timeRemaining}ms</p>
+      <p>Show Warning: {showWarning ? 'Yes' : 'No'}</p>
+      <p>Last Activity: {new Date(status.lastActivity).toLocaleTimeString()}</p>
+      
+      <Button onClick={resetActivity}>Reset Timer</Button>
+    </div>
+  );
+}
+```
+
+## Best Practices
+
+### 1. Appropriate Timeouts
+
+```tsx
+// Short sessions (banking, admin)
+const shortSession = useInactivityTracker({
+  idleTimeoutMs: 5 * 60 * 1000,  // 5 minutes
+  warnBeforeMs: 1 * 60 * 1000    // 1 minute warning
+});
+
+// Medium sessions (general apps)
+const mediumSession = useInactivityTracker({
+  idleTimeoutMs: 30 * 60 * 1000, // 30 minutes
+  warnBeforeMs: 5 * 60 * 1000    // 5 minutes warning
+});
+
+// Long sessions (content creation)
+const longSession = useInactivityTracker({
+  idleTimeoutMs: 2 * 60 * 60 * 1000, // 2 hours
+  warnBeforeMs: 15 * 60 * 1000       // 15 minutes warning
+});
+```
+
+### 2. User Experience
+
+```tsx
+// Provide clear feedback
+const userFriendly = useInactivityTracker({
+  onWarning: () => {
+    // Show toast notification
+    toast.info('Your session will expire soon');
+  },
+  onIdle: () => {
+    // Save work before signing out
+    saveUserWork();
+    signOut();
+  }
+});
+```
+
+### 3. Security Considerations
+
+```tsx
+// Clear sensitive data on idle
+const secure = useInactivityTracker({
+  onIdle: () => {
+    // Clear sensitive data from memory
+    clearSensitiveData();
+    // Clear local storage
+    localStorage.removeItem('sensitive-data');
+    // Sign out
+    signOut();
+  }
+});
+```
+
+## Next Steps
+
+- **[Authentication Integration](./permission-enforcement.md)** - Security patterns
+- **[Performance Optimization](./performance.md)** - Large application considerations
+- **[Accessibility Guidelines](../best-practices/accessibility.md)** - Accessibility best practices
+- **[Security Best Practices](../best-practices/security.md)** - Security considerations