@jmruthers/pace-core 0.5.181 → 0.5.182

package/docs/getting-started/quick-start.md

@@ -0,0 +1,517 @@
+---
+lastUpdated: 2025-11-18T14:00:00+11:00
+version: 0.5.181
+reviewedBy: documentation-standards-audit
+---
+
+# Quick Start Guide
+
+> **🚀 Build Your First App** | [← Back to Documentation](../README.md) | [Installation Guide](./installation-guide.md) | [Examples](./examples/README.md)
+
+This guide walks you through building a minimal Supabase-backed admin screen end-to-end using PACE Core. You'll create a simple app with authentication, a data table, and basic navigation.
+
+## Prerequisites
+
+- Node.js 18+ installed
+- A Supabase account (free tier works)
+- Basic knowledge of React and TypeScript
+
+## Step 1: Create Your Project
+
+```bash
+# Create a new Vite + React + TypeScript project
+npm create vite@latest my-pace-app -- --template react-ts
+cd my-pace-app
+
+# Install dependencies
+npm install
+```
+
+## Step 2: Install PACE Core
+
+```bash
+# Install PACE Core and required peer dependencies
+npm install @jmruthers/pace-core \
+  @supabase/supabase-js \
+  @tanstack/react-query @tanstack/react-table \
+  @radix-ui/react-avatar @radix-ui/react-checkbox @radix-ui/react-dialog \
+  @radix-ui/react-label @radix-ui/react-progress @radix-ui/react-slot \
+  @radix-ui/react-switch @radix-ui/react-tabs @radix-ui/react-toast @radix-ui/react-tooltip \
+  clsx lucide-react react-day-picker react-hook-form react-router-dom tailwind-merge zod
+
+# Install Tailwind v4
+npm install -D tailwindcss@^4.0.0 @tailwindcss/vite
+```
+
+## Step 3: Configure Vite
+
+Create or update `vite.config.ts`:
+
+```typescript
+import { defineConfig } from 'vite';
+import react from '@vitejs/plugin-react';
+import tailwindcss from '@tailwindcss/vite';
+
+export default defineConfig({
+  plugins: [
+    react(),
+    tailwindcss({
+      content: [
+        './src/**/*.{js,ts,jsx,tsx}',
+        './node_modules/@jmruthers/pace-core/src/**/*.{js,ts,jsx,tsx}'
+      ]
+    })
+  ],
+  server: {
+    port: 3000,
+    open: true,
+  },
+});
+```
+
+## Step 4: Set Up Tailwind CSS
+
+Create `src/app.css`:
+
+```css
+@import 'tailwindcss';
+@import '@jmruthers/pace-core/src/styles/core.css';
+```
+
+## Step 5: Configure Supabase
+
+Create `.env.local`:
+
+```env
+VITE_SUPABASE_URL=your_supabase_project_url
+VITE_SUPABASE_ANON_KEY=your_supabase_anon_key
+```
+
+Create `src/lib/supabase.ts`:
+
+```typescript
+import { createClient } from '@supabase/supabase-js';
+
+const supabaseUrl = import.meta.env.VITE_SUPABASE_URL!;
+const supabaseAnonKey = import.meta.env.VITE_SUPABASE_ANON_KEY!;
+
+export const supabase = createClient(supabaseUrl, supabaseAnonKey);
+```
+
+## Step 6: Set Up Your Database
+
+In your Supabase dashboard, run this SQL to create a simple `tasks` table:
+
+```sql
+-- Create tasks table
+CREATE TABLE tasks (
+  id UUID DEFAULT gen_random_uuid() PRIMARY KEY,
+  title TEXT NOT NULL,
+  description TEXT,
+  completed BOOLEAN DEFAULT false,
+  created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW(),
+  user_id UUID REFERENCES auth.users(id)
+);
+
+-- Enable RLS
+ALTER TABLE tasks ENABLE ROW LEVEL SECURITY;
+
+-- Create policy: users can only see their own tasks
+CREATE POLICY "Users can view their own tasks" ON tasks
+  FOR SELECT USING (auth.uid() = user_id);
+
+-- Create policy: users can insert their own tasks
+CREATE POLICY "Users can insert their own tasks" ON tasks
+  FOR INSERT WITH CHECK (auth.uid() = user_id);
+
+-- Create policy: users can update their own tasks
+CREATE POLICY "Users can update their own tasks" ON tasks
+  FOR UPDATE USING (auth.uid() = user_id);
+
+-- Create policy: users can delete their own tasks
+CREATE POLICY "Users can delete their own tasks" ON tasks
+  FOR DELETE USING (auth.uid() = user_id);
+```
+
+## Step 7: Create Your App
+
+Update `src/main.tsx`:
+
+```tsx
+import React from 'react';
+import ReactDOM from 'react-dom/client';
+import { BrowserRouter } from 'react-router-dom';
+import { UnifiedAuthProvider } from '@jmruthers/pace-core';
+import { supabase } from './lib/supabase';
+import App from './App';
+import './app.css';
+
+ReactDOM.createRoot(document.getElementById('root')!).render(
+  <React.StrictMode>
+    <UnifiedAuthProvider
+      supabaseClient={supabase}
+      appName="My Task App"
+      idleTimeoutMs={30 * 60 * 1000} // 30 minutes
+      warnBeforeMs={60 * 1000} // 1 minute warning
+      onIdleLogout={() => window.location.assign('/login')}
+    >
+      <BrowserRouter>
+        <App />
+      </BrowserRouter>
+    </UnifiedAuthProvider>
+  </React.StrictMode>
+);
+```
+
+Create `src/App.tsx`:
+
+```tsx
+import { Routes, Route, Navigate } from 'react-router-dom';
+import { useUnifiedAuth, PaceLoginPage, PaceAppLayout, ProtectedRoute } from '@jmruthers/pace-core';
+import { TasksPage } from './pages/TasksPage';
+import { DashboardPage } from './pages/DashboardPage';
+
+function App() {
+  const { isAuthenticated } = useUnifiedAuth();
+
+  return (
+    <Routes>
+      <Route 
+        path="/login" 
+        element={isAuthenticated ? <Navigate to="/" replace /> : <PaceLoginPage appName="My Task App" />} 
+      />
+      <Route element={<ProtectedRoute />}>
+        <Route element={<PaceAppLayout appName="My Task App" />}>
+          <Route path="/" element={<DashboardPage />} />
+          <Route path="/tasks" element={<TasksPage />} />
+        </Route>
+      </Route>
+    </Routes>
+  );
+}
+
+export default App;
+```
+
+## Step 8: Create the Dashboard Page
+
+Create `src/pages/DashboardPage.tsx`:
+
+```tsx
+import { useUnifiedAuth } from '@jmruthers/pace-core';
+import { Card, CardHeader, CardTitle, CardContent } from '@jmruthers/pace-core';
+import { Link } from 'react-router-dom';
+import { Button } from '@jmruthers/pace-core';
+
+export function DashboardPage() {
+  const { user, signOut } = useUnifiedAuth();
+
+  return (
+    <div className="p-6">
+      <h1 className="text-3xl font-bold mb-6">Dashboard</h1>
+      
+      <div className="grid gap-4 md:grid-cols-2 lg:grid-cols-3 mb-6">
+        <Card>
+          <CardHeader>
+            <CardTitle>Welcome</CardTitle>
+          </CardHeader>
+          <CardContent>
+            <p className="text-sec-600">Hello, {user?.email}</p>
+          </CardContent>
+        </Card>
+        
+        <Card>
+          <CardHeader>
+            <CardTitle>Quick Actions</CardTitle>
+          </CardHeader>
+          <CardContent>
+            <Link to="/tasks">
+              <Button className="w-full">View Tasks</Button>
+            </Link>
+          </CardContent>
+        </Card>
+        
+        <Card>
+          <CardHeader>
+            <CardTitle>Account</CardTitle>
+          </CardHeader>
+          <CardContent>
+            <Button variant="outline" onClick={() => signOut()} className="w-full">
+              Sign Out
+            </Button>
+          </CardContent>
+        </Card>
+      </div>
+    </div>
+  );
+}
+```
+
+## Step 9: Create the Tasks Page with DataTable
+
+Create `src/pages/TasksPage.tsx`:
+
+```tsx
+import { useState, useEffect } from 'react';
+import { DataTable, type DataTableColumn } from '@jmruthers/pace-core';
+import { useUnifiedAuth } from '@jmruthers/pace-core';
+import { supabase } from '../lib/supabase';
+
+interface Task {
+  id: string;
+  title: string;
+  description: string | null;
+  completed: boolean;
+  created_at: string;
+}
+
+export function TasksPage() {
+  const { user } = useUnifiedAuth();
+  const [tasks, setTasks] = useState<Task[]>([]);
+  const [loading, setLoading] = useState(true);
+
+  useEffect(() => {
+    loadTasks();
+  }, [user]);
+
+  async function loadTasks() {
+    if (!user) return;
+    
+    setLoading(true);
+    const { data, error } = await supabase
+      .from('tasks')
+      .select('*')
+      .eq('user_id', user.id)
+      .order('created_at', { ascending: false });
+
+    if (error) {
+      console.error('Error loading tasks:', error);
+    } else {
+      setTasks(data || []);
+    }
+    setLoading(false);
+  }
+
+  async function handleCreateRow(newTask: Partial<Task>) {
+    if (!user) return;
+    
+    const { data, error } = await supabase
+      .from('tasks')
+      .insert({
+        title: newTask.title || 'New Task',
+        description: newTask.description || null,
+        completed: false,
+        user_id: user.id,
+      })
+      .select()
+      .single();
+
+    if (error) {
+      console.error('Error creating task:', error);
+    } else {
+      await loadTasks();
+    }
+  }
+
+  async function handleEditRow(row: Task, updates: Partial<Task>) {
+    const { error } = await supabase
+      .from('tasks')
+      .update(updates)
+      .eq('id', row.id);
+
+    if (error) {
+      console.error('Error updating task:', error);
+    } else {
+      await loadTasks();
+    }
+  }
+
+  async function handleDeleteRow(row: Task) {
+    const { error } = await supabase
+      .from('tasks')
+      .delete()
+      .eq('id', row.id);
+
+    if (error) {
+      console.error('Error deleting task:', error);
+    } else {
+      await loadTasks();
+    }
+  }
+
+  const columns: DataTableColumn<Task>[] = [
+    {
+      accessorKey: 'title',
+      header: 'Title',
+      sortable: true,
+      features: { search: true },
+    },
+    {
+      accessorKey: 'description',
+      header: 'Description',
+      sortable: true,
+      features: { search: true },
+    },
+    {
+      accessorKey: 'completed',
+      header: 'Status',
+      sortable: true,
+      cell: ({ row }) => (
+        <span className={`px-2 py-1 rounded text-xs ${
+          row.original.completed
+            ? 'bg-main-100 text-main-800'
+            : 'bg-sec-100 text-sec-800'
+        }`}>
+          {row.original.completed ? 'Completed' : 'Pending'}
+        </span>
+      ),
+    },
+    {
+      accessorKey: 'created_at',
+      header: 'Created',
+      sortable: true,
+      cell: ({ row }) => new Date(row.original.created_at).toLocaleDateString(),
+    },
+  ];
+
+  return (
+    <div className="p-6">
+      <h1 className="text-3xl font-bold mb-6">Tasks</h1>
+      
+      <DataTable
+        data={tasks}
+        columns={columns}
+        features={{
+          search: true,
+          pagination: true,
+          sorting: true,
+          creation: true,
+          editing: true,
+          deletion: true,
+        }}
+        onEditRow={handleEditRow}
+        onDeleteRow={handleDeleteRow}
+        onCreateRow={handleCreateRow}
+        isLoading={loading}
+        title="My Tasks"
+        description="Manage your tasks"
+      />
+    </div>
+  );
+}
+```
+
+## Step 10: Run Your App
+
+```bash
+npm run dev
+```
+
+Your app should now be running at `http://localhost:3000`. You can:
+
+1. Sign up for a new account or sign in
+2. View your dashboard
+3. Navigate to the Tasks page
+4. Create, edit, and delete tasks
+
+## Next Steps
+
+- **Add RBAC**: See the [RBAC Quick Start](../rbac/quick-start.md) guide
+- **Add Organisation Context**: See [Organisation Security](../implementation-guides/organisation-security.md)
+- **Customize Styling**: See [Component Styling](../implementation-guides/component-styling.md)
+- **Add More Features**: See [Full-Featured Example](./examples/full-featured-app.md)
+
+## Troubleshooting
+
+### Components appear unstyled
+- Ensure you've imported `@jmruthers/pace-core/src/styles/core.css` in your `app.css`
+- Verify Tailwind v4 is properly configured in `vite.config.ts`
+- Check that pace-core source files are included in content scanning
+
+### Authentication not working
+- Verify your Supabase URL and anon key are correct in `.env.local`
+- Check that email authentication is enabled in Supabase dashboard
+- Ensure RLS policies are set up correctly
+
+### DataTable not showing data
+- Verify your database table exists and has data
+- Check that RLS policies allow the current user to read data
+- Check browser console for errors
+
+## ♿ Accessibility
+
+The app you've built includes accessibility features:
+
+- **WCAG 2.1 AA compliant** - All PACE Core components meet accessibility standards
+- **Semantic HTML** - Proper use of semantic elements in your components
+- **Screen Reader Support** - All interactive elements have proper ARIA labels
+- **Keyboard Navigation** - Full keyboard support for navigation and data tables
+- **Focus Management** - Proper focus indicators and tab order
+
+### Accessibility Best Practices
+
+1. **Use semantic HTML** - Prefer `<nav>`, `<main>`, `<header>` over generic `<div>` elements
+2. **Label form inputs** - Always associate labels with form inputs
+3. **Test with screen readers** - Verify your app works with assistive technologies
+4. **Maintain keyboard access** - Ensure all interactive elements are keyboard accessible
+5. **Check color contrast** - Verify text meets WCAG contrast requirements
+
+## ⚠️ Edge Cases
+
+### Database Connection Failures
+
+When database connection fails:
+- Verify Supabase URL and keys are correct
+- Check network connectivity
+- Verify RLS policies allow access
+- Check Supabase project status
+- Review error messages in browser console
+
+### Authentication Issues
+
+When authentication doesn't work:
+- Verify Supabase auth is enabled
+- Check email/password format
+- Verify user exists in Supabase
+- Check RLS policies for auth tables
+- Review authentication error messages
+
+### DataTable Not Loading
+
+When DataTable doesn't show data:
+- Verify data structure matches column definitions
+- Check that `getRowId` function returns unique IDs
+- Verify data is not empty
+- Check for JavaScript errors in console
+- Ensure columns are properly defined
+
+### Styling Issues
+
+When components appear unstyled:
+- Verify CSS is imported in entry point
+- Check Vite config includes pace-core source files
+- Ensure Tailwind v4 is installed
+- Restart dev server after config changes
+- Check browser console for CSS errors
+
+### Build Errors
+
+When build fails:
+- Check for TypeScript errors
+- Verify all imports are correct
+- Check for missing dependencies
+- Review build error messages
+- Clear build cache and rebuild
+
+## What You've Built
+
+You've created a complete admin application with:
+- ✅ User authentication (sign up, sign in, sign out)
+- ✅ Protected routes
+- ✅ Data table with CRUD operations
+- ✅ Responsive layout
+- ✅ Row-level security
+- ✅ Session management
+
+Congratulations! You're ready to build more complex features with PACE Core.
+

