@jmruthers/pace-core 0.5.180 → 0.5.182

package/docs/api-reference/types.md

@@ -1,7 +1,7 @@
 ---
-lastUpdated: 2025-10-29T22:43:00+11:00
-version: 0.5.76
-reviewedBy: content-audit
+lastUpdated: 2025-11-18T20:00:00+11:00
+version: 0.5.181
+reviewedBy: documentation-standards-audit
 ---
 
 # Types API Reference
@@ -945,87 +945,99 @@ type Parameters<T> = T extends (...args: infer P) => any ? P : never;
 
 ## Type Exports
 
-All types are exported from the main package:
+Types are organized by domain for better discoverability and maintainability. Import from domain-specific modules:
 
 ```typescript
-export type {
-  // Authentication
-  User,
-  Session,
+// Core types (branded types, errors, primitives)
+import type { 
+  UserId, 
+  SessionToken, 
+  PermissionString, 
+  RequestId,
+  OrganisationId,
+  EventId,
+  AppId,
+  PageId,
   AuthError,
-  SignInCredentials,
-  SignUpCredentials,
-  
-  // Events
-  Event,
-  EventAccess,
-  EventSelectorProps,
-  
-  // RBAC
-  Role,
-  Permission,
-  UserRole,
-  PagePermission,
-  
-  // Organisations
+  PermissionError,
+  AuthErrorCode,
+  PermissionErrorCode,
+  DataRecord,
+  PermissionMap
+} from '@jmruthers/pace-core/types/core';
+
+// Authentication types
+import type { 
+  User, 
+  Session, 
+  SessionRestorationState 
+} from '@jmruthers/pace-core/types/auth';
+
+// Event types
+import type { 
+  Event, 
+  EventContextType,
+  EventTheme,
+  ThemeColors
+} from '@jmruthers/pace-core/types/event';
+
+// Organisation types
+import type {
   Organisation,
+  OrganisationMembership,
+  UserProfile,
   OrganisationSettings,
-  OrganisationMember,
-  
-  // UI Components
-  ButtonProps,
-  DataTableProps,
-  ExportOptions,
-  ColumnDef,
-  PaginationConfig,
-  SortingConfig,
-  FilteringConfig,
-  Filter,
-  
-  // Forms
-  FormProps,
-  InputProps,
-  SelectProps,
-  SelectOption,
-  
-  // Dialogs and Alerts
-  DialogProps,
-  AlertProps,
-  
-  // Toasts
-  ToastConfig,
-  Toast,
-  
-  // Theme
-  Theme,
-  ThemeConfig,
-  
-  // Hooks
-  UseUnifiedAuthReturn,
-  UseRBACReturn,
-  UseEventsReturn,
-  UseToastReturn,
-  
-  // Utilities
-  DeepPartial,
-  OptionalKeys,
-  RequiredKeys,
-  ValueOf,
-  
-  // Database
-  Database,
-  
-  // API
-  ApiResponse,
-  ApiError,
-  PaginatedResponse,
-  
-  // Configuration
-  AppConfig,
-  FeatureFlags,
-} from '@jmruthers/pace-core';
+  OrganisationRole,
+  OrganisationPermission
+} from '@jmruthers/pace-core/types/organisation';
+
+// File reference types
+import type {
+  FileReference,
+  FileMetadata,
+  FileUploadOptions,
+  FileCategory
+} from '@jmruthers/pace-core/types/file-reference';
+
+// Database types
+import type { Database } from '@jmruthers/pace-core/types/database';
+
+// RBAC types
+import type {
+  UUID,
+  Operation,
+  Permission,
+  AccessLevel,
+  Scope,
+  PermissionCheck
+} from '@jmruthers/pace-core/rbac/types';
+
+// RBAC function types (RPC parameters/results)
+import type {
+  RBACPermissionCheckParams,
+  RBACPermissionCheckResult,
+  RBACRoleGrantParams,
+  RPCFunction,
+  RBACErrorCode
+} from '@jmruthers/pace-core/rbac/types/functions';
+
+// Validation types
+import type {
+  ValidationError,
+  ValidationResult,
+  LoginFormValues,
+  RegistrationFormValues
+} from '@jmruthers/pace-core/types/validation';
+
+// DataTable types (from components)
+import type {
+  DataTableColumn,
+  DataTableAction,
+  DataTableFeatureConfig
+} from '@jmruthers/pace-core/components';
 ```
 
