@jmruthers/pace-core 0.2.4

package/docs/api-reference/types.md

@@ -0,0 +1,1005 @@
+# Types API Reference
+
+This section provides detailed documentation for all TypeScript types and interfaces in `@jmruthers/pace-core`.
+
+## Authentication Types
+
+### User
+
+Represents a user in the system.
+
+```typescript
+interface User {
+  id: string;
+  email: string;
+  email_confirmed_at?: string;
+  phone?: string;
+  phone_confirmed_at?: string;
+  created_at: string;
+  updated_at: string;
+  last_sign_in_at?: string;
+  role: string;
+  aud: string;
+  app_metadata: {
+    provider?: string;
+    providers?: string[];
+  };
+  user_metadata: Record<string, any>;
+  identities?: Identity[];
+  factors?: Factor[];
+}
+```
+
+### Session
+
+Represents an active user session.
+
+```typescript
+interface Session {
+  access_token: string;
+  token_type: string;
+  expires_in: number;
+  refresh_token: string;
+  user: User;
+  expires_at?: number;
+}
+```
+
+### AuthError
+
+Represents authentication-related errors.
+
+```typescript
+interface AuthError {
+  message: string;
+  status?: number;
+  name?: string;
+}
+```
+
+### SignInCredentials
+
+Credentials for user sign-in.
+
+```typescript
+interface SignInCredentials {
+  email: string;
+  password: string;
+  remember?: boolean;
+}
+```
+
+### SignUpCredentials
+
+Credentials for user registration.
+
+```typescript
+interface SignUpCredentials {
+  email: string;
+  password: string;
+  phone?: string;
+  data?: Record<string, any>;
+}
+```
+
+## Event Types
+
+### Event
+
+Represents an event in the system.
+
+```typescript
+interface Event {
+  id: string;
+  name: string;
+  description?: string;
+  start_date: string;
+  end_date: string;
+  location?: string;
+  organiser_id: string;
+  organisation_id: string;
+  created_at: string;
+  updated_at: string;
+  status: 'draft' | 'published' | 'cancelled';
+  max_participants?: number;
+  current_participants: number;
+  is_public: boolean;
+  tags?: string[];
+  metadata?: Record<string, any>;
+}
+```
+
+### EventAccess
+
+Represents user access to an event.
+
+```typescript
+interface EventAccess {
+  event_id: string;
+  user_id: string;
+  role: 'organiser' | 'admin' | 'participant' | 'viewer';
+  granted_at: string;
+  granted_by?: string;
+  permissions: string[];
+}
+```
+
+### EventSelectorProps
+
+Props for the EventSelector component.
+
+```typescript
+interface EventSelectorProps {
+  events: Event[];
+  selectedEvent: Event | null;
+  onSelect: (event: Event | null) => void;
+  loading?: boolean;
+  error?: string;
+  className?: string;
+}
+```
+
+## RBAC Types
+
+### Role
+
+Represents a user role in the system.
+
+```typescript
+interface Role {
+  id: string;
+  name: string;
+  description?: string;
+  permissions: Permission[];
+  created_at: string;
+  updated_at: string;
+  is_system: boolean;
+}
+```
+
+### Permission
+
+Represents a permission in the system.
+
+```typescript
+interface Permission {
+  id: string;
+  name: string;
+  description?: string;
+  resource: string;
+  action: string;
+  created_at: string;
+  updated_at: string;
+}
+```
+
+### UserRole
+
+Represents a user's role assignment.
+
+```typescript
+interface UserRole {
+  user_id: string;
+  role_id: string;
+  organisation_id: string;
+  granted_at: string;
+  granted_by?: string;
+  expires_at?: string;
+}
+```
+
+### PagePermission
+
+Represents page-level permissions.
+
+```typescript
+interface PagePermission {
+  page: string;
+  roles: string[];
+  permissions: string[];
+  redirect_to?: string;
+}
+```
+
+## Organisation Types
+
+### Organisation
+
+Represents an organisation in the system.
+
+```typescript
+interface Organisation {
+  id: string;
+  name: string;
+  description?: string;
+  slug: string;
+  logo_url?: string;
+  website?: string;
+  contact_email?: string;
+  created_at: string;
+  updated_at: string;
+  settings: OrganisationSettings;
+}
+```
+
+### OrganisationSettings
+
+Settings for an organisation.
+
+```typescript
+interface OrganisationSettings {
+  timezone: string;
+  date_format: string;
+  time_format: '12h' | '24h';
+  notifications: {
+    email: boolean;
+    push: boolean;
+    sms: boolean;
+  };
+  features: {
+    events: boolean;
+    users: boolean;
+    analytics: boolean;
+  };
+}
+```
+
+### OrganisationMembership
+
+Represents a member of an organisation with enhanced role system.
+
+```typescript
+interface OrganisationMembership {
+  id: string;
+  user_id: string;
+  organisation_id: string;
+  role: 'org_admin' | 'leader' | 'member' | 'supporter';
+  status: 'active' | 'inactive' | 'suspended';
+  granted_at: string;
+  granted_by?: string;
+  revoked_at?: string;
+  revoked_by?: string;
+  notes?: string;
+  created_at: string;
+  updated_at: string;
+}
+```
+
+### OrganisationRole
+
+Defines the available organisation roles.
+
+```typescript
+type OrganisationRole = 'org_admin' | 'leader' | 'member' | 'supporter';
+```
+
+### OrganisationPermission
+
+Defines the available organisation permissions.
+
+```typescript
+type OrganisationPermission = 
+  | 'view_basic'
+  | 'view_details'
+  | 'moderate_content'
+  | 'manage_events'
+  | 'manage_members'
+  | 'manage_settings'
+  | '*';
+```
+
+### UseOrganisationPermissionsReturn
+
+Return type for the `useOrganisationPermissions` hook.
+
+```typescript
+interface UseOrganisationPermissionsReturn {
+  userRole: OrganisationRole | 'no_access';
+  isOrgAdmin: boolean;
+  isSuperAdmin: boolean;
+  canModerate: boolean;
+  canManageMembers: boolean;
+  canManageSettings: boolean;
+  canManageEvents: boolean;
+  hasAdminPrivileges: boolean;
+  hasOrganisationAccess: boolean;
+  hasPermission: (permission: OrganisationPermission) => boolean;
+  getAllPermissions: () => OrganisationPermission[];
+  organisationId: string;
+}
+```
+
+## UI Component Types
+
+### ButtonProps
+
+Props for the Button component.
+
+```typescript
+interface ButtonProps {
+  variant?: 'primary' | 'secondary' | 'outline' | 'ghost' | 'destructive';
+  size?: 'sm' | 'md' | 'lg';
+  disabled?: boolean;
+  loading?: boolean;
+  children: React.ReactNode;
+  onClick?: () => void;
+  type?: 'button' | 'submit' | 'reset';
+  className?: string;
+}
+```
+
+### DataTableProps
+
+Props for the DataTable component.
+
+```typescript
+interface DataTableProps<T> {
+  data: T[];
+  columns: ColumnDef<T>[];
+  loading?: boolean;
+  pagination?: PaginationConfig;
+  sorting?: SortingConfig;
+  filtering?: FilteringConfig;
+  onRowClick?: (row: T) => void;
+  className?: string;
+}
+```
+
+### ColumnDef
+
+Definition for a table column.
+
+```typescript
+interface ColumnDef<T> {
+  accessorKey: keyof T;
+  header: string;
+  cell?: (value: any, row: T) => React.ReactNode;
+  sortable?: boolean;
+  filterable?: boolean;
+  width?: number | string;
+  className?: string;
+}
+```
+
+### PaginationConfig
+
+Configuration for table pagination.
+
+```typescript
+interface PaginationConfig {
+  // Pagination is now handled internally by the DataTable component
+  // Use the features.pagination prop to enable/disable pagination
+  // This interface is kept for backward compatibility
+  pageSize?: number;
+  pageIndex?: number;
+  pageCount?: number;
+  totalCount?: number;
+  onPageChange?: (page: number) => void;
+  onPageSizeChange?: (pageSize: number) => void;
+}
+```
+
+### SortingConfig
+
+Configuration for table sorting.
+
+```typescript
+interface SortingConfig {
+  sortBy: string;
+  sortDirection: 'asc' | 'desc';
+  onSort?: (column: string, direction: 'asc' | 'desc') => void;
+}
+```
+
+### FilteringConfig
+
+Configuration for table filtering.
+
+```typescript
+interface FilteringConfig {
+  filters: Filter[];
+  onFilterChange?: (filters: Filter[]) => void;
+  globalFilter?: string;
+  onGlobalFilterChange?: (value: string) => void;
+}
+```
+
+### Filter
+
+Represents a table filter.
+
+```typescript
+interface Filter {
+  id: string;
+  column: string;
+  value: any;
+  operator: 'equals' | 'contains' | 'startsWith' | 'endsWith' | 'in' | 'between';
+}
+```
+
+## Form Types
+
+### FormProps
+
+Props for the Form component.
+
+```typescript
+interface FormProps<T> {
+  schema: ZodSchema<T>;
+  onSubmit: (data: T) => void;
+  defaultValues?: Partial<T>;
+  children: React.ReactNode;
+  className?: string;
+}
+```
+
+### InputProps
+
+Props for the Input component.
+
+```typescript
+interface InputProps {
+  name: string;
+  label?: string;
+  type?: 'text' | 'email' | 'password' | 'number' | 'tel' | 'url';
+  placeholder?: string;
+  required?: boolean;
+  disabled?: boolean;
+  className?: string;
+  error?: string;
+}
+```
+
+### SelectProps
+
+Props for the Select component.
+
+```typescript
+interface SelectProps<T> {
+  name: string;
+  label?: string;
+  options: SelectOption<T>[];
+  value?: T;
+  onChange: (value: T) => void;
+  placeholder?: string;
+  disabled?: boolean;
+  searchable?: boolean;
+  multiple?: boolean;
+  className?: string;
+  error?: string;
+}
+```
+
+### SelectOption
+
+Represents a select option.
+
+```typescript
+interface SelectOption<T> {
+  value: T;
+  label: string;
+  disabled?: boolean;
+  icon?: React.ReactNode;
+}
+```
+
+## Dialog Types
+
+### DialogProps
+
+Props for the Dialog component (replaces Modal).
+
+```typescript
+interface DialogProps {
+  children: React.ReactNode;
+  open?: boolean;
+  onOpenChange?: (open: boolean) => void;
+}
+```
+
+### DialogContentProps
+
+Props for the DialogContent component.
+
+```typescript
+interface DialogContentProps {
+  children: React.ReactNode;
+  className?: string;
+  size?: 'sm' | 'md' | 'lg' | 'xl' | 'full' | 'auto';
+  showCloseButton?: boolean;
+  overlayClassName?: string;
+  preventCloseOnEscape?: boolean;
+  preventCloseOnOutsideClick?: boolean;
+  maxHeightPercent?: number;
+  maxWidthPercent?: number;
+  enableScrolling?: boolean;
+  maxHeight?: string;
+  maxWidth?: string;
+  minHeight?: string;
+  minWidth?: string;
+}
+```
+
+### DialogBodyProps
+
+Props for the DialogBody component with HTML content support.
+
+```typescript
+interface DialogBodyProps {
+  children: React.ReactNode;
+  className?: string;
+  maxHeight?: string;
+  htmlContent?: string;
+  allowHtml?: boolean;
+  strictSanitization?: boolean;
+  logWarnings?: boolean;
+}
+```
+
+### DialogTitleProps
+
+Props for the DialogTitle component with HTML content support.
+
+```typescript
+interface DialogTitleProps {
+  children: React.ReactNode;
+  className?: string;
+  htmlContent?: string;
+  allowHtml?: boolean;
+}
+```
+
+### DialogDescriptionProps
+
+Props for the DialogDescription component with HTML content support.
+
+```typescript
+interface DialogDescriptionProps {
+  children: React.ReactNode;
+  className?: string;
+  htmlContent?: string;
+  allowHtml?: boolean;
+}
+```
+
+## Alert Types
+
+### AlertProps
+
+Props for the Alert component.
+
+```typescript
+interface AlertProps {
+  variant?: 'info' | 'success' | 'warning' | 'error';
+  title?: string;
+  children: React.ReactNode;
+  onClose?: () => void;
+  className?: string;
+  dismissible?: boolean;
+}
+```
+
+## Toast Types
+
+### ToastConfig
+
+Configuration for toast notifications.
+
+```typescript
+interface ToastConfig {
+  id?: string;
+  message: string;
+  variant?: 'info' | 'success' | 'warning' | 'error';
+  duration?: number;
+  onClose?: () => void;
+  action?: {
+    label: string;
+    onClick: () => void;
+  };
+}
+```
+
+### Toast
+
+Represents a toast notification.
+
+```typescript
+interface Toast extends ToastConfig {
+  id: string;
+  createdAt: number;
+}
+```
+
+
+## Hook Return Types
+
+### UseUnifiedAuthReturn
+
+Return type for the useUnifiedAuth hook.
+
+```typescript
+interface UseUnifiedAuthReturn {
+  user: User | null;
+  session: Session | null;
+  loading: boolean;
+  error: AuthError | null;
+  signIn: (credentials: SignInCredentials) => Promise<void>;
+  signUp: (credentials: SignUpCredentials) => Promise<void>;
+  signOut: () => Promise<void>;
+  resetPassword: (email: string) => Promise<void>;
+  updatePassword: (password: string) => Promise<void>;
+  events: Event[];
+  selectedEvent: Event | null;
+  setSelectedEvent: (event: Event | null) => void;
+  hasEventAccess: (eventId: string) => boolean;
+}
+```
+
+### UseRBACReturn
+
+Return type for the useRBAC hook.
+
+```typescript
+interface UseRBACReturn {
+  user: User | null;
+  roles: Role[];
+  permissions: Permission[];
+  hasRole: (role: string) => boolean;
+  hasPermission: (permission: string) => boolean;
+  canAccess: (resource: string, action: string) => boolean;
+  checkPagePermission: (page: string) => boolean;
+}
+```
+
+### UseEventsReturn
+
+Return type for the useEvents hook.
+
+```typescript
+interface UseEventsReturn {
+  events: Event[];
+  selectedEvent: Event | null;
+  loading: boolean;
+  error: string | null;
+  setSelectedEvent: (event: Event | null) => void;
+  hasAccess: (eventId: string) => boolean;
+  refreshEvents: () => Promise<void>;
+}
+```
+
+  theme: Theme;
+  setTheme: (theme: Theme) => void;
+  toggleTheme: () => void;
+  isDark: boolean;
+}
+```
+
+### UseToastReturn
+
+Return type for the useToast hook.
+
+```typescript
+interface UseToastReturn {
+  showToast: (toast: ToastConfig) => void;
+  hideToast: (id: string) => void;
+  clearToasts: () => void;
+  toasts: Toast[];
+}
+```
+
+## Utility Types
+
+### DeepPartial
+
+Makes all properties in an object optional recursively.
+
+```typescript
+type DeepPartial<T> = {
+  [P in keyof T]?: T[P] extends object ? DeepPartial<T[P]> : T[P];
+};
+```
+
+### OptionalKeys
+
+Extracts keys of optional properties from an object type.
+
+```typescript
+type OptionalKeys<T> = {
+  [K in keyof T]-?: {} extends Pick<T, K> ? K : never;
+}[keyof T];
+```
+
+### RequiredKeys
+
+Extracts keys of required properties from an object type.
+
+```typescript
+type RequiredKeys<T> = {
+  [K in keyof T]-?: {} extends Pick<T, K> ? never : K;
+}[keyof T];
+```
+
+### ValueOf
+
+Extracts the value type from an object.
+
+```typescript
+type ValueOf<T> = T[keyof T];
+```
+
+## Database Types
+
+### Database
+
+Main database schema type.
+
+```typescript
+interface Database {
+  public: {
+    Tables: {
+      users: {
+        Row: User;
+        Insert: Omit<User, 'id' | 'created_at' | 'updated_at'>;
+        Update: Partial<Omit<User, 'id' | 'created_at' | 'updated_at'>>;
+      };
+      events: {
+        Row: Event;
+        Insert: Omit<Event, 'id' | 'created_at' | 'updated_at'>;
+        Update: Partial<Omit<Event, 'id' | 'created_at' | 'updated_at'>>;
+      };
+      organisations: {
+        Row: Organisation;
+        Insert: Omit<Organisation, 'id' | 'created_at' | 'updated_at'>;
+        Update: Partial<Omit<Organisation, 'id' | 'created_at' | 'updated_at'>>;
+      };
+      // ... other tables
+    };
+    Views: {
+      // ... views
+    };
+    Functions: {
+      // ... functions
+    };
+  };
+}
+```
+
+## API Response Types
+
+### ApiResponse
+
+Generic API response wrapper.
+
+```typescript
+interface ApiResponse<T> {
+  data: T;
+  error: null;
+  status: number;
+  message?: string;
+}
+```
+
+### ApiError
+
+API error response.
+
+```typescript
+interface ApiError {
+  data: null;
+  error: {
+    message: string;
+    code?: string;
+    details?: any;
+  };
+  status: number;
+}
+```
+
+### PaginatedResponse
+
+Paginated API response.
+
+```typescript
+interface PaginatedResponse<T> {
+  data: T[];
+  pagination: {
+    page: number;
+    pageSize: number;
+    totalCount: number;
+    totalPages: number;
+  };
+  error: null;
+  status: number;
+}
+```
+
+## Configuration Types
+
+### AppConfig
+
+Application configuration.
+
+```typescript
+interface AppConfig {
+  supabase: {
+    url: string;
+    anonKey: string;
+  };
+  auth: {
+    redirectTo?: string;
+    autoRefreshToken?: boolean;
+    persistSession?: boolean;
+  };
+  events: {
+    defaultPageSize: number;
+    maxPageSize: number;
+  };
+  ui: {
+    theme: Theme;
+    language: string;
+    timezone: string;
+  };
+}
+```
+
+### FeatureFlags
+
+Feature flag configuration.
+
+```typescript
+interface FeatureFlags {
+  events: boolean;
+  organisations: boolean;
+  analytics: boolean;
+  notifications: boolean;
+  experimental: {
+    newUI: boolean;
+    betaFeatures: boolean;
+  };
+}
+```
+
+## Type Guards
+
+### Type Guards
+
+Utility functions for type checking.
+
+```typescript
+// Check if value is a User
+function isUser(value: any): value is User {
+  return value && typeof value === 'object' && 'id' in value && 'email' in value;
+}
+
+// Check if value is an Event
+function isEvent(value: any): value is Event {
+  return value && typeof value === 'object' && 'id' in value && 'name' in value;
+}
+
+// Check if value is an Organisation
+function isOrganisation(value: any): value is Organisation {
+  return value && typeof value === 'object' && 'id' in value && 'name' in value;
+}
+
+// Check if value is a Session
+function isSession(value: any): value is Session {
+  return value && typeof value === 'object' && 'access_token' in value && 'user' in value;
+}
+```
+
+## Type Utilities
+
+### Type Utilities
+
+Utility types for common transformations.
+
+```typescript
+// Make all properties optional except specified ones
+type OptionalExcept<T, K extends keyof T> = Partial<T> & Pick<T, K>;
+
+// Make specified properties required
+type RequiredKeys<T, K extends keyof T> = T & Required<Pick<T, K>>;
+
+// Extract props from a component
+type ComponentProps<T> = T extends React.ComponentType<infer P> ? P : never;
+
+// Extract return type from a function
+type ReturnType<T> = T extends (...args: any[]) => infer R ? R : never;
+
+// Extract parameter types from a function
+type Parameters<T> = T extends (...args: infer P) => any ? P : never;
+```
+
+## Type Exports
+
+All types are exported from the main package:
+
+```typescript
+export type {
+  // Authentication
+  User,
+  Session,
+  AuthError,
+  SignInCredentials,
+  SignUpCredentials,
+  
+  // Events
+  Event,
+  EventAccess,
+  EventSelectorProps,
+  
+  // RBAC
+  Role,
+  Permission,
+  UserRole,
+  PagePermission,
+  
+  // Organisations
+  Organisation,
+  OrganisationSettings,
+  OrganisationMember,
+  
+  // UI Components
+  ButtonProps,
+  DataTableProps,
+  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';
+```
+
+## Type Safety
+
+All types in `@jmruthers/pace-core` are designed to provide:
+
+- **Compile-time Safety**: Catch errors at build time
+- **IntelliSense Support**: Full autocomplete and documentation
+- **Runtime Validation**: Zod schemas for runtime type checking
+- **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).