@jmruthers/pace-core 0.5.135 → 0.5.136

package/docs/api-reference/components.md

@@ -346,11 +346,18 @@ const userSchema = z.object({
   age: z.number().min(18, "Must be at least 18 years old")
 });
 
+import { logger } from '@jmruthers/pace-core/utils';
+
 <Form
   schema={userSchema}
   defaultValues={{ name: "", email: "", age: 0 }}
-  onSubmit={(data) => console.log(data)}
-  onError={(errors) => console.error(errors)}
+  onSubmit={(data) => {
+    // Handle form submission
+    logger.debug('Form', 'Form submitted:', data);
+  }}
+  onError={(errors) => {
+    logger.error('Form', 'Form validation errors:', errors);
+  }}
 >
   <FormField name="name" label="Name" />
   <FormField name="email" label="Email" type="email" />
@@ -362,13 +369,29 @@ const userSchema = z.object({
 ### Form Components
 
 - **FormField**: Individual form fields with validation
-- **FormErrorSummary**: Error display for forms
-- **FormLiveRegion**: Live region for accessibility
-- **FormFieldset**: Grouped form fields
 
 ## Dialog
 
-A comprehensive, accessible dialog component system with enhanced features for modern web applications. Built on Radix UI primitives with semantic HTML structure and smart height management.
+A comprehensive, accessible dialog component system built on top of Radix UI primitives with enhanced features for modern web applications.
+
+### Features
+
+#### Core Features
+- **Semantic HTML Structure** - Uses native `<dialog>` element with proper header, main, footer elements
+- **Accessibility First** - WCAG 2.1 AA compliant with full screen reader support
+- **Focus Management** - Automatic focus trapping and restoration
+- **Keyboard Navigation** - Escape to close, Tab for focus management
+- **Responsive Design** - Adapts to all screen sizes with smart constraints
+
+#### Advanced Features
+- **Smart Height Management** - Automatic viewport-based height constraints
+- **Scrollable Content** - Long content scrolls while keeping headers/footers visible
+- **Sticky Headers/Footers** - Important UI elements remain accessible during scrolling
+- **Multiple Size Variants** - sm, md, lg, xl, full, auto sizing options
+- **Custom Dimensions** - Fine-grained control over width and height
+- **Configurable Close Behavior** - Control escape key and outside click behavior
+- **Smooth Animations** - Polished transitions and micro-interactions
+- **HTML Content Rendering** - Safe HTML content with automatic sanitization
 
 ### Props
 
@@ -585,24 +608,40 @@ import {
 </Dialog>
 ```
 
-### Features
+### HTML Content Rendering
 
-#### Core Features
-- **Semantic HTML Structure**: Uses native `<dialog>` element with proper header, main, footer elements
-- **Accessibility First**: WCAG 2.1 AA compliant with full screen reader support
-- **Focus Management**: Automatic focus trapping and restoration
-- **Keyboard Navigation**: Escape to close, Tab for focus management
-- **Responsive Design**: Adapts to all screen sizes with smart constraints
+The Dialog components support rich HTML content rendering with automatic sanitization. This is perfect for formatted instructions, feature announcements, error details, or any HTML that needs to be displayed in dialogs.
 
-#### Advanced Features
-- **Smart Height Management**: Automatic viewport-based height constraints
-- **Scrollable Content**: Long content scrolls while keeping headers/footers visible
-- **Sticky Headers/Footers**: Important UI elements remain accessible during scrolling
-- **HTML Content Rendering**: Safe HTML content with automatic sanitization
-- **Multiple Size Variants**: sm, md, lg, xl, full, auto sizing options
-- **Custom Dimensions**: Fine-grained control over width and height
-- **Configurable Close Behavior**: Control escape key and outside click behavior
-- **Smooth Animations**: Polished transitions and micro-interactions
+**Key Features:**
+- **Rich HTML Rendering**: Full HTML support with proper styling
+- **Safe Sanitization**: Automatic XSS protection
+- **Prose Styling**: Typography classes for readable content
+- **Fallback Support**: Graceful degradation if HTML fails
+
+**Configuration Options:**
+
+| Property | Type | Default | Description |
+|----------|------|---------|-------------|
+| `htmlContent` | `string` | `undefined` | HTML string to render |
+| `allowHtml` | `boolean` | `true` | Enable/disable HTML rendering |
+| `strictSanitization` | `boolean` | `true` | Use strict HTML sanitization |
+| `logWarnings` | `boolean` | `false` | Log sanitization warnings to console |
+
+**Supported HTML Elements:**
+- Text formatting: `p`, `div`, `span`, `h1`-`h6`, `strong`, `em`, `b`, `i`, `u`, `s`, `mark`, `small`, `sub`, `sup`
+- Lists: `ul`, `ol`, `li`, `dl`, `dt`, `dd`
+- Code: `pre`, `code`, `kbd`, `samp`
+- Links: `a` (with href validation)
+- Tables: `table`, `thead`, `tbody`, `tfoot`, `tr`, `th`, `td`
+- Media: `img` (with src validation)
+- Layout: `section`, `article`, `aside`, `header`, `footer`, `main`, `nav`
+- Interactive: `details`, `summary`
+
+**Removed Elements (for security):**
+- Scripts: `script`, `iframe`, `object`, `embed`
+- Forms: `form`, `input`, `button`
+- Event handlers: `onclick`, `onload`, etc.
+- Dangerous protocols: `javascript:`, `data:`
 
 ### Size Variants
 
@@ -615,6 +654,46 @@ import {
 | `full` | 100% | Full screen experiences |
 | `auto` | Content-based | Dynamic content sizing |
 
+### Accessibility
+
+#### WCAG 2.1 AA Compliance
+- **Semantic HTML** - Uses proper `<dialog>`, `<header>`, `<main>`, `<footer>` elements
+- **Focus Management** - Automatic focus trapping and restoration
+- **Keyboard Navigation** - Full keyboard support with proper tab order
+- **Screen Reader Support** - Complete ARIA attributes and announcements
+- **Landmark Navigation** - Proper semantic structure for screen reader navigation
+
+#### Keyboard Shortcuts
+- **Escape** - Close dialog (configurable)
+- **Tab** - Navigate through focusable elements
+- **Shift + Tab** - Navigate backwards through focusable elements
+
+### Performance
+
+#### Optimizations
+- **Efficient Focus Management** - Minimal DOM queries and updates
+- **Optimized Animations** - Hardware-accelerated transitions
+- **Memory Leak Prevention** - Proper cleanup of event listeners
+- **Conditional Rendering** - Only renders when needed
+- **Optimized Scroll Handling** - Debounced resize events
+
+#### Best Practices
+- Use `enableScrolling={true}` for content that might overflow
+- Set appropriate `maxHeightPercent` to prevent viewport overflow
+- Use sticky headers/footers for important UI elements
+- Consider `size="auto"` for dynamic content
+
+### Troubleshooting
+
+**Common Issues:**
+
+1. **Content not scrolling** - Ensure `enableScrolling={true}` is set
+2. **Header/footer not sticky** - Add `sticky={true}` to header/footer props
+3. **Dialog too tall** - Use `maxHeightPercent` or `maxHeight` props
+4. **Focus issues** - Ensure proper semantic structure with DialogBody
+5. **HTML not rendering** - Check that `allowHtml={true}` is set and HTML is valid
+6. **Content being stripped** - Check sanitization settings and verify HTML elements are allowed
+
 ## Select
 
 A dropdown select component with search functionality and keyboard navigation.
@@ -1388,12 +1467,13 @@ For more details, see the [Authentication Implementation Guide](../implementatio
 Form component for changing user passwords.
 
 ```tsx
-import { PasswordChangeForm } from '@jmruthers/pace-core';
+import { PasswordChangeForm, logger } from '@jmruthers/pace-core';
 
 <PasswordChangeForm 
   onSubmit={(values) => {
     // Handle password change
-    console.log('New password:', values.newPassword);
+    logger.debug('PasswordChange', 'Password change initiated');
+    // Note: Never log actual password values in production
   }}
 />
 ```
@@ -1594,11 +1674,11 @@ interface FileUploadProps {
 #### Usage
 
 ```tsx
-import { FileUpload, FileCategory } from '@jmruthers/pace-core';
+import { FileUpload, FileCategory, logger } from '@jmruthers/pace-core';
 
 function MyFileUpload() {
   const handleUpload = (fileRef: FileReference) => {
-    console.log('File uploaded:', fileRef);
+    logger.debug('FileUpload', 'File uploaded:', { fileId: fileRef.id, fileName: fileRef.name });
   };
 
   return (

package/docs/architecture/README.md

@@ -229,8 +229,6 @@ graph TD
     
     E --> R[Form]
     E --> S[FormField]
-    E --> T[FormErrorSummary]
-    E --> U[FormLiveRegion]
 ```
 
 ### Styling Architecture

package/docs/implementation-guides/data-tables.md

@@ -532,6 +532,266 @@ const columns: DataTableColumn<Dish>[] = [
 // 3. Parent-child relationships are maintained
 ```
 
+## Grouped Row Aggregation
+
+### Overview
+
+The DataTable supports custom aggregation functions in grouped rows, allowing columns to display aggregated values (sum, average, count, etc.) instead of just row counts. This is particularly useful for data analysis and reporting use cases.
+
+### Quick Start
+
+#### 1. Enable Grouping
+
+```tsx
+<DataTable
+  data={data}
+  columns={columns}
+  features={{
+    grouping: true, // Enable grouping
+  }}
+  defaultGrouping={['category']} // Optional: group by category on load
+/>
+```
+
+#### 2. Add Aggregation Functions to Columns
+
+```tsx
+import { DataTable, sum, average, count } from '@jmruthers/pace-core';
+
+const columns: DataTableColumn<DinerData>[] = [
+  {
+    accessorKey: 'diet',
+    header: 'Diet',
+    enableGrouping: true,
+  },
+  {
+    accessorKey: 'youth',
+    header: 'Total Youth',
+    aggregateFn: sum('youth'), // Sum all youth values in the group
+  },
+  {
+    accessorKey: 'adults',
+    header: 'Total Adults',
+    aggregateFn: sum('adults'), // Sum all adult values in the group
+  },
+  {
+    accessorKey: 'cost',
+    header: 'Avg Cost',
+    aggregateFn: average('cost'), // Average cost across the group
+  },
+];
+```
+
+### Built-in Aggregation Functions
+
+The DataTable provides several built-in aggregation utility functions:
+
+#### Sum
+
+```tsx
+{
+  accessorKey: 'quantity',
+  header: 'Total Quantity',
+  aggregateFn: sum('quantity'),
+}
+```
+
+#### Average
+
+```tsx
+{
+  accessorKey: 'price',
+  header: 'Avg Price',
+  aggregateFn: average('price'),
+}
+```
+
+#### Count
+
+```tsx
+{
+  accessorKey: 'id',
+  header: 'Count',
+  aggregateFn: count(),
+}
+```
+
+#### Min
+
+```tsx
+{
+  accessorKey: 'price',
+  header: 'Min Price',
+  aggregateFn: min('price'),
+}
+```
+
+#### Max
+
+```tsx
+{
+  accessorKey: 'price',
+  header: 'Max Price',
+  aggregateFn: max('price'),
+}
+```
+
+### Custom Aggregation Functions
+
+You can create custom aggregation functions for more complex calculations:
+
+```tsx
+const columns: DataTableColumn<DinerData>[] = [
+  {
+    accessorKey: 'diet',
+    header: 'Diet',
+    enableGrouping: true,
+  },
+  {
+    accessorKey: 'youth',
+    header: 'Total Diners',
+    aggregateFn: (rows) => {
+      // Custom: sum of youth + adults
+      return rows.reduce((total, row) => total + (row.youth || 0) + (row.adults || 0), 0);
+    },
+  },
+];
+```
+
+### Custom Aggregate Cell Renderer
+
+Use `aggregateCell` to customize how aggregated values are displayed:
+
+```tsx
+{
+  accessorKey: 'cost',
+  header: 'Total Cost',
+  aggregateFn: sum('cost'),
+  aggregateCell: (value) => {
+    // Custom formatting for aggregated value
+    return `$${value.toFixed(2)}`;
+  },
+}
+```
+
+If `aggregateCell` is not provided, the column's regular `cell` renderer will be used, or the raw value will be displayed.
+
+### Complete Example
+
+```tsx
+import { DataTable, sum, average, type DataTableColumn } from '@jmruthers/pace-core';
+
+interface DinerData {
+  id: string;
+  diet: string;
+  youth: number;
+  adults: number;
+  cost: number;
+}
+
+const dinerData: DinerData[] = [
+  { id: '1', diet: 'Standard', youth: 10, adults: 5, cost: 100.50 },
+  { id: '2', diet: 'Standard', youth: 15, adults: 8, cost: 150.75 },
+  { id: '3', diet: 'Standard', youth: 20, adults: 10, cost: 200.00 },
+  { id: '4', diet: 'Gluten Free', youth: 5, adults: 3, cost: 75.25 },
+  { id: '5', diet: 'Gluten Free', youth: 8, adults: 4, cost: 120.00 },
+];
+
+const columns: DataTableColumn<DinerData>[] = [
+  {
+    accessorKey: 'diet',
+    header: 'Diet',
+    enableGrouping: true,
+  },
+  {
+    accessorKey: 'youth',
+    header: 'Youth',
+    sortable: true,
+    aggregateFn: sum('youth'),
+    aggregateCell: (value) => value.toLocaleString(),
+  },
+  {
+    accessorKey: 'adults',
+    header: 'Adults',
+    sortable: true,
+    aggregateFn: sum('adults'),
+    aggregateCell: (value) => value.toLocaleString(),
+  },
+  {
+    accessorKey: 'cost',
+    header: 'Avg Cost',
+    sortable: true,
+    aggregateFn: average('cost'),
+    aggregateCell: (value) => `$${value.toFixed(2)}`,
+  },
+];
+
+function DinersTable() {
+  return (
+    <DataTable
+      data={dinerData}
+      columns={columns}
+      rbac={{ pageName: 'diners' }}
+      features={{
+        grouping: true,
+        sorting: true,
+        pagination: true,
+      }}
+      defaultGrouping={['diet']}
+      getRowId={(row) => row.id}
+    />
+  );
+}
+```
+
+### Edge Cases and Best Practices
+
+#### Handling Null/Undefined Values
+
+Aggregation functions should handle null/undefined values gracefully:
+
+```tsx
+{
+  accessorKey: 'quantity',
+  header: 'Total',
+  aggregateFn: (rows) => {
+    return rows.reduce((sum, row) => {
+      const value = row.quantity;
+      return sum + (value != null ? value : 0);
+    }, 0);
+  },
+}
+```
+
+The built-in aggregation functions (`sum`, `average`, etc.) already handle null/undefined values correctly.
+
+#### Empty Groups
+
+When a group has no rows, aggregation functions should return appropriate defaults:
+- `sum`: Returns `0`
+- `average`: Returns `0`
+- `count`: Returns `0`
+- `min`/`max`: Returns `null`
+
+#### Columns Without Aggregation
+
+Columns without an `aggregateFn` will show empty cells in grouped rows (current behavior). This is intentional and allows you to selectively aggregate only the columns that need it.
+
+#### Performance Considerations
+
+- Aggregation functions are called once per group when the group is rendered
+- For large datasets, consider memoizing expensive aggregation functions
+- Aggregated values are recalculated when group membership changes
+
+### Integration with Other Features
+
+Grouped row aggregation works seamlessly with:
+- **Sorting**: Aggregated values can be sorted
+- **Filtering**: Aggregated values respect filters
+- **Pagination**: Aggregated values work with pagination
+- **Search**: Aggregated values are searchable
+- **Nested Grouping**: Aggregation works at each grouping level
+
 ## Advanced Filtering
 
 ### Filter Types
@@ -1019,12 +1279,14 @@ const columns = [
 #### Real-Time Metrics
 
 ```tsx
+import { logger } from '@jmruthers/pace-core/utils';
+
 <DataTable
   data={data}
   columns={columns}
   showPerformanceMetrics={true}
   onPerformanceMetrics={(metrics) => {
-    console.log('Performance metrics:', {
+    logger.debug('DataTable', 'Performance metrics:', {
       renderTime: metrics.renderTime,
       memoryUsage: metrics.memoryUsage,
       visibleRows: metrics.visibleRows,
@@ -1075,7 +1337,7 @@ const columns = [
 
 ```tsx
 import { useState } from 'react';
-import { DataTable } from '@jmruthers/pace-core';
+import { DataTable, logger } from '@jmruthers/pace-core';
 import { supabase } from '../supabaseClient';
 
 interface User {
@@ -1101,7 +1363,7 @@ function UserManagement() {
       if (error) throw error;
       setUsers(data || []);
     } catch (error) {
-      console.error('Error fetching users:', error);
+      logger.error('UserManagement', 'Error fetching users:', error);
     } finally {
       setLoading(false);
     }
@@ -1123,7 +1385,7 @@ function UserManagement() {
       
       return { success: true, data };
     } catch (error) {
-      console.error('Error creating user:', error);
+      logger.error('UserManagement', 'Error creating user:', error);
       return { success: false, error };
     }
   };
@@ -1147,7 +1409,7 @@ function UserManagement() {
       
       return { success: true, data };
     } catch (error) {
-      console.error('Error updating user:', error);
+      logger.error('UserManagement', 'Error updating user:', error);
       return { success: false, error };
     }
   };
@@ -1167,7 +1429,7 @@ function UserManagement() {
       
       return { success: true };
     } catch (error) {
-      console.error('Error deleting user:', error);
+      logger.error('UserManagement', 'Error deleting user:', error);
       return { success: false, error };
     }
   };
@@ -1187,7 +1449,7 @@ function UserManagement() {
       
       return { success: true };
     } catch (error) {
-      console.error('Error deleting selected users:', error);
+      logger.error('UserManagement', 'Error deleting selected users:', error);
       return { success: false, error };
     }
   };
@@ -1333,7 +1595,7 @@ const columns = [
 
 ```tsx
 import { useState, useCallback, useMemo } from 'react';
-import { DataTable } from '@jmruthers/pace-core';
+import { DataTable, logger } from '@jmruthers/pace-core';
 
 interface Item {
   id: string;
@@ -1363,7 +1625,7 @@ function ItemsTable() {
     };
     
     setCategories(prev => [...prev, newCategory]);
-    console.log(`Created new category: "${inputValue}"`);
+    logger.debug('CategoryManager', `Created new category: "${inputValue}"`);
     
     return newCategory.value;
   }, []);
@@ -1756,7 +2018,7 @@ The export filename is automatically generated from the table `title` prop:
 By default, the DataTable exports all **visible columns**. To customize the export (different columns, custom filename, etc.), you can provide a custom `onExport` handler:
 
 ```tsx
-import { DataTable, type ExportOptions, exportToCSVWithTableRows, type ExportColumn } from '@jmruthers/pace-core';
+import { DataTable, type ExportOptions, exportToCSVWithTableRows, type ExportColumn, logger } from '@jmruthers/pace-core';
 
 <DataTable
   title="Meals"
@@ -1780,7 +2042,7 @@ import { DataTable, type ExportOptions, exportToCSVWithTableRows, type ExportCol
         
         // Verify this column ID exists in the mapping (for getValue() to work)
         if (!options.columnIdToTableColumn.has(tableColumnId)) {
-          console.warn(`Column ID ${tableColumnId} not found in columnIdToTableColumn map`);
+          logger.warn('DataTable', `Column ID ${tableColumnId} not found in columnIdToTableColumn map`);
           return null;
         }
 
@@ -2105,6 +2367,8 @@ Enable debug logging for DataTable issues:
 
 Enable detailed logging:
 ```tsx
+import { logger } from '@jmruthers/pace-core/utils';
+
 <DataTable
   data={data}
   columns={columns}
@@ -2112,10 +2376,10 @@ Enable detailed logging:
   onPerformanceMetrics={(metrics) => {
     // Log performance issues
     if (metrics.renderTime > 100) {
-      console.warn('Slow render detected:', metrics.renderTime);
+      logger.warn('DataTable', 'Slow render detected:', metrics.renderTime);
     }
     if (metrics.memoryUsage > 100) {
-      console.warn('High memory usage:', metrics.memoryUsage);
+      logger.warn('DataTable', 'High memory usage:', metrics.memoryUsage);
     }
   }}
 />

package/docs/implementation-guides/forms.md

@@ -484,22 +484,7 @@ function FormWithState() {
 </p>
 ```
 
-### 2. Error Announcements
-
-```tsx
-import { FormLiveRegion } from '@jmruthers/pace-core';
-
-function AccessibleForm() {
-  return (
-    <Form schema={userSchema} onSubmit={handleSubmit}>
-      <FormLiveRegion />
-      {/* Form fields */}
-    </Form>
-  );
-}
-```
-
-### 3. Keyboard Navigation
+### 2. Keyboard Navigation
 
 All form components support full keyboard navigation:
 

package/docs/implementation-guides/permission-enforcement.md

@@ -570,12 +570,15 @@ FOR SELECT USING (
 Monitor permission checks for security:
 
 ```tsx
+import { getRBACLogger } from '@jmruthers/pace-core/rbac';
+
 // Enable audit trail in development
 const { getAuditTrail } = usePermissionCache();
+const rbacLogger = getRBACLogger();
 
 // Log permission decisions
 const auditTrail = getAuditTrail();
-console.log('Permission audit:', auditTrail);
+rbacLogger.debug('Permission audit:', auditTrail);
 ```
 
 ## Best Practices
@@ -743,12 +746,15 @@ setupRBAC(supabase);
 Enable debug logging to troubleshoot permission issues:
 
 ```tsx
+import { getRBACLogger } from '@jmruthers/pace-core/rbac';
+
 // Add to your app for debugging
 const { getDebugInfo } = usePermissionCache();
+const rbacLogger = getRBACLogger();
 
 // Log debug information
 const debugInfo = getDebugInfo();
-console.log('Permission debug:', debugInfo);
+rbacLogger.debug('Permission debug:', debugInfo);
 ```
 
 ## 🎯 **Pattern Selection Guide**