@jmruthers/pace-core 0.2.7 → 0.4.1

package/docs/api/README.md

@@ -1,301 +1,299 @@
 @jmruthers/pace-core / [Exports](modules.md)
 
-# @jmruthers/pace-core
+# PACE Core
 
-Clean, modern React component library with Tailwind v4 styling and native utilities.
+A comprehensive React component library and utilities for PACE applications.
 
-## 🚀 PaceAppLayout Usage
+## Installation
 
-**PaceAppLayout uses React Router's nested routing pattern for optimal performance and scalability.**
+```bash
+npm install @jmruthers/pace-core
+```
+
+## Styling Setup
+
+**IMPORTANT**: PACE Core components require CSS styles to render correctly. We use a clean 3-file CSS structure with Tailwind v4.
+
+### Quick Start
 
 ```tsx
-// ✅ Correct usage with React Router
-<Router>
-  <Routes>
-    <Route path="/" element={<PaceAppLayout appName="My App" />}>
-      <Route path="dashboard" element={<Dashboard />} />
-      <Route path="settings" element={<Settings />} />
-    </Route>
-  </Routes>
-</Router>
+// Import the three core CSS files
+import '@jmruthers/pace-core/styles/base.css';
+import '@jmruthers/pace-core/styles/theme.css';
+import '@jmruthers/pace-core/styles/dark.css';
+import './app.css'; // Your app's color palette
 ```
 
-## 🚀 Complete Installation Guide
+### Define Your App's Colors
 
-### 1. Install Dependencies
+Create `app.css` with your brand colors:
 
-```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
+```css
+/* app.css - Your app's specific palette */
+@theme static {
+  /* MAIN palette - your primary brand color */
+  --color-main-raw: oklch(0.7 0.057 252.02);
+  --color-main-50: oklch(0.98 0.001 252.02);
+  --color-main-100: oklch(0.96 0.005 252.02);
+  /* ... complete palette for main, sec, acc */
+}
+```
+
+### Use Native Tailwind Utilities
 
-# Install Tailwind CSS v4 and Vite plugin
-npm install -D @tailwindcss/vite tailwindcss@^4.0.0
+```tsx
+// Components use standard Tailwind classes
+<Button className="bg-main-600 hover:bg-main-700">
+  Click me
+</Button>
+
+<Card className="bg-main-50 border-main-200">
+  <h2 className="text-main-900">Welcome</h2>
+</Card>
 ```
 
-### 2. Import Core Styles
+### Dynamic Theming
 
 ```tsx
-// 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 root = ReactDOM.createRoot(document.getElementById('root') as HTMLElement);
-root.render(
-  <React.StrictMode>
-    <App />
-  </React.StrictMode>
-);
+import { applyPalette, clearPalette } from '@jmruthers/pace-core/theming/runtime';
+
+// Apply organisation colors
+applyPalette({
+  main: orgData.colors.main,
+  sec: orgData.colors.sec,
+  acc: orgData.colors.acc
+});
 ```
 
-### 3. Configure Vite with Tailwind v4
+For detailed styling instructions, see the [Usage Guide](./docs/usage.md).
+
+## Import Strategy
+
+PACE Core provides two import paths to optimize for different use cases:
+
+### Main Export (Recommended for Common Components)
 
-**NEW in v0.4.17+:** Pace-core uses Tailwind v4's CSS-first approach with corrected `@source` directives. This automatically scans the published source files without requiring complex Vite configuration.
+Use the main export for frequently used components and utilities:
 
 ```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({
-      // 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,
-  },
-})
+import { 
+  Button, 
+  Card, 
+  Input, 
+  DropdownMenu, 
+  Select, 
+  Dialog,
+  useUnifiedAuth 
+} from '@jmruthers/pace-core';
 ```
 
-**Fallback Configuration:** If the CSS-first approach doesn't work, you can explicitly include pace-core source files:
+**Available from main export:**
+- **Basic UI**: Button, Card, Input, Label, Alert, Avatar, Checkbox, Progress
+- **Advanced UI**: Dialog, DropdownMenu, Select, Toast, Tooltip
+- **Data Display**: DataTable, Table
+- **Forms**: Form, LoginForm
+- **Layout**: Header, Footer, NavigationMenu, UserMenu
+- **Utilities**: ErrorBoundary, LoadingSpinner, EventSelector
+- **Providers**: UnifiedAuthProvider
+- **Hooks**: useUnifiedAuth
+- **Utils**: cn, appConfig utilities
+
+### Complete Components Export (For Specialized Components)
+
+Use the complete export for specialized or advanced components:
 
 ```typescript
