@jmruthers/pace-core 0.4.1 → 0.5.1

package/CHANGELOG.md

@@ -5,6 +5,31 @@ All notable changes to the `@jmruthers/pace-core` package will be documented in
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+### Added
+- **DataTable Initial Page Size**: Added `initialPageSize` prop to DataTable component for customizing the initial page size
+- **Page Size Validation**: Automatic validation of initial page size against available options with fallback to closest valid option
+- **Console Warnings**: Helpful warnings when invalid page sizes are provided
+- **DataTable Expand/Collapse All**: Added expand/collapse all button in hierarchical DataTable headers for quick parent row management
+- **Smart State Detection**: Button automatically updates icon (▶️/🔽) based on current expansion state
+- **Accessibility Support**: Full ARIA labels and keyboard navigation for expand/collapse all functionality
+- **DataTable Column Ordering**: Added `columnOrder` prop to DataTable component for custom column positioning
+- **Selection Column Positioning**: Selection column can now be positioned anywhere in the column order
+- **Actions Column Positioning**: Actions column can now be positioned anywhere in the column order
+- **Default Behavior**: When `columnOrder` doesn't include 'select', selection column defaults to first position
+
+### Fixed
+- **DataTable Infinite Loop Prevention**: Fixed infinite re-rendering loops when using complex data processing with `useMemo` hooks
+- **Data Reference Stability**: Improved data reference stability to prevent unnecessary re-renders
+- **Memory Optimization**: Added safeguards against infinite loops with render counting and data comparison
+- **Performance**: Optimized table configuration memoization to prevent unnecessary re-creation
+
+### Improved
+- **Data Processing Documentation**: Added comprehensive best practices for data processing with DataTable
+- **Error Handling**: Added infinite loop detection and prevention mechanisms
+- **Type Safety**: Improved TypeScript type handling for complex data scenarios
+
 ## [0.3.52] - 2024-12-19
 
 ### Changed
@@ -22,7 +47,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - **CRITICAL**: Fixed component classes (.pace-button, .pace-input, .pace-card) to be self-contained
 - **CRITICAL**: Fixed missing basic colors (white, black, transparent, current) in Tailwind v4 theme file
 - **CRITICAL**: Fixed semantic color mappings to match demo app appearance (blue-tinted theme instead of neutral gray)
-- **CRITICAL**: Fixed header layout by adding missing CSS variables (--app-width, --color-app-main-*, --color-app-sec-*, --color-app-acc-*)
+- **CRITICAL**: Fixed header layout by adding missing CSS variables (--app-width, --color-main-*, --color-sec-*, --color-acc-*)
 - **CRITICAL**: Added comprehensive CSS variable coverage for all components (fonts, design tokens, event colors, Radix UI variables)
 - **CRITICAL**: Added comprehensive troubleshooting guide for "unrecognized configuration parameter" database errors
 

package/README.md

@@ -1,297 +1,299 @@
-# 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/dist/{DataTable-2LB6HI6V.js → DataTable-GX3XERFJ.js}

@@ -7,16 +7,14 @@ import {
   ColumnVisibilityDropdown,
   DataManager,
   DataTable,
-  DataTableBody,
+  DataTableCore,
   DataTableErrorBoundary,
-  DataTableHeader,
   DataTableModals,
   DataTableProvider,
   DataTableToolbar,
   EditableRow,
   EmptyState,
   EnhancedPaginationControls,
-  EnhancedVirtualizedDataTable,
   GroupHeader,
   GroupingDropdown,
   ImportModal,
@@ -25,8 +23,7 @@ import {
   PaginationControls,
   PluginRegistryImpl,
   StateManagerImpl,
-  ViewRowModal,
-  VirtualizedDataTable,
+  UnifiedTableBody,
   exportToCSV,
   generateCSVContent,
   useActionManager,
@@ -35,10 +32,12 @@ import {
   useDataTableContext,
   usePluginRegistry,
   useStateManager
-} from "./chunk-4MCJAK7J.js";
+} from "./chunk-GSNM5D6H.js";
+import "./chunk-AUE24LVR.js";
+import "./chunk-C5G2A4PO.js";
+import "./chunk-7BNPOCLL.js";
 import {
   DataChunkManager,
-  PerformanceMonitor,
   SearchIndex,
   VisibilityTracker,
   chunkData,
@@ -47,9 +46,11 @@ import {
   getOptimalPageSizeOptions,
   throttle,
   useDataTablePerformance
-} from "./chunk-WHLSWC6W.js";
-import "./chunk-U7DY5T33.js";
-import "./chunk-DC5AMYBS.js";
+} from "./chunk-SS3E6QLB.js";
+import "./chunk-6CR3MRZN.js";
+import "./chunk-YDJW5XTN.js";
+import "./chunk-OYRY44Q2.js";
+import "./chunk-PLDDJCW6.js";
 export {
   ActionButtons,
   ActionManagerImpl as ActionManager,
@@ -60,28 +61,24 @@ export {
   DataChunkManager,
   DataManager,
   DataTable,
-  DataTableBody,
+  DataTableCore,
   DataTableErrorBoundary,
-  DataTableHeader,
   DataTableModals,
   DataTableProvider,
   DataTableToolbar,
   EditableRow,
   EmptyState,
   EnhancedPaginationControls,
-  EnhancedVirtualizedDataTable,
   GroupHeader,
   GroupingDropdown,
   ImportModal,
   LoadingState,
   LocalDataAdapter,
   PaginationControls,
-  PerformanceMonitor,
   PluginRegistryImpl as PluginRegistry,
   SearchIndex,
   StateManagerImpl as StateManager,
-  ViewRowModal,
-  VirtualizedDataTable,
+  UnifiedTableBody,
   VisibilityTracker,
   chunkData,
   debounce,
@@ -98,4 +95,4 @@ export {
   usePluginRegistry,
   useStateManager
 };
-//# sourceMappingURL=DataTable-2LB6HI6V.js.map
+//# sourceMappingURL=DataTable-GX3XERFJ.js.map