@jmruthers/pace-core 0.2.7 → 0.4.1

package/docs/getting-started/installation.md

@@ -1,269 +1,90 @@
-# Complete Installation Guide
+# Installation & Setup
 
-This is the definitive guide for installing and configuring pace-core in your application. Follow these steps exactly to ensure proper styling and functionality.
+Get PACE Core up and running in your project in under 5 minutes.
 
-## 🚨 Critical Requirements
+## Prerequisites
 
-**IMPORTANT**: Pace-core requires specific configuration to work properly. Without following these steps exactly, components will be unstyled and the UI will be severely compromised.
+- Node.js 18+ and npm/yarn/pnpm
+- React 18+ project (Next.js, Create React App, Vite, etc.)
+- Supabase project (free tier works great)
 
-## Step 1: Install Dependencies
+## Quick Installation
 
-### Required Packages
+### 1. Install Dependencies
 
 ```bash
-# Install pace-core and all required peer dependencies
-npm install @jmruthers/pace-core @tanstack/react-table @radix-ui/react-checkbox @radix-ui/react-dialog @radix-ui/react-dropdown-menu @radix-ui/react-label @radix-ui/react-slot lucide-react class-variance-authority clsx tailwind-merge
-
-# Install Tailwind CSS v4 and Vite plugin (REQUIRED)
-npm install -D @tailwindcss/vite tailwindcss@^4.0.0
+npm install @jmruthers/pace-core @supabase/supabase-js
+npm install -D tailwindcss @types/react @types/react-dom
 ```
 
-### Optional Packages (for full functionality)
+### 2. Configure Tailwind CSS
 
 ```bash
-# For authentication and database
-npm install @supabase/supabase-js
-
-# For routing
-npm install react-router-dom
-
-# For TypeScript support
-npm install -D @types/react @types/react-dom
+npx tailwindcss init
 ```
 
-## Step 2: Configure Vite with Tailwind v4
-
-**⚠️ CRITICAL**: This configuration is essential for pace-core components to be styled correctly.
+Update your `tailwind.config.js`:
 
-Create or update your `vite.config.ts`:
-
-```typescript
-// vite.config.ts
-import { defineConfig } from 'vite'
-import react from '@vitejs/plugin-react'
-import tailwindcss from '@tailwindcss/vite'
-import path from 'path'
-
-export default defineConfig({
-  plugins: [
-    react(),
-    tailwindcss({
-      // CRITICAL: Include pace-core components for scanning
-      content: [
-        './src/**/*.{js,ts,jsx,tsx}',
-        './node_modules/@jmruthers/pace-core/**/*.{js,ts,jsx,tsx}'
-      ]
-    })
+```js
+/** @type {import('tailwindcss').Config} */
+module.exports = {
+  content: [
+    './src/**/*.{js,ts,jsx,tsx}',
+    './node_modules/@jmruthers/pace-core/**/*.{js,ts,jsx,tsx}',
   ],
-  resolve: {
-    alias: {
-      "@": path.resolve(__dirname, "./src"),
-    },
-  },
-  server: {
-    port: 3000,
-    open: true,
-  },
-  build: {
-    outDir: 'dist',
-    sourcemap: true,
+  theme: {
+    extend: {},
   },
-})
+  plugins: [],
+}
 ```
 
-### Why This Configuration is Critical
-
-Pace-core components contain Tailwind classes that must be scanned during the build process. Without this configuration:
-
-- ❌ Component styles will be missing or broken
-- ❌ Colors, spacing, and typography won't work
-- ❌ The UI will be severely compromised
-- ❌ The entire point of using this UI library is undermined
-
-### Alternative Configuration (if needed)
+### 3. Set Up Environment Variables
 
-If you're still having issues with component scanning:
+Create `.env.local` (or `.env` for Create React App):
 
-```typescript
-// vite.config.ts
-import { defineConfig } from 'vite'
-import react from '@vitejs/plugin-react'
-import tailwindcss from '@tailwindcss/vite'
+```bash
+# Supabase Configuration
+NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
+NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key-here
 
-export default defineConfig({
-  plugins: [
-    react(),
-    tailwindcss({
-      content: {
-        files: [
-          './src/**/*.{js,ts,jsx,tsx}',
-          './node_modules/@jmruthers/pace-core/**/*.{js,ts,jsx,tsx}',
-          './node_modules/@jmruthers/pace-core/dist/**/*.{js,ts,jsx,tsx}'
-        ]
-      }
-    })
-  ],
-})
+# For Create React App, use REACT_APP_ prefix:
+# REACT_APP_SUPABASE_URL=https://your-project.supabase.co
+# REACT_APP_SUPABASE_ANON_KEY=your-anon-key-here
 ```
 
