@jmruthers/pace-core 0.2.7 → 0.4.1

package/docs/getting-started/examples/basic-auth-app.md

@@ -1,141 +1,52 @@
 # Basic Authentication App
 
-> **🎯 Perfect for**: Learning the basics, simple apps, prototypes  
-> **⏱️ Build Time**: ~15 minutes  
-> **Prerequisites**: Node.js 18+, basic React knowledge
+A minimal PACE Core application showing just authentication and basic UI components.
 
-A minimal PACE Core application demonstrating authentication, basic UI components, and responsive design.
+## 🎯 What This Example Shows
 
-## 🎯 What You'll Build
+- Basic authentication setup
+- Simple login/logout flow
+- Basic dashboard with cards
+- Responsive navigation
+- Minimal code structure
 
-A simple dashboard app with:
-- User login/logout functionality
-- Basic dashboard with user info
-- Simple navigation
-- Responsive design
-- Permission-based content
-
-## 🚀 Step-by-Step Implementation
-
-### 1. Project Setup
-
-```bash
-# Create new React app
-npx create-react-app basic-auth-app --template typescript
-cd basic-auth-app
-
-# Install PACE Core
-npm install @jmruthers/pace-core
-
-# Install additional dependencies
-npm install @supabase/supabase-js react-router-dom
-```
-
-### 2. Environment Configuration
-
-Create `.env.local`:
-```env
-VITE_SUPABASE_URL=your_supabase_url
-VITE_SUPABASE_ANON_KEY=your_supabase_anon_key
-VITE_APP_NAME=Basic Auth App
-```
-
-### 3. Supabase Setup
-
-Create a new Supabase project and set up the database:
-
-```sql
--- Create users table
-CREATE TABLE users (
-  id UUID REFERENCES auth.users(id) PRIMARY KEY,
-  email TEXT UNIQUE NOT NULL,
-  name TEXT,
-  role TEXT DEFAULT 'user',
-  created_at TIMESTAMP WITH TIME ZONE DEFAULT NOW()
-);
-
--- Enable RLS
-ALTER TABLE users ENABLE ROW LEVEL SECURITY;
-
--- Create policy
-CREATE POLICY "Users can view their own data" ON users
-  FOR SELECT USING (auth.uid() = id);
-```
-
-### 4. App Structure
+## 📁 Project Structure
 
 ```
 src/
+├── App.tsx                 # Main app with providers
+├── lib/
+│   └── supabase.ts        # Supabase client
 ├── components/
-│   ├── Dashboard.tsx
-│   ├── LoginForm.tsx
-│   └── Navigation.tsx
-├── hooks/
-│   └── useSupabase.ts
-├── types/
-│   └── index.ts
-├── App.tsx
-├── main.tsx
-└── index.css
+│   ├── LoginPage.tsx      # Login form
+│   ├── Dashboard.tsx      # Simple dashboard
+│   └── Navigation.tsx     # Basic navigation
+└── main.tsx               # App entry point
 ```
 
-### 5. Supabase Client Setup
-
-`src/hooks/useSupabase.ts`:
-```tsx
-import { createClient } from '@supabase/supabase-js';
-
-const supabaseUrl = import.meta.env.VITE_SUPABASE_URL;
-const supabaseKey = import.meta.env.VITE_SUPABASE_ANON_KEY;
-
-export const supabase = createClient(supabaseUrl, supabaseKey);
-```
+## 🚀 Implementation
 
-### 6. Types Definition
+### 1. App.tsx - Main Application
 
