@jmruthers/pace-core 0.5.184 → 0.5.186

package/src/hooks/__tests__/useFormDialog.test.ts

@@ -0,0 +1,478 @@
+/**
+ * @file useFormDialog Hook Unit Tests
+ * @package @jmruthers/pace-core
+ * @module Hooks/__tests__/useFormDialog
+ * @since 0.1.0
+ * 
+ * Comprehensive tests for the useFormDialog hook covering all critical functionality.
+ */
+
+import { renderHook, act } from '@testing-library/react';
+import { describe, it, expect, vi, beforeEach } from 'vitest';
+import { useFormDialog, type UseFormDialogOptions } from '../useFormDialog';
+
+interface TestFormData {
+  id: string;
+  name: string;
+  email: string;
+}
+
+describe('useFormDialog', () => {
+  describe('Initial state', () => {
+    it('should initialize with closed state and null formData', () => {
+      const { result } = renderHook(() => useFormDialog());
+      
+      expect(result.current.isOpen).toBe(false);
+      expect(result.current.formData).toBeNull();
+    });
+
+    it('should initialize with closed state for typed hook', () => {
+      const { result } = renderHook(() => useFormDialog<TestFormData>());
+      
+      expect(result.current.isOpen).toBe(false);
+      expect(result.current.formData).toBeNull();
+    });
+  });
+
+  describe('Opening dialog', () => {
+    it('should open dialog without data', () => {
+      const { result } = renderHook(() => useFormDialog());
+      
+      act(() => {
+        result.current.openDialog();
+      });
+      
+      expect(result.current.isOpen).toBe(true);
+      expect(result.current.formData).toBeNull();
+    });
+
+    it('should open dialog with data', () => {
+      const testData: TestFormData = {
+        id: '1',
+        name: 'John Doe',
+        email: 'john@example.com'
+      };
+      
+      const { result } = renderHook(() => useFormDialog<TestFormData>());
+      
+      act(() => {
+        result.current.openDialog(testData);
+      });
+      
+      expect(result.current.isOpen).toBe(true);
+      expect(result.current.formData).toEqual(testData);
+    });
+
+    it('should open dialog with null data explicitly', () => {
+      const { result } = renderHook(() => useFormDialog<TestFormData>());
+      
+      act(() => {
+        result.current.openDialog(null);
+      });
+      
+      expect(result.current.isOpen).toBe(true);
+      expect(result.current.formData).toBeNull();
+    });
+  });
+
+  describe('Closing dialog', () => {
+    it('should close dialog and reset formData by default', () => {
+      const testData: TestFormData = {
+        id: '1',
+        name: 'John Doe',
+        email: 'john@example.com'
+      };
+      
+      const { result } = renderHook(() => useFormDialog<TestFormData>());
+      
+      act(() => {
+        result.current.openDialog(testData);
+      });
+      
+      expect(result.current.isOpen).toBe(true);
+      expect(result.current.formData).toEqual(testData);
+      
+      act(() => {
+        result.current.closeDialog();
+      });
+      
+      expect(result.current.isOpen).toBe(false);
+      expect(result.current.formData).toBeNull();
+    });
+
+    it('should close dialog without resetting formData when resetOnClose is false', () => {
+      const testData: TestFormData = {
+        id: '1',
+        name: 'John Doe',
+        email: 'john@example.com'
+      };
+      
+      const { result } = renderHook(() => 
+        useFormDialog<TestFormData>({ resetOnClose: false })
+      );
+      
+      act(() => {
+        result.current.openDialog(testData);
+      });
+      
+      act(() => {
+        result.current.closeDialog();
+      });
+      
+      expect(result.current.isOpen).toBe(false);
+      expect(result.current.formData).toEqual(testData);
+    });
+  });
+
+  describe('handleOpenChange', () => {
+    it('should update state when opening via handleOpenChange', () => {
+      const { result } = renderHook(() => useFormDialog());
+      
+      act(() => {
+        result.current.handleOpenChange(true);
+      });
+      
+      expect(result.current.isOpen).toBe(true);
+    });
+
+    it('should update state when closing via handleOpenChange', () => {
+      const { result } = renderHook(() => useFormDialog());
+      
+      act(() => {
+        result.current.openDialog();
+      });
+      
+      act(() => {
+        result.current.handleOpenChange(false);
+      });
+      
+      expect(result.current.isOpen).toBe(false);
+    });
+
+    it('should reset formData when closing via handleOpenChange with resetOnClose true', () => {
+      const testData: TestFormData = {
+        id: '1',
+        name: 'John Doe',
+        email: 'john@example.com'
+      };
+      
+      const { result } = renderHook(() => useFormDialog<TestFormData>());
+      
+      act(() => {
+        result.current.openDialog(testData);
+      });
+      
+      act(() => {
+        result.current.handleOpenChange(false);
+      });
+      
+      expect(result.current.isOpen).toBe(false);
+      expect(result.current.formData).toBeNull();
+    });
+
+    it('should not reset formData when closing via handleOpenChange with resetOnClose false', () => {
+      const testData: TestFormData = {
+        id: '1',
+        name: 'John Doe',
+        email: 'john@example.com'
+      };
+      
+      const { result } = renderHook(() => 
+        useFormDialog<TestFormData>({ resetOnClose: false })
+      );
+      
+      act(() => {
+        result.current.openDialog(testData);
+      });
+      
+      act(() => {
+        result.current.handleOpenChange(false);
+      });
+      
+      expect(result.current.isOpen).toBe(false);
+      expect(result.current.formData).toEqual(testData);
+    });
+  });
+
+  describe('onOpenChange callback', () => {
+    it('should call onOpenChange when opening dialog', () => {
+      const onOpenChange = vi.fn();
+      const { result } = renderHook(() => 
+        useFormDialog({ onOpenChange })
+      );
+      
+      act(() => {
+        result.current.openDialog();
+      });
+      
+      expect(onOpenChange).toHaveBeenCalledWith(true);
+      expect(onOpenChange).toHaveBeenCalledTimes(1);
+    });
+
+    it('should call onOpenChange when closing dialog', () => {
+      const onOpenChange = vi.fn();
+      const { result } = renderHook(() => 
+        useFormDialog({ onOpenChange })
+      );
+      
+      act(() => {
+        result.current.openDialog();
+      });
+      
+      act(() => {
+        result.current.closeDialog();
+      });
+      
+      expect(onOpenChange).toHaveBeenCalledWith(false);
+      expect(onOpenChange).toHaveBeenCalledTimes(2); // Once for open, once for close
+    });
+
+    it('should call onOpenChange when using handleOpenChange', () => {
+      const onOpenChange = vi.fn();
+      const { result } = renderHook(() => 
+        useFormDialog({ onOpenChange })
+      );
+      
+      act(() => {
+        result.current.handleOpenChange(true);
+      });
+      
+      expect(onOpenChange).toHaveBeenCalledWith(true);
+      
+      act(() => {
+        result.current.handleOpenChange(false);
+      });
+      
+      expect(onOpenChange).toHaveBeenCalledWith(false);
+      expect(onOpenChange).toHaveBeenCalledTimes(2);
+    });
+
+    it('should not call onOpenChange if not provided', () => {
+      const { result } = renderHook(() => useFormDialog());
+      
+      act(() => {
+        result.current.openDialog();
+      });
+      
+      act(() => {
+        result.current.closeDialog();
+      });
+      
+      // Should not throw
+      expect(result.current.isOpen).toBe(false);
+    });
+  });
+
+  describe('Controlled vs uncontrolled usage', () => {
+    it('should work in uncontrolled mode (using openDialog/closeDialog)', () => {
+      const { result } = renderHook(() => useFormDialog());
+      
+      act(() => {
+        result.current.openDialog();
+      });
+      expect(result.current.isOpen).toBe(true);
+      
+      act(() => {
+        result.current.closeDialog();
+      });
+      expect(result.current.isOpen).toBe(false);
+    });
+
+    it('should work in controlled mode (using handleOpenChange)', () => {
+      const { result } = renderHook(() => useFormDialog());
+      
+      act(() => {
+        result.current.handleOpenChange(true);
+      });
+      expect(result.current.isOpen).toBe(true);
+      
+      act(() => {
+        result.current.handleOpenChange(false);
+      });
+      expect(result.current.isOpen).toBe(false);
+    });
+
+    it('should work with mixed usage', () => {
+      const { result } = renderHook(() => useFormDialog());
+      
+      act(() => {
+        result.current.openDialog();
+      });
+      expect(result.current.isOpen).toBe(true);
+      
+      act(() => {
+        result.current.handleOpenChange(false);
+      });
+      expect(result.current.isOpen).toBe(false);
+      
+      act(() => {
+        result.current.handleOpenChange(true);
+      });
+      expect(result.current.isOpen).toBe(true);
+      
+      act(() => {
+        result.current.closeDialog();
+      });
+      expect(result.current.isOpen).toBe(false);
+    });
+  });
+
+  describe('Edge cases', () => {
+    it('should handle rapid open/close operations', () => {
+      const { result } = renderHook(() => useFormDialog());
+      
+      act(() => {
+        result.current.openDialog();
+        result.current.closeDialog();
+        result.current.openDialog();
+        result.current.closeDialog();
+      });
+      
+      expect(result.current.isOpen).toBe(false);
+      expect(result.current.formData).toBeNull();
+    });
+
+    it('should handle opening with undefined data', () => {
+      const { result } = renderHook(() => useFormDialog<TestFormData>());
+      
+      act(() => {
+        result.current.openDialog(undefined as unknown as TestFormData);
+      });
+      
+      expect(result.current.isOpen).toBe(true);
+      // When undefined is passed, it becomes null in the state
+      expect(result.current.formData).toBeNull();
+    });
+
+    it('should handle replacing formData when dialog is already open', () => {
+      const initialData: TestFormData = {
+        id: '1',
+        name: 'John Doe',
+        email: 'john@example.com'
+      };
+      
+      const newData: TestFormData = {
+        id: '2',
+        name: 'Jane Doe',
+        email: 'jane@example.com'
+      };
+      
+      const { result } = renderHook(() => useFormDialog<TestFormData>());
+      
+      act(() => {
+        result.current.openDialog(initialData);
+      });
+      
+      expect(result.current.formData).toEqual(initialData);
+      
+      act(() => {
+        result.current.openDialog(newData);
+      });
+      
+      expect(result.current.isOpen).toBe(true);
+      expect(result.current.formData).toEqual(newData);
+    });
+
+    it('should handle closing when already closed', () => {
+      const { result } = renderHook(() => useFormDialog());
+      
+      expect(result.current.isOpen).toBe(false);
+      
+      act(() => {
+        result.current.closeDialog();
+      });
+      
+      expect(result.current.isOpen).toBe(false);
+      expect(result.current.formData).toBeNull();
+    });
+  });
+
+  describe('Type safety', () => {
+    it('should maintain type safety with generic type parameter', () => {
+      const testData: TestFormData = {
+        id: '1',
+        name: 'John Doe',
+        email: 'john@example.com'
+      };
+      
+      const { result } = renderHook(() => useFormDialog<TestFormData>());
+      
+      act(() => {
+        result.current.openDialog(testData);
+      });
+      
+      // TypeScript should infer the correct type
+      if (result.current.formData) {
+        expect(result.current.formData.id).toBe('1');
+        expect(result.current.formData.name).toBe('John Doe');
+        expect(result.current.formData.email).toBe('john@example.com');
+      }
+    });
+
+    it('should work with primitive types', () => {
+      const { result } = renderHook(() => useFormDialog<string>());
+      
+      act(() => {
+        result.current.openDialog('test string');
+      });
+      
+      expect(result.current.formData).toBe('test string');
+    });
+
+    it('should work with number types', () => {
+      const { result } = renderHook(() => useFormDialog<number>());
+      
+      act(() => {
+        result.current.openDialog(42);
+      });
+      
+      expect(result.current.formData).toBe(42);
+    });
+  });
+
+  describe('Options handling', () => {
+    it('should use default resetOnClose value of true', () => {
+      const testData: TestFormData = {
+        id: '1',
+        name: 'John Doe',
+        email: 'john@example.com'
+      };
+      
+      const { result } = renderHook(() => useFormDialog<TestFormData>());
+      
+      act(() => {
+        result.current.openDialog(testData);
+      });
+      
+      act(() => {
+        result.current.closeDialog();
+      });
+      
+      // Should reset by default
+      expect(result.current.formData).toBeNull();
+    });
+
+    it('should respect resetOnClose option', () => {
+      const testData: TestFormData = {
+        id: '1',
+        name: 'John Doe',
+        email: 'john@example.com'
+      };
+      
+      const { result } = renderHook(() => 
+        useFormDialog<TestFormData>({ resetOnClose: false })
+      );
+      
+      act(() => {
+        result.current.openDialog(testData);
+      });
+      
+      act(() => {
+        result.current.closeDialog();
+      });
+      
+      // Should not reset when resetOnClose is false
+      expect(result.current.formData).toEqual(testData);
+    });
+  });
+});

