@jmruthers/pace-core 0.4.1 → 0.5.3

package/docs/api/README.md

@@ -1,299 +1,301 @@
 @jmruthers/pace-core / [Exports](modules.md)
 
-# PACE Core
+# @jmruthers/pace-core
 
-A comprehensive React component library and utilities for PACE applications.
+Clean, modern React component library with Tailwind v4 styling and native utilities.
 
-## Installation
+## 🚀 PaceAppLayout Usage
 
-```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
+**PaceAppLayout uses React Router's nested routing pattern for optimal performance and scalability.**
 
 ```tsx
-// 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
+// ✅ 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>
 ```
 
-### Define Your App's Colors
-
-Create `app.css` with your brand colors:
+## 🚀 Complete Installation Guide
 
-```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 */
-}
-```
+### 1. Install Dependencies
 
-### Use Native Tailwind Utilities
+```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
 
-```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>
+# Install Tailwind CSS v4 and Vite plugin
+npm install -D @tailwindcss/vite tailwindcss@^4.0.0
 ```
 
-### Dynamic Theming
+### 2. Import Core Styles
 
 ```tsx
-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
-});
+// 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>
+);
 ```
 
-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)
+### 3. Configure Vite with Tailwind v4
 
-Use the main export for frequently used components and utilities:
+**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.
 
 ```typescript
-import { 
-  Button, 
-  Card, 
-  Input, 
-  DropdownMenu, 
-  Select, 
-  Dialog,
-  useUnifiedAuth 
-} from '@jmruthers/pace-core';
+// 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,
+  },
+})
 ```
 
-**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:
+**Fallback Configuration:** If the CSS-first approach doesn't work, you can explicitly include pace-core source files:
 
 ```typescript
-import { 
-  DataTable, 
-  NavigationMenu,
-  FormField,
-  FormErrorSummary 
-} from '@jmruthers/pace-core/components';
+// 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
+})
 ```
 
-**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
+### 4. Verify Installation
 
-### When to Use Which Import?
+Create a test component to ensure everything works:
 
-**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
+```tsx
+// src/App.tsx
+import { Button, Card, Input } from '@jmruthers/pace-core';
 
-**Use Complete Export When:**
-- Need advanced form components
-- Working with complex data tables
-- Require specialized dropdown or select features
-- Building complete page 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>
+  );
+}
 
-### Bundle Size Optimization
+export default App;
+```
 
-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.
+**Expected Result:** You should see properly styled components with PACE Core's design system colors and typography.
 
-```typescript
-// ✅ Good - Only imports what you need
-import { Button, Card } from '@jmruthers/pace-core';
+## ⚠️ Critical Configuration Notes
 
-// ✅ Good - Imports specialized components when needed
-import { FormField, FormErrorSummary } from '@jmruthers/pace-core/components';
+### Why Source File Scanning is Required
 
-// ❌ Avoid - Don't import everything if you only need a few components
-import * as PaceCore from '@jmruthers/pace-core/components';
-```
+Pace-core v0.4.15+ includes source files in the published package because:
 
-## Quick Start
+- 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
 
-### Basic Usage
+### Alternative Configuration (if source files don't work)
 
-```tsx
-import { Button, Card, CardHeader, CardTitle, CardContent } from '@jmruthers/pace-core';
+If you're still having issues with component scanning:
 
-function MyComponent() {
-  return (
-      <Card>
-      <CardHeader>
-        <CardTitle>Welcome</CardTitle>
-      </CardHeader>
-      <CardContent>
-        <Button>Click me</Button>
-      </CardContent>
-      </Card>
-  );
-}
+```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}'
+      ]
+    })
+  ],
+})
 ```
 
-### With Authentication
+### Legacy Configuration (v0.4.14 and below)
 
-```tsx
-import { 
-  UnifiedAuthProvider, 
-  LoginForm, 
-  useUnifiedAuth 
-} from '@jmruthers/pace-core';
-
-function App() {
-  return (
-    <UnifiedAuthProvider>
-      <MyApp />
-    </UnifiedAuthProvider>
-  );
-}
+For older versions, use this configuration:
 
-function MyApp() {
-  const { user, signOut } = useUnifiedAuth();
-  
-  if (!user) {
-    return <LoginForm />;
-  }
-  
-  return (
-    <div>
-      <p>Welcome, {user.email}!</p>
-      <Button onClick={signOut}>Sign Out</Button>
-    </div>
-  );
-}
+```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}'
+      ]
+    })
+  ],
+})
 ```
 
-### Advanced Forms
+## 🔍 Troubleshooting
 
-```tsx
-import { 
-  Form, 
-  FormField, 
-  FormErrorSummary 
-} from '@jmruthers/pace-core/components';
-
-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: Only 292 CSS rules instead of 800+
 
-## 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`
 
-### Basic UI Components
+### Issue: Components appear unstyled
 
-- **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**: 
+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
 
-### Advanced UI Components
+### Issue: Build errors with source files
 
-- **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
+**Solution**: Add TypeScript configuration for node_modules:
 
-### Data Display
+```json
+// tsconfig.json
+{
+  "compilerOptions": {
+    "skipLibCheck": true
+  }
+}
+```
 
-- **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
+## Features
 
-### Forms
+- 🎨 **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
 
-- **Form** - Form container with validation
-- **LoginForm** - Pre-built login form
-- **FormField** - Individual form fields with validation
-- **FormErrorSummary** - Error display for forms
+## Documentation
 