-`src/types/index.ts`:
 ```tsx
-export interface User {
-  id: string;
-  email: string;
-  name: string;
-  role: 'admin' | 'user';
-}
-
-export interface AuthState {
-  user: User | null;
-  loading: boolean;
-  error: string | null;
-}
-```
-
-### 7. Main App Component
-
-`src/App.tsx`:
-```tsx
-import React from 'react';
-import { BrowserRouter as Router, Routes, Route } from 'react-router-dom';
 import { UnifiedAuthProvider } from '@jmruthers/pace-core';
-import { supabase } from './hooks/useSupabase';
-import LoginForm from './components/LoginForm';
-import Dashboard from './components/Dashboard';
-import '@jmruthers/pace-core/styles/core.css';
+import { BrowserRouter, Routes, Route } from 'react-router-dom';
+import { supabase } from './lib/supabase';
+import { LoginPage } from './components/LoginPage';
+import { Dashboard } from './components/Dashboard';
 
 function App() {
   return (
     <UnifiedAuthProvider 
       supabaseClient={supabase} 
-      appName="Basic Auth App"
+      appName="basic-auth-app"
     >
-      <Router>
-        <div className="min-h-screen bg-gray-50">
-          <Routes>
-            <Route path="/login" element={<LoginForm />} />
-            <Route path="/" element={<Dashboard />} />
-            <Route path="/dashboard" element={<Dashboard />} />
-          </Routes>
-        </div>
-      </Router>
+      <BrowserRouter>
+        <Routes>
+          <Route path="/login" element={<LoginPage />} />
+          <Route path="/" element={<Dashboard />} />
+        </Routes>
+      </BrowserRouter>
     </UnifiedAuthProvider>
   );
 }
@@ -143,379 +54,143 @@ function App() {
 export default App;
 ```
 
-### 8. Login Form Component
+### 2. lib/supabase.ts - Supabase Client
+
+```typescript
+import { createClient } from '@supabase/supabase-js';
+
+const supabaseUrl = process.env.REACT_APP_SUPABASE_URL!;
+const supabaseAnonKey = process.env.REACT_APP_SUPABASE_ANON_KEY!;
+
+export const supabase = createClient(supabaseUrl, supabaseAnonKey);
+```
+
+### 3. components/LoginPage.tsx - Login Form
 
-`src/components/LoginForm.tsx`:
 ```tsx
-import React, { useState } from 'react';
+import { LoginForm, Card, CardHeader, CardTitle, CardContent } from '@jmruthers/pace-core';
 import { useNavigate } from 'react-router-dom';
-import { Button, Card, Input, Alert } from '@jmruthers/pace-core';
-import { useUnifiedAuth } from '@jmruthers/pace-core';
 
-const LoginForm: React.FC = () => {
-  const [email, setEmail] = useState('');
-  const [password, setPassword] = useState('');
-  const [loading, setLoading] = useState(false);
-  const [error, setError] = useState('');
+export function LoginPage() {
   const navigate = useNavigate();
-  const { signIn } = useUnifiedAuth();
-
-  const handleSubmit = async (e: React.FormEvent) => {
-    e.preventDefault();
-    setLoading(true);
-    setError('');
-
-    try {
-      await signIn({ email, password });
-      navigate('/dashboard');
-    } catch (err) {
-      setError(err instanceof Error ? err.message : 'Login failed');
-    } finally {
-      setLoading(false);
-    }
+
+  const handleLoginSuccess = () => {
+    navigate('/');
   };
 
   return (
-    <div className="min-h-screen flex items-center justify-center bg-gray-50 py-12 px-4 sm:px-6 lg:px-8">
-      <div className="max-w-md w-full space-y-8">
-        <div>
-          <h2 className="mt-6 text-center text-3xl font-extrabold text-gray-900">
-            Sign in to your account
-          </h2>
-        </div>
-        
-        <Card className="mt-8 space-y-6 p-8">
-          <form onSubmit={handleSubmit} className="space-y-6">
-            {error && (
-              <Alert variant="destructive">
-                {error}
-              </Alert>
-            )}
-            
-            <div>
-              <Input
-                label="Email address"
-                type="email"
-                value={email}
-                onChange={(e) => setEmail(e.target.value)}
-                required
-                placeholder="Enter your email"
-              />
-            </div>
-            
-            <div>
-              <Input
-                label="Password"
-                type="password"
-                value={password}
-                onChange={(e) => setPassword(e.target.value)}
-                required
-                placeholder="Enter your password"
-              />
-            </div>
-            
-            <Button
-              type="submit"
-              className="w-full"
-              disabled={loading}
-            >
-              {loading ? 'Signing in...' : 'Sign in'}
-            </Button>
-          </form>
-        </Card>
-      </div>
+    <div className="min-h-screen flex items-center justify-center bg-gray-50">
+      <Card className="w-full max-w-md">
+        <CardHeader>
+          <CardTitle className="text-center">Welcome Back</CardTitle>
+        </CardHeader>
+        <CardContent>
+          <LoginForm onLoginSuccess={handleLoginSuccess} />
+        </CardContent>
+      </Card>
     </div>
   );
-};
-
-export default LoginForm;
+}
 ```
 