package/src/hooks/index.ts

@@ -39,6 +39,8 @@ export type { OrganisationSecurityHook } from './useOrganisationSecurity';
 
 // === FORM HOOKS ===
 export { useZodForm } from './useZodForm';
+export { useFormDialog } from './useFormDialog';
+export type { UseFormDialogOptions, UseFormDialogReturn } from './useFormDialog';
 
 
 // === PERFORMANCE HOOKS ===
@@ -62,6 +64,9 @@ export type { UseStorageOptions, UseStorageReturn } from './useStorage';
 // === PUBLIC DATA ACCESS HOOKS ===
 export * from './public';
 
+// === PAGE LIFECYCLE HOOKS ===
+export { usePreventTabReload } from './usePreventTabReload';
+export type { UsePreventTabReloadOptions } from './usePreventTabReload';
 
 // RBAC Hooks - Use @jmruthers/pace-core/rbac instead
 // Note: RBAC functionality has been moved to the dedicated RBAC module

package/src/hooks/useFileReference.test.ts

@@ -67,6 +67,8 @@ const mockFileUploadOptions = {
   organisation_id: 'test-org-123',
   app_id: 'test-app-123',
   category: FileCategory.GENERAL_DOCUMENTS,
+  folder: 'documents',
+  pageContext: 'configuration',
   is_public: false
 };
 