-## Step 3: Import Core Styles
-
-**CRITICAL**: Import the CSS file in your main entry point:
+### 4. Basic Provider Setup
 
 ```tsx
-// src/main.tsx (or your app's entry point)
-import '@jmruthers/pace-core/styles/core.css';
-import React from 'react';
-import ReactDOM from 'react-dom/client';
-import App from './App';
+// App.tsx
+import { UnifiedAuthProvider } from '@jmruthers/pace-core';
+import { createClient } from '@supabase/supabase-js';
 
-const root = ReactDOM.createRoot(document.getElementById('root') as HTMLElement);
-root.render(
-  <React.StrictMode>
-    <App />
-  </React.StrictMode>
+const supabase = createClient(
+  process.env.NEXT_PUBLIC_SUPABASE_URL!,
+  process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!
 );
-```
-
-### What the CSS File Includes
-
-The `core.css` file provides:
-- Complete color palettes (main, secondary, accent)
-- Font definitions with system font fallbacks
-- Base element styles and resets
-- Tailwind v4 utility classes
-- Component styling foundation
-
-**Note on Fonts**: The CSS includes font definitions that fall back to system fonts. For custom fonts, you'll need to provide them separately in your consuming app.
-
-## Step 4: Verify Installation
-
-Create a test component to ensure everything works:
-
-```tsx
-// src/App.tsx
-import { Button, Card, Input } from '@jmruthers/pace-core';
 
 function App() {
   return (
-    <div className="p-8 space-y-4">
-      <h1 className="text-2xl font-bold text-main-900">PACE Core Test</h1>
-      
-      <Card className="p-4">
-        <h2 className="text-lg font-semibold text-sec-800 mb-2">Components Test</h2>
-        <div className="space-y-2">
-          <Button variant="primary">Primary Button</Button>
-          <Button variant="secondary">Secondary Button</Button>
-          <Input placeholder="Test input field" />
-        </div>
-      </Card>
-    </div>
+    <UnifiedAuthProvider 
+      supabaseClient={supabase} 
+      appName="my-app"
+    >
+      <AppContent />
+    </UnifiedAuthProvider>
   );
 }
-
-export default App;
 ```
 
-### Expected Result
-
-You should see:
-- ✅ Properly styled components with PACE Core's design system
-- ✅ Colors working (text-main-900, bg-sec-500, etc.)
-- ✅ Typography and spacing applied correctly
-- ✅ Hover effects and transitions working
-
-## Step 5: Set Up Authentication (Optional)
+## What's Next?
 
-If you're using pace-core's authentication features:
-
-### Install Supabase
-
-```bash
-npm install @supabase/supabase-js
-```
-
-### Create Supabase Client
-
-```typescript
-// src/lib/supabase.ts
-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)
-```
-
-### Set Up Environment Variables
-
-Create `.env.local`:
-
-```bash
-REACT_APP_SUPABASE_URL=https://your-project.supabase.co
-REACT_APP_SUPABASE_ANON_KEY=your-anon-key-here
-```
-
-### Configure Providers
-
-```tsx
-// src/main.tsx
-import { UnifiedAuthProvider, OrganisationProvider, EventProvider } from '@jmruthers/pace-core';
-import { supabase } from './lib/supabase';
-
-ReactDOM.createRoot(document.getElementById('root')!).render(
-  <React.StrictMode>
-    <UnifiedAuthProvider supabaseClient={supabase} appName="your-app">
-      <OrganisationProvider>
-        <EventProvider>
-          <App />
-        </EventProvider>
-      </OrganisationProvider>
-    </UnifiedAuthProvider>
-  </React.StrictMode>
-);
-```
-
-## Troubleshooting
-
-### Common Issues
-
-1. **Components appear unstyled**
-   - Check that pace-core is included in your Vite content configuration
-   - Ensure the CSS file is imported
-   - Restart your dev server
-
-2. **Colors don't work**
-   - Verify the CSS file is imported
-   - Check that content scanning includes pace-core
-   - Ensure you're using Tailwind v4
-
-3. **Build errors about missing classes**
-   - Verify your content paths are correct
-   - Check that both source files and pace-core are included
-
-### Verification Checklist
-
-Before asking for help, verify:
-
-- [ ] CSS file is imported: `import '@jmruthers/pace-core/styles/core.css'`
-- [ ] Vite config includes pace-core in content scanning
-- [ ] Using Tailwind v4 (not v3)
-- [ ] Dev server restarted after config changes
-- [ ] All required peer dependencies installed
-- [ ] Test component renders with proper styling
-
-## Next Steps
-
-- [Quick Start Guide](./quick-start.md) - Build your first app
-- [Vite Configuration](../consuming-app-vite-config.md) - Detailed Vite setup
-- [Troubleshooting](../troubleshooting/styling-issues.md) - Fix common problems
-- [Component API](../api/README.md) - Explore all components
+- **[Quick Start](./quick-start.md)** - Build your first app in 5 minutes
+- **[Examples](./examples/)** - Complete working examples
+- **[Core Concepts](../core-concepts/)** - Understand the fundamentals
 
 ## Need Help?
 
