@jmruthers/pace-core 0.5.139 → 0.5.140

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

@@ -0,0 +1,616 @@
+# 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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@jmruthers/pace-core",
-  "version": "0.5.139",
+  "version": "0.5.140",
   "description": "Clean, modern React component library with Tailwind v4 styling and native utilities",
   "private": false,
   "publishConfig": {

package/src/utils/performance/bundleAnalysis.ts

@@ -14,7 +14,13 @@ interface ChunkInfo {
 }
 
 class BundleAnalyzer {
-  private enabled = import.meta.env.MODE === 'development';
+  private get enabled(): boolean {
+    try {
+      return import.meta.env?.MODE === 'development';
+    } catch {
+      return false;
+    }
+  }
 
   analyzeBundle(): BundleStats | null {
     if (!this.enabled) return null;
@@ -104,7 +110,11 @@ export const bundleAnalyzer = new BundleAnalyzer();
 
 // Helper to check if imports are optimized
 export function validateImportPattern(moduleId: string, importedItems: string[]): void {
-  if (import.meta.env.MODE !== 'development') return;
+  try {
+    if (import.meta.env?.MODE !== 'development') return;
+  } catch {
+    return; // Silently skip in test environments
+  }
 
   const largeModules = ['lodash', 'moment', 'rxjs'];
   const isLargeModule = largeModules.some(mod => moduleId.includes(mod));
@@ -121,7 +131,11 @@ export function validateImportPattern(moduleId: string, importedItems: string[])
 
 // Monitor dynamic imports
 export function trackDynamicImport(moduleName: string): void {
-  if (import.meta.env.MODE !== 'development') return;
+  try {
+    if (import.meta.env?.MODE !== 'development') return;
+  } catch {
+    return; // Silently skip in test environments
+  }
   
   // TODO: Replace with proper logging service integration
   // For now, we'll log to console for testing purposes