@jmruthers/pace-core 0.4.1 → 0.5.3

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-gray-900">Dashboard</h1>
-        <p className="text-gray-600 mt-2">
+        <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>
@@ -238,7 +238,7 @@ export function DashboardPage() {
           </CardHeader>
           <CardContent>
             <p className="text-3xl font-bold">{mealsLoading ? '...' : totalMeals}</p>
-            <p className="text-sm text-gray-600">All time</p>
+            <p className="text-sm text-sec-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-gray-600">Last 7 days</p>
+            <p className="text-sm text-sec-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-gray-600">Active users</p>
+            <p className="text-sm text-sec-600">Active users</p>
           </CardContent>
         </Card>
       </div>
@@ -269,7 +269,7 @@ export function DashboardPage() {
           <CardTitle>Recent Activity</CardTitle>
         </CardHeader>
         <CardContent>
-          <p className="text-gray-600">
+          <p className="text-sec-600">
             Your meal tracking activity will appear here.
           </p>
         </CardContent>

package/docs/getting-started/installation.md

@@ -1,90 +1,269 @@
-# Installation & Setup
+# Complete Installation Guide
 
-Get PACE Core up and running in your project in under 5 minutes.
+This is the definitive guide for installing and configuring pace-core in your application. Follow these steps exactly to ensure proper styling and functionality.
 
-## Prerequisites
+## 🚨 Critical Requirements
 
-- Node.js 18+ and npm/yarn/pnpm
-- React 18+ project (Next.js, Create React App, Vite, etc.)
-- Supabase project (free tier works great)
+**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.
 
-## Quick Installation
+## Step 1: Install Dependencies
 
-### 1. Install Dependencies
+### Required Packages
 
 ```bash
-npm install @jmruthers/pace-core @supabase/supabase-js
-npm install -D tailwindcss @types/react @types/react-dom
+# 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
 ```
 
-### 2. Configure Tailwind CSS
+### Optional Packages (for full functionality)
 
 ```bash
-npx tailwindcss init
+# 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
 ```
 
-Update your `tailwind.config.js`:
+## Step 2: Configure Vite with Tailwind v4
+
+**⚠️ CRITICAL**: This configuration is essential for pace-core components to be styled correctly.
 
-```js
-/** @type {import('tailwindcss').Config} */
-module.exports = {
-  content: [
-    './src/**/*.{js,ts,jsx,tsx}',
-    './node_modules/@jmruthers/pace-core/**/*.{js,ts,jsx,tsx}',
+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}'
+      ]
+    })
   ],
-  theme: {
-    extend: {},
+  resolve: {
+    alias: {
+      "@": path.resolve(__dirname, "./src"),
+    },
   },
-  plugins: [],
-}
+  server: {
+    port: 3000,
+    open: true,
+  },
+  build: {
+    outDir: 'dist',
+    sourcemap: true,
+  },
+})
 ```
 
-### 3. Set Up Environment Variables
+### Why This Configuration is Critical
 
-Create `.env.local` (or `.env` for Create React App):
+Pace-core components contain Tailwind classes that must be scanned during the build process. Without this configuration:
 
-```bash
-# Supabase Configuration
-NEXT_PUBLIC_SUPABASE_URL=https://your-project.supabase.co
-NEXT_PUBLIC_SUPABASE_ANON_KEY=your-anon-key-here
+- ❌ 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)
+
+If you're still having issues with component scanning:
 
-# 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
+```typescript
+// vite.config.ts
+import { defineConfig } from 'vite'
+import react from '@vitejs/plugin-react'
+import tailwindcss from '@tailwindcss/vite'
+
+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}'
+        ]
+      }
+    })
+  ],
+})
 ```
 
-### 4. Basic Provider Setup
+## Step 3: Import Core Styles
+
+**CRITICAL**: Import the CSS file in your main entry point:
 
 ```tsx
-// App.tsx
-import { UnifiedAuthProvider } from '@jmruthers/pace-core';
-import { createClient } from '@supabase/supabase-js';
+// 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';
 
-const supabase = createClient(
-  process.env.NEXT_PUBLIC_SUPABASE_URL!,
-  process.env.NEXT_PUBLIC_SUPABASE_ANON_KEY!
+const root = ReactDOM.createRoot(document.getElementById('root') as HTMLElement);
+root.render(
+  <React.StrictMode>
+    <App />
+  </React.StrictMode>
 );
+```
+
+### 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 (
-    <UnifiedAuthProvider 
-      supabaseClient={supabase} 
-      appName="my-app"
-    >
-      <AppContent />
-    </UnifiedAuthProvider>
+    <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>
   );
 }
+
+export default App;
 ```
 
-## What's Next?
+### 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)
 
-- **[Quick Start](./quick-start.md)** - Build your first app in 5 minutes
-- **[Examples](./examples/)** - Complete working examples
-- **[Core Concepts](../core-concepts/)** - Understand the fundamentals
+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
 
 ## Need Help?
 
-- Check the [Common Issues](../troubleshooting/common-issues.md) guide
-- Review [Troubleshooting](../troubleshooting/) for debugging help
-- See [Best Practices](../best-practices/) for production-ready patterns
+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

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

@@ -2,14 +2,29 @@
 
 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 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
+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
 
 ## 🚀 Step-by-Step Implementation
 
@@ -25,32 +40,56 @@ cd meal-manager
 ### 2. Install Dependencies
 
 ```bash
-npm install @jmruthers/pace-core @supabase/supabase-js react-router-dom
-npm install -D tailwindcss @types/react @types/react-dom
+# 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
 ```
 
-### 3. Configure Tailwind CSS
+### 3. Configure Tailwind CSS v4 (CRITICAL)
 
+**⚠️ CRITICAL**: pace-core requires Tailwind v4 with proper content scanning. Without this configuration, components will be unstyled.
+
+Install Tailwind v4:
 ```bash
-npx tailwindcss init
+npm install -D @tailwindcss/vite tailwindcss@^4.0.0
+# Remove old Tailwind v3 if installed
+npm uninstall tailwindcss@^3.0.0
 ```
 
-Update `tailwind.config.js`:
+**REQUIRED Vite Configuration** - You MUST include pace-core in content scanning:
 
 ```js
-/** @type {import('tailwindcss').Config} */
-module.exports = {
-  content: [
-    './src/**/*.{js,ts,jsx,tsx}',
-    './node_modules/@jmruthers/pace-core/**/*.{js,ts,jsx,tsx}',
+// 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}'
+      ]
+    })
   ],
-  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`:
@@ -72,7 +111,65 @@ const supabaseAnonKey = process.env.REACT_APP_SUPABASE_ANON_KEY!
 export const supabase = createClient(supabaseUrl, supabaseAnonKey)
 ```
 
-### 6. Set Up App Structure
+### 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
 
 ```tsx
 // src/App.tsx
@@ -131,10 +228,10 @@ export function LoginPage() {
   };
 
   return (
-    <div className="min-h-screen flex items-center justify-center bg-gray-50">
+    <div className="min-h-screen flex items-center justify-center bg-sec-50">
       <div className="max-w-md w-full space-y-8">
         <div>
-          <h2 className="mt-6 text-center text-3xl font-extrabold text-gray-900">
+          <h2 className="mt-6 text-center text-3xl font-extrabold text-sec-900">
             Sign in to Meal Manager
           </h2>
         </div>