package/src/hooks/useFormDialog.ts

@@ -0,0 +1,147 @@
+/**
+ * @file useFormDialog Hook
+ * @package @jmruthers/pace-core
+ * @module Hooks
+ * @since 0.1.0
+ * 
+ * Generic React hook for managing form dialog state (open/close, form data, reset behavior).
+ * 
+ * @example
+ * ```ts
+ * interface ContactFormData {
+ *   name: string;
+ *   email: string;
+ * }
+ * 
+ * function ContactDialog() {
+ *   const { isOpen, formData, openDialog, closeDialog, handleOpenChange } = 
+ *     useFormDialog<ContactFormData>();
+ * 
+ *   // Use in Dialog component
+ *   // <Dialog open={isOpen} onOpenChange={handleOpenChange}>...</Dialog>
+ * }
+ * ```
+ */
+
+import { useState, useCallback } from 'react';
+
+/**
+ * Options for configuring the useFormDialog hook behavior
+ */
+export interface UseFormDialogOptions<T = unknown> {
+  /**
+   * Callback invoked when the dialog open state changes
+   * @param open - The new open state
+   */
+  onOpenChange?: (open: boolean) => void;
+  
+  /**
+   * Whether to reset form data when the dialog closes
+   * @default true
+   */
+  resetOnClose?: boolean;
+}
+
+/**
+ * Return type for the useFormDialog hook
+ */
+export interface UseFormDialogReturn<T = unknown> {
+  /**
+   * Current open state of the dialog
+   */
+  isOpen: boolean;
+  
+  /**
+   * Current form data (null when dialog is closed or no data provided)
+   */
+  formData: T | null;
+  
+  /**
+   * Open the dialog with optional form data
+   * @param data - Optional form data to populate the dialog
+   */
+  openDialog: (data?: T | null) => void;
+  
+  /**
+   * Close the dialog
+   */
+  closeDialog: () => void;
+  
+  /**
+   * Handler for controlled dialog components (e.g., Radix UI Dialog)
+   * @param open - The new open state
+   */
+  handleOpenChange: (open: boolean) => void;
+}
+
+/**
+ * Generic React hook for managing form dialog state.
+ * 
+ * Provides state management for form dialogs including:
+ * - Open/close state
+ * - Form data management
+ * - Automatic reset on close (configurable)
+ * - Controlled and uncontrolled usage patterns
+ * 
+ * @param options - Configuration options for the hook
+ * @returns Object containing dialog state and control functions
+ * 
+ * @example
+ * ```ts
+ * // Basic usage
+ * const { isOpen, openDialog, closeDialog } = useFormDialog();
+ * 
+ * // With form data
+ * interface UserData {
+ *   id: string;
+ *   name: string;
+ * }
+ * const { isOpen, formData, openDialog } = useFormDialog<UserData>();
+ * 
+ * // Open with data
+ * openDialog({ id: '1', name: 'John' });
+ * 
+ * // Controlled usage with callback
+ * const { handleOpenChange, isOpen } = useFormDialog({
+ *   onOpenChange: (open) => console.log('Dialog state:', open),
+ *   resetOnClose: false
+ * });
+ * ```
+ */
+export function useFormDialog<T = unknown>({
+  onOpenChange,
+  resetOnClose = true,
+}: UseFormDialogOptions<T> = {}): UseFormDialogReturn<T> {
+  const [isOpen, setIsOpen] = useState(false);
+  const [formData, setFormData] = useState<T | null>(null);
+
+  const openDialog = useCallback((data: T | null = null) => {
+    setFormData(data);
+    setIsOpen(true);
+    onOpenChange?.(true);
+  }, [onOpenChange]);
+
+  const closeDialog = useCallback(() => {
+    setIsOpen(false);
+    if (resetOnClose) {
+      setFormData(null);
+    }
+    onOpenChange?.(false);
+  }, [resetOnClose, onOpenChange]);
+
+  const handleOpenChange = useCallback((open: boolean) => {
+    setIsOpen(open);
+    if (!open && resetOnClose) {
+      setFormData(null);
+    }
+    onOpenChange?.(open);
+  }, [resetOnClose, onOpenChange]);
+
+  return {
+    isOpen,
+    formData,
+    openDialog,
+    closeDialog,
+    handleOpenChange,
+  };
+}