@jmruthers/pace-core 0.5.67 → 0.5.69

package/docs/getting-started/installation-guide.md

@@ -0,0 +1,284 @@
+# PACE Core Installation Guide
+
+> **📚 Complete Setup Instructions** | [← Back to Documentation](../README.md) | [Quick Start](./quick-start.md)
+
+**This is the single authoritative source for PACE Core installation.** Follow this guide exactly to ensure proper functionality.
+
+## Quick Start (TL;DR)
+
+```bash
+# 1. Install the package
+npm install @jmruthers/pace-core
+
+# 2. Install peer dependencies
+npm install @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
+
+# 3. Install Tailwind v4
+npm install -D @tailwindcss/vite tailwindcss@^4.0.0
+
+# 4. Import CSS in your app
+import '@jmruthers/pace-core/src/styles/core.css';
+```
+
+## Complete Installation Steps
+
+### Step 1: Install PACE Core Package
+
+```bash
+npm install @jmruthers/pace-core
+```
+
+**Required Peer Dependencies:**
+```bash
+npm install @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
+```
+
+### Step 2: Install Tailwind CSS v4
+
+**CRITICAL**: PACE Core requires Tailwind CSS v4 with the Vite plugin.
+
+```bash
+npm install -D @tailwindcss/vite tailwindcss@^4.0.0
+```
+
+**Remove Tailwind v3 if present:**
+```bash
+npm uninstall tailwindcss@^3.0.0 postcss autoprefixer
+```
+
+### Step 3: Configure Vite
+
+**⚠️ CRITICAL**: Without this configuration, PACE Core components will not be styled.
+
+Create or update `vite.config.ts`:
+
+```typescript
+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 source files for Tailwind scanning
+      content: [
+        './src/**/*.{js,ts,jsx,tsx}',
+        './node_modules/@jmruthers/pace-core/src/**/*.{js,ts,jsx,tsx}'
+      ]
+    })
+  ],
+  server: {
+    port: 3000,
+    open: true,
+  },
+})
+```
+
+**Why This Configuration is Critical:**
+
+- Tailwind v4 scans TypeScript files to detect utility classes
+- Without scanning `pace-core` source files, components will be unstyled
+- Only ~292 CSS rules will be generated instead of 800+ needed
+- The entire purpose of using this UI library will be defeated
+
+### Step 4: Import Core Styles
+
+**⚠️ CRITICAL**: Import the CSS file in your app's entry point.
+
+```tsx
+// src/main.tsx (or your app's entry point)
+import '@jmruthers/pace-core/src/styles/core.css';
+import React from 'react';
+import ReactDOM from 'react-dom/client';
+import App from './App';
+
+const root = ReactDOM.createRoot(document.getElementById('root') as HTMLElement);
+root.render(
+  <React.StrictMode>
+    <App />
+  </React.StrictMode>
+);
+```
+
+**What the CSS file includes:**
+- Complete color palettes (main, secondary, accent)
+- Font definitions with system font fallbacks
+- Base element styles and resets
+- Tailwind v4 utility classes
+- Component styling foundation
+
+### Step 5: Verify Installation
+
+Create a test component to verify 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" className="bg-main-600 text-main-50">
+            Primary Button
+          </Button>
+          <Button variant="secondary" className="bg-sec-500 text-main-50">
+            Secondary Button
+          </Button>
+          <Input placeholder="Test input field" className="border-main-300" />
+        </div>
+      </Card>
+    </div>
+  );
+}
+
+export default App;
+```
+
+**Expected Result**: You should see properly styled components with PACE Core's design system colors, typography, and spacing.
+
+### Step 6: Optional - Supabase Authentication Setup
+
+If you're using PACE Core's authentication features:
+
+```bash
+npm install @supabase/supabase-js
+```
+
+Create `src/lib/supabase.ts`:
+
+```typescript
+import { createClient } from '@supabase/supabase-js'
+
+const supabaseUrl = process.env.VITE_SUPABASE_URL!
+const supabaseAnonKey = process.env.VITE_SUPABASE_ANON_KEY!
+
+export const supabase = createClient(supabaseUrl, supabaseAnonKey)
+```
+
+Set environment variables in `.env.local`:
+
+```bash
+VITE_SUPABASE_URL=https://your-project.supabase.co
+VITE_SUPABASE_ANON_KEY=your-anon-key-here
+```
+
+Wrap your app with providers:
+
+```tsx
+import { UnifiedAuthProvider } from '@jmruthers/pace-core';
+import { supabase } from './lib/supabase';
+
+function App() {
+  return (
+    <UnifiedAuthProvider
+      supabaseClient={supabase}
+      appName="my-app"
+      idleTimeoutMs={30 * 60 * 1000}
+      warnBeforeMs={5 * 60 * 1000}
+      onIdleLogout={() => window.location.href = '/login'}
+    >
+      <YourApp />
+    </UnifiedAuthProvider>
+  );
+}
+```
+
+## 🚨 Breaking Changes (v0.5.65+)
+
+**CRITICAL**: As of v0.5.65+, inactivity timeouts are **mandatory** in `UnifiedAuthProvider`.
+
+### Required Configuration
+
+```tsx
+// ❌ BEFORE (will cause TypeScript errors)
+<UnifiedAuthProvider supabaseClient={supabase} appName="my-app">
+  <App />
+</UnifiedAuthProvider>
+
+// ✅ AFTER (required configuration)
+<UnifiedAuthProvider 
+  supabaseClient={supabase} 
+  appName="my-app"
+  idleTimeoutMs={30 * 60 * 1000}  // Required
+  warnBeforeMs={5 * 60 * 1000}    // Required
+  onIdleLogout={() => navigate('/login')}  // Required
+>
+  <App />
+</UnifiedAuthProvider>
+```
+
+See [Migration Guide](../migration-guides/unified-auth-provider-mandatory-timeouts.md) for details.
+
+## Troubleshooting
+
+### Issue: Components appear unstyled
+
+**Causes:**
+1. Missing Vite configuration for pace-core source scanning
+2. CSS file not imported
+3. Using Tailwind v3 instead of v4
+
+**Solution**:
+1. Verify your `vite.config.ts` includes pace-core in content scanning
+2. Ensure `import '@jmruthers/pace-core/src/styles/core.css';` is in your entry point
+3. Confirm you're using Tailwind v4: `npm list tailwindcss`
+
+### Issue: Build errors about missing classes
+
+**Cause**: Tailwind not scanning pace-core source files
+
+**Solution**: Update Vite config to include:
+```typescript
+content: [
+  './src/**/*.{js,ts,jsx,tsx}',
+  './node_modules/@jmruthers/pace-core/src/**/*.{js,ts,jsx,tsx}'
+]
+```
+
+### Issue: TypeScript errors with unified auth
+
+**Cause**: Breaking changes in v0.5.65+ requiring mandatory inactivity timeout configuration
+
+**Solution**: Add required timeout props as shown in Breaking Changes section above
+
+### Verification Checklist
+
+Before asking for help, verify:
+- [ ] CSS file is imported: `import '@jmruthers/pace-core/src/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
+
+---
+
+**Last Updated:** 2025-01-XX | **Version:** v0.5.65+
+
+## Next Steps
+
+- **[Quick Start Guide](./quick-start.md)** - Build your first app
+- **[API Reference](../api-reference/components.md)** - Explore all components
+- **[Styling Guide](../styles/README.md)** - Understand the design system
+- **[Troubleshooting](../troubleshooting/styling-issues.md)** - Fix common problems
+- **[Examples](./examples/)** - Complete working applications
+
+## Additional Resources
+
+- **Tailwind v4 Docs**: https://tailwindcss.com/docs
+- **Supabase Docs**: https://supabase.com/docs
+- **React Router**: https://reactrouter.com
+
+## Need Help?
+
+If you're still having issues:
+1. Check the [Troubleshooting Guide](../troubleshooting/README.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

@@ -1,5 +1,7 @@
 # Quick Start - Build Your First App
 
+> **🎯 Build Your First App** | [← Back to Documentation](../README.md) | [Installation Guide](./installation-guide.md) | [Examples](./examples/)
+
 Build a complete PACE Core application with authentication, permissions, and a modern UI in under 10 minutes.
 
 > **⏱️ Time to Complete**: ~10 minutes  
@@ -33,8 +35,13 @@ Your app will have:
 If you don't have a project yet:
 
 ```bash
-npx create-react-app meal-manager --template typescript
+# Using Vite (recommended)
+npm create vite@latest meal-manager -- --template react-ts
 cd meal-manager
+
+# Or using Create React App (legacy)
+# npx create-react-app meal-manager --template typescript
+# cd meal-manager
 ```
 
 ### 2. Install Dependencies

package/docs/implementation-guides/app-layout.md

@@ -1,4 +1,6 @@
-# App Layout Implementation Guide
+# App Layout
+
+> **📚 Implementation Guides** | [← Back to Documentation](../README.md) | [Navigation](./navigation.md) | [Data Tables](./data-tables.md) Implementation Guide
 
 This guide covers how to implement application layouts using PACE Core's layout components with permission enforcement and responsive design.
 

package/docs/implementation-guides/data-tables.md

@@ -1,5 +1,7 @@
 # Data Tables
 
+> **📚 Implementation Guides** | [← Back to Documentation](../README.md) | [Forms](./forms.md) | [RBAC Usage](./datatable-rbac-usage.md)
+
 This guide covers implementing data tables with PACE Core's DataTable component, including basic usage, advanced features, and best practices.
 
 ## Overview

package/docs/implementation-guides/dynamic-colors.md

@@ -74,9 +74,32 @@ const themeCSS = generateSSRThemeCSS(paletteData);
 // Inject into your HTML head
 ```
 
-### Integration with React
+### Automatic Event Theming
 
-Here's how to integrate with React components:
+**Recommended approach for event-based theming:**
+
+If your app uses events with the `EventProvider`, simply call the `useEventTheme()` hook at the top level of your app:
+
+```tsx
+import { useEventTheme } from '@jmruthers/pace-core';
+
+function MyApp() {
+  // Automatically applies event colors when an event is selected
+  useEventTheme();
+  
+  return <div>Your app content</div>;
+}
+```
+
+This hook will:
+- Automatically apply event colors when an event is selected
+- Clear theming when no event is selected
+- Handle cleanup and error handling
+- Work consistently across all apps in the pace suite
+
+### Manual Integration with React
+
+For custom logic or organisation-based theming:
 
 ```tsx
 import { useEffect } from 'react';
@@ -169,6 +192,28 @@ const currentTheme = getCurrentThemeData();
 console.log('Current theme:', currentTheme);
 ```
 
+### useEventTheme()
+
+**Automatic event-based theming hook.**
+
+This hook automatically applies event colors when an event is selected and clears them when no event is selected.
+
+**Usage:**
+```tsx
+import { useEventTheme } from '@jmruthers/pace-core';
+
+function App() {
+  useEventTheme();
+  // Rest of your app
+}
+```
+
+**Benefits:**
+- Zero configuration - automatically works with `EventProvider`
+- Consistent UX across all apps
+- Handles cleanup and error cases
+- No manual event watching needed
+
 ## Benefits
 
 - **Simple API** - Just two functions: `applyPalette()` and `clearPalette()`

package/docs/implementation-guides/event-theming-summary.md

@@ -0,0 +1,220 @@
+# Event Theming Implementation Summary
+
+## What Exists in pace-core
+
+### Database Schema
+Events have an `event_colours` JSONB field that stores theme colors in OKLCH format:
+
+```typescript
+interface Event {
+  event_colours?: Record<string, unknown> | null; // JSONB field for theme colors
+}
+```
+
+The expected format:
+```json
+{
+  "main": {
+    "50": {"L": 0.98, "C": 0.007, "H": 29.203},
+    "100": {"L": 0.96, "C": 0.018, "H": 29.203},
+    // ... all Tailwind shades 50-950
+    "raw": {"L": 0.587, "C": 0.24, "H": 29.203}
+  },
+  "sec": { /* secondary palette */ },
+  "acc": { /* accent palette */ }
+}
+```
+
+### Runtime Theming System
+Located in `packages/core/src/theming/runtime.ts`:
+
+- **`applyPalette(palette)`** - Applies event colors dynamically
+- **`clearPalette()`** - Clears dynamic theming, returns to app defaults
+- **`generateSSRThemeCSS(palette)`** - SSR support
+- **`isDynamicThemingActive()`** - Debug helper
+
+### EventProvider
+`packages/core/src/providers/EventProvider.tsx`:
+- Fetches events from database via RPC `data_user_events_get`
+- Stores `event_colours` in the event object
+- Manages event selection state
+- Auto-selects next upcoming event
+
+## What Was Missing
+
+### Automatic Event Theming Integration
+There was **no automatic connection** between event selection and theming application. Consuming apps would need to manually:
+1. Watch for selectedEvent changes
+2. Extract event_colours
+3. Call applyPalette()
+4. Handle cleanup
+
+## What I Added
+
+### New Hook: `useEventTheme()`
+
+**Location:** `packages/core/src/hooks/useEventTheme.ts`
+
+**What it does:**
+- Automatically watches selectedEvent from EventProvider
+- Applies event colors when an event with `event_colours` is selected
+- Clears theming when no event is selected
+- Handles validation, errors, and cleanup
+- Works consistently across all apps
+
+**Usage:**
+```tsx
+import { useEventTheme } from '@jmruthers/pace-core';
+
+function MyApp() {
+  useEventTheme(); // Just call it!
+  
+  return <div>Your app</div>;
+}
+```
+
+**Exports:**
+- Available from `@jmruthers/pace-core` (main export)
+- Available from `@jmruthers/pace-core/hooks` (hooks export)
+
+## Why This in pace-core?
+
+This follows the pace-core principles:
+
+### 1. **Consistency Across App Suite**
+Every app (CAKE, TRACE, ADMIN, etc.) needs event theming. By having it in pace-core, all apps get the same behavior, UX, and error handling.
+
+### 2. **Maximum Code Reuse**
+Instead of every app implementing this logic, it's once in pace-core:
+- No duplicated `useEffect` logic
+- No duplicated event watching
+- No duplicated error handling
+- Centralized improvements benefit all apps
+
+### 3. **Opt-in Design**
+The hook is opt-in - apps call `useEventTheme()` if they want automatic theming. Apps can still use manual `applyPalette()` if they need custom logic.
+
+## Architecture Decision
+
+### What's in pace-core:
+- ✅ Event theming infrastructure (runtime APIs)
+- ✅ Automatic event theming hook (`useEventTheme`)
+- ✅ Documentation and examples
+- ✅ Type definitions
+
+### What's in consuming apps:
+- ✅ Calling `useEventTheme()` in the app component
+- ✅ ADMIN app: Palette picker UI to set colors
+- ✅ ADMIN app: Save colors to database via `event_colours` field
+
+## How It Works
+
+1. **ADMIN app** sets event colors via a palette picker and saves to `event.event_colours` in the database
+2. **Consuming apps** (CAKE, TRACE) call `useEventTheme()` hook
+3. When user selects an event via `EventSelector`, the hook detects the change
+4. Hook extracts `event_colours` from selected event
+5. Hook calls `applyPalette()` with the colors
+6. CSS variables update dynamically → UI colors change
+7. When event is deselected, hook calls `clearPalette()`
+
+## Database Flow
+
+```
+ADMIN App
+  ↓ (User sets colors in palette picker)
+  ↓ (Save to database)
+event.event_colours = {
+  main: { 50: {...}, 100: {...}, ... },
+  sec: { 50: {...}, 100: {...}, ... },
+  acc: { 50: {...}, 100: {...}, ... }
+}
+  ↓ (RPC fetches events)
+EventProvider loads events
+  ↓ (User selects event)
+useEventTheme() detects change
+  ↓ (Applies colors)
+applyPalette() → CSS variables update
+  ↓
+UI colors change in CAKE/TRACE
+```
+
+## Usage Example
+
+```tsx
+// In your consuming app (e.g., CAKE or TRACE)
+
+import { 
+  UnifiedAuthProvider, 
+  EventProvider, 
+  OrganisationProvider,
+  useEventTheme 
+} from '@jmruthers/pace-core';
+
+function App() {
+  // Enable automatic event theming
+  useEventTheme();
+  
+  return (
+    <div>
+      <EventSelector />
+      {/* Rest of your app */}
+    </div>
+  );
+}
+
+function RootLayout() {
+  return (
+    <UnifiedAuthProvider supabaseClient={supabase} appName="CAKE">
+      <OrganisationProvider>
+        <EventProvider>
+          <App />
+        </EventProvider>
+      </OrganisationProvider>
+    </UnifiedAuthProvider>
+  );
+}
+```
+
+## Migration Guide
+
+If you're already manually applying event colors in your consuming apps:
+
+### Before:
+```tsx
+function App() {
+  const { selectedEvent } = useEvents();
+  
+  useEffect(() => {
+    if (selectedEvent?.event_colours) {
+      applyPalette(selectedEvent.event_colours);
+    } else {
+      clearPalette();
+    }
+  }, [selectedEvent]);
+}
+```
+
+### After:
+```tsx
+function App() {
+  useEventTheme(); // Replaces the above useEffect
+  
+  return <div>Your app</div>;
+}
+```
+
+## Benefits
+
+- **Zero boilerplate** - One line to enable automatic theming
+- **Consistent UX** - All apps behave the same way
+- **Less code** - No duplication across apps
+- **Type safe** - Full TypeScript support
+- **Maintainable** - Centralized improvements
+- **Flexible** - Can still use manual API if needed
+
+## Documentation
+
+Full documentation available at:
+- **Implementation Guide:** `packages/core/docs/implementation-guides/dynamic-colors.md`
+- **Usage Guide:** `packages/core/docs/usage.md`
+- **API Reference:** Available in code docs and type definitions

package/docs/implementation-guides/forms.md

@@ -1,4 +1,6 @@
-# Forms Implementation Guide
+# Forms
+
+> **📚 Implementation Guides** | [← Back to Documentation](../README.md) | [Data Tables](./data-tables.md) | [Validation](./forms.md) Implementation Guide
 
 This guide covers how to implement forms using PACE Core's form components and validation system.
 
@@ -175,7 +177,7 @@ const conditionalSchema = z.object({
   }
   return true;
 }, {
-  message: "Organization details are required for organization accounts",
+  message: "Organisation details are required for organization accounts",
   path: ["organizationName"]
 });
 
@@ -191,7 +193,7 @@ function ConditionalForm() {
         type="select" 
         options={[
           { value: 'individual', label: 'Individual' },
-          { value: 'organization', label: 'Organization' }
+          { value: 'organization', label: 'Organisation' }
         ]} 
       />
       
@@ -200,11 +202,11 @@ function ConditionalForm() {
       
       {userType === 'organization' && (
         <Card className="p-4 space-y-4">
-          <h3 className="text-lg font-semibold">Organization Details</h3>
-          <FormField name="organizationName" label="Organization Name" />
+          <h3 className="text-lg font-semibold">Organisation Details</h3>
+          <FormField name="organizationName" label="Organisation Name" />
           <FormField 
             name="organizationSize" 
-            label="Organization Size" 
+            label="Organisation Size" 
             type="select" 
             options={[
               { value: 'small', label: 'Small (1-50 employees)' },
@@ -361,7 +363,7 @@ function CustomFormField({ name, label, ...props }) {
 
 ## Best Practices
 
-### 1. Schema Organization
+### 1. Schema Organisation
 
 ```typescript
 // schemas/user.ts

package/docs/implementation-guides/navigation.md

@@ -1,5 +1,7 @@
 # Navigation Implementation Guide
 
+> **📚 Implementation Guides** | [← Back to Documentation](../README.md) | [App Layout](./app-layout.md) | [Permission Enforcement](./permission-enforcement.md)
+
 This guide covers how to implement navigation systems using PACE Core's navigation components with permission-based filtering and RBAC integration.
 
 ## Overview