-// vite.config.ts - Fallback configuration
-export default defineConfig({
-  plugins: [
-    react(),
-    tailwindcss({
-      content: [
-        './src/**/*.{js,ts,jsx,tsx}',
-        './node_modules/@jmruthers/pace-core/src/**/*.{js,ts,jsx,tsx}'
-      ]
-    })
-  ],
-  // ... rest of config
-})
+import { 
+  DataTable, 
+  NavigationMenu,
+  FormField,
+  FormErrorSummary 
+} from '@jmruthers/pace-core/components';
 ```
 
-### 4. Verify Installation
+**Available from complete export:**
+- All components from main export
+- **Advanced Form Components**: FormField, FormErrorSummary, FormLiveRegion
+- **Specialized UI**: All DropdownMenu sub-components, Select sub-components
+- **Data Components**: Full DataTable with all features
+- **Layout Components**: PaceAppLayout, PaceLoginPage
+- **Authentication**: PasswordResetForm, PasswordChangeForm
 
-Create a test component to ensure everything works:
+### When to Use Which Import?
 
-```tsx
-// src/App.tsx
-import { Button, Card, Input } from '@jmruthers/pace-core';
+**Use Main Export When:**
+- Building common UI patterns
+- Need basic components (Button, Card, Input, etc.)
+- Want smaller bundle size
+- Working on simple forms or layouts
 
-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>
-  );
-}
+**Use Complete Export When:**
+- Need advanced form components
+- Working with complex data tables
+- Require specialized dropdown or select features
+- Building complete page layouts
 
-export default App;
-```
+### Bundle Size Optimization
 
-**Expected Result:** You should see properly styled components with PACE Core's design system colors and typography.
+The main export is optimized for tree-shaking and smaller bundle sizes. The complete export includes all components but may result in larger bundles if not properly tree-shaken.
 
-## ⚠️ Critical Configuration Notes
+```typescript
+// ✅ Good - Only imports what you need
+import { Button, Card } from '@jmruthers/pace-core';
 
-### Why Source File Scanning is Required
+// ✅ Good - Imports specialized components when needed
+import { FormField, FormErrorSummary } from '@jmruthers/pace-core/components';
 
-Pace-core v0.4.15+ includes source files in the published package because:
+// ❌ Avoid - Don't import everything if you only need a few components
+import * as PaceCore from '@jmruthers/pace-core/components';
+```
 
-- Tailwind v4 needs to scan original TypeScript/JSX files to detect utility classes
-- Compiled JavaScript files don't contain the class names Tailwind needs
-- Without proper scanning, only ~292 CSS rules are generated instead of 800+ needed
+## Quick Start
 
-### Alternative Configuration (if source files don't work)
+### Basic Usage
 
-If you're still having issues with component scanning:
+```tsx
+import { Button, Card, CardHeader, CardTitle, CardContent } from '@jmruthers/pace-core';
 
-```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: [
-        './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}'
-      ]
-    })
-  ],
-})
+function MyComponent() {
+  return (
+      <Card>
+      <CardHeader>
+        <CardTitle>Welcome</CardTitle>
+      </CardHeader>
+      <CardContent>
+        <Button>Click me</Button>
+      </CardContent>
+      </Card>
+  );
+}
 ```
 
-### Legacy Configuration (v0.4.14 and below)
+### With Authentication
 
