@jmruthers/pace-core 0.2.4

package/docs/consuming-app-example.md

@@ -0,0 +1,290 @@
+# Consuming App Example
+
+This example shows how to properly use PACE Core DataTable in a consuming application with CSS-first Tailwind v4 configuration.
+
+## Project Setup
+
+### 1. Create a new React app
+
+```bash
+npx create-react-app my-app --template typescript
+cd my-app
+```
+
+### 2. Install PACE Core
+
+```bash
+npm install @jmruthers/pace-core
+```
+
+### 3. Install 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
+```
+
+### 4. Install Tailwind CSS v4
+
+```bash
+npm install -D @tailwindcss/vite tailwindcss@^4.0.0
+```
+
+## Implementation
+
+### 1. Import PACE Core styles
+
+```tsx
+// src/index.tsx
+// Import the core CSS file - includes everything you need
+import '@jmruthers/pace-core/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>
+);
+```
+
+**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
+
+### 2. Create your DataTable component
+
+```tsx
+// src/App.tsx
+import React, { useMemo } from 'react';
+import { DataTable } from '@jmruthers/pace-core';
+import type { DataTableFeatureConfig } from '@jmruthers/pace-core';
+
+interface User {
+  id: string;
+  name: string;
+  email: string;
+  role: string;
+  status: 'active' | 'inactive' | 'pending';
+  priority: 'low' | 'medium' | 'high';
+}
+
+const App: React.FC = () => {
+  const data: User[] = [
+    { id: '1', name: 'John Doe', email: 'john@example.com', role: 'Admin', status: 'active', priority: 'high' },
+    { id: '2', name: 'Jane Smith', email: 'jane@example.com', role: 'User', status: 'active', priority: 'medium' },
+    { id: '3', name: 'Bob Johnson', email: 'bob@example.com', role: 'User', status: 'pending', priority: 'low' },
+    { id: '4', name: 'Alice Brown', email: 'alice@example.com', role: 'Manager', status: 'inactive', priority: 'high' },
+  ];
+
+  const columns = useMemo(() => [
+    {
+      accessorKey: 'name',
+      header: 'Name',
+      enableSorting: true,
+      enableGrouping: true,
+      enableColumnFilter: true,
+    },
+    {
+      accessorKey: 'email',
+      header: 'Email',
+      enableSorting: true,
+      enableGrouping: true,
+      enableColumnFilter: true,
+    },
+    {
+      accessorKey: 'role',
+      header: 'Role',
+      enableSorting: true,
+      enableGrouping: true,
+      enableColumnFilter: true,
+      cell: ({ row }: { row: { original: User } }) => (
+        <span className="inline-flex items-center rounded-full border px-2.5 py-0.5 text-xs font-semibold bg-primary text-primary-foreground">
+          {row.original.role}
+        </span>
+      ),
+    },
+    {
+      accessorKey: 'status',
+      header: 'Status',
+      enableSorting: true,
+      enableGrouping: true,
+      enableColumnFilter: true,
+      cell: ({ row }: { row: { original: User } }) => {
+        const status = row.original.status;
+        const badgeClass = status === 'active' ? 'bg-success text-success-foreground' :
+                          status === 'pending' ? 'bg-warning text-warning-foreground' :
+                          'bg-error text-error-foreground';
+        return (
+          <span className={`inline-flex items-center rounded-full border px-2.5 py-0.5 text-xs font-semibold ${badgeClass}`}>
+            {status}
+          </span>
+        );
+      },
+    },
+    {
+      accessorKey: 'priority',
+      header: 'Priority',
+      enableSorting: true,
+      enableGrouping: true,
+      enableColumnFilter: true,
+      cell: ({ row }: { row: { original: User } }) => {
+        const priority = row.original.priority;
+        const badgeClass = priority === 'high' ? 'bg-error text-error-foreground' :
+                          priority === 'medium' ? 'bg-warning text-warning-foreground' :
+                          'bg-success text-success-foreground';
+        return (
+          <span className={`inline-flex items-center rounded-full border px-2.5 py-0.5 text-xs font-semibold ${badgeClass}`}>
+            {priority}
+          </span>
+        );
+      },
+    },
+  ], []);
+
+  const features: DataTableFeatureConfig = {
+    search: true,
+    pagination: true,
+    sorting: true,
+    filtering: true,
+    import: false,
+    export: true,
+    selection: true,
+    creation: true,
+    editing: true,
+    deletion: true,
+    deleteSelected: true,
+    grouping: true,
+    columnVisibility: true,
+    columnReordering: true,
+    virtualization: false,
+    performanceMetrics: false,
+    bulkOperations: true,
+    rowActions: true,
+  };
+
+  return (
+    <div className="min-h-screen bg-sec-50 p-8">
+      <div className="max-w-7xl mx-auto">
+        <h1 className="text-3xl font-bold text-sec-900 mb-8">
+          My Application with PACE Core DataTable
+        </h1>
+        
+        <div className="bg-main-50 rounded-lg shadow">
+          <DataTable
+            data={data}
+            columns={columns}
+            title="Users"
+            description="Manage your application users"
+            features={features}
+            onEditRow={(row, data) => {
+              console.log('Edit row:', row, data);
+            }}
+            onDeleteRow={(row) => {
+              console.log('Delete row:', row);
+            }}
+            onCreateRow={(data) => {
+              console.log('Create row:', data);
+            }}
+            onImport={(data) => {
+              console.log('Import data:', data);
+            }}
+          />
+        </div>
+      </div>
+    </div>
+  );
+};
+
+export default App;
+```
+
+### 3. Configure Vite with Tailwind CSS v4
+
+```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()
+  ],
+})
+```
+
+### 4. Alternative: Use PACE Core Vite Plugin
+
+For easier setup, you can use the provided PACE Core Vite plugin:
+
+```js
+// vite.config.js
+import { createPaceCoreViteConfig } from '@jmruthers/pace-core/vite-plugin-tailwind-v4'
+
+export default createPaceCoreViteConfig({
+  // Your custom Vite options here
+})
+```
+
+## Key Points
+
+1. **Import styles**: The CSS file provides all styling out of the box:
+   ```tsx
+   import '@jmruthers/pace-core/styles/core.css';
+   ```
+2. **Use native utilities**: Use standard Tailwind utilities like `bg-main-600`, `text-sec-700`, `border-acc-500`, etc.
+3. **Configure features**: Set up the `features` object to enable/disable DataTable functionality
+4. **Component styling**: Components handle their own internal styling - no need for component-specific utility classes
+
+## Expected Result
+
+With this setup, your DataTable should render with:
+- ✅ Proper toolbar with search and action buttons
+- ✅ Styled table headers and rows
+- ✅ Colored badges for status and priority
+- ✅ Hover effects and transitions
+- ✅ Consistent PACE Core design system
+- ✅ All functionality working correctly
+
+## Troubleshooting
+
+If the DataTable doesn't look styled:
+
+1. **Check imports**: Ensure the CSS file is imported at the top of your main file:
+   ```tsx
+   import '@jmruthers/pace-core/styles/core.css';
+   ```
+2. **Check dependencies**: Make sure all peer dependencies are installed
+3. **Check Tailwind**: Ensure Tailwind CSS v4 is properly configured
+4. **Check console**: Look for any build or runtime errors
+
+## How It Works
+
+Tailwind v4 automatically scans for utility classes through your build tool configuration:
+
+**Your vite.config.ts handles the scanning:**
+```ts
+// vite.config.ts
+export default defineConfig({
+  plugins: [
+    react(),
+    tailwindcss() // Automatically scans all source files
+  ],
+})
+```
+
+**The core.css file provides:**
+- Complete color palettes and theme definitions
+- Base styles and typography
+- Font definitions
+- Component styling foundation
+
+This means Tailwind automatically detects and includes all utility classes used in your source files, ensuring complete styling coverage without any manual configuration.

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

@@ -0,0 +1,233 @@
+# 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/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/core-concepts/authentication.md

@@ -0,0 +1,98 @@
+# Authentication
+
+> **📚 New Developer?** Start with the [Installation](../getting-started/installation.md) guide, then [Quick Start](../getting-started/quick-start.md) to build your first app.
+
+PACE Core provides a comprehensive authentication system built on Supabase that handles user authentication, session management, and multi-tenant organisation support.
+
+## Overview
+
+The authentication system provides:
+- **Supabase Integration** - Built on Supabase Auth for reliability and security
+- **Multi-Tenant Support** - Organisation-based access control
+- **Event Management** - Event-specific authentication and access
+- **Session Tracking** - Comprehensive audit logging
+- **Type Safety** - Full TypeScript support
+- **Security First** - Security-first design with RLS policies
+
+## Architecture
+
+### Provider Hierarchy
+
+```
+UnifiedAuthProvider (Root)
+├── OrganisationProvider (Multi-tenant)
+├── EventProvider (Event management)
+└── Your App Components
+```
+
+### Authentication Flow
+
+1. **User Registration/Login** - Via Supabase Auth
+2. **Organisation Context** - User selects or is assigned to an organisation
+3. **Event Context** - User selects or is assigned to an event (optional)
+4. **Permission Validation** - RBAC system validates user permissions
+5. **Session Tracking** - All actions are logged for audit purposes
+
+## Core Concepts
+
+### Authentication States
+
+- **Unauthenticated** - User not logged in
+- **Authenticated** - User logged in, no organisation context
+- **Organisation Context** - User authenticated and has organisation access
+- **Event Context** - User authenticated with organisation and event access
+
+### Session Management
+
+- **Automatic Refresh** - Sessions automatically refresh before expiry
+- **Persistent State** - Authentication state persists across page reloads
+- **Multi-Tab Support** - Authentication state synchronized across tabs
+- **Graceful Degradation** - Handles network issues and token expiry
+
+### Security Features
+
+- **Row Level Security (RLS)** - Database-level access control
+- **JWT Tokens** - Secure, stateless authentication
+- **CSRF Protection** - Cross-site request forgery prevention
+- **Audit Logging** - Complete action tracking for compliance
+
+## Multi-Tenancy
+
+### Organisation Isolation
+
+- **Data Segregation** - Each organisation's data is completely isolated
+- **User Membership** - Users can belong to multiple organisations
+- **Context Switching** - Users can switch between organisations
+- **Permission Inheritance** - Permissions are organisation-specific
+
+### Event Management
+
+- **Event Context** - Additional layer of access control
+- **Temporal Access** - Event-specific permissions and data
+- **Cross-Event Access** - Users can access multiple events within an organisation
+- **Event Switching** - Seamless switching between events
+
+## RBAC Integration
+
+### Permission System
+
+- **Role-Based Permissions** - Permissions automatically assigned based on organisation roles
+- **Organisation Context** - All permissions are scoped to the current organisation
+- **Dynamic Permission Checking** - Real-time permission validation
+- **Hierarchical Role Structure** - Clear role hierarchy with inherited permissions
+
+### Access Control
+
+- **Page-Level Protection** - Route-based access control
+- **Component-Level Protection** - UI element access control
+- **Data-Level Protection** - Database query access control
+- **API-Level Protection** - Endpoint access control
+
+## What's Next?
+
+- **[Installation](../getting-started/installation.md)** - Get PACE Core set up
+- **[Quick Start](../getting-started/quick-start.md)** - Build your first app
+- **[RBAC System](./rbac-system.md)** - Understand role-based access control
+- **[Organisations](./organisations.md)** - Learn about multi-tenancy
+- **[Events](./events.md)** - Understand event management
+- **[Implementation Guides](../implementation-guides/)** - Practical implementation patterns