@jmruthers/pace-core 0.5.76 → 0.5.78

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

@@ -1,376 +0,0 @@
-# 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  
-> **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
-
-## 🚀 Step-by-Step Implementation
-
-### 1. Project Setup
-
-If you don't have a project yet:
-
-```bash
-# 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
-
-```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
-```
-
-### 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
-npm install -D @tailwindcss/vite tailwindcss@^4.0.0
-# Remove old Tailwind v3 if installed
-npm uninstall tailwindcss@^3.0.0
-```
-
-**REQUIRED Vite Configuration** - You MUST include pace-core in content scanning:
-
-```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}'
-      ]
-    })
-  ],
-})
-```
-
-**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`:
-
-```bash
-# Supabase Configuration
-REACT_APP_SUPABASE_URL=https://your-project.supabase.co
-REACT_APP_SUPABASE_ANON_KEY=your-anon-key-here
-
-# ⚠️ CRITICAL: Use anon key, NOT service role key
-# The anon key starts with: eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9
-# The service role key has different permissions and can cause RPC timeouts
-```
-
-### 5. 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!
-
-if (!supabaseUrl || !supabaseAnonKey) {
-  throw new Error('Missing Supabase environment variables')
-}
-
-export const supabase = createClient(supabaseUrl, supabaseAnonKey)
-```
-
-### 6. Set Up App with Authentication
-
-**CRITICAL**: UnifiedAuthProvider now requires inactivity timeout configuration:
-
-```tsx
-// src/main.tsx
-import React from 'react'
-import ReactDOM from 'react-dom/client'
-import { BrowserRouter } from 'react-router-dom'
-import { 
-  UnifiedAuthProvider
-} 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/src/styles/core.css'
-
-ReactDOM.createRoot(document.getElementById('root')!).render(
-  <React.StrictMode>
-    <BrowserRouter>
-      <UnifiedAuthProvider 
-        supabaseClient={supabase} 
-        appName="meal-manager"
-        enableRBAC={true}
-        requireOrganisationContext={true}
-        idleTimeoutMs={30 * 60 * 1000}  // 30 minutes - REQUIRED
-        warnBeforeMs={60 * 1000}        // 60 seconds - REQUIRED
-        onIdleLogout={() => window.location.href = '/login'}  // REQUIRED
-      >
-        <App />
-      </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. Create Login Page
-
-```tsx
-// src/pages/LoginPage.tsx
-import { LoginForm } from '@jmruthers/pace-core';
-import { useNavigate } from 'react-router-dom';
-
-export function LoginPage() {
-  const navigate = useNavigate();
-
-  const handleLoginSuccess = () => {
-    navigate('/');
-  };
-
-  return (
-    <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-sec-900">
-            Sign in to Meal Manager
-          </h2>
-        </div>
-        <LoginForm onLoginSuccess={handleLoginSuccess} />
-      </div>
-    </div>
-  );
-}
-```
-
-### 9. Create App Layout
-
-```tsx
-// src/components/AppLayout.tsx
-import { PaceAppLayout } from '@jmruthers/pace-core';
-import { Outlet } from 'react-router-dom';
-
-const navItems = [
-  {
-    title: 'Dashboard',
-    href: '/',
-    icon: 'HomeIcon'
-  },
-  {
-    title: 'Meals',
-    href: '/meals',
-    icon: 'UtensilsIcon'
-  }
-];
-
-export function AppLayout() {
-  return (
-    <PaceAppLayout 
-      appName="Meal Manager"
-      navItems={navItems}
-    >
-      <Outlet />
-    </PaceAppLayout>
-  );
-}
-```
-
-### 10. Create Dashboard Page
-
-```tsx
-// src/pages/DashboardPage.tsx
-import { Card, CardHeader, CardTitle, CardContent } from '@jmruthers/pace-core';
-
-export function DashboardPage() {
-  return (
-    <div className="p-6">
-      <h1 className="text-2xl font-bold mb-6">Dashboard</h1>
-      
-      <div className="grid grid-cols-1 md:grid-cols-3 gap-6">
-        <Card>
-          <CardHeader>
-            <CardTitle>Total Meals</CardTitle>
-          </CardHeader>
-          <CardContent>
-            <p className="text-3xl font-bold">24</p>
-          </CardContent>
-        </Card>
-        
-        <Card>
-          <CardHeader>
-            <CardTitle>This Week</CardTitle>
-          </CardHeader>
-          <CardContent>
-            <p className="text-3xl font-bold">7</p>
-          </CardContent>
-        </Card>
-        
-        <Card>
-          <CardHeader>
-            <CardTitle>Categories</CardTitle>
-          </CardHeader>
-          <CardContent>
-            <p className="text-3xl font-bold">5</p>
-          </CardContent>
-        </Card>
-      </div>
-    </div>
-  );
-}
-```
-
-### 11. Create Meals Page with DataTable
-
-```tsx
-// src/pages/MealsPage.tsx
-import { DataTable, type DataTableColumn } from '@jmruthers/pace-core';
-import { useState } from 'react';
-
-interface Meal {
-  id: string;
-  name: string;
-  category: string;
-  calories: number;
-  date: string;
-}
-
-const sampleMeals: Meal[] = [
-  { id: '1', name: 'Grilled Chicken Salad', category: 'Healthy', calories: 350, date: '2024-01-15' },
-  { id: '2', name: 'Pasta Carbonara', category: 'Italian', calories: 650, date: '2024-01-15' },
-  { id: '3', name: 'Vegetable Stir Fry', category: 'Asian', calories: 280, date: '2024-01-14' },
-];
-
-const columns: DataTableColumn<Meal>[] = [
-  {
-    accessorKey: 'name',
-    header: 'Meal Name',
-  },
-  {
-    accessorKey: 'category',
-    header: 'Category',
-  },
-  {
-    accessorKey: 'calories',
-    header: 'Calories',
-  },
-  {
-    accessorKey: 'date',
-    header: 'Date',
-  },
-];
-
-export function MealsPage() {
-  const [meals] = useState<Meal[]>(sampleMeals);
-
-  return (
-    <div className="p-6">
-      <h1 className="text-2xl font-bold mb-6">Meals</h1>
-      
-      <DataTable
-        data={meals}
-        columns={columns}
-        rbac={{ pageId: 'meals' }}
-        features={{
-          search: true,
-          pagination: true,
-        }}
-      />
-    </div>
-  );
-}
-```
-
-## 🎉 You're Done!
-
-Your app now has:
-- ✅ User authentication with Supabase
-- ✅ Role-based access control
-- ✅ Modern UI components
-- ✅ Responsive layout
-- ✅ Data table with sorting and pagination
-
-## 🚀 Next Steps
-
-- **[Core Concepts](../core-concepts/)** - Understand authentication, RBAC, and events
-- **[Implementation Guides](../implementation-guides/)** - Learn advanced patterns
-- **[API Reference](../api-reference/)** - Explore all available components and hooks
-- **[Examples](./examples/)** - See complete working applications
-
-## 🆘 Need Help?
-
-- Check [Common Issues](../troubleshooting/common-issues.md)
-- Review [Troubleshooting](../troubleshooting/) for debugging
-- See [Best Practices](../best-practices/) for production patterns

package/docs/implementation-guides/datatable-filtering.md

@@ -1,313 +0,0 @@
-# DataTable Filtering Guide
-
-## Overview
-
-The DataTable component supports multiple types of column filtering, including text, select dropdowns, number, and date filters. This guide explains how to configure each filter type and provides examples for common use cases.
-
-## Filter Types
-
-### 1. Text Filters (Default)
-Text filters allow users to type and search for values in a column.
-
-```typescript
-const columns = [
-  {
-    id: 'name',
-    accessorKey: 'name',
-    header: 'Name',
-    enableColumnFilter: true,
-    // No filterType specified - defaults to 'text'
-  }
-];
-```
-
-### 2. Select Filters
-Select filters provide dropdown menus with predefined options, perfect for categorical data.
-
-#### Method 1: Using `filterSelectOptions` (Recommended)
-```typescript
-const columns = [
-  {
-    id: 'meal_type',
-    accessorFn: (row) => row.mealtype?.mealtype_name || 'N/A',
-    header: 'Type',
-    enableColumnFilter: true,
-    filterType: 'select',
-    filterSelectOptions: [
-      { value: 'breakfast', label: 'Breakfast' },
-      { value: 'lunch', label: 'Lunch' },
-      { value: 'dinner', label: 'Dinner' },
-      { value: 'morning_tea', label: 'Morning Tea' },
-      { value: 'afternoon_tea', label: 'Afternoon Tea' },
-      { value: 'pantry', label: 'Pantry' }
-    ],
-    filterFn: (row, id, value) => {
-      return value.includes(row.original.mealtype?.mealtype_id);
-    }
-  }
-];
-```
-
-#### Method 2: Using `fieldOptions`
-```typescript
-const columns = [
-  {
-    id: 'status',
-    accessorKey: 'status',
-    header: 'Status',
-    enableColumnFilter: true,
-    filterType: 'select',
-    fieldOptions: [
-      { value: 'active', label: 'Active' },
-      { value: 'inactive', label: 'Inactive' },
-      { value: 'pending', label: 'Pending' }
-    ]
-  }
-];
-```
-
-#### Method 3: Auto-detection
-The DataTable automatically detects select filters when a column has limited unique values (≤10):
-
-```typescript
-const columns = [
-  {
-    id: 'priority',
-    accessorKey: 'priority',
-    header: 'Priority',
-    enableColumnFilter: true,
-    // No filterType specified - will auto-detect as 'select' if ≤10 unique values
-  }
-];
-```
-
-### 3. Number Filters
-Number filters provide numeric input with comparison operators.
-
-```typescript
-const columns = [
-  {
-    id: 'price',
-    accessorKey: 'price',
-    header: 'Price',
-    enableColumnFilter: true,
-    filterType: 'number'
-  }
-];
-```
-
-### 4. Date Filters
-Date filters provide date picker inputs.
-
-```typescript
-const columns = [
-  {
-    id: 'created_date',
-    accessorKey: 'created_date',
-    header: 'Created Date',
-    enableColumnFilter: true,
-    filterType: 'date'
-  }
-];
-```
-
-## Complete Example
-
-Here's a complete example showing different filter types:
-
-```typescript
-import { DataTable } from '@jmruthers/pace-core';
-
-function MealsTable() {
-  const meals = [
-    {
-      id: '1',
-      meal_code: '28py',
-      mealtype: { mealtype_id: 'breakfast', mealtype_name: 'Breakfast' },
-      meal_date: '2024-12-28',
-      price: 15.50
-    },
-    // ... more data
-  ];
-
-  const mealTypes = [
-    { mealtype_id: 'breakfast', mealtype_name: 'Breakfast' },
-    { mealtype_id: 'lunch', mealtype_name: 'Lunch' },
-    { mealtype_id: 'dinner', mealtype_name: 'Dinner' },
-    { mealtype_id: 'morning_tea', mealtype_name: 'Morning Tea' },
-    { mealtype_id: 'afternoon_tea', mealtype_name: 'Afternoon Tea' },
-    { mealtype_id: 'pantry', mealtype_name: 'Pantry' }
-  ];
-
-  const columns = [
-    {
-      id: 'meal_code',
-      accessorKey: 'meal_code',
-      header: 'Meal Code',
-      enableColumnFilter: true,
-      // Text filter (default)
-    },
-    {
-      id: 'meal_type',
-      accessorFn: (row) => row.mealtype?.mealtype_name || 'N/A',
-      header: 'Type',
-      enableColumnFilter: true,
-      filterType: 'select',
-      filterSelectOptions: mealTypes.map(mt => ({
-        value: mt.mealtype_id,
-        label: mt.mealtype_name
-      })),
-      filterFn: (row, id, value) => {
-        return value.includes(row.original.mealtype?.mealtype_id);
-      }
-    },
-    {
-      id: 'meal_date',
-      accessorKey: 'meal_date',
-      header: 'Date',
-      enableColumnFilter: true,
-      filterType: 'date'
-    },
-    {
-      id: 'price',
-      accessorKey: 'price',
-      header: 'Price',
-      enableColumnFilter: true,
-      filterType: 'number'
-    }
-  ];
-
-  return (
-    <DataTable
-      data={meals}
-      columns={columns}
-      features={{
-        filtering: true,  // Enable filtering
-        search: true,
-        pagination: true,
-        sorting: true
-      }}
-      rbac={{
-        pageName: 'meals'
-      }}
-    />
-  );
-}
-```
-
-## Filter Configuration Options
-
-### Column Properties
-
-| Property | Type | Description |
-|----------|------|-------------|
-| `enableColumnFilter` | `boolean` | Enable filtering for this column |
-| `filterType` | `'text' \| 'select' \| 'number' \| 'date'` | Type of filter to render |
-| `filterSelectOptions` | `Array<{value: string\|number, label: string}>` | Options for select filters |
-| `fieldOptions` | `Array<{value: string\|number, label: string}>` | Alternative options for select filters |
-| `filterFn` | `(row, id, value) => boolean` | Custom filter function |
-
-### DataTable Features
-
-```typescript
-features={{
-  filtering: true,        // Enable column filtering
-  search: true,          // Enable global search
-  showFilterRow: true,   // Show filter row by default
-}}
-```
-
-## Advanced Filtering
-
-### Custom Filter Functions
-
-For complex filtering logic, you can provide a custom `filterFn`:
-
-```typescript
-{
-  id: 'meal_type',
-  accessorFn: (row) => row.mealtype?.mealtype_name || 'N/A',
-  header: 'Type',
-  enableColumnFilter: true,
-  filterType: 'select',
-  filterSelectOptions: mealTypes.map(mt => ({
-    value: mt.mealtype_id,
-    label: mt.mealtype_name
-  })),
-  filterFn: (row, id, value) => {
-    // Custom logic: filter by mealtype_id but display mealtype_name
-    const mealtypeId = row.original.mealtype?.mealtype_id;
-    return value.includes(mealtypeId);
-  }
-}
-```
-
-### Multiple Value Selection
-
-Select filters support multiple value selection by default:
-
-```typescript
-// Users can select multiple meal types
-filterSelectOptions: [
-  { value: 'breakfast', label: 'Breakfast' },
-  { value: 'lunch', label: 'Lunch' },
-  { value: 'dinner', label: 'Dinner' }
-]
-// When user selects "Breakfast" and "Lunch", 
-// filterFn receives: ['breakfast', 'lunch']
-```
-
-## Troubleshooting
-
-### Common Issues
-
-1. **Select filter not showing dropdown:**
-   - Ensure `filterType: 'select'` is set
-   - Verify `filterSelectOptions` or `fieldOptions` is provided
-   - Check that `enableColumnFilter: true` is set
-
-2. **Filter not working with foreign key data:**
-   - Use `accessorFn` to extract the display value
-   - Provide custom `filterFn` to match against the actual ID
-   - Ensure `filterSelectOptions` uses the ID values
-
-3. **Auto-detection not working:**
-   - Ensure column has ≤10 unique values
-   - Check that values are not null/undefined
-   - Verify `enableColumnFilter: true` is set
-
-### Debug Tips
-
-Enable debug logging to see filter behavior:
-
-```typescript
-// In your app setup
-<UnifiedAuthProvider 
-  supabaseClient={supabase}
-  appName="your-app"
-  enableRBAC={true}
-  debug={true}  // Enable debug logging
->
-  <YourApp />
-</UnifiedAuthProvider>
-```
-
-## Best Practices
-
-1. **Use `filterSelectOptions` for predefined options** - More explicit and clear
-2. **Provide meaningful labels** - Use human-readable labels, not IDs
-3. **Use custom `filterFn` for foreign keys** - Match against IDs, display names
-4. **Limit select options** - Keep dropdowns manageable (≤20 options)
-5. **Test with real data** - Ensure filters work with actual data values
-6. **Consider performance** - Large datasets may need server-side filtering
-
-## Migration from Old Filtering
-
-If you're upgrading from an older version:
-
-1. **Replace `meta.filterOptions`** with `filterSelectOptions`
-2. **Add `filterType: 'select'`** for explicit select filters
-3. **Update `filterFn`** to work with new filter value format
-4. **Test all filter combinations** to ensure they work correctly
-
-This comprehensive filtering system provides a great user experience for data exploration and analysis.