@jmruthers/pace-core 0.5.181 → 0.5.182

package/docs/getting-started/consuming-app-vite-config.md

@@ -1,239 +0,0 @@
----
-lastUpdated: 2025-10-29T22:43:00+11:00
-version: 0.5.76
-reviewedBy: content-audit
----
-
-# Consuming App Vite Configuration
-
-This document shows the **CRITICAL** Vite configuration for consuming apps using pace-core with Tailwind v4. Proper configuration is essential to ensure pace-core components are styled correctly.
-
-## ⚠️ Critical: Why This Configuration Matters
-
-Pace-core components contain Tailwind classes that **MUST** be scanned during the build process. Without proper 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
-
-## ✅ Solution: CSS-First Approach (v0.4.16+)
-
-**NEW**: Pace-core v0.4.16+ uses Tailwind v4's CSS-first approach with `@source` directives in `core.css`. This automatically scans the published source files without requiring complex Vite configuration.
-
-### Method 1: CSS-First Configuration (Recommended)
-
-```ts
-// 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({
-      // Only need to scan your app's source files
-      // pace-core source files are automatically scanned via @source directives
-      content: [
-        './src/**/*.{js,ts,jsx,tsx}'
-      ]
-    })
-  ],
-  resolve: {
-    alias: {
-      "@": path.resolve(__dirname, "./src"),
-    },
-  },
-  server: {
-    port: 3000,
-    open: true,
-  },
-  build: {
-    outDir: 'dist',
-    sourcemap: true,
-  },
-})
-```
-
-### Method 2: Explicit Source File Scanning (Fallback)
-
-If the CSS-first approach doesn't work, you can explicitly include pace-core source files:
-
-```ts
-// 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({
-      // Explicitly include pace-core source files for scanning
-      content: [
-        './src/**/*.{js,ts,jsx,tsx}',
-        './node_modules/@jmruthers/pace-core/src/**/*.{js,ts,jsx,tsx}'
-      ]
-    })
-  ],
-  resolve: {
-    alias: {
-      "@": path.resolve(__dirname, "./src"),
-    },
-  },
-  server: {
-    port: 3000,
-    open: true,
-  },
-  build: {
-    outDir: 'dist',
-    sourcemap: true,
-  },
-})
-```
-
-### Alternative: PostCSS Configuration
-
-If you prefer PostCSS over Vite plugin:
-
-```javascript
-// tailwind.config.js
-/** @type {import('tailwindcss').Config} */
-module.exports = {
-  content: [
-    './src/**/*.{js,ts,jsx,tsx}',
-    './node_modules/@jmruthers/pace-core/src/**/*.{js,ts,jsx,tsx}'
-  ],
-  theme: {
-    extend: {},
-  },
-  plugins: [],
-}
-```
-
-## 🔄 Fallback: Hybrid Approach
-
-If source file scanning doesn't work, try this hybrid approach:
-
-```ts
-// 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: [
-        './src/**/*.{js,ts,jsx,tsx}',
-        // Try source files first
-        './node_modules/@jmruthers/pace-core/src/**/*.{js,ts,jsx,tsx}',
-        // Fallback: also scan dist files
-        './node_modules/@jmruthers/pace-core/dist/**/*.{js,ts,jsx,tsx}'
-      ]
-    })
-  ],
-})
-```
-
-## 🚨 Legacy Configuration (v0.4.14 and below)
-
-If you're using an older version, use this configuration:
-
-```ts
-// 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: [
-        './src/**/*.{js,ts,jsx,tsx}',
-        './node_modules/@jmruthers/pace-core/**/*.{js,ts,jsx,tsx}'
-      ]
-    })
-  ],
-})
-```
-
-## What This Configuration Does
-
-1. **Scans Your Source Files**: Detects Tailwind classes in your app's source code
-2. **Scans Pace-Core Source Files**: Ensures all Tailwind classes used in pace-core components are included
-3. **Generates Complete CSS**: Creates a CSS file with all necessary utility classes
-4. **Enables Proper Styling**: Allows pace-core components to render with correct styles
-
-## Verification Steps
-
-After configuration, verify everything works:
-
-1. **Import the CSS file** in your main entry point:
-   ```tsx
-   import '@jmruthers/pace-core/src/styles/core.css';
-   ```
-
-2. **Create a test component**:
-   ```tsx
-   import { Button, Card } from '@jmruthers/pace-core';
-   
-   function TestComponent() {
-     return (
-       <Card className="p-4">
-         <Button variant="primary" className="bg-main-600 text-main-50">
-           Test Button
-         </Button>
-       </Card>
-     );
-   }
-   ```
-
-3. **Check the result**: The component should render with proper PACE Core styling
-
-4. **Verify CSS size**: Your CSS file should be 50-100+ kB (not 20-30 kB)
-
-## Common Issues and Solutions
-
-### Issue: Components appear unstyled
-**Solution**: Ensure pace-core source files are included in content scanning
-
-### Issue: Colors don't work (text-main-900, bg-sec-500, etc.)
-**Solution**: Verify the CSS file is imported and content scanning includes pace-core source files
-
-### Issue: Build errors about missing classes
-**Solution**: Check that your content paths are correct and include both source files and pace-core source files
-
-### Issue: Still only 292 CSS rules instead of 800+
-**Solution**: 
-1. Update to pace-core v0.4.15+
-2. Use source file paths: `./node_modules/@jmruthers/pace-core/src/**/*.{js,ts,jsx,tsx}`
-3. Clear build cache and rebuild
-
-### Issue: Source files not found
-**Solution**: Ensure you're using pace-core v0.4.15+ which includes source files in the published package
-
-## Key Points
-
-- ✅ **Required**: Must include pace-core source files in content scanning
-- ✅ **Critical**: Without this, components won't be styled
-- ✅ **Simple**: Just add the source file paths to your content array
-- ✅ **Reliable**: Works with any project structure when configured correctly
-
-## What NOT to Do
-
-- ❌ **Don't skip content configuration** - pace-core won't be scanned
-- ❌ **Don't rely on automatic scanning only** - it may not catch node_modules
-- ❌ **Don't forget to import the CSS file** - styles won't be available
-- ❌ **Don't assume it works without testing** - always verify with a test component
-
-## Next Steps
-
-- [Installation Guide](./getting-started/installation.md) - Complete setup instructions
-- [Tailwind Content Scanning Guide](./troubleshooting/tailwind-content-scanning.md) - Detailed troubleshooting
-- [Troubleshooting Guide](./troubleshooting/styling-issues.md) - Fix common problems

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

@@ -1,226 +0,0 @@
----
-lastUpdated: 2025-10-29T22:43:00+11:00
-version: 0.5.76
-reviewedBy: content-audit
----
-
-# 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