+
 ## Type Safety
 
 All types in `@jmruthers/pace-core` are designed to provide:
@@ -1036,4 +1048,49 @@ All types in `@jmruthers/pace-core` are designed to provide:
 - **Generic Support**: Flexible types that work with your data
 - **Strict Mode**: Compatible with TypeScript strict mode
 
-For more information about using types effectively, see the [TypeScript Guide](../best-practices/typescript.md). 
+For more information about using types effectively, see the [TypeScript Guide](../best-practices/typescript.md).
+
+## ♿ Accessibility
+
+Type definitions support accessibility:
+
+- **Semantic types** - Types are designed to support semantic HTML and ARIA attributes
+- **Accessibility props** - Component types include accessibility-related props (aria-label, role, etc.)
+- **Type safety for accessibility** - TypeScript ensures accessibility props are properly typed
+- **Screen reader support** - Types support screen reader-friendly implementations
+
+### Accessibility Best Practices
+
+1. **Use semantic types** - Prefer semantic type definitions over generic ones
+2. **Include accessibility props** - Ensure component types include accessibility-related props
+3. **Type ARIA attributes** - Use proper types for ARIA attributes
+4. **Test with types** - Leverage TypeScript to catch accessibility issues at compile time
+
+## ⚠️ Edge Cases
+
+### Type Compatibility Issues
+
+When types don't match expected interfaces:
+- Verify type definitions match actual implementations
+- Check for version mismatches between pace-core and consuming apps
+- Review type exports to ensure all types are properly exported
+- Test with TypeScript strict mode enabled
+- Verify generic type constraints are correct
+
+### Missing Type Definitions
+
+When types are missing:
+- Check if types are exported from the main package
+- Verify type definitions exist in the source code
+- Review type exports in package.json
+- Check for type-only imports vs value imports
+- Ensure all public APIs have type definitions
+
+### Type Inference Issues
+
+When TypeScript can't infer types correctly:
+- Provide explicit type annotations where needed
+- Check generic type parameters are correctly specified
+- Verify type constraints are appropriate
+- Review type narrowing and type guards
+- Test with different TypeScript versions 

package/docs/api-reference/utilities.md

@@ -1,388 +1,14 @@
 ---
-lastUpdated: 2025-10-29T22:43:00+11:00
-version: 0.5.76
-reviewedBy: content-audit
+lastUpdated: 2025-11-18T20:00:00+11:00
+version: 0.5.181
+reviewedBy: documentation-standards-audit
 ---
 
 # Utilities API Reference
 
-This section provides detailed documentation for all utility functions in `@jmruthers/pace-core`.
+This section provides detailed documentation for all utility functions exported from `@jmruthers/pace-core`.
 
