@jmruthers/pace-core 0.2.4

package/CHANGELOG.md

@@ -0,0 +1,202 @@
+# Changelog
+
+All notable changes to the `@jmruthers/pace-core` package will be documented in this file.
+
+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
+- **Row Actions Simplification**: Removed incomplete `features.rowActions` implementation and kept robust `actions` prop as the single method for custom row actions
+- **Documentation Update**: Updated all documentation to reflect single row actions approach using `actions` prop
+
+### Fixed
+- **Actions Prop Implementation**: Verified and confirmed that the `actions` prop is fully implemented and working correctly in DataTable component
+
+### Fixed
+- **CRITICAL**: Fixed timing issue in OrganisationProvider where database organisation context was not set before other components tried to use it
+- **CRITICAL**: Fixed race condition that caused RLS policies to fail on first load
+- **CRITICAL**: Fixed super admin permissions returning false for all operations due to missing organisation context
+- **CRITICAL**: Fixed Tailwind v4 theme file with missing semantic colors and circular @apply references
+- **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-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
+
+### Added
+- Comprehensive JSDoc documentation for all public components
+- Enhanced API documentation with examples and TypeScript types
+- Complete testing guide with utilities and patterns
+- Quick start examples and troubleshooting guides
+- Performance optimization recommendations
+- Migration guides from Auth0 and Firebase
+- Interactive CodeSandbox and StackBlitz examples
+- Context readiness state to ensure database context is set before rendering children
+
+### Enhanced
+- Button component with full JSDoc documentation and examples
+- README with 3-minute quick start guide
+- Error handling documentation with common solutions
+- Component documentation with accessibility guidelines
+- OrganisationProvider with proper async context setting and loading states
+
+### Improved
+- Developer experience with better onboarding materials
+- Documentation structure for easier navigation
+- Code examples with TypeScript types and best practices
+- Organisation context reliability and timing
+
+## [0.1.102] - 2025-05-26
+
+### Added
+- Enhanced package structure for better modularity
+- Granular exports in package.json for better tree-shaking
+- Improved boundary validation scripts
+- CHANGELOG.md for tracking package versions
+
+### Fixed
+- Resolved duplicate exports of EventSelectorProps
+- Clean separation between test utilities and production code
+- Enhanced demo discoverability with improved index page
+
+### Changed
+- Optimized main index.ts exports to avoid conflicts
+- Strengthened validation scripts with circular dependency checks
+- Improved package.json exports for better modularity
+
+## [0.1.101] - Previous Release
+
+### Added
+- Core component library with Button, Card, Input, DataTable
+- Authentication module with Supabase integration
+- RBAC system with permission guards and hooks
+- Event management with dynamic theming
+- Form validation with Zod schemas
+- Comprehensive test utilities and mock providers
+
+### Features
+- TypeScript support with strict typing
+- Tree-shakeable exports
+- Tailwind CSS styling
+- shadcn/ui component integration
+- Accessibility support
+- Comprehensive documentation
+
+### Components
+- **UI Components**: Button, Card, Input, Alert, Avatar, Progress
+- **Form Components**: Form, FormField, Input validation
+- **Layout Components**: Header, Footer, NavigationMenu
+- **Data Components**: DataTable with sorting, filtering, pagination
+- **Authentication**: LoginForm, UserMenu, AuthProvider
+- **RBAC**: PermissionGuard, RBACProvider
+
+### Hooks
+- **Authentication**: useAuth, useAutoLogout, useSecureAuth
+- **Permissions**: useHasPermission, usePermissionCheck, usePermissions
+- **UI**: useToast, useIsMobile, useFocusManagement
+- **Forms**: useZodForm, form validation hooks
+
+### Utilities
+- **Validation**: Email, password, form schemas
+- **Security**: Encryption, rate limiting, audit logging
+- **Formatting**: Date, currency, percentage formatters
+- **Performance**: Debouncing, throttling, memoization
+
+### Types
+- **Core Types**: User, Session, AuthError, PermissionString
+- **Component Types**: ButtonProps, FormProps, DataTableProps
+- **Utility Types**: AccessLevel, ValidationError, SecurityLevel
+
+## [0.1.0] - Initial Release
+
+### Added
+- Initial package structure
+- Basic component library foundation
+- Authentication provider setup
+- RBAC permission system
+- Form validation utilities
+- TypeScript configuration
+- Build and test infrastructure
+
+### Infrastructure
+- Vite build system
+- Vitest testing framework
+- ESLint and Prettier configuration
+- GitHub Actions CI/CD
+- NPM publishing workflow
+
+---
+
+## Migration Guide
+
+### Upgrading from 0.1.101 to 0.1.102
+
+No breaking changes. This release focuses on improved documentation and developer experience.
+
+### Upgrading to Future Versions
+
+Check this changelog for breaking changes and migration instructions for each version.
+
+## Security Updates
+
+Security fixes will be documented here with details about:
+- CVE numbers (if applicable)
+- Affected versions
+- Recommended upgrade paths
+- Workarounds for immediate fixes
+
+## Deprecation Notices
+
+Features planned for deprecation will be announced here with:
+- Deprecation version
+- Removal timeline
+- Migration instructions
+- Alternative solutions
+
+## Roadmap
+
+### v0.2.0 (Planned)
+- Enhanced DataTable with virtual scrolling
+- Advanced form components (date pickers, file uploads)
+- Improved accessibility features
+- Performance optimizations
+
+### v0.3.0 (Planned)
+- React Server Components support
+- Advanced RBAC features
+- Internationalization support
+- Theme customization system
+
+### v1.0.0 (Planned)
+- Stable API with semantic versioning guarantees
+- Complete documentation coverage
+- Comprehensive test suite
+- Production-ready performance optimizations

