@jmruthers/pace-core 0.5.76 → 0.5.78

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

@@ -1,520 +0,0 @@
-# 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 demonstrating authentication, basic UI components, and responsive design.
-
-## 🎯 What You'll Build
-
-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
-
-```
-src/
-├── components/
-│   ├── Dashboard.tsx
-│   ├── LoginForm.tsx
-│   └── Navigation.tsx
-├── hooks/
-│   └── useSupabase.ts
-├── types/
-│   └── index.ts
-├── App.tsx
-├── main.tsx
-└── index.css
-```
-
-### 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);
-```
-
-### 6. Types Definition
-
-`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/src/styles/core.css';
-
-function App() {
-  return (
-    <UnifiedAuthProvider 
-      supabaseClient={supabase} 
-      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>
-    </UnifiedAuthProvider>
-  );
-}
-
-export default App;
-```
-
-### 8. Login Form Component
-
-`src/components/LoginForm.tsx`:
-```tsx
-import React, { useState } from 'react';
-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('');
-  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);
-    }
-  };
-
-  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>
-  );
-};
-
-export default LoginForm;
-```
-
-### 9. Dashboard Component
-
-`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 { useUnifiedAuth } from '@jmruthers/pace-core';
-
-const Dashboard: React.FC = () => {
-  const { user, signOut, loading } = 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 () => {
-    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>
-
-        <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>
-          </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>
-          </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>
-          </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;
-      }}
-    />
-  );
-};
-
-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
-
-# Build for production
-npm run build
-
-# Preview production build
-npm run preview
-```
-
-## 🎯 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
-
-## 📚 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
-
-### Common Issues
-
-**Styling not working:**
-- Ensure CSS import is first: `import '@jmruthers/pace-core/src/styles/core.css';`
-- Check Vite configuration for content scanning
-
-**Authentication not working:**
-- Verify Supabase credentials in `.env.local`
-- Check database setup and RLS policies
-
-**Build errors:**
-- Clear node_modules and reinstall
-- Check TypeScript configuration
-- Verify all imports are correct
-
-For more help, see the [Troubleshooting Guide](../../troubleshooting/README.md).