-## Authentication Utilities
-
-### createSupabaseClient
-
-Creates a configured Supabase client instance.
-
-```typescript
-function createSupabaseClient(
-  supabaseUrl: string,
-  supabaseAnonKey: string,
-  options?: SupabaseClientOptions
-): SupabaseClient<Database>;
-```
-
-#### Usage
-
-```typescript
-import { createSupabaseClient } from '@jmruthers/pace-core';
-
-const supabase = createSupabaseClient(
-  process.env.SUPABASE_URL!,
-  process.env.SUPABASE_ANON_KEY!
-);
-```
-
-### validateAuthSession
-
-Validates a user session and returns user information.
-
-```typescript
-function validateAuthSession(session: Session | null): {
-  isValid: boolean;
-  user: User | null;
-  error?: string;
-};
-```
-
-#### Usage
-
-```typescript
-import { validateAuthSession } from '@jmruthers/pace-core';
-
-const { isValid, user, error } = validateAuthSession(session);
-
-if (!isValid) {
-  console.error('Invalid session:', error);
-}
-```
-
-### refreshAuthToken
-
-Refreshes an authentication token.
-
-```typescript
-function refreshAuthToken(
-  supabase: SupabaseClient<Database>,
-  refreshToken: string
-): Promise<{
-  success: boolean;
-  session?: Session;
-  error?: string;
-}>;
-```
-
-#### Usage
-
-```typescript
-import { refreshAuthToken } from '@jmruthers/pace-core';
-
-const { success, session, error } = await refreshAuthToken(
-  supabase,
-  currentSession.refresh_token
-);
-
-if (success && session) {
-  // Update session
-}
-```
-
-## Event Utilities
-
-### filterEventsByAccess
-
-Filters events based on user access permissions.
-
-```typescript
-function filterEventsByAccess(
-  events: Event[],
-  userAccess: EventAccess[]
-): Event[];
-```
-
-#### Usage
-
-```typescript
-import { filterEventsByAccess } from '@jmruthers/pace-core';
-
-const accessibleEvents = filterEventsByAccess(events, userAccess);
-```
-
-### sortEventsByDate
-
-Sorts events by date with configurable order.
-
-```typescript
-function sortEventsByDate(
-  events: Event[],
-  order: 'asc' | 'desc' = 'asc'
-): Event[];
-```
-
-#### Usage
-
-```typescript
-import { sortEventsByDate } from '@jmruthers/pace-core';
-
-const sortedEvents = sortEventsByDate(events, 'desc');
-```
-
-### groupEventsByDate
-
-Groups events by date for display purposes.
-
-```typescript
-function groupEventsByDate(events: Event[]): {
-  [date: string]: Event[];
-};
-```
-
-#### Usage
-
-```typescript
-import { groupEventsByDate } from '@jmruthers/pace-core';
-
-const groupedEvents = groupEventsByDate(events);
-
-// Result: { '2024-01-15': [event1, event2], '2024-01-16': [event3] }
-```
-
-### calculateEventDuration
-
-Calculates the duration of an event in various formats.
-
-```typescript
-function calculateEventDuration(
-  startDate: string,
-  endDate: string,
-  format: 'hours' | 'days' | 'minutes' = 'hours'
-): number;
-```
-
-#### Usage
-
-```typescript
-import { calculateEventDuration } from '@jmruthers/pace-core';
-
-const duration = calculateEventDuration(
-  '2024-01-15T09:00:00Z',
-  '2024-01-15T17:00:00Z',
-  'hours'
-); // Returns 8
-```
-
-## RBAC Utilities
-
-### checkPermission
-
-Checks if a user has a specific permission.
-
-```typescript
-function checkPermission(
-  userPermissions: Permission[],
-  requiredPermission: string
-): boolean;
-```
-
-#### Usage
-
-```typescript
-import { checkPermission } from '@jmruthers/pace-core';
-
-const canEditUsers = checkPermission(userPermissions, 'edit:users');
-```
-
-### hasRole
-
-Checks if a user has a specific role.
-
-```typescript
-function hasRole(userRoles: Role[], roleName: string): boolean;
-```
-
-#### Usage
-
-```typescript
-import { hasRole } from '@jmruthers/pace-core';
-
-const isAdmin = hasRole(userRoles, 'admin');
-```
-
-### canAccessResource
-
-Checks if a user can access a specific resource with a given action.
-
-```typescript
-function canAccessResource(
-  userPermissions: Permission[],
-  resource: string,
-  action: string
-): boolean;
-```
-
-#### Usage
-
-```typescript
-import { canAccessResource } from '@jmruthers/pace-core';
-
-const canCreateEvents = canAccessResource(
-  userPermissions,
-  'events',
-  'create'
-);
-```
-
-### buildPermissionString
-
-Builds a permission string from resource and action.
-
-```typescript
-function buildPermissionString(resource: string, action: string): string;
-```
-
-#### Usage
-
-```typescript
-import { buildPermissionString } from '@jmruthers/pace-core';
-
-const permission = buildPermissionString('users', 'read'); // Returns 'read:users'
-```
-
-## Organisation Utilities
-
-### validateOrganisationAccess
-
-Validates if a user has access to an organisation.
-
-```typescript
-function validateOrganisationAccess(
-  userId: string,
-  organisationId: string,
-  organisationMembers: OrganisationMember[]
-): {
-  hasAccess: boolean;
-  role?: string;
-  error?: string;
-};
-```
-
-#### Usage
-
-```typescript
-import { validateOrganisationAccess } from '@jmruthers/pace-core';
-
-const { hasAccess, role } = validateOrganisationAccess(
-  userId,
-  organisationId,
-  organisationMembers
-);
-```
-
-### getOrganisationSettings
-
-Retrieves organisation settings with defaults.
-
-```typescript
-function getOrganisationSettings(
-  organisation: Organisation
-): OrganisationSettings;
-```
-
-#### Usage
-
-```typescript
-import { getOrganisationSettings } from '@jmruthers/pace-core';
-
-const settings = getOrganisationSettings(organisation);
-```
-
-### formatOrganisationName
-
-Formats organisation name for display.
-
-```typescript
-function formatOrganisationName(
-  organisation: Organisation,
-  options?: {
-    includeDescription?: boolean;
-    maxLength?: number;
-  }
-): string;
-```
-
-#### Usage
-
-```typescript
-import { formatOrganisationName } from '@jmruthers/pace-core';
-
-const displayName = formatOrganisationName(organisation, {
-  includeDescription: true,
-  maxLength: 50
-});
-```
-
-## Form Utilities
-
-### validateFormData
-
-Validates form data against a Zod schema.
-
-```typescript
-function validateFormData<T>(
-  data: any,
-  schema: ZodSchema<T>
-): {
-  isValid: boolean;
-  data?: T;
-  errors?: Record<string, string>;
-};
-```
-
-#### Usage
-
-```typescript
-import { validateFormData } from '@jmruthers/pace-core';
-import { z } from 'zod';
-
-const schema = z.object({
-  name: z.string().min(1),
-  email: z.string().email(),
-});
-
-const { isValid, data, errors } = validateFormData(formData, schema);
-```
-
-### formatFormErrors
-
-Formats form validation errors for display.
-
-```typescript
-function formatFormErrors(errors: Record<string, string>): string[];
-```
-
-#### Usage
-
-```typescript
-import { formatFormErrors } from '@jmruthers/pace-core';
-
-const errorMessages = formatFormErrors(errors);
-```
-
-### sanitizeFormData
-
-Sanitizes form data to prevent XSS attacks.
-
-```typescript
-function sanitizeFormData(data: Record<string, any>): Record<string, any>;
-```
-
-#### Usage
-
-```typescript
-import { sanitizeFormData } from '@jmruthers/pace-core';
-
-const sanitizedData = sanitizeFormData(formData);
-```
+> **Note**: Some utilities are available from the main package export (`@jmruthers/pace-core`), while others may be available from sub-modules like `@jmruthers/pace-core/utils` or `@jmruthers/pace-core/rbac`. Check the import path for each utility below.
 
 ## Utility Functions
 
