@jmruthers/pace-core 0.2.4

package/dist/hooks.d.ts

@@ -0,0 +1,449 @@
+import * as React$1 from 'react';
+import { SortingState, ColumnFiltersState, ExpandedState } from '@tanstack/react-table';
+export { O as OrganisationSecurityHook, r as UseAppConfigReturn, q as UseOrganisationPermissionsReturn, o as UsePublicEventLogoOptions, n as UsePublicEventLogoReturn, m as UsePublicEventOptions, U as UsePublicEventReturn, p as UsePublicRouteParamsReturn, d as clearPublicEventCache, f as clearPublicLogoCache, l as extractEventCodeFromPath, k as generatePublicRoutePath, g as getPublicEventCacheStats, h as getPublicLogoCacheStats, b as useAppConfig, u as useOrganisationPermissions, a as useOrganisationSecurity, c as usePublicEvent, j as usePublicEventCode, e as usePublicEventLogo, i as usePublicRouteParams } from './usePublicRouteParams-B6i0KtXW.js';
+import * as react_hook_form from 'react-hook-form';
+import { z } from 'zod';
+export { u as useComponentPerformance } from './useComponentPerformance-DE9l5RkL.js';
+import { c as PaginationMode, D as DataRecord, P as PerformanceConfig, S as ServerSideConfig, C as ChunkingConfig, d as SearchIndexConfig, g as ServerSideParams, h as ServerSideResponse } from './types-CInEi-ng.js';
+import './organisation-CO3Sh3_D.js';
+import './unified-CM7T0aTK.js';
+import '@supabase/supabase-js';
+import './database-C3Szpi5J.js';
+
+/**
+ * @file Error Handling and Fallbacks for DataTable Performance
+ * @package @jmruthers/pace-core
+ * @module Components/DataTable/Utils/ErrorHandling
+ * @since 0.3.0
+ */
+
+/**
+ * Error types for DataTable performance operations
+ */
+declare enum DataTableErrorType {
+    VIRTUALIZATION_ERROR = "VIRTUALIZATION_ERROR",
+    SEARCH_INDEX_ERROR = "SEARCH_INDEX_ERROR",
+    DATA_CHUNK_ERROR = "DATA_CHUNK_ERROR",
+    SERVER_FETCH_ERROR = "SERVER_FETCH_ERROR",
+    MEMORY_ERROR = "MEMORY_ERROR",
+    PERFORMANCE_MONITOR_ERROR = "PERFORMANCE_MONITOR_ERROR",
+    VISIBILITY_TRACKER_ERROR = "VISIBILITY_TRACKER_ERROR"
+}
+/**
+ * Custom error class for DataTable operations
+ */
+declare class DataTableError extends Error {
+    readonly type: DataTableErrorType;
+    readonly timestamp: number;
+    readonly context?: Record<string, any>;
+    readonly recoverable: boolean;
+    constructor(message: string, type: DataTableErrorType, context?: Record<string, any>, recoverable?: boolean);
+}
+/**
+ * Fallback configurations for different performance features
+ */
+interface FallbackConfig {
+    /** Fallback pagination mode when auto-detection fails */
+    fallbackPaginationMode: PaginationMode;
+    /** Fallback page size options */
+    fallbackPageSizeOptions: number[];
+    /** Maximum retry attempts for server requests */
+    maxRetries: number;
+    /** Retry delay in milliseconds */
+    retryDelay: number;
+    /** Maximum memory usage before falling back (in MB) */
+    maxMemoryUsage: number;
+    /** Enable graceful degradation */
+    enableGracefulDegradation: boolean;
+}
+
+/**
+ * @file DataTable Performance Hook
+ * @package @jmruthers/pace-core
+ * @module Hooks/DataTablePerformance
+ * @since 0.3.0
+ */
+
+interface UseDataTablePerformanceOptions<TData extends DataRecord> {
+    data: TData[];
+    performance?: PerformanceConfig;
+    serverSide?: ServerSideConfig<TData>;
+    chunking?: ChunkingConfig;
+    searchIndex?: SearchIndexConfig;
+    fallbackConfig?: FallbackConfig;
+    onError?: (error: DataTableError) => void;
+    enableErrorRecovery?: boolean;
+}
+interface UseDataTablePerformanceReturn<TData extends DataRecord> {
+    paginationMode: PaginationMode;
+    isVirtualized: boolean;
+    pageSizeOptions: number[];
+    processedData: TData[];
+    totalCount: number;
+    isLoading: boolean;
+    searchQuery: string;
+    setSearchQuery: (query: string) => void;
+    searchResults: number[];
+    fetchServerData: (params: ServerSideParams) => Promise<void>;
+    serverData: ServerSideResponse<TData> | null;
+    memoryUsage: number;
+    errorState: {
+        hasErrors: boolean;
+        errorCount: number;
+        lastError: DataTableError | null;
+        fallbacksActive: string[];
+    };
+    retryLastOperation: () => Promise<void>;
+    clearErrors: () => void;
+    cleanup: () => void;
+}
+/**
+ * Hook for managing DataTable performance optimizations
+ */
+declare function useDataTablePerformance<TData extends DataRecord>({ data, performance, serverSide, chunking, searchIndex, fallbackConfig, onError, enableErrorRecovery }: UseDataTablePerformanceOptions<TData>): UseDataTablePerformanceReturn<TData>;
+
+/**
+ * @file Toast hook for managing toast notifications
+ * @package @jmruthers/pace-core
+ * @module Hooks
+ * @since 0.1.0
+ */
+
+interface ToastProps {
+    title?: React$1.ReactNode;
+    description?: React$1.ReactNode;
+    variant?: 'default' | 'destructive' | 'success';
+    duration?: number;
+    onClose?: () => void;
+    action?: React$1.ReactElement;
+}
+/**
+ * Extended toast props with additional properties
+ * @interface ToasterToast
+ */
+type ToasterToast = ToastProps & {
+    /** Unique identifier for the toast */
+    id: string;
+    /** Optional title content */
+    title?: React$1.ReactNode;
+    /** Optional description content */
+    description?: React$1.ReactNode;
+    /** Optional action button */
+    action?: React$1.ReactElement;
+    /** Open state */
+    open?: boolean;
+    /** Open change handler */
+    onOpenChange?: (open: boolean) => void;
+    /** Dismiss function */
+    dismiss?: () => void;
+};
+/**
+ * Toast configuration without ID
+ */
+type Toast = Omit<ToasterToast, "id">;
+/**
+ * Creates a new toast notification
+ * @param props - Toast configuration
+ * @returns Object with toast ID and control methods
+ */
+declare function toast({ ...props }: Toast): {
+    id: string;
+    dismiss: () => void;
+    update: (props: Partial<Omit<ToasterToast, "id">>) => void;
+};
+/**
+ * Hook for managing toast notifications
+ * @returns Object with toast state and control methods
+ */
+declare function useToast(): {
+    toast: typeof toast;
+    dismiss: (toastId?: string) => void;
+    /** Array of active toasts */
+    toasts: ToasterToast[];
+};
+
+interface FocusManagementOptions {
+    trapFocus?: boolean;
+    autoFocus?: boolean;
+    restoreFocus?: boolean;
+    onEscape?: () => void;
+    onFocusFirst?: () => void;
+    onFocusLast?: () => void;
+}
+interface FocusManagementReturn {
+    containerRef: React.RefObject<HTMLDivElement>;
+    focusRef: React.RefObject<HTMLElement>;
+    setFocus: (element: HTMLElement | null) => void;
+    focusFirst: () => void;
+    focusLast: () => void;
+    trapFocus: () => void;
+    releaseFocus: () => void;
+    getFocusableElements: () => HTMLElement[];
+    handleEscape: (callback: () => void) => () => void;
+}
+declare function useFocusManagement(options?: FocusManagementOptions): FocusManagementReturn;
+
+interface FocusTrapOptions {
+    /** Whether the focus trap is active */
+    isActive?: boolean;
+    /** Whether to auto-focus the first element when activated */
+    autoFocus?: boolean;
+    /** Whether to restore focus to the previously focused element when deactivated */
+    restoreFocus?: boolean;
+    /** Callback when Escape key is pressed */
+    onEscape?: () => void;
+    /** Selector for focusable elements (optional override) */
+    focusableSelector?: string;
+}
+interface FocusTrapReturn {
+    /** Ref to attach to the container element */
+    containerRef: React.RefObject<HTMLElement>;
+    /** Focus the first focusable element */
+    focusFirst: () => void;
+    /** Focus the last focusable element */
+    focusLast: () => void;
+    /** Get all focusable elements in the container */
+    getFocusableElements: () => HTMLElement[];
+}
+/**
+ * Hook for creating accessible focus traps
+ * Useful for modals, dropdowns, and other overlay components
+ */
+declare function useFocusTrap(options?: FocusTrapOptions): FocusTrapReturn;
+
+interface KeyboardShortcut {
+    /** Key combination (e.g., 'Escape', 'Enter', 'ArrowDown', 'ctrl+s') */
+    key: string;
+    /** Callback function to execute */
+    handler: (event: KeyboardEvent) => void;
+    /** Description for documentation/help */
+    description?: string;
+    /** Whether the shortcut is enabled */
+    enabled?: boolean;
+    /** Prevent default browser behavior */
+    preventDefault?: boolean;
+    /** Stop event propagation */
+    stopPropagation?: boolean;
+}
+interface KeyboardShortcutsOptions {
+    /** Element to attach listeners to (defaults to document) */
+    element?: HTMLElement | Document;
+    /** Whether shortcuts are globally enabled */
+    enabled?: boolean;
+}
+/**
+ * Hook for managing keyboard shortcuts
+ *
+ * @example
+ * ```tsx
+ * function MyComponent() {
+ *   const shortcuts = [
+ *     {
+ *       key: 'Escape',
+ *       handler: () => setIsOpen(false),
+ *       description: 'Close modal'
+ *     },
+ *     {
+ *       key: 'ctrl+s',
+ *       handler: (e) => handleSave(),
+ *       description: 'Save document',
+ *       preventDefault: true
+ *     }
+ *   ];
+ *
+ *   useKeyboardShortcuts(shortcuts);
+ *
+ *   return <div>Content</div>;
+ * }
+ * ```
+ */
+declare function useKeyboardShortcuts(shortcuts: KeyboardShortcut[], options?: KeyboardShortcutsOptions): void;
+
+/**
+ * @file useIsMobile Hook
+ * @description Hook for detecting mobile viewport using modern matchMedia API
+ */
+/**
+ * Hook to detect if the viewport is mobile-sized using matchMedia API.
+ * More performant than window resize events.
+ * @returns {boolean} True if mobile, false otherwise.
+ */
+declare function useIsMobile(): boolean;
+
+declare function useDebounce<T>(value: T, delay: number): T;
+
+interface UseDataTableStateOptions {
+    initialPageSize?: number;
+    data: any[];
+}
+/**
+ * Hook for managing DataTable state
+ * @param options Configuration options
+ * @returns Object containing state, actions, and computed values
+ */
+declare function useDataTableState(options: UseDataTableStateOptions): {
+    state: {
+        sorting: SortingState;
+        columnFilters: ColumnFiltersState;
+        expanded: ExpandedState;
+        pageSize: number;
+        pageIndex: number;
+        selectedRows: string[];
+    };
+    actions: {
+        setSorting: React$1.Dispatch<React$1.SetStateAction<SortingState>>;
+        setColumnFilters: React$1.Dispatch<React$1.SetStateAction<ColumnFiltersState>>;
+        setExpanded: React$1.Dispatch<React$1.SetStateAction<ExpandedState>>;
+        setPageSize: React$1.Dispatch<React$1.SetStateAction<number>>;
+        setPageIndex: React$1.Dispatch<React$1.SetStateAction<number>>;
+        setSelectedRows: React$1.Dispatch<React$1.SetStateAction<string[]>>;
+        resetState: () => void;
+    };
+    computed: {
+        paginatedData: any[];
+        totalPages: number;
+        hasNextPage: boolean;
+        hasPreviousPage: boolean;
+    };
+};
+
+/**
+ * @file useSecureDataAccess Hook
+ * @package @jmruthers/pace-core
+ * @module Hooks/useSecureDataAccess
+ * @since 0.4.0
+ *
+ * Hook for secure database operations with mandatory organisation context.
+ * Ensures all data access is properly scoped to the user's current organisation.
+ *
+ * @example
+ * ```tsx
+ * function DataComponent() {
+ *   const { secureQuery, secureInsert, secureUpdate, secureDelete } = useSecureDataAccess();
+ *
+ *   const loadData = async () => {
+ *     try {
+ *       // Automatically includes organisation_id filter
+ *       const events = await secureQuery('event', '*', { is_visible: true });
+ *       console.log('Organisation events:', events);
+ *     } catch (error) {
+ *       console.error('Failed to load data:', error);
+ *     }
+ *   };
+ *
+ *   const createEvent = async (eventData) => {
+ *     try {
+ *       // Automatically sets organisation_id
+ *       const newEvent = await secureInsert('event', eventData);
+ *       console.log('Created event:', newEvent);
+ *     } catch (error) {
+ *       console.error('Failed to create event:', error);
+ *     }
+ *   };
+ *
+ *   return (
+ *     <div>
+ *       <button onClick={loadData}>Load Data</button>
+ *       <button onClick={() => createEvent({ event_name: 'New Event' })}>
+ *         Create Event
+ *       </button>
+ *     </div>
+ *   );
+ * }
+ * ```
+ *
+ * @security
+ * - All queries automatically include organisation_id filter
+ * - Validates organisation context before any operation
+ * - Prevents data leaks between organisations
+ * - Error handling for security violations
+ * - Type-safe database operations
+ */
+interface SecureDataAccessReturn {
+    /** Execute a secure query with organisation filtering */
+    secureQuery: <T = any>(table: string, columns: string, filters?: Record<string, any>, options?: {
+        orderBy?: string;
+        ascending?: boolean;
+        limit?: number;
+        offset?: number;
+    }) => Promise<T[]>;
+    /** Execute a secure insert with organisation context */
+    secureInsert: <T = any>(table: string, data: Record<string, any>) => Promise<T>;
+    /** Execute a secure update with organisation filtering */
+    secureUpdate: <T = any>(table: string, data: Record<string, any>, filters: Record<string, any>) => Promise<T[]>;
+    /** Execute a secure delete with organisation filtering */
+    secureDelete: (table: string, filters: Record<string, any>) => Promise<void>;
+    /** Execute a secure RPC call with organisation context */
+    secureRpc: <T = any>(functionName: string, params?: Record<string, any>) => Promise<T>;
+    /** Get current organisation ID */
+    getCurrentOrganisationId: () => string;
+    /** Validate organisation context */
+    validateContext: () => void;
+    /** Check if data access is allowed for a table and operation */
+    isDataAccessAllowed: (table: string, operation: string) => boolean;
+    /** Get all data access permissions for current user */
+    getDataAccessPermissions: () => Record<string, string[]>;
+    /** Check if strict mode is enabled */
+    isStrictMode: boolean;
+    /** Check if audit logging is enabled */
+    isAuditLogEnabled: boolean;
+    /** Get data access history */
+    getDataAccessHistory: () => DataAccessRecord[];
+    /** Clear data access history */
+    clearDataAccessHistory: () => void;
+    /** Validate data access attempt */
+    validateDataAccess: (table: string, operation: string) => boolean;
+}
+interface DataAccessRecord {
+    table: string;
+    operation: string;
+    userId: string;
+    organisationId: string;
+    allowed: boolean;
+    timestamp: string;
+    query?: string;
+    filters?: Record<string, any>;
+}
+/**
+ * Hook for secure data access with automatic organisation filtering
+ *
+ * All database operations automatically include organisation context:
+ * - Queries filter by organisation_id
+ * - Inserts include organisation_id
+ * - Updates/deletes are scoped to organisation
+ * - RPC calls include organisation_id parameter
+ */
+declare function useSecureDataAccess(): SecureDataAccessReturn;
+
+interface UseZodFormProps<T extends z.ZodTypeAny> {
+    schema: T;
+    defaultValues?: Partial<z.infer<T>>;
+    mode?: 'onSubmit' | 'onBlur' | 'onChange' | 'onTouched' | 'all';
+}
+declare function useZodForm<T extends z.ZodTypeAny>({ schema, defaultValues, mode }: UseZodFormProps<T>): react_hook_form.UseFormReturn<z.TypeOf<T>, any, z.TypeOf<T>>;
+
+interface PerformanceMetrics {
+    renderTime: number;
+    componentName: string;
+    timestamp: number;
+}
+/**
+ * Hook for monitoring component performance with budget validation
+ * @param componentName - Name of the component being monitored
+ * @param enabled - Whether performance monitoring is enabled
+ * @param budgetName - Performance budget to validate against
+ */
+declare function usePerformanceMonitor(componentName: string, enabled?: boolean, budgetName?: string): {
+    getMetrics: () => PerformanceMetrics[];
+    getAverageRenderTime: () => number;
+    getBudgetStatus: () => {
+        budget: number;
+        average: number;
+        passed: boolean;
+        efficiency: number;
+    } | null;
+    startMeasurement: () => void;
+    endMeasurement: () => void;
+};
+
+export { type SecureDataAccessReturn, type UseDataTablePerformanceOptions, type UseDataTablePerformanceReturn, useDataTablePerformance, useDataTableState, useDebounce, useFocusManagement, useFocusTrap, useIsMobile, useKeyboardShortcuts, usePerformanceMonitor, useSecureDataAccess, useToast, useZodForm };