-If you're still having issues:
-
-1. Check the [Troubleshooting Guide](../troubleshooting/styling-issues.md)
-2. Verify your setup matches this guide exactly
-3. Test with a minimal example to isolate the issue
-4. Check your package versions for compatibility
+- Check the [Common Issues](../troubleshooting/common-issues.md) guide
+- Review [Troubleshooting](../troubleshooting/) for debugging help
+- See [Best Practices](../best-practices/) for production-ready patterns

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

@@ -2,29 +2,14 @@
 
 Build a complete PACE Core application with authentication, permissions, and a modern UI in under 10 minutes.
 
-> **⏱️ Time to Complete**: ~10 minutes  
-> **Prerequisites**: Node.js 18+, npm/yarn/pnpm  
-> **Difficulty**: Beginner
-
 ## 🎯 What We'll Build
 
-A complete meal management application featuring:
-- ✅ **User Authentication** - Login/logout with Supabase
-- ✅ **Role-Based Access Control** - Different permissions for different users
-- ✅ **Interactive Data Tables** - CRUD operations with sorting, filtering, pagination
-- ✅ **Form Validation** - Real-time validation with Zod schemas
-- ✅ **Responsive Design** - Mobile-first with Tailwind CSS
-- ✅ **Print Reports** - Generate PDF-ready reports
-- ✅ **Modern UI** - Accessible, consistent component library
-
-### Final Result Preview
-
-Your app will have:
-- A login page with proper authentication
-- A dashboard with user-specific content
-- A data table for managing meals with full CRUD operations
-- Permission-based UI elements (admin-only features)
-- Responsive design that works on all devices
+A simple meal management app that demonstrates:
+- User authentication and session management
+- Role-based access control (RBAC)
+- Permission enforcement
+- Modern UI components
+- Data management with DataTable
 
 ## 🚀 Step-by-Step Implementation
 
@@ -40,56 +25,32 @@ cd meal-manager
 ### 2. Install Dependencies
 
 ```bash
-# Install pace-core and required peer dependencies
-npm install @jmruthers/pace-core @tanstack/react-table @radix-ui/react-checkbox @radix-ui/react-dialog @radix-ui/react-dropdown-menu @radix-ui/react-label @radix-ui/react-slot lucide-react class-variance-authority clsx tailwind-merge
-
-# Install Supabase and routing
-npm install @supabase/supabase-js react-router-dom
-
-# Install Tailwind CSS v4 and development dependencies
-npm install -D @tailwindcss/vite tailwindcss@^4.0.0 @types/react @types/react-dom
+npm install @jmruthers/pace-core @supabase/supabase-js react-router-dom
+npm install -D tailwindcss @types/react @types/react-dom
 ```
 
-### 3. Configure Tailwind CSS v4 (CRITICAL)
+### 3. Configure Tailwind CSS
 
