@jmruthers/pace-core 0.5.180 → 0.5.182

package/docs/implementation-guides/component-styling.md

@@ -1,7 +1,7 @@
 ---
-lastUpdated: 2025-10-29T22:43:00+11:00
-version: 0.5.76
-reviewedBy: content-audit
+lastUpdated: 2025-11-18T14:00:00+11:00
+version: 0.5.181
+reviewedBy: documentation-standards-audit
 ---
 
 # Component Styling Guide
@@ -413,4 +413,54 @@ function DashboardCard({ title, children }) {
 
 ---
 
+## ♿ Accessibility
+
+Component styling maintains accessibility standards:
+
+- **Color Contrast** - All custom colors should meet WCAG 2.1 AA contrast requirements
+- **Focus Indicators** - Custom styles should not remove or obscure focus indicators
+- **Screen Reader Support** - Styling changes don't affect screen reader functionality
+- **High Contrast Mode** - Custom styles work with system high contrast settings
+
+### Accessibility Best Practices
+
+1. **Test color contrast** - Ensure all color combinations meet WCAG standards
+2. **Preserve focus indicators** - Don't remove or hide focus styles
+3. **Test with high contrast mode** - Verify styles work with system accessibility settings
+4. **Maintain semantic structure** - Don't use styling to convey information alone
+
+## ⚠️ Edge Cases
+
+### Theme Application Failures
+
+When theme application fails:
+- System falls back to default theme
+- Errors are logged to console in development
+- Components remain functional with default styles
+- Clear error messages guide recovery
+
+### CSS Conflicts
+
+When custom styles conflict with component styles:
+- Component styles take precedence for functionality
+- Custom styles can override with `!important` when needed
+- Clear documentation explains style precedence
+- No breaking changes to component functionality
+
+### Missing Design Tokens
+
+When required design tokens are missing:
+- System falls back to default tokens
+- Components remain functional
+- Clear warnings indicate missing tokens
+- Documentation guides token setup
+
+### Browser Compatibility
+
+When styles don't work in certain browsers:
+- System provides fallback styles
+- Progressive enhancement ensures functionality
+- Clear documentation explains browser support
+- Graceful degradation maintains usability
+
 **Next Steps**: Start customizing components to match your brand while maintaining design system consistency.

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

@@ -1,7 +1,7 @@
 ---
-lastUpdated: 2025-10-29T22:43:00+11:00
-version: 0.5.76
-reviewedBy: content-audit
+lastUpdated: 2025-11-18T14:00:00+11:00
+version: 0.5.181
+reviewedBy: documentation-standards-audit
 ---
 
 # DataTable Implementation Guide
@@ -66,13 +66,13 @@ const columns: DataTableColumn<User>[] = [
     accessorKey: 'name',
     header: 'Name',
     sortable: true,
-    features: { search: true },
+    searchable: true,  // Include this column in global search
   },
   {
     accessorKey: 'email',
     header: 'Email',
     sortable: true,
-    features: { search: true },
+    searchable: true,  // Include this column in global search
   },
   {
     accessorKey: 'role',
@@ -2356,7 +2356,6 @@ Enable debug logging for DataTable issues:
 <UnifiedAuthProvider 
   supabaseClient={supabase}
   appName="your-app"
-  enableRBAC={true}
   debug={true}  // Enable debug logging
 >
   <YourApp />
@@ -2540,8 +2539,78 @@ DataTable
 - **60fps scrolling** performance guaranteed
 - **< 10ms search times** for indexed fields
 
+## ♿ Accessibility
+
+The DataTable component is designed with accessibility in mind and meets WCAG 2.1 AA standards:
+
+- **Keyboard Navigation** - Full keyboard support for all interactive elements (sorting, filtering, pagination, row selection)
+- **Screen Reader Support** - Proper ARIA labels and roles for all table elements
+- **Focus Management** - Logical tab order and visible focus indicators
+- **Semantic HTML** - Uses proper `<table>`, `<thead>`, `<tbody>`, `<th>`, `<td>` elements
+- **Color Contrast** - All text meets WCAG contrast requirements
+- **Responsive Design** - Works with screen readers and assistive technologies
+
+### Accessibility Features
+
+1. **ARIA Labels** - All interactive elements have descriptive ARIA labels
+2. **Row Headers** - Column headers are properly associated with data cells
+3. **Sort Indicators** - Visual and text indicators for sort direction
+4. **Loading States** - Loading indicators are announced to screen readers
+5. **Error Messages** - Error states are properly announced
+6. **Keyboard Shortcuts** - Common operations accessible via keyboard
+
+### Accessibility Best Practices
+
+1. **Use semantic column headers** - Ensure headers clearly describe column content
+2. **Provide alt text for images** - Any images in cells should have alt text
+3. **Test with screen readers** - Verify table is navigable with screen readers
+4. **Maintain focus visibility** - Ensure focus indicators are visible
+5. **Use proper heading hierarchy** - Use appropriate heading levels for table context
+
+## ⚠️ Edge Cases
+
+### Empty Data Sets
+
+When no data is available:
+- Table displays "No data" message
+- All features remain functional (search, filters, etc.)
+- Empty state is announced to screen readers
+- Custom empty state can be provided via `emptyState` prop
+
+### Very Large Datasets
+
+When handling 100,000+ records:
+- Virtualization is automatically enabled
+- Server-side pagination is recommended
+- Memory usage is monitored and optimized
+- Performance metrics help identify bottlenecks
+
+### Rapid Data Updates
+
+When data changes frequently:
+- Table handles updates gracefully
+- Selection state is preserved when possible
+- Sorting and filtering are recalculated efficiently
+- Performance optimizations prevent UI lag
+
+### Concurrent User Actions
+
+When multiple operations occur simultaneously:
+- Operations are queued and processed in order
+- Loading states prevent conflicting actions
+- Error handling ensures data consistency
+- User feedback is provided for all operations
+
+### Network Failures
+
+When network requests fail:
+- Error states are clearly displayed
+- Retry mechanisms are available
+- Partial data is preserved when possible
+- User-friendly error messages are shown
+
 ## Conclusion
 
 The PACE Core DataTable provides enterprise-grade functionality with comprehensive features for data management, RBAC integration, hierarchical data display, advanced filtering, and performance optimization. With automatic performance tuning, intelligent pagination modes, advanced search indexing, and memory management, it can handle datasets from hundreds to hundreds of thousands of records while maintaining excellent user experience.
 
-The implementation includes extensive testing, performance monitoring, and backward compatibility, making it a powerful tool for building data-rich applications with PACE Core.
+The implementation includes extensive testing, performance monitoring, backward compatibility, and full accessibility support, making it a powerful tool for building data-rich applications with PACE Core.

package/docs/implementation-guides/datatable-filtering.md

@@ -285,7 +285,6 @@ Enable debug logging to see filter behavior:
 <UnifiedAuthProvider 
   supabaseClient={supabase}
   appName="your-app"
-  enableRBAC={true}
   debug={true}  // Enable debug logging
 >
   <YourApp />
@@ -303,7 +302,7 @@ Enable debug logging to see filter behavior:
 
 ## Migration from Old Filtering
 
-If you're upgrading from an older version:
+If you're upgrading from an older version: 0.5.181
 
 1. **Replace `meta.filterOptions`** with `filterSelectOptions`
 2. **Add `filterType: 'select'`** for explicit select filters

package/docs/implementation-guides/datatable-rbac-usage.md

@@ -218,7 +218,6 @@ Enable debug logging to see permission checks:
 <UnifiedAuthProvider 
   supabaseClient={supabase}
   appName="your-app"
-  enableRBAC={true}
   debug={true}  // Enable debug logging
 >
   <YourApp />

package/docs/implementation-guides/dynamic-colors.md

@@ -1,7 +1,7 @@
 ---
-lastUpdated: 2025-10-29T22:43:00+11:00
-version: 0.5.76
-reviewedBy: content-audit
+lastUpdated: 2025-11-18T14:00:00+11:00
+version: 0.5.181
+reviewedBy: documentation-standards-audit
 ---
 
 # Dynamic Theming
@@ -228,6 +228,101 @@ function App() {
 - **Performance Optimized** - Minimal DOM updates
 - **Type Safe** - Full TypeScript support
 
+## Event Theming
+
+### Overview
+
+Event theming allows you to automatically apply event-specific colors when an event is selected. The system uses the `event_colours` JSONB field in the events table to store theme colors.
+
+### Database Schema
+
+Events have an `event_colours` JSONB field that stores theme colors in OKLCH format:
+
+```typescript
+interface Event {
+  event_colours?: Record<string, unknown> | null; // JSONB field for theme colors
+}
+```
+
+The expected format:
+```json
+{
+  "main": {
+    "50": {"L": 0.98, "C": 0.007, "H": 29.203},
+    "100": {"L": 0.96, "C": 0.018, "H": 29.203},
+    // ... all Tailwind shades 50-950
+    "raw": {"L": 0.587, "C": 0.24, "H": 29.203}
+  },
+  "sec": { /* secondary palette */ },
+  "acc": { /* accent palette */ }
+}
+```
+
+### Automatic Event Theming
+
+The `useEventTheme()` hook automatically applies event colors when an event is selected:
+
+```tsx
+import { useEventTheme } from '@jmruthers/pace-core';
+
+function MyApp() {
+  useEventTheme(); // Automatically applies event colors
+  
+  return <div>Your app content</div>;
+}
+```
+
+### How It Works
+
+1. **ADMIN app** sets event colors via a palette picker and saves to `event.event_colours` in the database
+2. **Consuming apps** (CAKE, TRACE) call `useEventTheme()` hook
+3. When user selects an event via `EventSelector`, the hook detects the change
+4. Hook extracts `event_colours` from selected event
+5. Hook calls `applyPalette()` with the colors
+6. CSS variables update dynamically → UI colors change
+7. When event is deselected, hook calls `clearPalette()`
+
+### Architecture Decision
+
+**What's in pace-core:**
+- ✅ Event theming infrastructure (runtime APIs)
+- ✅ Automatic event theming hook (`useEventTheme`)
+- ✅ Documentation and examples
+- ✅ Type definitions
+
+**What's in consuming apps:**
+- ✅ Calling `useEventTheme()` in the app component
+- ✅ ADMIN app: Palette picker UI to set colors
+- ✅ ADMIN app: Save colors to database via `event_colours` field
+
+### Migration Guide
+
+If you're already manually applying event colors in your consuming apps:
+
+**Before:**
+```tsx
+function App() {
+  const { selectedEvent } = useEvents();
+  
+  useEffect(() => {
+    if (selectedEvent?.event_colours) {
+      applyPalette(selectedEvent.event_colours);
+    } else {
+      clearPalette();
+    }
+  }, [selectedEvent]);
+}
+```
+
+**After:**
+```tsx
+function App() {
+  useEventTheme(); // Replaces the above useEffect
+  
+  return <div>Your app</div>;
+}
+```
+
 ## Troubleshooting
 
 ### Colors Not Applying
@@ -240,7 +335,63 @@ function App() {
 - Check that all required shades (50-950) are provided
 - Use `isDynamicThemingActive()` to debug
 
+### Event Theming Not Working
+- Ensure `useEventTheme()` is called at the top level of your app
+- Verify event has `event_colours` field populated
+- Check that EventProvider is properly set up
+- Verify event selection is working correctly
+
 ### SSR Issues
 - Ensure `generateSSRThemeCSS()` is called on server
 - Verify CSS is injected into HTML head
-- Check for hydration mismatches 
+- Check for hydration mismatches
+
+## ♿ Accessibility
+
+The dynamic theming system maintains accessibility standards:
+
+- **Color Contrast** - All theme colors should meet WCAG 2.1 AA contrast requirements
+- **Color Independence** - Information is not conveyed by color alone
+- **High Contrast Mode** - Theme colors work with system high contrast settings
+- **Screen Reader Support** - Theme changes don't affect screen reader functionality
+
+### Accessibility Best Practices
+
+1. **Test color contrast** - Ensure all color combinations meet WCAG standards
+2. **Provide alternative indicators** - Don't rely solely on color to convey information
+3. **Test with high contrast mode** - Verify themes work with system accessibility settings
+4. **Maintain readability** - Ensure text remains readable with all theme variations
+
+## ⚠️ Edge Cases
+
+### Missing Palette Data
+
+When palette data is incomplete or missing:
+- `applyPalette()` validates palette structure before applying
+- Missing shades default to nearest available shade
+- Invalid OKLCH values are rejected with error messages
+- System falls back to default app colors if validation fails
+
+### Theme Application Failures
+
+When theme application fails:
+- Errors are logged to console in development mode
+- System gracefully falls back to default colors
+- `isDynamicThemingActive()` returns false on failure
+- `getCurrentThemeData()` returns null if no theme is active
+
+### Event Theme Conflicts
+
+When multiple events are selected:
+- Latest event theme takes precedence
+- Previous themes are automatically cleared
+- `useEventTheme()` handles cleanup automatically
+- No manual intervention required
+
+### SSR/CSR Mismatches
+
+When server and client themes differ:
+- SSR theme is applied first, then client theme updates
+- Hydration mismatches are avoided by applying theme early
+- `generateSSRThemeCSS()` ensures consistent initial render
+- Client-side theme updates are applied after hydration

package/docs/implementation-guides/file-reference-system.md

@@ -1,7 +1,7 @@
 ---
-lastUpdated: 2025-11-01T14:58:00+11:00
-version: 0.5.102
-reviewedBy: content-audit
+lastUpdated: 2025-11-18T14:00:00+11:00
+version: 0.5.181
+reviewedBy: documentation-standards-audit
 ---
 
 # File Reference System
@@ -1048,6 +1048,75 @@ Run the cleanup migration (if applicable):
 - Remove manual URL generation code
 - Remove deprecated RPC function calls
 
+## ♿ Accessibility
+
+The File Reference System components are designed with accessibility in mind:
+
+- **WCAG 2.1 AA compliant** - All file management components meet accessibility standards
+- **Keyboard Navigation** - Full keyboard support for file operations
+- **Screen Reader Support** - Proper ARIA labels for file uploads and displays
+- **Focus Management** - Logical tab order for file management interfaces
+- **Error Announcements** - File upload errors are properly announced
+- **Loading States** - Upload progress is accessible and announced
+
+### Accessibility Best Practices
+
+1. **Provide alt text for file previews** - All file previews should have descriptive alt text
+2. **Label file inputs clearly** - Use proper labels for file upload inputs
+3. **Announce upload progress** - Use ARIA live regions for upload status
+4. **Test with screen readers** - Verify file operations work with assistive technologies
+5. **Ensure keyboard access** - All file management actions should be keyboard accessible
+
+## ⚠️ Edge Cases
+
+### Large File Uploads
+
+When uploading very large files:
+- Progress indicators show upload status
+- Network failures can be retried
+- Partial uploads are handled gracefully
+- File size validation prevents oversized uploads
+
+### Storage Quota Exceeded
+
+When storage quota is exceeded:
+- Clear error messages explain the issue
+- Users are notified of quota limits
+- File operations fail gracefully
+- Alternative storage options can be suggested
+
+### Orphaned Files
+
+When files become orphaned (record deleted but file remains):
+- Audit functions identify orphaned files
+- Cleanup utilities help manage orphaned files
+- Storage costs are minimized through cleanup
+- Files can be safely deleted after verification
+
+### Network Failures During Upload
+
+When network fails during file upload:
+- Upload progress is preserved when possible
+- Retry mechanisms are available
+- Partial uploads are cleaned up automatically
+- User-friendly error messages guide recovery
+
+### Invalid File Types
+
+When invalid file types are uploaded:
+- File type validation prevents invalid uploads
+- Clear error messages explain allowed types
+- File type detection is automatic
+- User guidance helps select correct files
+
+### Concurrent File Operations
+
+When multiple file operations occur simultaneously:
+- Operations are queued and processed in order
+- File conflicts are handled gracefully
+- User feedback is provided for all operations
+- Data consistency is maintained
+
 ## Support
 
 For issues or questions about the File Reference System:

package/docs/implementation-guides/file-upload-storage.md

@@ -1,7 +1,7 @@
 ---
-lastUpdated: 2025-10-29T22:43:00+11:00
-version: 0.5.76
-reviewedBy: content-audit
+lastUpdated: 2025-11-18T14:00:00+11:00
+version: 0.5.181
+reviewedBy: documentation-standards-audit
 ---
 
 # File Upload & Storage System
@@ -811,6 +811,75 @@ setRBACConfig({
 });
 ```
 
+## ♿ Accessibility
+
+File upload and storage components are designed with accessibility in mind:
+
+- **WCAG 2.1 AA compliant** - All file components meet accessibility standards
+- **Keyboard Navigation** - Full keyboard support for drag-and-drop and file selection
+- **Screen Reader Support** - Proper ARIA labels for file upload areas and file lists
+- **Focus Management** - Logical tab order for file management interfaces
+- **Error Announcements** - Upload errors are properly announced to screen readers
+- **Progress Indicators** - Upload progress is accessible and announced
+
+### Accessibility Best Practices
+
+1. **Label file inputs clearly** - Use descriptive labels for file upload inputs
+2. **Provide keyboard alternatives** - Ensure drag-and-drop has keyboard equivalents
+3. **Announce upload status** - Use ARIA live regions for upload progress
+4. **Test with screen readers** - Verify file operations work with assistive technologies
+5. **Ensure focus visibility** - File upload areas should have visible focus indicators
+
+## ⚠️ Edge Cases
+
+### File Upload Failures
+
+When file uploads fail:
+- Clear error messages explain the failure
+- Retry mechanisms are available
+- Partial uploads are cleaned up
+- User guidance helps resolve issues
+
+### Storage Quota Exceeded
+
+When storage quota is exceeded:
+- Error messages clearly explain the issue
+- Users are notified of quota limits
+- File operations fail gracefully
+- Alternative solutions can be suggested
+
+### Invalid File Types
+
+When invalid file types are selected:
+- File type validation prevents invalid uploads
+- Clear error messages explain allowed types
+- File type detection is automatic
+- User guidance helps select correct files
+
+### Large File Uploads
+
+When uploading very large files:
+- Progress indicators show upload status
+- Network failures can be retried
+- Partial uploads are handled gracefully
+- File size validation prevents oversized uploads
+
+### Concurrent File Operations
+
+When multiple file operations occur simultaneously:
+- Operations are queued and processed in order
+- File conflicts are handled gracefully
+- User feedback is provided for all operations
+- Data consistency is maintained
+
+### Network Interruptions
+
+When network is interrupted during upload:
+- Upload progress is preserved when possible
+- Automatic retry mechanisms are available
+- Partial uploads are cleaned up
+- User-friendly error messages guide recovery
+
 ## Next Steps
 
 - **[Storage Utilities](../api-reference/utilities.md#storage)** - Additional storage utilities

package/docs/implementation-guides/forms.md

@@ -1,7 +1,7 @@
 ---
-lastUpdated: 2025-10-29T22:43:00+11:00
-version: 0.5.76
-reviewedBy: content-audit
+lastUpdated: 2025-11-18T14:00:00+11:00
+version: 0.5.181
+reviewedBy: documentation-standards-audit
 ---
 
 # Forms
@@ -568,4 +568,54 @@ function FormDebugger() {
 }
 ```
 
+## ⚠️ Edge Cases
+
+### Form Submission Failures
+
+When form submission fails:
+- Error messages are clearly displayed
+- Form data is preserved (not lost)
+- Retry mechanisms are available
+- User-friendly error messages guide recovery
+
+### Network Interruptions
+
+When network is interrupted during submission:
+- Form state is preserved
+- Partial submissions are prevented
+- Clear error messages explain the issue
+- Retry mechanisms are available
+
+### Validation Race Conditions
+
+When validation occurs during rapid input:
+- Validation is debounced to prevent conflicts
+- Latest validation results are used
+- No flickering or inconsistent states
+- Smooth user experience maintained
+
+### Large Form Data
+
+When forms contain large amounts of data:
+- Performance remains optimal
+- Validation is efficient
+- Memory usage is managed
+- No degradation with large datasets
+
+### Concurrent Form Submissions
+
+When multiple submissions occur:
+- Duplicate submissions are prevented
+- Loading states prevent conflicts
+- Error handling ensures data consistency
+- User feedback is provided for all operations
+
+### Browser Back/Forward Navigation
+
+When users navigate back/forward:
+- Form state is preserved when possible
+- Validation errors are maintained
+- User data is not lost
+- Smooth navigation experience
+
 For more advanced form patterns and examples, see the [Form Examples](../examples/forms.md) guide.

package/docs/implementation-guides/inactivity-tracking.md

@@ -1,7 +1,7 @@
 ---
-lastUpdated: 2025-10-29T22:43:00+11:00
-version: 0.5.76
-reviewedBy: content-audit
+lastUpdated: 2025-11-18T14:00:00+11:00
+version: 0.5.181
+reviewedBy: documentation-standards-audit
 ---
 
 # Inactivity Tracking
@@ -777,6 +777,56 @@ const secure = useInactivityTracker({
 });
 ```
 
+## ⚠️ Edge Cases
+
+### Multiple Tab Sessions
+
+When users have multiple tabs open:
+- Activity is synchronized across all tabs via BroadcastChannel
+- Inactivity warnings appear in all tabs simultaneously
+- Logout in one tab logs out all tabs
+- Activity in any tab resets the timer for all tabs
+
+### Browser Tab Switching
+
+When users switch between browser tabs:
+- Activity tracking continues in background tabs
+- Warnings are shown when user returns to the tab
+- Focus management ensures warnings are visible
+- Timer continues counting even when tab is inactive
+
+### Network Failures
+
+When network fails during inactivity tracking:
+- Local tracking continues to work
+- Warnings are still shown
+- Logout callbacks are executed
+- Cross-tab sync may be delayed until network recovers
+
+### Rapid Activity Changes
+
+When user activity changes rapidly:
+- Event throttling prevents excessive updates
+- Timer resets are debounced for performance
+- Warning states are managed efficiently
+- No performance degradation with rapid changes
+
+### Browser Storage Limitations
+
+When browser storage is limited or disabled:
+- System gracefully degrades to single-tab mode
+- Cross-tab sync may not work
+- Local tracking continues to function
+- Clear error messages explain limitations
+
+### Session Extension During Warning
+
+When user extends session during warning:
+- Timer is immediately reset
+- Warning modal is closed
+- Activity tracking resumes
+- No interruption to user workflow
+
 ## Next Steps
 
 - **[Authentication Integration](./permission-enforcement.md)** - Security patterns