@@ -1394,4 +1020,49 @@ export {
 - Validate input parameters
 - Return consistent types
 
-For more information about using utilities effectively, see the [Best Practices Guide](../best-practices/utilities.md). 
+For more information about using utilities effectively, see the [Best Practices Guide](../best-practices/utilities.md).
+
+## ♿ Accessibility
+
+Utility functions support accessibility:
+
+- **Accessible formatting** - Date, time, and number formatting utilities support accessibility
+- **Screen reader friendly** - Text utilities preserve semantic meaning
+- **ARIA support** - Utilities can be used to generate accessible content
+- **Keyboard navigation** - Utilities support keyboard-accessible implementations
+
+### Accessibility Best Practices
+
+1. **Use accessible formatting** - Prefer utilities that maintain semantic meaning
+2. **Test with screen readers** - Verify utility outputs work with assistive technologies
+3. **Preserve context** - Ensure utilities don't strip important context
+4. **Support ARIA** - Use utilities to generate ARIA-friendly content
+
+## ⚠️ Edge Cases
+
+### Utility Function Failures
+
+When utility functions fail:
+- Verify input types match expected parameters
+- Check for null/undefined inputs
+- Review error handling in utility functions
+- Test with edge case inputs (empty strings, null, undefined, etc.)
+- Verify utility functions handle invalid inputs gracefully
+
+### Performance Issues
+
+When utilities are slow:
+- Check for unnecessary computations
+- Review memoization opportunities
+- Test with large datasets
+- Profile utility function performance
+- Consider caching for expensive operations
+
+### Import Path Issues
+
+When utilities can't be imported:
+- Verify import paths are correct
+- Check if utilities are exported from main package
+- Review sub-module exports (utils, rbac, etc.)
+- Test with different import styles
+- Verify package.json exports configuration