-For older versions, use this configuration:
+```tsx
+import { 
+  UnifiedAuthProvider, 
+  LoginForm, 
+  useUnifiedAuth 
+} from '@jmruthers/pace-core';
 
-```typescript
-// vite.config.ts
-export default defineConfig({
-  plugins: [
-    react(),
-    tailwindcss({
-      content: [
-        './src/**/*.{js,ts,jsx,tsx}',
-        './node_modules/@jmruthers/pace-core/**/*.{js,ts,jsx,tsx}'
-      ]
-    })
-  ],
-})
+function App() {
+  return (
+    <UnifiedAuthProvider>
+      <MyApp />
+    </UnifiedAuthProvider>
+  );
+}
+
+function MyApp() {
+  const { user, signOut } = useUnifiedAuth();
+  
+  if (!user) {
+    return <LoginForm />;
+  }
+  
+  return (
+    <div>
+      <p>Welcome, {user.email}!</p>
+      <Button onClick={signOut}>Sign Out</Button>
+    </div>
+  );
+}
 ```
 
-## 🔍 Troubleshooting
+### Advanced Forms
 
-### Issue: Only 292 CSS rules instead of 800+
+```tsx
+import { 
+  Form, 
+  FormField, 
+  FormErrorSummary 
+} from '@jmruthers/pace-core/components';
 