-### 9. Dashboard Component
+### 4. components/Dashboard.tsx - Simple Dashboard
 
-`src/components/Dashboard.tsx`:
 ```tsx
-import React from 'react';
-import { useNavigate } from 'react-router-dom';
-import { 
-  Card, 
-  Button, 
-  Alert,
-  PaceAppLayout,
-  Header,
-  UserMenu
-} from '@jmruthers/pace-core';
+import { Card, CardHeader, CardTitle, CardContent, Button } from '@jmruthers/pace-core';
 import { useUnifiedAuth } from '@jmruthers/pace-core';
+import { useNavigate } from 'react-router-dom';
 
-const Dashboard: React.FC = () => {
-  const { user, signOut, loading } = useUnifiedAuth();
+export function Dashboard() {
+  const { user, signOut } = useUnifiedAuth();
   const navigate = useNavigate();
 
-  if (loading) {
-    return (
-      <div className="min-h-screen flex items-center justify-center">
-        <div className="text-center">
-          <div className="animate-spin rounded-full h-32 w-32 border-b-2 border-blue-600 mx-auto"></div>
-          <p className="mt-4 text-gray-600">Loading...</p>
-        </div>
-      </div>
-    );
-  }
-
-  if (!user) {
-    navigate('/login');
-    return null;
-  }
-
-  const handleLogout = async () => {
+  const handleSignOut = async () => {
     await signOut();
     navigate('/login');
   };
 
-  const navigationItems = [
-    { label: 'Dashboard', href: '/dashboard', icon: 'Home' },
-    { label: 'Profile', href: '/profile', icon: 'User' },
-    { label: 'Settings', href: '/settings', icon: 'Settings' }
-  ];
-
   return (
-    <PaceAppLayout
-      title="Basic Auth App"
-      user={user}
-      onLogout={handleLogout}
-      navigation={navigationItems}
-    >
-      <div className="p-6">
-        <div className="mb-6">
-          <h1 className="text-3xl font-bold text-gray-900">Welcome, {user.name || user.email}!</h1>
-          <p className="text-gray-600">This is your basic dashboard.</p>
+    <div className="min-h-screen bg-gray-50 p-6">
+      <div className="max-w-4xl mx-auto">
+        {/* Header */}
+        <div className="flex justify-between items-center mb-8">
+          <h1 className="text-3xl font-bold text-gray-900">Dashboard</h1>
+          <div className="flex items-center gap-4">
+            <span className="text-gray-600">Welcome, {user?.email}</span>
+            <Button variant="outline" onClick={handleSignOut}>
+              Sign Out
+            </Button>
+          </div>
         </div>
 
+        {/* Content Cards */}
         <div className="grid grid-cols-1 md:grid-cols-2 lg:grid-cols-3 gap-6">
           <Card>
-            <div className="p-6">
-              <h3 className="text-lg font-semibold text-gray-900 mb-2">User Info</h3>
-              <p className="text-gray-600 mb-4">Your account details</p>
-              <div className="space-y-2">
-                <p><strong>Email:</strong> {user.email}</p>
-                <p><strong>Role:</strong> {user.role}</p>
-                <p><strong>ID:</strong> {user.id}</p>
-              </div>
-            </div>
-          </Card>
-
-          <Card>
-            <div className="p-6">
-              <h3 className="text-lg font-semibold text-gray-900 mb-2">Quick Actions</h3>
-              <p className="text-gray-600 mb-4">Common tasks</p>
-              <div className="space-y-2">
-                <Button variant="outline" className="w-full justify-start">
-                  Edit Profile
-                </Button>
-                <Button variant="outline" className="w-full justify-start">
-                  Change Password
-                </Button>
-                <Button variant="outline" className="w-full justify-start">
-                  View Settings
-                </Button>
-              </div>
-            </div>
+            <CardHeader>
+              <CardTitle>Getting Started</CardTitle>
+            </CardHeader>
+            <CardContent>
+              <p className="text-gray-600">
+                Welcome to your PACE Core application! This is a basic example showing authentication and UI components.
+              </p>
+            </CardContent>
           </Card>
 
           <Card>
-            <div className="p-6">
-              <h3 className="text-lg font-semibold text-gray-900 mb-2">System Status</h3>
-              <p className="text-gray-600 mb-4">Application health</p>
-              <Alert>
-                <div className="flex items-center">
-                  <div className="w-2 h-2 bg-green-500 rounded-full mr-2"></div>
-                  All systems operational
-                </div>
-              </Alert>
-            </div>
+            <CardHeader>
+              <CardTitle>Next Steps</CardTitle>
+            </CardHeader>
+            <CardContent>
+              <p className="text-gray-600">
+                Explore the examples to learn about DataTables, forms, navigation, and more advanced features.
+              </p>
+            </CardContent>
           </Card>
-        </div>
 
-        <div className="mt-8">
           <Card>
-            <div className="p-6">
-              <h3 className="text-lg font-semibold text-gray-900 mb-4">Recent Activity</h3>
-              <div className="space-y-3">
-                <div className="flex items-center justify-between py-2 border-b border-gray-200">
-                  <span className="text-gray-600">Logged in successfully</span>
-                  <span className="text-sm text-gray-500">Just now</span>
-                </div>
-                <div className="flex items-center justify-between py-2 border-b border-gray-200">
-                  <span className="text-gray-600">Account created</span>
-                  <span className="text-sm text-gray-500">2 days ago</span>
-                </div>
-              </div>
-            </div>
+            <CardHeader>
+              <CardTitle>Resources</CardTitle>
+            </CardHeader>
+            <CardContent>
+              <p className="text-gray-600">
+                Check out the documentation for implementation guides, API reference, and best practices.
+              </p>
+            </CardContent>
           </Card>
         </div>
       </div>
-    </PaceAppLayout>
-  );
-};
-
-export default Dashboard;
-```
-
-### 10. Navigation Component
-
-`src/components/Navigation.tsx`:
-```tsx
-import React from 'react';
-import { Link, useLocation } from 'react-router-dom';
-import { NavigationMenu } from '@jmruthers/pace-core';
-
-const Navigation: React.FC = () => {
-  const location = useLocation();
-
-  const navigationItems = [
-    { label: 'Dashboard', href: '/dashboard', icon: 'Home' },
-    { label: 'Profile', href: '/profile', icon: 'User' },
-    { label: 'Settings', href: '/settings', icon: 'Settings' }
-  ];
-
-  return (
-    <NavigationMenu
-      items={navigationItems}
-      currentPath={location.pathname}
-      onNavigate={(href) => {
-        // Navigation is handled by React Router
-        window.location.href = href;
-      }}
-    />
+    </div>
   );
-};
-
-export default Navigation;
-```
-
-### 11. Vite Configuration
-
-`vite.config.ts`:
-```ts
-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/**/*.{js,ts,jsx,tsx}'
-      ]
-    })
-  ],
-  server: {
-    port: 3000,
-    open: true
-  }
-});
-```
-
-### 12. Package.json Scripts
-
-```json
-{
-  "scripts": {
-    "dev": "vite",
-    "build": "tsc && vite build",
-    "preview": "vite preview",
-    "type-check": "tsc --noEmit"
-  }
 }
 ```
 
