@jmruthers/pace-core 0.6.5 → 0.6.7

package/docs/best-practices/common-patterns.md

@@ -1,516 +0,0 @@
----
-lastUpdated: 2025-11-18T17:00:00+11:00
-version: 0.5.181
-reviewedBy: documentation-standards-audit
----
-
-# Common Patterns & Best Practices
-
-> **📚 Common Patterns** | [← Back to Documentation](./README.md) | [Quick Start](./getting-started/quick-start.md) | [API Reference](./api-reference/components.md)
-
-Reusable patterns and best practices for building with PACE Core.
-
-## Table of Contents
-
-1. [Authentication Patterns](#authentication-patterns)
-2. [Permission Patterns](#permission-patterns)
-3. [Data Fetching Patterns](#data-fetching-patterns)
-4. [Form Handling Patterns](#form-handling-patterns)
-5. [Error Handling Patterns](#error-handling-patterns)
-6. [UI Patterns](#ui-patterns)
-
-## Authentication Patterns
-
-### Basic Authentication Setup
-
-```tsx
-import { UnifiedAuthProvider } from '@jmruthers/pace-core';
-import { supabase } from './lib/supabase';
-
-function App() {
-  return (
-    <UnifiedAuthProvider
-      supabaseClient={supabase}
-      appName="my-app"
-      idleTimeoutMs={30 * 60 * 1000}
-      warnBeforeMs={5 * 60 * 1000}
-      onIdleLogout={() => window.location.href = '/login'}
-    >
-      <YourApp />
-    </UnifiedAuthProvider>
-  );
-}
-```
-
-### Protected Routes
-
-**✅ Use the standard ProtectedRoute component from pace-core:**
-
-```tsx
-import { ProtectedRoute } from '@jmruthers/pace-core';
-import { Routes, Route } from 'react-router-dom';
-
-function App() {
-  return (
-    <Routes>
-      <Route path="/login" element={<LoginPage />} />
-      {/* Routes requiring authentication and event selection */}
-      <Route element={<ProtectedRoute />}>
-        <Route path="/dashboard" element={<DashboardPage />} />
-      </Route>
-      {/* Routes requiring authentication only (no event needed) */}
-      <Route element={<ProtectedRoute requireEvent={false} />}>
-        <Route path="/settings" element={<SettingsPage />} />
-      </Route>
-    </Routes>
-  );
-}
-```
-
-**Why use the standard component?**
-- Prevents the chicken-and-egg problem where checking `selectedEvent` blocks the event selector from being visible
-- Handles session restoration automatically
-- Manages loading states properly
-- Provides consistent behavior across all pace apps
-
-**❌ Avoid custom ProtectedRoute implementations that block rendering when no event is selected**, as this prevents users from seeing the event selector dropdown in the header.
-
-### Session Management
-
-```tsx
-import { useUnifiedAuth } from '@jmruthers/pace-core';
-
-function UserMenu() {
-  const { user, signOut } = useUnifiedAuth();
-
-  const handleSignOut = async () => {
-    await signOut();
-    window.location.href = '/login';
-  };
-
-  return (
-    <div>
-      <p>Welcome, {user?.email}</p>
-      <button onClick={handleSignOut}>Sign Out</button>
-    </div>
-  );
-}
-```
-
-## Permission Patterns
-
-### Basic Permission Check
-
-```tsx
-import { useCan } from '@jmruthers/pace-core';
-
-function UserActions({ userId, organisationId }) {
-  const { hasPermission, isLoading } = useCan();
-  const [canEdit, setCanEdit] = useState(false);
-
-  useEffect(() => {
-    if (!isLoading) {
-      hasPermission('update:users', { userId, organisationId })
-        .then(setCanEdit);
-    }
-  }, [hasPermission, isLoading, userId, organisationId]);
-
-  return (
-    <div>
-      {canEdit && <EditButton />}
-      <ViewButton />
-    </div>
-  );
-}
-```
-
-### Permission-Guided UI
-
-```tsx
-import { useCan } from '@jmruthers/pace-core';
-import { Button, Card } from '@jmruthers/pace-core';
-
-function UserManagement() {
-  const { hasPermission } = useCan();
-  const [canCreate, setCanCreate] = useState(false);
-  const [canDelete, setCanDelete] = useState(false);
-
-  useEffect(() => {
-    const checkPermissions = async () => {
-      setCanCreate(await hasPermission('create:users'));
-      setCanDelete(await hasPermission('delete:users'));
-    };
-    checkPermissions();
-  }, [hasPermission]);
-
-  return (
-    <Card>
-      {canCreate && (
-        <Button onClick={handleCreate}>Create User</Button>
-      )}
-      {canDelete && (
-        <Button variant="destructive" onClick={handleDelete}>
-          Delete Selected
-        </Button>
-      )}
-    </Card>
-  );
-}
-```
-
-### Batch Permission Checking
-
-```tsx
-import { usePermissions } from '@jmruthers/pace-core';
-
-function AdminDashboard() {
-  const { permissions, isLoading } = usePermissions({ 
-    userId, 
-    organisationId 
-  });
-
-  const canUpdate = permissions.includes('update:users') || 
-                   permissions.includes('update:settings');
-
-  return (
-    <div>
-      {isLoading && <div>Loading...</div>}
-      {canUpdate && <AdminPanel />}
-    </div>
-  );
-}
-```
-
-## Data Fetching Patterns
-
-### Fetch with Permissions
-
-```tsx
-import { useCan } from '@jmruthers/pace-core';
-
-function UserList({ organisationId }) {
-  const { hasPermission } = useCan();
-  const [data, setData] = useState([]);
-  const [loading, setLoading] = useState(true);
-
-  useEffect(() => {
-    const fetchData = async () => {
-      const canRead = await hasPermission('read:users', { organisationId });
-      if (canRead) {
-        const users = await supabase
-          .from('users')
-          .select('*');
-        setData(users.data || []);
-      }
-      setLoading(false);
-    };
-    
-    fetchData();
-  }, [hasPermission, organisationId]);
-
-  if (loading) return <div>Loading...</div>;
-  return <DataTable data={data} />;
-}
-```
-
-### Real-time Data with Permissions
-
-```tsx
-import { useEffect, useState } from 'react';
-import { useCan } from '@jmruthers/pace-core';
-
-function LiveData({ organisationId }) {
-  const { hasPermission } = useCan();
-  const [data, setData] = useState([]);
-
-  useEffect(() => {
-    const checkAndSubscribe = async () => {
-      const canRead = await hasPermission('read:data', { organisationId });
-      
-      if (canRead) {
-        const subscription = supabase
-          .channel('data')
-          .on('postgres_changes', 
-            { event: '*', schema: 'public', table: 'data' },
-            (payload) => {
-              setData(prev => [...prev, payload.new]);
-            }
-          )
-          .subscribe();
-
-        return () => {
-          supabase.removeChannel(subscription);
-        };
-      }
-    };
-
-    checkAndSubscribe();
-  }, [hasPermission, organisationId]);
-
-  return <DataTable data={data} />;
-}
-```
-
-## Form Handling Patterns
-
-### Basic Form with Validation
-
-```tsx
-import { Form, Input, Button } from '@jmruthers/pace-core';
-
-function UserForm() {
-  const [errors, setErrors] = useState({});
-
-  const validate = (data) => {
-    const newErrors = {};
-    if (!data.email) newErrors.email = 'Email required';
-    if (!data.name) newErrors.name = 'Name required';
-    return newErrors;
-  };
-
-  const handleSubmit = async (data) => {
-    const newErrors = validate(data);
-    if (Object.keys(newErrors).length) {
-      setErrors(newErrors);
-      return;
-    }
-
-    await supabase.from('users').insert(data);
-  };
-
-  return (
-    <Form onSubmit={handleSubmit}>
-      <Input name="name" error={errors.name} />
-      <Input name="email" type="email" error={errors.email} />
-      <Button type="submit">Save</Button>
-    </Form>
-  );
-}
-```
-
-### Form with Permission Checks
-
-```tsx
-import { useCan } from '@jmruthers/pace-core';
-
-function EditableForm({ user, organisationId }) {
-  const { hasPermission } = useCan();
-  const [canEdit, setCanEdit] = useState(false);
-
-  useEffect(() => {
-    hasPermission('update:users', { organisationId })
-      .then(setCanEdit);
-  }, [hasPermission, organisationId]);
-
-  return (
-    <Form initialValues={user}>
-      <Input name="name" disabled={!canEdit} />
-      <Input name="email" disabled={!canEdit} />
-      {canEdit && <Button type="submit">Save Changes</Button>}
-    </Form>
-  );
-}
-```
-
-## Error Handling Patterns
-
-### Comprehensive Error Handling
-
-```tsx
-import { useState } from 'react';
-import { Alert } from '@jmruthers/pace-core';
-
-function DataFetcher() {
-  const [data, setData] = useState([]);
-  const [loading, setLoading] = useState(true);
-  const [error, setError] = useState<string | null>(null);
-
-  useEffect(() => {
-    const fetchData = async () => {
-      try {
-        setLoading(true);
-        setError(null);
-        
-        const { data: result, error: fetchError } = await supabase
-          .from('users')
-          .select('*');
-
-        if (fetchError) throw fetchError;
-        setData(result || []);
-      } catch (err) {
-        setError(err instanceof Error ? err.message : 'Unknown error');
-      } finally {
-        setLoading(false);
-      }
-    };
-
-    fetchData();
-  }, []);
-
-  if (loading) return <div>Loading...</div>;
-  if (error) return <Alert variant="destructive">{error}</Alert>;
-  return <DataTable data={data} />;
-}
-```
-
-### Loading States
-
-```tsx
-import { useState } from 'react';
-
-function AsyncComponent() {
-  const [loading, setLoading] = useState(true);
-  const [error, setError] = useState<string | null>(null);
-  const [data, setData] = useState(null);
-
-  useEffect(() => {
-    fetchData().then(setData).catch(setError).finally(() => setLoading(false));
-  }, []);
-
-  if (loading) return <LoadingSpinner />;
-  if (error) return <ErrorMessage error={error} />;
-  return <DataDisplay data={data} />;
-}
-```
-
-## UI Patterns
-
-### Conditional Rendering with Permissions
-
-```tsx
-import { useCan } from '@jmruthers/pace-core';
-import { Button } from '@jmruthers/pace-core';
-
-function ActionButtons() {
-  const { hasPermission } = useCan();
-  const [canEdit, setCanEdit] = useState(false);
-  const [canDelete, setCanDelete] = useState(false);
-
-  useEffect(() => {
-    Promise.all([
-      hasPermission('update:users'),
-      hasPermission('delete:users')
-    ]).then(([edit, del]) => {
-      setCanEdit(edit);
-      setCanDelete(del);
-    });
-  }, [hasPermission]);
-
-  return (
-    <div className="flex gap-2">
-      {canEdit && <Button>Edit</Button>}
-      {canDelete && <Button variant="destructive">Delete</Button>}
-      <Button>View</Button>
-    </div>
-  );
-}
-```
-
-### Modal with Confirmation
-
-```tsx
-import { Dialog, Button } from '@jmruthers/pace-core';
-import { useState } from 'react';
-
-function DeleteConfirmation({ item, onConfirm }) {
-  const [open, setOpen] = useState(false);
-
-  return (
-    <>
-      <Button variant="destructive" onClick={() => setOpen(true)}>
-        Delete
-      </Button>
-
-      <Dialog open={open} onOpenChange={setOpen}>
-        <Dialog.Header>Confirm Delete</Dialog.Header>
-        <Dialog.Content>
-          <p>Are you sure you want to delete {item.name}?</p>
-        </Dialog.Content>
-        <Dialog.Footer>
-          <Button variant="ghost" onClick={() => setOpen(false)}>
-            Cancel
-          </Button>
-          <Button variant="destructive" onClick={onConfirm}>
-            Delete
-          </Button>
-        </Dialog.Footer>
-      </Dialog>
-    </>
-  );
-}
-```
-
-## Best Practices Summary
-
-### Do's ✅
-
-- Always check permissions before showing sensitive UI
-- Include loading and error states in async operations
-- Use TypeScript for type safety
-- Handle errors gracefully with user-friendly messages
-- Cache permission checks when possible
-- Use proper loading states for better UX
-
-### Don'ts ❌
-
-- Don't assume permissions without checking
-- Don't fetch data without permission validation
-- Don't forget to handle loading and error states
-- Don't expose sensitive operations without checks
-- Don't skip TypeScript types in examples
-- Don't forget to import CSS files
-
-## Next Steps
-
-- **[Installation Guide](./getting-started/installation-guide.md)** - Set up PACE Core
-- **[RBAC Guide](./rbac/README.md)** - Learn about permissions
-- **[Implementation Guides](./implementation-guides/)** - Explore specific features
-- **[API Reference](./api-reference/components.md)** - Component documentation
-
-## ♿ Accessibility
-
-Common patterns should maintain accessibility:
-
-- **Patterns include accessibility features** - All patterns should consider accessibility
-- **Keyboard navigation is supported** - Patterns should support keyboard navigation
-- **Screen reader compatibility** - Patterns should work with screen readers
-- **Focus management** - Patterns should handle focus correctly
-- **ARIA labels are included** - Patterns should include proper ARIA labels
-
-### Accessibility Best Practices
-
-1. **Test patterns with screen readers** - Verify patterns work with assistive technologies
-2. **Ensure keyboard access** - All patterns should be keyboard accessible
-3. **Include ARIA labels** - Patterns should have proper ARIA attributes
-4. **Test focus management** - Verify focus handling in patterns
-5. **Document accessibility requirements** - Include accessibility in pattern documentation
-
-## ⚠️ Edge Cases
-
-### Pattern Conflicts
-
-When patterns conflict:
-- Document pattern trade-offs
-- Provide guidance on pattern selection
-- Test pattern combinations
-- Verify patterns work together
-- Consider pattern alternatives
-
-### Pattern Scalability
-
-When patterns don't scale:
-- Test patterns with large datasets
-- Verify patterns work with many components
-- Monitor pattern performance
-- Optimize patterns for scale
-- Document scalability limitations
-
-### Pattern Maintenance
-
-When patterns need updates:
-- Version pattern documentation
-- Provide migration guides
-- Test pattern updates thoroughly
-- Document breaking changes
-- Maintain backward compatibility when possible
-