@jmruthers/pace-core 0.5.181 → 0.5.183

package/docs/api-reference/components.md

@@ -1,7 +1,7 @@
 ---
-lastUpdated: 2025-10-29T22:43:00+11:00
-version: 0.5.76
-reviewedBy: content-audit
+lastUpdated: 2025-11-18T12:00:00+11:00
+version: 0.5.181
+reviewedBy: documentation-standards-audit
 ---
 
 # Components API Reference
@@ -29,6 +29,8 @@ interface ButtonProps extends React.ButtonHTMLAttributes<HTMLButtonElement> {
 
 ```tsx
 import { Button } from '@jmruthers/pace-core';
+import { Link } from 'react-router-dom'; // or your routing library
+import { Settings } from 'lucide-react'; // for icon example
 
 // Default button
 <Button onClick={handleClick}>
@@ -67,6 +69,102 @@ import { Button } from '@jmruthers/pace-core';
 - **lg**: Large button (h-10 px-8)
 - **icon**: Square icon button (h-8 w-8)
 
+### Accessibility
+
+- **Keyboard Navigation**: Fully keyboard accessible. Use `Enter` or `Space` to activate.
+- **ARIA Attributes**: Supports all standard ARIA attributes via `React.ButtonHTMLAttributes`.
+- **Disabled State**: When disabled, button is not focusable and has `aria-disabled="true"`.
+- **Icon Buttons**: Always provide `aria-label` for icon-only buttons for screen readers.
+- **Focus Management**: Visible focus indicators via `focus-visible` styles.
+- **Screen Readers**: Button text is automatically announced. Use descriptive labels.
+
+### Edge Cases
+
+- **asChild Prop**: When using `asChild`, the button renders as the child element (e.g., `<Link>`). The `type` attribute is not applied in this case.
+- **Disabled State**: Disabled buttons cannot be clicked and are excluded from keyboard navigation.
+- **Loading States**: For loading states, combine with `disabled` prop and show loading indicator as children.
+- **Form Submission**: Use `type="submit"` for form submission buttons. Default is `type="button"`.
+- **Composition**: When composing with other components via `asChild`, ensure child element supports button-like behavior.
+
+### ButtonGroup
+
+A component that groups multiple buttons together with consistent styling and spacing.
+
+#### Props
+
+```typescript
+interface ButtonGroupProps {
+  children: React.ReactNode;
+  orientation?: 'horizontal' | 'vertical';
+  variant?: 'default' | 'outline' | 'ghost';
+  size?: 'sm' | 'default' | 'lg';
+  className?: string;
+  spacing?: 'none' | 'sm' | 'md' | 'lg';
+}
+```
+
+#### Usage
+
+```tsx
+import { Button } from '@jmruthers/pace-core';
+import { ButtonGroup } from '@jmruthers/pace-core/components';
+
+// Horizontal button group
+<ButtonGroup variant="outline" spacing="md">
+  <Button>Cancel</Button>
+  <Button variant="default">Save</Button>
+</ButtonGroup>
+
+// Vertical button group
+<ButtonGroup orientation="vertical" spacing="lg">
+  <Button>Option 1</Button>
+  <Button>Option 2</Button>
+  <Button>Option 3</Button>
+</ButtonGroup>
+```
+
+#### Features
+
+- Automatically applies variant and size to child Button components
+- Configurable spacing between buttons
+- Supports horizontal and vertical orientations
+- Uses `role="group"` for accessibility
+
+### IconButton
+
+A button component specifically designed for icon-only interactions with built-in tooltip support.
+
+#### Props
+
+```typescript
+interface IconButtonProps extends Omit<ButtonProps, 'children'> {
+  icon: React.ReactNode;
+  'aria-label': string; // Required for accessibility
+  tooltip?: string;
+}
+```
+
+#### Usage
+
+```tsx
+import { IconButton } from '@jmruthers/pace-core/components';
+import { Settings } from 'lucide-react';
+
+<IconButton 
+  icon={<Settings />} 
+  aria-label="Settings"
+  tooltip="Open settings"
+  onClick={handleClick} 
+/>
+```
+
+#### Accessibility
+
+- **Required aria-label**: IconButton requires an `aria-label` prop for screen readers
+- **Tooltip Support**: Optional tooltip provides additional context on hover
+- **Keyboard Accessible**: Fully keyboard accessible like standard Button
+- **Focus Indicators**: Visible focus indicators for keyboard navigation
+
 ## DataTable
 
 A comprehensive, enterprise-grade data table with advanced features and performance optimizations.
@@ -106,6 +204,9 @@ interface DataTableProps<TData extends DataRecord> {
   data: TData[];
   columns: (DataTableColumn<TData> | SimpleColumn<TData>)[];
   
+  // MANDATORY RBAC - REQUIRED for all DataTables
+  rbac: DataTableRBACConfig;
+  
   // Display
   title?: string;
   description?: string;
@@ -115,8 +216,8 @@ interface DataTableProps<TData extends DataRecord> {
   // Column ordering
   columnOrder?: string[];
   
-  // Feature configuration (required)
-  features: DataTableFeatureConfig;
+  // Feature configuration (optional - all features disabled by default)
+  features?: DataTableFeatureConfig;
   
   // Event handlers
   onEditRow?: (row: TData, data: Partial<TData>) => void;
@@ -130,18 +231,44 @@ interface DataTableProps<TData extends DataRecord> {
    */
   onExport?: (options: ExportOptions<TData>) => void | Promise<void>;
   onDeleteSelected?: (selectedRows: Record<string, boolean>) => void;
+  onRowSelectionChange?: (selection: Record<string, boolean>) => void;
+  selection?: Record<string, boolean>;
   
   // Performance
   performance?: PerformanceConfig;
   serverSide?: ServerSideConfig<TData>;
+  paginationMode?: PaginationMode;
+  chunking?: ChunkingConfig;
+  searchIndex?: SearchIndexConfig;
+  initialPageSize?: number;
   isLoading?: boolean;
   
   // Utilities
   getRowId?: GetRowId<TData>;
-  emptyState?: EmptyStateConfig;
+  emptyState?: EmptyStateConfig | React.ReactElement;
+  aggregates?: AggregateConfig[];
+  importModalConfig?: ImportModalConfig;
   
   // Hierarchical configuration
   hierarchical?: HierarchicalConfig;
+  
+  // Default state configuration
+  defaultGrouping?: string[];
+  defaultSorting?: Array<{ id: string; desc: boolean }>;
+  
+  // Persistence configuration
+  storageKey?: string;
+  onLayoutChange?: (layout: { columnOrder: string[]; columnVisibility: Record<string, boolean> }) => void;
+  
+  // Enhanced pagination
+  enhancedPagination?: boolean;
+  
+  // Custom components
+  loadingComponent?: React.ComponentType;
+  errorComponent?: React.ComponentType<{ error: Error; retry: () => void }>;
+  
+  // Virtual scrolling
+  virtualHeight?: number;
 }
 ```
 
@@ -819,6 +946,8 @@ A flexible card component suite for displaying content with consistent styling a
 
 ```typescript
 interface CardProps extends React.HTMLAttributes<HTMLElement> {
+  variant?: 'default' | 'outline' | 'ghost';
+  size?: 'default' | 'sm' | 'lg';
   className?: string;
 }
 
@@ -878,14 +1007,39 @@ import {
 </Card>
 ```
 
+### Variants
+
+- **default**: Standard card with shadow (shadow-xl)
+- **outline**: Card with prominent border (border-2)
+- **ghost**: Card without border or shadow (border-0 shadow-none)
+
+### Sizes
+
+- **default**: Standard card size
+- **sm**: Small card with smaller text (text-sm)
+- **lg**: Large card with larger text (text-lg)
+
 ### Semantic Structure
 
 - **Card**: `<article>` element for self-contained content
 - **CardHeader**: `<header>` element for card heading area
-- **CardContent**: `<div>` element for primary card content
+- **CardContent**: `<main>` element for primary card content
 - **CardFooter**: `<footer>` element for card footer area
 - **CardActions**: `<nav>` element for action buttons
 
+### Accessibility
+
+- **Semantic HTML**: Uses proper semantic elements (`<article>`, `<header>`, `<main>`, `<footer>`, `<nav>`) for screen readers
+- **Keyboard Navigation**: All interactive elements within cards are keyboard accessible
+- **Focus Management**: Proper focus indicators on interactive card content
+- **Screen Readers**: Semantic structure provides clear content hierarchy
+
+### Edge Cases
+
+- **Nested Cards**: CardContent uses `<main>` element which should only appear once per page. When nesting cards, consider using a different structure.
+- **Empty Cards**: Cards can be empty or contain only header/footer without content
+- **Variant Combinations**: Variant and size props work independently and can be combined
+
 ## LoadingSpinner
 
 A simple, accessible loading spinner component for indicating loading states.
@@ -927,10 +1081,27 @@ import { LoadingSpinner } from '@jmruthers/pace-core';
 
 ### Features
 
-- **Accessibility**: WCAG 2.1 AA compliant with proper ARIA attributes
-- **Reduced Motion**: Supports users with vestibular disorders
-- **Screen Reader**: Announces "Loading..." to screen readers
-- **Performance**: CSS-only animations for optimal performance
+- Multiple size variants (sm, md, lg)
+- Smooth CSS animations with reduced motion support
+- Screen reader friendly with proper ARIA attributes
+- Customizable styling via className
+- Lightweight and performant (CSS-only animations)
+
+### Accessibility
+
+- **ARIA Role**: Uses `role="status"` for screen reader announcement
+- **Screen Reader Text**: Includes "Loading..." text for screen readers (visually hidden)
+- **Reduced Motion**: Respects `prefers-reduced-motion` media query for users with vestibular disorders
+- **High Contrast**: Works with high contrast mode
+- **Focus Management**: Non-interactive element, no focus concerns
+
+### Edge Cases
+
+- **Multiple Spinners**: Can be used multiple times on the same page without conflicts
+- **Nested Usage**: Safe to nest within buttons, cards, or other components
+- **Custom Styling**: className prop allows full customization while maintaining accessibility
+- **Size Variants**: Default size is 'md' if not specified
+- **Animation Performance**: CSS-only animations ensure smooth performance even with multiple spinners
 
 ## Toast
 
@@ -1159,7 +1330,7 @@ interface NavigationMenuProps {
   auditLog?: boolean;
   onNavigationAccessDenied?: (itemId: string, reason: string) => void;
   onStrictModeViolation?: (itemId: string, reason: string) => void;
-  filterByPermissions?: boolean;
+  // filterByPermissions prop removed - permission filtering is always enabled
 }
 
 interface NavigationItem {
@@ -1250,7 +1421,7 @@ function AuthenticatedNavigation() {
       currentPath={location.pathname}
       onNavigate={(item) => navigate(item.href)}
       buttonText="Navigation"
-      filterByPermissions={true}
+      // Permission filtering is always enabled
       auditLog={true}
     />
   );
@@ -1786,7 +1957,7 @@ function EventHeader({ eventId }: { eventId: string }) {
 }
 ```
 
-For detailed implementation, see [Public Pages Advanced Guide](../implementation-guides/public-pages-advanced.md).
+For detailed implementation, see [Public Pages Guide](../implementation-guides/public-pages.md#advanced-topics).
 
 ## Component Styling
 
@@ -1808,7 +1979,7 @@ All components include:
 - **Visual Tests**: Visual regression testing
 - **Performance Tests**: Rendering performance
 
-For more information about testing components, see the [Testing Guide](../best-practices/testing.md).
+For more information about testing components, see the [Testing Guide](../testing/README.md).
 
 ## Avatar
 

package/docs/api-reference/deprecated.md

@@ -0,0 +1,376 @@
+---
+lastUpdated: 2025-11-18T12:00:00+11:00
+version: 0.5.181
+reviewedBy: documentation-standards-audit
+---
+
+# Deprecated API Reference
+
+This document lists all deprecated APIs in `@jmruthers/pace-core` and provides migration paths. Deprecated items follow a 2-release retirement window as per the [API & RPC Standard](../standards/02-api-and-rpc-standard.md).
+
+## Deprecation Policy
+
+- **Retirement Window**: 2 stable releases
+- **Marking**: Items are marked with `@deprecated` JSDoc tags
+- **Documentation**: Migration paths are provided below
+- **Timeline**: Check package version for removal timeline
+
+## Component Deprecations
+
+### ProtectedRoute.allowSuperAdminBypass
+
+**Status**: Deprecated  
+**Since**: v0.5.x  
+**Removal**: v0.7.x
+
+**Deprecated Prop**:
+```typescript
+interface ProtectedRouteProps {
+  /**
+   * @deprecated Use requireEvent={false} for routes that don't need events
+   */
+  allowSuperAdminBypass?: boolean;
+}
+```
+
+**Migration**:
+```tsx
+// Old
+<ProtectedRoute allowSuperAdminBypass={true}>
+  <Route path="/settings" element={<SettingsPage />} />
+</ProtectedRoute>
+
+// New
+<ProtectedRoute requireEvent={false}>
+  <Route path="/settings" element={<SettingsPage />} />
+</ProtectedRoute>
+```
+
+### PublicPageLayout.className
+
+**Status**: Deprecated  
+**Since**: v0.5.x  
+**Removal**: v0.7.x
+
+**Reason**: Wrapper div was removed from PublicPageLayout component.
+
+**Deprecated Prop**:
+```typescript
+interface PublicPageLayoutProps {
+  /**
+   * @deprecated Custom CSS classes for the layout - no longer used as wrapper div was removed
+   */
+  className?: string;
+}
+```
+
+**Migration**: Remove `className` prop usage. Use custom header/footer components for styling:
+```tsx
+// Old
+<PublicPageLayout className="custom-layout" eventCode={eventCode}>
+
+// New
+<PublicPageLayout 
+  eventCode={eventCode}
+  customHeader={<CustomHeader className="custom-layout" />}
+>
+```
+
+### usePublicPageContext Hook
+
+**Status**: Deprecated  
+**Since**: v0.5.x  
+**Removal**: v0.7.x
+
+**Location**: `packages/core/src/components/PublicLayout/PublicPageLayout.tsx`
+
+**Deprecated Hook**:
+```typescript
+/**
+ * @deprecated This hook is no longer needed as PublicPageLayout no longer
+ * automatically fetches event data. Use usePublicRouteParams and usePublicEvent
+ * directly in your components instead.
+ */
+export function usePublicPageContext()
+```
+
+**Migration**: Use `usePublicRouteParams` and `usePublicEvent` hooks directly:
+```tsx
+// Old
+import { usePublicPageContext } from '@jmruthers/pace-core';
+const { event, eventCode, isLoading } = usePublicPageContext();
+
+// New
+import { usePublicRouteParams, usePublicEvent } from '@jmruthers/pace-core';
+const { eventCode } = usePublicRouteParams({ fetchEventData: false });
+const { event, isLoading } = usePublicEvent(eventCode || '');
+```
+
+## Hook Deprecations
+
+### usePermissionCache
+
+**Status**: Deprecated  
+**Since**: v0.4.x  
+**Removal**: v0.6.x
+
+**Location**: `packages/core/src/hooks/usePermissionCache.ts`
+
+**Deprecated Hook**:
+```typescript
+/**
+ * @deprecated Consider using useCan() or usePermissions() hooks directly instead.
+ */
+export function usePermissionCache(...)
+```
+
+**Migration**:
+```tsx
+// Old
+import { usePermissionCache } from '@jmruthers/pace-core';
+
+// New - Use RBAC hooks directly
+import { useCan, usePermissions } from '@jmruthers/pace-core/rbac';
+
+const { hasPermission } = useCan();
+const { permissions } = usePermissions({ userId, scope });
+```
+
+## Utility Deprecations
+
+### sanitizeUserInput (from validationUtils)
+
+**Status**: Deprecated  
+**Since**: v0.5.x  
+**Removal**: v0.7.x
+
+**Location**: `packages/core/src/utils/validation/validationUtils.ts`
+
+**Deprecated Function**:
+```typescript
+/**
+ * @deprecated Use sanitizeUserInput from lib/sanitization instead
+ */
+export function sanitizeUserInput(...)
+```
+
+**Migration**:
+```typescript
+// Old
+import { sanitizeUserInput } from '@jmruthers/pace-core/utils/validation/validationUtils';
+
+// New
+import { sanitizeUserInput } from '@jmruthers/pace-core/utils/validation/sanitization';
+```
+
+### sortHierarchicalDataByStructure
+
+**Status**: Deprecated  
+**Since**: v0.5.x  
+**Removal**: v0.7.x
+
+**Location**: `packages/core/src/components/DataTable/utils/hierarchicalUtils.ts`
+
+**Deprecated Function**:
+```typescript
+/**
+ * @deprecated Use sortHierarchicalDataByStructure from hierarchicalSorting.ts
+ */
+export function sortHierarchicalDataByStructure(...)
+```
+
+**Migration**:
+```typescript
+// Old
+import { sortHierarchicalDataByStructure } from './hierarchicalUtils';
+
+// New
+import { sortHierarchicalDataByStructure } from './hierarchicalSorting';
+```
+
+## RBAC Deprecations
+
+### getPermissionsForRole
+
+**Status**: Removed  
+**Since**: v0.4.x  
+**Reason**: Removed to ensure RBAC compliance - permissions must be queried from database
+
+**Deprecated Function**:
+```typescript
+/**
+ * @deprecated This function has been removed to ensure RBAC compliance.
+ */
+export function getPermissionsForRole(role: string): Permission[]
+```
+
+**Migration**: Query permissions from database:
+```typescript
+// Old
+const permissions = getPermissionsForRole('admin');
+
+// New - Query from database
+const { data } = await supabase
+  .from('rbac_page_permissions')
+  .select('operation, allowed')
+  .eq('role_name', 'admin')
+  .eq('organisation_id', organisationId)
+  .eq('allowed', true);
+```
+
+## RPC Function Deprecations
+
+### Legacy File Reference RPCs
+
+**Status**: Deprecated  
+**Since**: v0.5.x  
+**Removal**: v0.7.x
+
+**Deprecated Functions**:
+- `insert_file_reference` → Use `data_file_reference_create`
+- `get_file_url` → Use `data_file_reference_url_get`
+- `get_file_signed_url` → Use `data_file_reference_signed_url_get`
+- `delete_file_reference` → Use `data_file_reference_delete`
+- `get_record_files` → Use `data_file_reference_list`
+- `get_record_file_count` → Use `data_file_reference_count_get`
+
+**Migration**: Use the new RPC naming pattern (`data_*` prefix) or use the service layer:
+```typescript
+// Old
+await supabase.rpc('insert_file_reference', { ... });
+
+// New - Direct RPC
+await supabase.rpc('data_file_reference_create', { ... });
+
+// New - Service layer (recommended)
+import { useFileReference } from '@jmruthers/pace-core';
+const { uploadFile } = useFileReference(supabase);
+await uploadFile({ ... }, file);
+```
+
+### Legacy RBAC RPCs
+
+**Status**: Removed  
+**Since**: v0.5.x  
+**Reason**: Replaced with standardized `rbac_*` prefix functions
+
+**Removed Functions**:
+- `get_rbac_permissions` → Use `rbac_permissions_get`
+- `check_page_permission` → Use `rbac_page_access_check` or `rbac_check_permission_simplified`
+- `has_organisation_role` → Use `rbac_role_validate` or query `rbac_user_organisation_roles`
+- `grant_organisation_role` → Use `rbac_role_grant`
+- `revoke_organisation_role` → Use `rbac_role_revoke`
+
+**Migration**:
+```typescript
+// Old
+const { data } = await supabase.rpc('get_rbac_permissions', { ... });
+const { data: hasPermission } = await supabase.rpc('check_page_permission', { ... });
+const { data: roleId } = await supabase.rpc('grant_organisation_role', { ... });
+
+// New
+const { data } = await supabase.rpc('rbac_permissions_get', { ... });
+const { data: hasPermission } = await supabase.rpc('rbac_page_access_check', { ... });
+const { data: roleId } = await supabase.rpc('rbac_role_grant', { ... });
+```
+
+### Legacy Event RPCs
+
+**Status**: Deprecated  
+**Since**: v0.5.x  
+**Removal**: v0.7.x
+
+**Deprecated Functions**:
+- `get_pace_user_events` → Use `data_user_events_get`
+
+**Migration**:
+```typescript
+// Old
+const { data } = await supabase.rpc('get_pace_user_events', {
+  user_uuid: userId,
+  app_name: appName,
+  p_organisation_id: orgId
+});
+
+// New
+const { data, error } = await supabase.rpc('data_user_events_get', {
+  p_user_id: userId,
+  p_app_id: appId, // Use app ID instead of app name
+  p_organisation_id: orgId
+});
+```
+
+### Legacy Data Access RPCs
+
+**Status**: Removed  
+**Since**: v0.5.x  
+**Reason**: Replaced with standardized naming pattern
+
+**Removed Functions**:
+- `data_cake_meals_get` → Use `data_cake_meals_list` (provides pagination support)
+
+**Migration**:
+```typescript
+// Old
+const { data } = await supabase.rpc('data_cake_meals_get', {
+  p_event_id: eventId,
+  p_user_id: userId,
+  p_organisation_id: orgId
+});
+
+// New
+const { data, error } = await supabase.rpc('data_cake_meals_list', {
+  p_event_id: eventId,
+  p_user_id: userId,
+  p_organisation_id: orgId,
+  p_limit: 100, // Pagination support
+  p_offset: 0
+});
+```
+
+## Service Deprecations
+
+### RBACService
+
+**Status**: Deprecated  
+**Since**: v0.4.x  
+**Removal**: v0.6.x
+
+**Location**: `packages/core/src/providers/services/RBACService.ts`
+
+**Deprecated Service**: Use RBAC Engine instead.
+
+**Migration**:
+```typescript
+// Old
+import { RBACService } from '@jmruthers/pace-core/providers/services';
+
+// New
+import { useRBAC } from '@jmruthers/pace-core/rbac';
+const { hasPermission } = useRBAC();
+```
+
+## Migration Checklist
+
+When migrating deprecated APIs:
+
+- [ ] Check current package version
+- [ ] Identify all deprecated API usage in codebase
+- [ ] Review migration paths above
+- [ ] Update imports and function calls
+- [ ] Test thoroughly
+- [ ] Remove deprecated code before removal version
+
+## Reporting Issues
+
+If you encounter issues migrating from deprecated APIs, please:
+
+1. Check this documentation first
+2. Review the [Migration Guide](../migration/MIGRATION_GUIDE.md)
+3. Check [Troubleshooting](../troubleshooting/README.md)
+4. Open an issue on GitHub with:
+   - Package version
+   - Deprecated API being used
+   - Error messages
+   - Migration attempt details
+