-## 🚀 Running the App
-
-```bash
-# Start development server
-npm run dev
+## 🔧 Environment Setup
 
-# Build for production
-npm run build
+Create `.env.local`:
 
-# Preview production build
-npm run preview
+```bash
+REACT_APP_SUPABASE_URL=https://your-project.supabase.co
+REACT_APP_SUPABASE_ANON_KEY=your-anon-key-here
 ```
 
-## 🎯 Features Demonstrated
-
-### Authentication
-- ✅ User login with email/password
-- ✅ Session management
-- ✅ Automatic redirects
-- ✅ Loading states
-- ✅ Error handling
-
-### UI Components
-- ✅ Card layouts
-- ✅ Form inputs
-- ✅ Buttons with variants
-- ✅ Alerts and notifications
-- ✅ Responsive design
-
-### Layout
-- ✅ App layout with header
-- ✅ Navigation menu
-- ✅ User menu
-- ✅ Responsive sidebar
-
-### State Management
-- ✅ Authentication state
-- ✅ User data
-- ✅ Loading states
-- ✅ Error states
-
-## 🔧 Customization
-
-### Adding New Pages
-
-1. Create new component in `src/components/`
-2. Add route in `App.tsx`
-3. Add navigation item in `Navigation.tsx`
-
-### Styling
-
-The app uses PACE Core's design system. You can customize:
-- Colors via CSS variables
-- Typography via Tailwind classes
-- Component variants via props
-
-### Adding Features
-
-- **Forms**: Use PACE Core's Form components
-- **Data Tables**: Add DataTable for data management
-- **Permissions**: Implement RBAC with useCan hook
-- **Print Reports**: Add PrintLayout components
-
-## 📚 Next Steps
-
-- **[Full-Featured App](./full-featured-app.md)** - Complete application with all features
-- **[Data Tables Guide](../implementation-guides/data-tables.md)** - Advanced data management
-- **[Forms Guide](../implementation-guides/forms.md)** - Form handling and validation
-- **[RBAC Guide](../../rbac/README.md)** - Role-based access control
-
-## 🐛 Troubleshooting
+## 🎉 What You Get
 
-### Common Issues
+- ✅ User authentication with Supabase
+- ✅ Protected dashboard route
+- ✅ Responsive UI components
+- ✅ Clean, minimal code structure
+- ✅ Easy to extend and customize
 
-**Styling not working:**
-- Ensure CSS import is first: `import '@jmruthers/pace-core/styles/core.css';`
-- Check Vite configuration for content scanning
+## 🚀 Next Steps
 
-**Authentication not working:**
-- Verify Supabase credentials in `.env.local`
-- Check database setup and RLS policies
+- **Add more features** - Forms, data tables, navigation
+- **Implement RBAC** - Role-based access control
+- **Add organisation support** - Multi-tenant features
+- **Explore components** - See all available UI components
 
-**Build errors:**
-- Clear node_modules and reinstall
-- Check TypeScript configuration
-- Verify all imports are correct
+## 📚 Related Documentation
 
-For more help, see the [Troubleshooting Guide](../../troubleshooting/README.md).
+- **[Quick Start](../quick-start.md)** - Build a full-featured app
+- **[Core Concepts](../core-concepts/)** - Understand authentication and RBAC
+- **[API Reference](../api-reference/)** - Explore all components and hooks
+- **[Implementation Guides](../implementation-guides/)** - Advanced patterns

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

@@ -225,8 +225,8 @@ export function DashboardPage() {
   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">
+        <h1 className="text-3xl font-bold text-gray-900">Dashboard</h1>
+        <p className="text-gray-600 mt-2">
           Welcome back, {user?.email}. Here's what's happening with your meals.
         </p>
       </div>
@@ -238,7 +238,7 @@ export function DashboardPage() {
           </CardHeader>
           <CardContent>
             <p className="text-3xl font-bold">{mealsLoading ? '...' : totalMeals}</p>
-            <p className="text-sm text-sec-600">All time</p>
+            <p className="text-sm text-gray-600">All time</p>
           </CardContent>
         </Card>
         
@@ -248,7 +248,7 @@ export function DashboardPage() {
           </CardHeader>
           <CardContent>
             <p className="text-3xl font-bold">{mealsLoading ? '...' : thisWeekMeals}</p>
-            <p className="text-sm text-sec-600">Last 7 days</p>
+            <p className="text-sm text-gray-600">Last 7 days</p>
           </CardContent>
         </Card>
         
@@ -258,7 +258,7 @@ export function DashboardPage() {
           </CardHeader>
           <CardContent>
             <p className="text-3xl font-bold">{usersLoading ? '...' : totalUsers}</p>
-            <p className="text-sm text-sec-600">Active users</p>
+            <p className="text-sm text-gray-600">Active users</p>
           </CardContent>
         </Card>
       </div>
@@ -269,7 +269,7 @@ export function DashboardPage() {
           <CardTitle>Recent Activity</CardTitle>
         </CardHeader>
         <CardContent>
-          <p className="text-sec-600">
+          <p className="text-gray-600">
             Your meal tracking activity will appear here.
           </p>
         </CardContent>