-**⚠️ CRITICAL**: pace-core requires Tailwind v4 with proper content scanning. Without this configuration, components will be unstyled.
-
-Install Tailwind v4:
 ```bash
-npm install -D @tailwindcss/vite tailwindcss@^4.0.0
-# Remove old Tailwind v3 if installed
-npm uninstall tailwindcss@^3.0.0
+npx tailwindcss init
 ```
 
-**REQUIRED Vite Configuration** - You MUST include pace-core in content scanning:
+Update `tailwind.config.js`:
 
 ```js
-// vite.config.js
-import { defineConfig } from 'vite'
-import react from '@vitejs/plugin-react'
-import tailwindcss from '@tailwindcss/vite'
-
-export default defineConfig({
-  plugins: [
-    react(),
-    tailwindcss({
-      // CRITICAL: Include pace-core components for scanning
-      content: [
-        './src/**/*.{js,ts,jsx,tsx}',
-        './node_modules/@jmruthers/pace-core/**/*.{js,ts,jsx,tsx}'
-      ]
-    })
+/** @type {import('tailwindcss').Config} */
+module.exports = {
+  content: [
+    './src/**/*.{js,ts,jsx,tsx}',
+    './node_modules/@jmruthers/pace-core/**/*.{js,ts,jsx,tsx}',
   ],
-})
+  theme: {
+    extend: {},
+  },
+  plugins: [],
+}
 ```
 
-**Why this is critical:**
-- Pace-core components contain Tailwind classes that must be scanned
-- Without proper content configuration, components will appear unstyled
-- The UI will be severely compromised without this step
-
-**No `tailwind.config.js` file needed** - pace-core handles all configuration via CSS imports.
-
 ### 4. Set Up Environment Variables
 
 Create `.env.local`:
@@ -111,65 +72,7 @@ const supabaseAnonKey = process.env.REACT_APP_SUPABASE_ANON_KEY!
 export const supabase = createClient(supabaseUrl, supabaseAnonKey)
 ```
 
-### 6. Set Up CSS Imports and HTML Structure
-
-**CRITICAL**: Import the CSS file in your main entry point:
-
-```tsx
-// src/main.tsx
-import React from 'react'
-import ReactDOM from 'react-dom/client'
-import { BrowserRouter } from 'react-router-dom'
-import { 
-  UnifiedAuthProvider, 
-  OrganisationProvider, 
-  EventProvider
-} from '@jmruthers/pace-core'
-import { supabase } from './lib/supabase'
-import App from './App.tsx'
-
-// CRITICAL: Import the CSS system - includes everything you need
-import '@jmruthers/pace-core/styles/core.css'
-
-ReactDOM.createRoot(document.getElementById('root')!).render(
-  <React.StrictMode>
-    <BrowserRouter>
-      <UnifiedAuthProvider supabaseClient={supabase} appName="meal-manager">
-        <OrganisationProvider>
-          <EventProvider>
-            <App />
-          </EventProvider>
-        </OrganisationProvider>
-      </UnifiedAuthProvider>
-    </BrowserRouter>
-  </React.StrictMode>,
-)
-```
-
-**That's it!** The core.css file includes:
-- Complete color palettes (main, secondary, accent)
-- All fonts (Georama, Open Sans, Reddit Mono)
-- Base element styles and resets
-- Tailwind v4 utility classes
-- Component styling
-
-Update your `index.html`:
-```html
-<!DOCTYPE html>
-<html lang="en">
-  <head>
-    <meta charset="UTF-8" />
-    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
-    <title>Meal Manager</title>
-  </head>
-  <body class="appGradient">
-    <div id="root" class="grid grid-rows-[auto_1fr_auto] min-h-screen"></div>
-    <script type="module" src="/src/main.tsx"></script>
-  </body>
-</html>
-```
-
-### 7. Set Up App Structure
+### 6. Set Up App Structure
 
 ```tsx
 // src/App.tsx
@@ -228,10 +131,10 @@ export function LoginPage() {
   };
 
   return (
-    <div className="min-h-screen flex items-center justify-center bg-sec-50">
+    <div className="min-h-screen flex items-center justify-center bg-gray-50">
       <div className="max-w-md w-full space-y-8">
         <div>
-          <h2 className="mt-6 text-center text-3xl font-extrabold text-sec-900">
+          <h2 className="mt-6 text-center text-3xl font-extrabold text-gray-900">
             Sign in to Meal Manager
           </h2>
         </div>