package/docs/implementation-guides/app-layout.md

@@ -1,7 +1,7 @@
 ---
-lastUpdated: 2025-10-29T22:43:00+11:00
-version: 0.5.76
-reviewedBy: content-audit
+lastUpdated: 2025-11-18T14:00:00+11:00
+version: 0.5.181
+reviewedBy: documentation-standards-audit
 ---
 
 # App Layout
@@ -988,4 +988,46 @@ test('renders mobile layout correctly', () => {
 - Ensure sufficient color contrast
 - Test with screen readers
 
+## ⚠️ Edge Cases
+
+### Layout State Loss
+
+When layout state is lost:
+- Default states are restored
+- Navigation rebuilds from configuration
+- No data loss or corruption
+- Graceful recovery from errors
+
+### Permission Changes During Session
+
+When user permissions change during active session:
+- Layout updates automatically
+- Navigation items appear/disappear dynamically
+- No page refresh required
+- Clear feedback explains permission changes
+
+### Responsive Breakpoint Changes
+
+When screen size changes rapidly:
+- Layout adapts smoothly to new breakpoints
+- Navigation state is preserved
+- No flickering or layout shifts
+- Smooth transitions maintained
+
+### Missing Navigation Configuration
+
+When navigation configuration is missing:
+- Layout gracefully handles missing items
+- Default navigation is shown
+- Error states are handled gracefully
+- User experience is not disrupted
+
+### Concurrent Layout Updates
+
+When multiple layout updates occur:
+- Updates are queued and processed in order
+- State conflicts are prevented
+- User feedback is provided
+- Data consistency is maintained
+
 For more advanced layout patterns and examples, see the [Layout Examples](../examples/layouts.md) guide.

package/docs/implementation-guides/authentication.md

@@ -1,7 +1,7 @@
 ---
-lastUpdated: 2025-10-29T22:43:00+11:00
-version: 0.5.76
-reviewedBy: content-audit
+lastUpdated: 2025-11-18T14:00:00+11:00
+version: 0.5.181
+reviewedBy: documentation-standards-audit
 ---
 
 # Authentication Implementation Guide
@@ -93,7 +93,6 @@ ReactDOM.createRoot(document.getElementById('root')!).render(
       <UnifiedAuthProvider 
         supabaseClient={supabase} 
         appName="my-app"
-        enableRBAC={true}
         requireOrganisationContext={true}
         idleTimeoutMs={30 * 60 * 1000}  // 30 minutes - REQUIRED
         warnBeforeMs={60 * 1000}        // 60 seconds - REQUIRED
@@ -202,7 +201,7 @@ interface UnifiedAuthProviderProps {
   onIdleLogout: () => void;     // Callback when session times out
   
   // Optional props
-  enableRBAC?: boolean;         // Enable RBAC integration (default: true)
+  // Note: RBAC is always enabled - no prop needed
   requireOrganisationContext?: boolean; // Require organisation selection (default: false)
   debug?: boolean;              // Enable debug logging (default: false)
   children: React.ReactNode;
@@ -215,7 +214,6 @@ interface UnifiedAuthProviderProps {
 <UnifiedAuthProvider
   supabaseClient={supabase}
   appName="meal-manager"
-  enableRBAC={true}
   requireOrganisationContext={true}
   debug={process.env.NODE_ENV === 'development'}
   idleTimeoutMs={30 * 60 * 1000}  // 30 minutes
@@ -1040,8 +1038,69 @@ See the [Common Patterns Guide](./best-practices/common-patterns.md) for advance
 - [Navigation Integration](./navigation.md) - Permission-based navigation
 - [Troubleshooting Guide](./troubleshooting/README.md) - Common issues and solutions
 
+## ♿ Accessibility
+
+The authentication system is designed with accessibility in mind:
+
+- **WCAG 2.1 AA compliant** - All authentication components meet accessibility standards
+- **Keyboard Navigation** - Full keyboard support for all authentication forms and interactions
+- **Screen Reader Support** - Proper ARIA labels and roles for all form elements
+- **Focus Management** - Logical tab order and visible focus indicators
+- **Error Announcements** - Error messages are properly announced to screen readers
+- **Loading States** - Loading indicators are accessible and announced
+
+### Accessibility Best Practices
+
+1. **Use semantic HTML** - Prefer `<form>`, `<label>`, `<input>` over generic divs
+2. **Associate labels with inputs** - Use proper `htmlFor` and `id` attributes
+3. **Provide error feedback** - Use ARIA live regions for dynamic error messages
+4. **Test with screen readers** - Verify authentication flows work with assistive technologies
+5. **Ensure keyboard navigation** - All interactive elements should be keyboard accessible
+
+## ⚠️ Edge Cases
+
+### Session Expiration During Use
+
+When a session expires while the user is actively using the app:
+- Inactivity warnings are shown before expiration
+- Users can extend their session before timeout
+- Automatic logout redirects to login page
+- Unsaved work should be preserved if possible
+
+### Network Failures During Authentication
+
+When network requests fail during login/signup:
+- Error messages are clearly displayed
+- Retry mechanisms are available
+- Partial form data is preserved when possible
+- User-friendly error messages guide recovery
+
+### Multiple Tab Sessions
+
+When users have multiple tabs open:
+- Session state is synchronized across tabs
+- Logout in one tab logs out all tabs
+- Organisation/event selection syncs across tabs
+- Inactivity tracking works across all tabs
+
+### Invalid Credentials
+
+When users enter invalid credentials:
+- Error messages are specific but don't reveal which field is wrong
+- Rate limiting prevents brute force attacks
+- Account lockout after multiple failed attempts
+- Clear guidance on password requirements
+
+### Organisation Context Loss
+
+When organisation context is lost:
+- User is redirected to organisation selection
+- Data is protected by RLS policies
+- Context is restored automatically when possible
+- Clear error messages explain the situation
+
 ## Conclusion
 
 PACE Core's authentication system provides a comprehensive solution for user authentication, session management, and access control. With built-in RBAC integration, event management, and inactivity handling, it provides everything needed for secure, user-friendly applications.
 
-The system is designed to be both powerful and easy to use, with extensive debugging support and clear error messages to help developers build robust authentication flows.
+The system is designed to be both powerful and easy to use, with extensive debugging support, clear error messages, and full accessibility support to help developers build robust authentication flows.