-**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: `rm -rf dist .vite node_modules && npm install`
+function AdvancedForm() {
+  return (
+    <Form onSubmit={handleSubmit}>
+      <FormField name="email" label="Email" type="email" required />
+      <FormField name="password" label="Password" type="password" required />
+      <FormErrorSummary />
+      <Button type="submit">Submit</Button>
+    </Form>
+  );
+}
+```
 
-### Issue: Components appear unstyled
+## Components
 
-**Solution**: 
-1. Check your Vite configuration includes pace-core source files
-2. Ensure CSS file is imported: `import '@jmruthers/pace-core/styles/core.css'`
-3. Restart dev server after configuration changes
+### Basic UI Components
 
-### Issue: Build errors with source files
+- **Button** - Versatile button component with multiple variants
+- **Card** - Container component with header, content, and footer
+- **Input** - Form input with validation support
+- **Label** - Accessible form labels
+- **Alert** - Status and notification messages
+- **Avatar** - User profile images with fallbacks
+- **Checkbox** - Form checkbox with proper accessibility
+- **Progress** - Progress indicators and loading states
 
-**Solution**: Add TypeScript configuration for node_modules:
+### Advanced UI Components
 
-```json
-// tsconfig.json
-{
-  "compilerOptions": {
-    "skipLibCheck": true
-  }
-}
-```
+- **Dialog** - Accessible modal dialogs with focus management, keyboard navigation, and smooth animations
+  - 📖 **[Dialog API Reference](./docs/api/modules.md#dialog)** - Auto-generated API documentation
+- **DropdownMenu** - Context menus and dropdowns
+- **Select** - Dropdown select components
+- **Toast** - Notification system
+- **Tooltip** - Hover tooltips
 
-## Features
+### Data Display
 
-- 🎨 **Complete Design System** - Colors, typography, spacing, shadows
-- 🧩 **React Components** - Buttons, inputs, cards, data tables, and more
-- 🔐 **RBAC System** - Role-based access control with Supabase
-- 🎨 **Tailwind v4** - CSS-first approach with design tokens
-- 📱 **Responsive** - Mobile-first design patterns
-- ♿ **Accessible** - WCAG compliant components
-- 🚀 **Performance** - Tree-shakeable, optimized bundle
+- **DataTable** - **Enterprise-grade data table** with comprehensive features including sorting, filtering, pagination, search, export/import, inline editing, grouping, virtual scrolling, and full accessibility. [View comprehensive documentation →](./docs/api/modules.md#datatable)
+- **Table** - Basic table components for simple data display
 
-## Documentation
+### Forms
 
-- [Quick Start Guide](./docs/getting-started/quick-start.md) - Complete step-by-step tutorial
-- [Installation Guide](./docs/getting-started/installation.md) - Detailed setup instructions
-- [Vite Configuration](./docs/consuming-app-vite-config.md) - **CRITICAL** Tailwind scanning setup
-- [Component API](./docs/api/README.md) - All available components and hooks
-- [Styling Guide](./docs/styles/README.md) - Understanding the design system
-- [Troubleshooting](./docs/troubleshooting/styling-issues.md) - Fix common styling problems
-- [Tailwind Content Scanning](./docs/troubleshooting/tailwind-content-scanning.md) - **NEW** Comprehensive scanning solutions
+- **Form** - Form container with validation
+- **LoginForm** - Pre-built login form
+- **FormField** - Individual form fields with validation
+- **FormErrorSummary** - Error display for forms
 
-## Import Strategy
+### Layout
 
-PACE Core provides two import paths to optimize for different use cases:
+- **Header** - Application header component
+- **Footer** - Application footer
+- **NavigationMenu** - Navigation menus
+- **UserMenu** - User account menu
+- **PaceAppLayout** - Complete application layout
+- **PaceLoginPage** - Login page layout
 
-### Main Export (Recommended for Common Components)
+### Utilities
 
-Use the main export for frequently used components and utilities:
+- **ErrorBoundary** - React error boundary with retry functionality and graceful error handling
+  - 📖 **[ErrorBoundary API Reference](./docs/api/classes/ErrorBoundary.md)** - Auto-generated API documentation
+- **LoadingSpinner** - Loading indicators
+- **EventSelector** - Event selection component
 
-```typescript
-import { 
-  Button, 
-  Card, 
-  Input, 
-  DropdownMenu, 
-  Select, 
-  Dialog,
-  useUnifiedAuth 
-} from '@jmruthers/pace-core';
-```
+## Hooks
 
-**Available from main export:**
-- **Basic UI**: Button, Card, Input, Label, Alert, Avatar, Checkbox, Progress
-- **Advanced UI**: Dialog (with HTML content), DropdownMenu, Select, Toast, Tooltip
-- **Data Display**: DataTable (with hierarchical actions & expand/collapse all), Table
-- **Forms**: Form, LoginForm
-- **Layout**: PaceAppLayout, Header, Footer, NavigationMenu
-- **Print Components**: PrintLayout, PrintDataTable, PrintCard, PrintHeader, PrintText, PrintButton, PrintGrid, PrintSection, PrintFooter, PrintPageBreak
-- **Providers**: UnifiedAuthProvider, OrganisationProvider, EventProvider
-- **Hooks**: useUnifiedAuth, useOrganisations, useEvents
+- **useUnifiedAuth** - Authentication state and methods
+- **useTheme** - Theme management
+- **useToast** - Toast notification system
 
-### Component Documentation
+## Providers
 
-- **[DataTable Component](docs/implementation-guides/data-tables.md)** - Enterprise-grade data table with hierarchical rows, expand/collapse all, actions, sorting, filtering, and performance optimization
-  - **[Hierarchical DataTable Guide](docs/implementation-guides/hierarchical-datatable.md)** - Complete guide for implementing parent/child rows with expand/collapse all and smart sorting
-- **[Print Components](docs/print-components/README.md)** - **NEW** Print-optimized layout system for reports, documents, and printable content
-  - **[Print Quick Start](docs/print-components/quick-start.md)** - 5-minute setup guide
-  - **[Print API Reference](docs/print-components/api-reference.md)** - Complete component documentation
-- **[Dialog Component](src/components/Dialog/README.md)** - Comprehensive dialog system with smart height management, scrolling, HTML content rendering, and accessibility features
-- **[Storage System](src/utils/storage/README.md)** - File storage utilities with organization-scoped access control
+- **UnifiedAuthProvider** - Authentication context provider
+- **ThemeProvider** - Theme context provider
+- **EventProvider** - Event management provider
 
-### Complete Components Export (For Specialized Components)
+## Utilities
 
-Use the complete export for specialized or advanced components:
+- **cn** - Class name utility (clsx + tailwind-merge)
+- **appConfig** - Application configuration utilities
 
-```typescript
-import { 
-  DataTable, 
-  NavigationMenu,
-  FormField,
-  FormErrorSummary 
-} from '@jmruthers/pace-core/components';
-```
+## Contributing
+
+See [CONTRIBUTING.md](./CONTRIBUTING.md) for development guidelines.
 
 ## License
 
-MIT License - see [LICENSE](./LICENSE) for details.
+MIT

package/docs/api/classes/ErrorBoundary.md

@@ -1,4 +1,4 @@
-[@jmruthers/pace-core - v0.2.7](../README.md) / [Exports](../modules.md) / ErrorBoundary
+[@jmruthers/pace-core - v0.4.01](../README.md) / [Exports](../modules.md) / ErrorBoundary
 
 # Class: ErrorBoundary
 

package/docs/api/interfaces/AggregateConfig.md

@@ -1,4 +1,4 @@
-[@jmruthers/pace-core - v0.2.7](../README.md) / [Exports](../modules.md) / AggregateConfig
+[@jmruthers/pace-core - v0.4.01](../README.md) / [Exports](../modules.md) / AggregateConfig
 
 # Interface: AggregateConfig
 
@@ -20,7 +20,7 @@ Aggregate configuration
 
 #### Defined in
 
-[packages/core/src/components/DataTable/types.ts:323](https://github.com/jmruthers/pace-core/blob/main/packages/core/src/components/DataTable/types.ts#L323)
+[packages/core/src/components/DataTable/types.ts:243](https://github.com/jmruthers/pace-core/blob/main/packages/core/src/components/DataTable/types.ts#L243)
 
 ___
 
@@ -30,7 +30,7 @@ ___
 
 #### Defined in
 
-[packages/core/src/components/DataTable/types.ts:324](https://github.com/jmruthers/pace-core/blob/main/packages/core/src/components/DataTable/types.ts#L324)
+[packages/core/src/components/DataTable/types.ts:244](https://github.com/jmruthers/pace-core/blob/main/packages/core/src/components/DataTable/types.ts#L244)
 
 ___
 
@@ -40,4 +40,4 @@ ___
 
 #### Defined in
 
-[packages/core/src/components/DataTable/types.ts:325](https://github.com/jmruthers/pace-core/blob/main/packages/core/src/components/DataTable/types.ts#L325)
+[packages/core/src/components/DataTable/types.ts:245](https://github.com/jmruthers/pace-core/blob/main/packages/core/src/components/DataTable/types.ts#L245)

package/docs/api/interfaces/ButtonProps.md

@@ -1,4 +1,4 @@
-[@jmruthers/pace-core - v0.2.7](../README.md) / [Exports](../modules.md) / ButtonProps
+[@jmruthers/pace-core - v0.4.01](../README.md) / [Exports](../modules.md) / ButtonProps
 
 # Interface: ButtonProps
 
@@ -32,7 +32,7 @@ ___
 
 ### size
 
-• `Optional` **size**: ``"sm"`` \| ``"lg"`` \| ``"default"`` \| ``"icon"``
+• `Optional` **size**: ``"default"`` \| ``"sm"`` \| ``"lg"`` \| ``"icon"``
 
 Size of the button
 

package/docs/api/interfaces/CardProps.md

@@ -1,4 +1,4 @@
-[@jmruthers/pace-core - v0.2.7](../README.md) / [Exports](../modules.md) / CardProps
+[@jmruthers/pace-core - v0.4.01](../README.md) / [Exports](../modules.md) / CardProps
 
 # Interface: CardProps
 
@@ -31,7 +31,7 @@ ___
 
 ### size
 
-• `Optional` **size**: ``"sm"`` \| ``"lg"`` \| ``"default"``
+• `Optional` **size**: ``"default"`` \| ``"sm"`` \| ``"lg"``
 
 Size of the card
 

package/docs/api/interfaces/ColorPalette.md

@@ -1,4 +1,4 @@
-[@jmruthers/pace-core - v0.2.7](../README.md) / [Exports](../modules.md) / ColorPalette
+[@jmruthers/pace-core - v0.4.01](../README.md) / [Exports](../modules.md) / ColorPalette
 
 # Interface: ColorPalette
 

package/docs/api/interfaces/ColorShade.md

@@ -1,4 +1,4 @@
-[@jmruthers/pace-core - v0.2.7](../README.md) / [Exports](../modules.md) / ColorShade
+[@jmruthers/pace-core - v0.4.01](../README.md) / [Exports](../modules.md) / ColorShade
 
 # Interface: ColorShade