package/README.md

@@ -0,0 +1,299 @@
+# @jmruthers/pace-core
+
+Clean, modern React component library with Tailwind v4 styling and native utilities.
+
+## 🚀 PaceAppLayout Usage
+
+**PaceAppLayout uses React Router's nested routing pattern for optimal performance and scalability.**
+
+```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>
+```
+
+## 🚀 Complete Installation Guide
+
+### 1. 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 Tailwind CSS v4 and Vite plugin
+npm install -D @tailwindcss/vite tailwindcss@^4.0.0
+```
+
+### 2. Import Core Styles
+
+```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>
+);
+```
+
+### 3. Configure Vite with Tailwind v4
+
+**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
+// 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,
+  },
+})
+```
+
+**Fallback Configuration:** If the CSS-first approach doesn't work, you can explicitly include pace-core source files:
+
+```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
+})
+```
+
+### 4. Verify Installation
+
+Create a test component to ensure everything works:
+
+```tsx
+// src/App.tsx
+import { Button, Card, Input } from '@jmruthers/pace-core';
+
+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>
+  );
+}
+
+export default App;
+```
+
+**Expected Result:** You should see properly styled components with PACE Core's design system colors and typography.
+
+## ⚠️ Critical Configuration Notes
+
+### Why Source File Scanning is Required
+
+Pace-core v0.4.15+ includes source files in the published package because:
+
+- 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
+
+### Alternative Configuration (if source files don't work)
+
+If you're still having issues with component scanning:
+
+```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}'
+      ]
+    })
+  ],
+})
+```
+
+### Legacy Configuration (v0.4.14 and below)
+
+For older versions, use this configuration:
+
+```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}'
+      ]
+    })
+  ],
+})
+```
+
+## 🔍 Troubleshooting
+
+### Issue: 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: `rm -rf dist .vite node_modules && npm install`
+
+### Issue: Components appear unstyled
+
+**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
+
+### Issue: Build errors with source files
+
+**Solution**: Add TypeScript configuration for node_modules:
+
+```json
+// tsconfig.json
+{
+  "compilerOptions": {
+    "skipLibCheck": true
+  }
+}
+```
+
+## Features
+
+- 🎨 **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
+
+## Documentation
+
+- [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
+
+## Import Strategy
+
+PACE Core provides two import paths to optimize for different use cases:
+
+### Main Export (Recommended for Common Components)
+
+Use the main export for frequently used components and utilities:
+
+```typescript
+import { 
+  Button, 
+  Card, 
+  Input, 
+  DropdownMenu, 
+  Select, 
+  Dialog,
+  useUnifiedAuth 
+} from '@jmruthers/pace-core';
+```
+
+**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
+
+### Component Documentation
+
+- **[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
+
+### Complete Components Export (For Specialized Components)
+
+Use the complete export for specialized or advanced components:
+
+```typescript
+import { 
+  DataTable, 
+  NavigationMenu,
+  FormField,
+  FormErrorSummary 
+} from '@jmruthers/pace-core/components';
+```
+
+## License
+
+MIT License - see [LICENSE](./LICENSE) for details.

package/dist/DataTable-BHlzyKZP.d.ts

@@ -0,0 +1,116 @@
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import React__default from 'react';
+import { D as DataRecord, a as DataTableColumn, b as DataTableFeatureConfig, H as HierarchicalConfig, P as PerformanceConfig, S as ServerSideConfig, c as PaginationMode, C as ChunkingConfig, d as SearchIndexConfig, G as GetRowId, E as EmptyStateConfig, A as AggregateConfig, e as DataTableAction } from './types-CInEi-ng.js';
+
+/**
+ * Configuration interface for customizing ImportModal text content
+ * @public
+ */
+interface ImportModalConfig {
+    /** Custom title for the import modal */
+    title?: string;
+    /** Custom description text shown below the title */
+    description?: string;
+    /** Custom text shown in the file upload area when no file is selected */
+    uploadText?: string;
+    /** Custom text for the file selection button */
+    selectFileButtonText?: string;
+    /** Custom text for the import button */
+    importButtonText?: string;
+    /** Custom text for the import button when processing */
+    importButtonProcessingText?: string;
+    /** Custom text for the cancel button */
+    cancelButtonText?: string;
+    /** Custom text for the preview section header */
+    previewHeaderText?: string;
+    /** Custom text pattern for total rows display. Use {count} as placeholder for the actual count */
+    totalRowsText?: string;
+}
+
+/**
+ * Enhanced DataTable props with performance features
+ * @template TData - The type of data records in the table
+ */
+interface DataTableProps<TData extends DataRecord> {
+    /** Array of data records to display in the table */
+    data: TData[];
+    /** Column definitions for the table */
+    columns: DataTableColumn<TData>[];
+    /** Optional title displayed above the table */
+    title?: string;
+    /** Optional description displayed below the title */
+    description?: string;
+    /** Visual variant of the table */
+    variant?: 'default' | 'compact' | 'spacious';
+    /** Additional CSS classes for the table container */
+    className?: string;
+    /** Feature configuration - all features are disabled by default */
+    features: DataTableFeatureConfig;
+    /** Hierarchical parent/child row configuration */
+    hierarchical?: HierarchicalConfig;
+    /** Performance optimization configuration */
+    performance?: PerformanceConfig;
+    /** Server-side data fetching configuration */
+    serverSide?: ServerSideConfig<TData>;
+    /** Override automatic pagination mode detection */
+    paginationMode?: PaginationMode;
+    /** Data chunking configuration for memory optimization */
+    chunking?: ChunkingConfig;
+    /** Search indexing configuration for fast search */
+    searchIndex?: SearchIndexConfig;
+    /** Virtual scrolling height */
+    virtualHeight?: number;
+    /** Initial page size for pagination */
+    initialPageSize?: number;
+    /** Enable enhanced pagination controls */
+    enhancedPagination?: boolean;
+    /** Custom loading component */
+    loadingComponent?: React__default.ComponentType;
+    /** Custom error component */
+    errorComponent?: React__default.ComponentType<{
+        error: Error;
+        retry: () => void;
+    }>;
+    /** Callback when a row is edited */
+    onEditRow?: (row: TData, data: Partial<TData>) => void;
+    /** Callback when a row is deleted */
+    onDeleteRow?: (row: TData) => void;
+    /** Callback when a new row is created */
+    onCreateRow?: (data: Partial<TData>) => void;
+    /** Callback when data is imported */
+    onImport?: (data: TData[]) => void | Promise<void>;
+    /** Callback when row selection changes */
+    onRowSelectionChange?: (selection: Record<string, boolean>) => void;
+    /** Controlled selection state */
+    selection?: Record<string, boolean>;
+    /** Callback when bulk delete selected rows is triggered */
+    onDeleteSelected?: (selectedRows: Record<string, boolean>) => void;
+    /** Function to generate unique row IDs */
+    getRowId?: GetRowId<TData>;
+    /** Whether the table is in a loading state */
+    isLoading?: boolean;
+    /** Custom component to display when table is empty */
+    emptyState?: EmptyStateConfig | React__default.ReactElement;
+    /** Array of aggregation functions for grouped data */
+    aggregates?: AggregateConfig[];
+    /** Import modal configuration */
+    importModalConfig?: ImportModalConfig;
+    /** Custom row actions - use this for custom action buttons */
+    actions?: DataTableAction<TData>[];
+    /** Column order configuration - array of column IDs in desired order */
+    columnOrder?: string[];
+}
+/**
+ * Enhanced DataTable with comprehensive performance optimizations
+ *
+ * This component automatically detects dataset size and applies appropriate performance optimizations:
+ * - < 1,000 records: Standard rendering with full feature support
+ * - 1,000+ records: Automatic virtual scrolling with intelligent memory management
+ * - 10,000+ records: Enhanced chunking and memory optimization
+ * - 100,000+ records: Advanced server-side processing with virtualization
+ *
+ * Features are configured through the unified `features` prop for maximum flexibility.
+ */
+declare function DataTable<TData extends DataRecord>(props: DataTableProps<TData>): react_jsx_runtime.JSX.Element;
+
+export { DataTable as D, type DataTableProps as a };