-### Layout
+- [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
 
-- **Header** - Application header component
-- **Footer** - Application footer
-- **NavigationMenu** - Navigation menus
-- **UserMenu** - User account menu
-- **PaceAppLayout** - Complete application layout
-- **PaceLoginPage** - Login page layout
+## Import Strategy
 
-### Utilities
+PACE Core provides two import paths to optimize for different use cases:
 
-- **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
+### Main Export (Recommended for Common Components)
 
-## Hooks
+Use the main export for frequently used components and utilities:
 
-- **useUnifiedAuth** - Authentication state and methods
-- **useTheme** - Theme management
-- **useToast** - Toast notification system
+```typescript
+import { 
+  Button, 
+  Card, 
+  Input, 
+  DropdownMenu, 
+  Select, 
+  Dialog,
+  useUnifiedAuth 
+} from '@jmruthers/pace-core';
+```
 
-## Providers
+**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
 
-- **UnifiedAuthProvider** - Authentication context provider
-- **ThemeProvider** - Theme context provider
-- **EventProvider** - Event management provider
+### Component Documentation
 
-## Utilities
+- **[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
 
-- **cn** - Class name utility (clsx + tailwind-merge)
-- **appConfig** - Application configuration utilities
+### Complete Components Export (For Specialized Components)
 
-## Contributing
+Use the complete export for specialized or advanced components:
 
-See [CONTRIBUTING.md](./CONTRIBUTING.md) for development guidelines.
+```typescript
+import { 
+  DataTable, 
+  NavigationMenu,
+  FormField,
+  FormErrorSummary 
+} from '@jmruthers/pace-core/components';
+```
 
 ## License
 
-MIT
+MIT License - see [LICENSE](./LICENSE) for details.

package/docs/api/classes/ErrorBoundary.md

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

package/docs/api/classes/InvalidScopeError.md

@@ -0,0 +1,73 @@
+[@jmruthers/pace-core - v0.5.3](../README.md) / [Exports](../modules.md) / InvalidScopeError
+
+# Class: InvalidScopeError
+
+## Hierarchy
+
+- [`RBACError`](RBACError.md)
+
+  ↳ **`InvalidScopeError`**
+
+## Table of contents
+
+### Constructors
+
+- [constructor](InvalidScopeError.md#constructor)
+
+### Properties
+
+- [code](InvalidScopeError.md#code)
+- [context](InvalidScopeError.md#context)
+
+## Constructors
+
+### constructor
+
+• **new InvalidScopeError**(`scope`, `reason`): [`InvalidScopeError`](InvalidScopeError.md)
+
+#### Parameters
+
+| Name | Type |
+| :------ | :------ |
+| `scope` | [`Scope`](../modules.md#scope) |
+| `reason` | `string` |
+
+#### Returns
+
+[`InvalidScopeError`](InvalidScopeError.md)
+
+#### Overrides
+
+[RBACError](RBACError.md).[constructor](RBACError.md#constructor)
+
+#### Defined in
+
+[packages/core/src/rbac/types.ts:325](https://github.com/jmruthers/pace-core/blob/main/packages/core/src/rbac/types.ts#L325)
+
+## Properties
+
+### code
+
+• **code**: `string`
+
+#### Inherited from
+
+[RBACError](RBACError.md).[code](RBACError.md#code)
+
+#### Defined in
+
+[packages/core/src/rbac/types.ts:285](https://github.com/jmruthers/pace-core/blob/main/packages/core/src/rbac/types.ts#L285)
+
+___
+
+### context
+
+• `Optional` **context**: `Record`\<`string`, `any`\>
+
+#### Inherited from
+
+[RBACError](RBACError.md).[context](RBACError.md#context)
+
+#### Defined in
+
+[packages/core/src/rbac/types.ts:286](https://github.com/jmruthers/pace-core/blob/main/packages/core/src/rbac/types.ts#L286)

package/docs/api/classes/MissingUserContextError.md

@@ -0,0 +1,66 @@
+[@jmruthers/pace-core - v0.5.3](../README.md) / [Exports](../modules.md) / MissingUserContextError
+
+# Class: MissingUserContextError
+
+## Hierarchy
+
+- [`RBACError`](RBACError.md)
+
+  ↳ **`MissingUserContextError`**
+
+## Table of contents
+
+### Constructors
+
+- [constructor](MissingUserContextError.md#constructor)
+
+### Properties
+
+- [code](MissingUserContextError.md#code)
+- [context](MissingUserContextError.md#context)
+
+## Constructors
+
+### constructor
+
+• **new MissingUserContextError**(): [`MissingUserContextError`](MissingUserContextError.md)
+
+#### Returns
+
+[`MissingUserContextError`](MissingUserContextError.md)
+
+#### Overrides
+
+[RBACError](RBACError.md).[constructor](RBACError.md#constructor)
+
+#### Defined in
+
+[packages/core/src/rbac/types.ts:336](https://github.com/jmruthers/pace-core/blob/main/packages/core/src/rbac/types.ts#L336)
+
+## Properties
+
+### code
+
+• **code**: `string`
+
+#### Inherited from
+
+[RBACError](RBACError.md).[code](RBACError.md#code)
+
+#### Defined in
+
+[packages/core/src/rbac/types.ts:285](https://github.com/jmruthers/pace-core/blob/main/packages/core/src/rbac/types.ts#L285)
+
+___
+
+### context
+
+• `Optional` **context**: `Record`\<`string`, `any`\>
+
+#### Inherited from
+
+[RBACError](RBACError.md).[context](RBACError.md#context)
+
+#### Defined in
+
+[packages/core/src/rbac/types.ts:286](https://github.com/jmruthers/pace-core/blob/main/packages/core/src/rbac/types.ts#L286)