@jmruthers/pace-core 0.5.76 → 0.5.78

package/docs/getting-started/examples/full-featured-app.md

@@ -1,616 +0,0 @@
-# Full-Featured Application
-
-A complete meal management application demonstrating all PACE Core features including authentication, RBAC, data tables, forms, and permission enforcement.
-
-## 🎯 What This Example Shows
-
-- Complete authentication flow with RBAC
-- Multi-tenant organisation support
-- Event management and selection
-- Advanced DataTable with CRUD operations
-- Form validation and error handling
-- Permission enforcement at page and component level
-- Responsive layout with navigation
-- Production-ready patterns
-
-## 📁 Project Structure
-
-```
-src/
-├── App.tsx                    # Main app with all providers
-├── lib/
-│   └── supabase.ts           # Supabase client
-├── components/
-│   ├── auth/
-│   │   ├── LoginPage.tsx     # Login form
-│   │   └── ProtectedRoute.tsx # Route protection
-│   ├── layout/
-│   │   ├── AppLayout.tsx     # Main layout
-│   │   └── Navigation.tsx    # Navigation menu
-│   ├── dashboard/
-│   │   └── DashboardPage.tsx # Dashboard with metrics
-│   ├── meals/
-│   │   ├── MealsPage.tsx     # Meals list with DataTable
-│   │   ├── MealForm.tsx      # Add/edit meal form
-│   │   └── MealModal.tsx     # Modal for meal operations
-│   ├── users/
-│   │   ├── UsersPage.tsx     # User management
-│   │   └── UserForm.tsx      # User creation/editing
-│   └── shared/
-│       ├── LoadingSpinner.tsx # Loading states
-│       └── ErrorBoundary.tsx  # Error handling
-├── hooks/
-│   ├── useMeals.ts           # Meals data management
-│   └── useUsers.ts           # Users data management
-├── types/
-│   ├── meal.ts               # Meal type definitions
-│   └── user.ts               # User type definitions
-└── utils/
-    ├── permissions.ts         # Permission checking
-    └── validation.ts          # Form validation schemas
-```
-
-## 🚀 Implementation
-
-### 1. App.tsx - Complete Application Setup
-
-```tsx
-import { 
-  UnifiedAuthProvider, 
-  OrganisationProvider,
-  EventProvider,
-  ErrorBoundary 
-} from '@jmruthers/pace-core';
-import { BrowserRouter } from 'react-router-dom';
-import { supabase } from './lib/supabase';
-import { AppRoutes } from './components/AppRoutes';
-
-function App() {
-  return (
-    <ErrorBoundary>
-      <UnifiedAuthProvider 
-        supabaseClient={supabase} 
-        appName="meal-manager"
-        enableRBAC={true}
-        requireOrganisationContext={true}
-        persistState={true}
-      >
-        <OrganisationProvider>
-          <EventProvider>
-            <BrowserRouter>
-              <AppRoutes />
-            </BrowserRouter>
-          </EventProvider>
-        </OrganisationProvider>
-      </UnifiedAuthProvider>
-    </ErrorBoundary>
-  );
-}
-
-export default App;
-```
-
-### 2. AppRoutes.tsx - Route Configuration
-
-```tsx
-import { Routes, Route, Navigate } from 'react-router-dom';
-import { ProtectedRoute } from './auth/ProtectedRoute';
-import { AppLayout } from './layout/AppLayout';
-import { LoginPage } from './auth/LoginPage';
-import { DashboardPage } from './dashboard/DashboardPage';
-import { MealsPage } from './meals/MealsPage';
-import { UsersPage } from './users/UsersPage';
-
-export function AppRoutes() {
-  return (
-    <Routes>
-      <Route path="/login" element={<LoginPage />} />
-      
-      <Route path="/" element={
-        <ProtectedRoute>
-          <AppLayout />
-        </ProtectedRoute>
-      }>
-        <Route index element={<DashboardPage />} />
-        <Route path="meals" element={<MealsPage />} />
-        <Route path="users" element={<UsersPage />} />
-      </Route>
-      
-      <Route path="*" element={<Navigate to="/" replace />} />
-    </Routes>
-  );
-}
-```
-
-### 3. ProtectedRoute.tsx - Route Protection
-
-```tsx
-import { useUnifiedAuth } from '@jmruthers/pace-core';
-import { Navigate, useLocation } from 'react-router-dom';
-import { LoadingSpinner } from '../shared/LoadingSpinner';
-
-interface ProtectedRouteProps {
-  children: React.ReactNode;
-  requiredPermission?: string;
-}
-
-export function ProtectedRoute({ children, requiredPermission }: ProtectedRouteProps) {
-  const { user, loading, hasPermission } = useUnifiedAuth();
-  const location = useLocation();
-
-  if (loading) {
-    return <LoadingSpinner />;
-  }
-
-  if (!user) {
-    return <Navigate to="/login" state={{ from: location }} replace />;
-  }
-
-  if (requiredPermission && !hasPermission(requiredPermission)) {
-    return <Navigate to="/unauthorized" replace />;
-  }
-
-  return <>{children}</>;
-}
-```
-
-### 4. AppLayout.tsx - Main Layout
-
-```tsx
-import { PaceAppLayout, OrganisationSelector, EventSelector } from '@jmruthers/pace-core';
-import { Outlet } from 'react-router-dom';
-
-const navItems = [
-  {
-    title: 'Dashboard',
-    href: '/',
-    icon: 'HomeIcon',
-    permission: 'read:dashboard'
-  },
-  {
-    title: 'Meals',
-    href: '/meals',
-    icon: 'UtensilsIcon',
-    permission: 'read:meals'
-  },
-  {
-    title: 'Users',
-    href: '/users',
-    icon: 'UsersIcon',
-    permission: 'read:users'
-  }
-];
-
-export function AppLayout() {
-  return (
-    <PaceAppLayout 
-      appName="Meal Manager"
-      navItems={navItems}
-      enforcePermissions={true}
-      defaultPermission="read"
-      headerActions={
-        <>
-          <OrganisationSelector />
-          <EventSelector />
-        </>
-      }
-    >
-      <Outlet />
-    </PaceAppLayout>
-  );
-}
-```
-
-### 5. DashboardPage.tsx - Dashboard with Metrics
-
-```tsx
-import { Card, CardHeader, CardTitle, CardContent } from '@jmruthers/pace-core';
-import { useUnifiedAuth } from '@jmruthers/pace-core';
-import { useMeals } from '../../hooks/useMeals';
-import { useUsers } from '../../hooks/useUsers';
-
-export function DashboardPage() {
-  const { user } = useUnifiedAuth();
-  const { meals, loading: mealsLoading } = useMeals();
-  const { users, loading: usersLoading } = useUsers();
-
-  const totalMeals = meals?.length || 0;
-  const totalUsers = users?.length || 0;
-  const thisWeekMeals = meals?.filter(meal => {
-    const weekAgo = new Date();
-    weekAgo.setDate(weekAgo.getDate() - 7);
-    return new Date(meal.date) >= weekAgo;
-  }).length || 0;
-
-  return (
-    <div className="p-6">
-      <div className="mb-8">
-        <h1 className="text-3xl font-bold text-sec-900">Dashboard</h1>
-        <p className="text-sec-600 mt-2">
-          Welcome back, {user?.email}. Here's what's happening with your meals.
-        </p>
-      </div>
-      
-      <div className="grid grid-cols-1 md:grid-cols-3 gap-6 mb-8">
-        <Card>
-          <CardHeader>
-            <CardTitle>Total Meals</CardTitle>
-          </CardHeader>
-          <CardContent>
-            <p className="text-3xl font-bold">{mealsLoading ? '...' : totalMeals}</p>
-            <p className="text-sm text-sec-600">All time</p>
-          </CardContent>
-        </Card>
-        
-        <Card>
-          <CardHeader>
-            <CardTitle>This Week</CardTitle>
-          </CardHeader>
-          <CardContent>
-            <p className="text-3xl font-bold">{mealsLoading ? '...' : thisWeekMeals}</p>
-            <p className="text-sm text-sec-600">Last 7 days</p>
-          </CardContent>
-        </Card>
-        
-        <Card>
-          <CardHeader>
-            <CardTitle>Total Users</CardTitle>
-          </CardHeader>
-          <CardContent>
-            <p className="text-3xl font-bold">{usersLoading ? '...' : totalUsers}</p>
-            <p className="text-sm text-sec-600">Active users</p>
-          </CardContent>
-        </Card>
-      </div>
-
-      {/* Recent Activity */}
-      <Card>
-        <CardHeader>
-          <CardTitle>Recent Activity</CardTitle>
-        </CardHeader>
-        <CardContent>
-          <p className="text-sec-600">
-            Your meal tracking activity will appear here.
-          </p>
-        </CardContent>
-      </Card>
-    </div>
-  );
-}
-```
-
-### 6. MealsPage.tsx - Advanced DataTable
-
-```tsx
-import { useState } from 'react';
-import { 
-  DataTable, 
-  Button, 
-  useToast,
-  useUnifiedAuth 
-} from '@jmruthers/pace-core';
-import { MealForm } from './MealForm';
-import { useMeals } from '../../hooks/useMeals';
-import { Meal } from '../../types/meal';
-
-export function MealsPage() {
-  const [showForm, setShowForm] = useState(false);
-  const [editingMeal, setEditingMeal] = useState<Meal | null>(null);
-  const { meals, loading, createMeal, updateMeal, deleteMeal } = useMeals();
-  const { hasPermission } = useUnifiedAuth();
-  const { toast } = useToast();
-
-  const canCreate = hasPermission('create:meals');
-  const canEdit = hasPermission('update:meals');
-  const canDelete = hasPermission('delete:meals');
-
-  const columns = [
-    {
-      accessorKey: 'name',
-      header: 'Meal Name',
-    },
-    {
-      accessorKey: 'category',
-      header: 'Category',
-    },
-    {
-      accessorKey: 'calories',
-      header: 'Calories',
-    },
-    {
-      accessorKey: 'date',
-      header: 'Date',
-    },
-    {
-      id: 'actions',
-      header: 'Actions',
-      cell: ({ row }: any) => (
-        <div className="flex gap-2">
-          {canEdit && (
-            <Button
-              variant="outline"
-              size="sm"
-              onClick={() => setEditingMeal(row.original)}
-            >
-              Edit
-            </Button>
-          )}
-          {canDelete && (
-            <Button
-              variant="destructive"
-              size="sm"
-              onClick={() => handleDelete(row.original.id)}
-            >
-              Delete
-            </Button>
-          )}
-        </div>
-      ),
-    },
-  ];
-
-  const handleDelete = async (id: string) => {
-    try {
-      await deleteMeal(id);
-      toast({
-        title: 'Success',
-        description: 'Meal deleted successfully',
-      });
-    } catch (error) {
-      toast({
-        title: 'Error',
-        description: 'Failed to delete meal',
-        variant: 'destructive',
-      });
-    }
-  };
-
-  const handleSubmit = async (mealData: Partial<Meal>) => {
-    try {
-      if (editingMeal) {
-        await updateMeal(editingMeal.id, mealData);
-        toast({
-          title: 'Success',
-          description: 'Meal updated successfully',
-        });
-      } else {
-        await createMeal(mealData);
-        toast({
-          title: 'Success',
-          description: 'Meal created successfully',
-        });
-      }
-      setShowForm(false);
-      setEditingMeal(null);
-    } catch (error) {
-      toast({
-        title: 'Error',
-        description: 'Failed to save meal',
-        variant: 'destructive',
-      });
-    }
-  };
-
-  return (
-    <div className="p-6">
-      <div className="flex justify-between items-center mb-6">
-        <h1 className="text-2xl font-bold">Meals</h1>
-        {canCreate && (
-          <Button onClick={() => setShowForm(true)}>
-            Add Meal
-          </Button>
-        )}
-      </div>
-      
-      <DataTable
-        data={meals || []}
-        columns={columns}
-        isLoading={loading}
-        features={{
-          search: true,
-          pagination: true,
-        }}
-        onRowClick={(meal) => canEdit && setEditingMeal(meal)}
-      />
-
-      {showForm && (
-        <MealForm
-          meal={editingMeal}
-          onSubmit={handleSubmit}
-          onCancel={() => {
-            setShowForm(false);
-            setEditingMeal(null);
-          }}
-        />
-      )}
-    </div>
-  );
-}
-```
-
-### 7. MealForm.tsx - Form with Validation
-
-```tsx
-import { useForm } from 'react-hook-form';
-import { zodResolver } from '@hookform/resolvers/zod';
-import { z } from 'zod';
-import { 
-  Form, 
-  FormField, 
-  FormItem, 
-  FormLabel, 
-  FormControl, 
-  FormMessage,
-  Button,
-  Input,
-  Select,
-  SelectContent,
-  SelectItem,
-  SelectTrigger,
-  SelectValue,
-  Card,
-  CardHeader,
-  CardTitle,
-  CardContent
-} from '@jmruthers/pace-core';
-import { Meal } from '../../types/meal';
-
-const mealSchema = z.object({
-  name: z.string().min(1, 'Meal name is required'),
-  category: z.string().min(1, 'Category is required'),
-  calories: z.number().min(1, 'Calories must be greater than 0'),
-  date: z.string().min(1, 'Date is required'),
-});
-
-interface MealFormProps {
-  meal?: Meal | null;
-  onSubmit: (data: Partial<Meal>) => Promise<void>;
-  onCancel: () => void;
-}
-
-export function MealForm({ meal, onSubmit, onCancel }: MealFormProps) {
-  const form = useForm({
-    resolver: zodResolver(mealSchema),
-    defaultValues: {
-      name: meal?.name || '',
-      category: meal?.category || '',
-      calories: meal?.calories || 0,
-      date: meal?.date || new Date().toISOString().split('T')[0],
-    },
-  });
-
-  const handleSubmit = async (data: any) => {
-    await onSubmit(data);
-  };
-
-  return (
-    <Card className="mt-6">
-      <CardHeader>
-        <CardTitle>{meal ? 'Edit Meal' : 'Add New Meal'}</CardTitle>
-      </CardHeader>
-      <CardContent>
-        <Form {...form}>
-          <form onSubmit={form.handleSubmit(handleSubmit)} className="space-y-4">
-            <FormField
-              control={form.control}
-              name="name"
-              render={({ field }) => (
-                <FormItem>
-                  <FormLabel>Meal Name</FormLabel>
-                  <FormControl>
-                    <Input placeholder="Enter meal name" {...field} />
-                  </FormControl>
-                  <FormMessage />
-                </FormItem>
-              )}
-            />
-
-            <FormField
-              control={form.control}
-              name="category"
-              render={({ field }) => (
-                <FormItem>
-                  <FormLabel>Category</FormLabel>
-                  <Select onValueChange={field.onChange} defaultValue={field.value}>
-                    <FormControl>
-                      <SelectTrigger>
-                        <SelectValue placeholder="Select category" />
-                      </SelectTrigger>
-                    </FormControl>
-                    <SelectContent>
-                      <SelectItem value="breakfast">Breakfast</SelectItem>
-                      <SelectItem value="lunch">Lunch</SelectItem>
-                      <SelectItem value="dinner">Dinner</SelectItem>
-                      <SelectItem value="snack">Snack</SelectItem>
-                    </SelectContent>
-                  </Select>
-                  <FormMessage />
-                </FormItem>
-              )}
-            />
-
-            <FormField
-              control={form.control}
-              name="calories"
-              render={({ field }) => (
-                <FormItem>
-                  <FormLabel>Calories</FormLabel>
-                  <FormControl>
-                    <Input 
-                      type="number" 
-                      placeholder="Enter calories" 
-                      {...field}
-                      onChange={(e) => field.onChange(parseInt(e.target.value) || 0)}
-                    />
-                  </FormControl>
-                  <FormMessage />
-                </FormItem>
-              )}
-            />
-
-            <FormField
-              control={form.control}
-              name="date"
-              render={({ field }) => (
-                <FormItem>
-                  <FormLabel>Date</FormLabel>
-                  <FormControl>
-                    <Input type="date" {...field} />
-                  </FormControl>
-                  <FormMessage />
-                </FormItem>
-              )}
-            />
-
-            <div className="flex gap-2 pt-4">
-              <Button type="submit">
-                {meal ? 'Update Meal' : 'Add Meal'}
-              </Button>
-              <Button type="button" variant="outline" onClick={onCancel}>
-                Cancel
-              </Button>
-            </div>
-          </form>
-        </Form>
-      </CardContent>
-    </Card>
-  );
-}
-```
-
-## 🔧 Environment Setup
-
-Create `.env.local`:
-
-```bash
-REACT_APP_SUPABASE_URL=https://your-project.supabase.co
-REACT_APP_SUPABASE_ANON_KEY=your-anon-key-here
-```
-
-## 🎉 What You Get
-
-- ✅ Complete authentication with RBAC
-- ✅ Multi-tenant organisation support
-- ✅ Event management
-- ✅ Advanced DataTable with CRUD
-- ✅ Form validation with Zod
-- ✅ Permission enforcement
-- ✅ Responsive layout
-- ✅ Error handling and loading states
-- ✅ Toast notifications
-- ✅ Production-ready patterns
-
-## 🚀 Next Steps
-
-- **Customize the design** - Adapt to your brand
-- **Add more features** - Reporting, analytics, integrations
-- **Implement real data** - Connect to your database
-- **Add tests** - Unit and integration testing
-- **Deploy** - Production deployment
-
-## 📚 Related Documentation
-
-- **[Core Concepts](../core-concepts/)** - Understand authentication and RBAC
-- **[Implementation Guides](../implementation-guides/)** - Advanced patterns
-- **[API Reference](../api-reference/)** - All components and hooks
-- **[Best Practices](../best-practices/)** - Production deployment