@tpzdsp/next-toolkit 1.12.1 → 1.13.0

package/src/components/InfoBox/hooks/useInfoBoxPosition.test.ts

@@ -0,0 +1,187 @@
+import type { RefObject } from 'react';
+
+import { renderHook, act } from '../../../test/renderers';
+import { POSITION_TOP_LEFT, POSITION_BOTTOM_RIGHT } from '../types';
+import { useInfoBoxPosition } from './useInfoBoxPosition';
+
+// Helper to avoid deep nesting in tests
+const renderInfoBoxPosition = (props: Parameters<typeof useInfoBoxPosition>[0]) =>
+  renderHook(() => useInfoBoxPosition(props));
+
+// Helper for rerenderable hook with isOpen parameter
+const renderInfoBoxPositionWithIsOpen = (
+  triggerRef: RefObject<HTMLElement>,
+  forcedPosition?: Parameters<typeof useInfoBoxPosition>[0]['forcedPosition'],
+  initialIsOpen = false,
+) =>
+  renderHook(({ isOpen }) => useInfoBoxPosition({ isOpen, triggerRef, forcedPosition }), {
+    initialProps: { isOpen: initialIsOpen },
+  });
+
+// Mock factory helpers to avoid deep nesting
+const createMockRect = (top: number, left: number, width = 24, height = 24) => ({
+  top,
+  left,
+  bottom: top + height,
+  right: left + width,
+  width,
+  height,
+  x: left,
+  y: top,
+  toJSON: () => ({}),
+});
+
+describe('useInfoBoxPosition', () => {
+  let mockTriggerElement: HTMLElement;
+  let triggerRef: RefObject<HTMLElement>;
+
+  beforeEach(() => {
+    // Mock window dimensions
+    Object.defineProperty(globalThis, 'innerWidth', {
+      value: 1000,
+      writable: true,
+      configurable: true,
+    });
+    Object.defineProperty(globalThis, 'innerHeight', {
+      value: 800,
+      writable: true,
+      configurable: true,
+    });
+
+    // Create mock trigger element
+    mockTriggerElement = document.createElement('button');
+    triggerRef = { current: mockTriggerElement };
+
+    // Mock getBoundingClientRect
+    mockTriggerElement.getBoundingClientRect = vi.fn(() => createMockRect(100, 100));
+  });
+
+  afterEach(() => {
+    vi.clearAllMocks();
+  });
+
+  describe('initialization', () => {
+    it('should start with default position', () => {
+      const { result } = renderInfoBoxPosition({
+        isOpen: false,
+        triggerRef,
+      });
+
+      expect(result.current.calculatedPosition).toBe(POSITION_BOTTOM_RIGHT);
+      expect(result.current.contentPosition).toEqual({ top: 0, left: 0 });
+    });
+
+    it('should not update position when closed', () => {
+      renderInfoBoxPosition({
+        isOpen: false,
+        triggerRef,
+      });
+
+      expect(mockTriggerElement.getBoundingClientRect).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('position calculation', () => {
+    it('should calculate position when opened', () => {
+      const { result, rerender } = renderInfoBoxPositionWithIsOpen(triggerRef);
+
+      rerender({ isOpen: true });
+
+      expect(result.current.calculatedPosition).toBe(POSITION_BOTTOM_RIGHT);
+      expect(result.current.contentPosition.top).toBeGreaterThan(0);
+      expect(result.current.contentPosition.left).toBeGreaterThan(0);
+    });
+
+    it('should use forced position when provided', () => {
+      const { result, rerender } = renderInfoBoxPositionWithIsOpen(triggerRef, POSITION_TOP_LEFT);
+
+      rerender({ isOpen: true });
+
+      expect(result.current.calculatedPosition).toBe(POSITION_TOP_LEFT);
+    });
+
+    it('should handle trigger in top-left quadrant', () => {
+      mockTriggerElement.getBoundingClientRect = vi.fn(() => createMockRect(100, 100));
+
+      const { result, rerender } = renderInfoBoxPositionWithIsOpen(triggerRef);
+
+      rerender({ isOpen: true });
+
+      // top=100 < 400 (half of 800) -> bottom
+      // left=100 < 500 (half of 1000) -> right
+      expect(result.current.calculatedPosition).toBe(POSITION_BOTTOM_RIGHT);
+    });
+
+    it('should handle trigger in bottom-right quadrant', () => {
+      mockTriggerElement.getBoundingClientRect = vi.fn(() => createMockRect(700, 800));
+
+      const { result, rerender } = renderInfoBoxPositionWithIsOpen(triggerRef);
+
+      rerender({ isOpen: true });
+
+      // top=700 >= 400 (half of 800) -> top
+      // left=800 >= 500 (half of 1000) -> left
+      expect(result.current.calculatedPosition).toBe(POSITION_TOP_LEFT);
+    });
+  });
+
+  describe('manual position update', () => {
+    it('should allow manual position updates', () => {
+      const { result, rerender } = renderInfoBoxPositionWithIsOpen(triggerRef);
+
+      rerender({ isOpen: true });
+
+      const initialPosition = { ...result.current.contentPosition };
+
+      // Change trigger position
+      mockTriggerElement.getBoundingClientRect = vi.fn(() => createMockRect(200, 200));
+
+      act(() => {
+        result.current.updateContentPosition();
+      });
+
+      expect(result.current.contentPosition).not.toEqual(initialPosition);
+    });
+  });
+
+  describe('event listeners', () => {
+    it('should add resize listener when open', () => {
+      const addEventListenerSpy = vi.spyOn(globalThis, 'addEventListener');
+
+      const { rerender } = renderInfoBoxPositionWithIsOpen(triggerRef);
+
+      rerender({ isOpen: true });
+
+      expect(addEventListenerSpy).toHaveBeenCalledWith('resize', expect.any(Function));
+      expect(addEventListenerSpy).toHaveBeenCalledWith('scroll', expect.any(Function), true);
+    });
+
+    it('should remove listeners when closed', () => {
+      const removeEventListenerSpy = vi.spyOn(globalThis, 'removeEventListener');
+
+      const { rerender, unmount } = renderInfoBoxPositionWithIsOpen(triggerRef, undefined, true);
+
+      rerender({ isOpen: false });
+      unmount();
+
+      expect(removeEventListenerSpy).toHaveBeenCalledWith('resize', expect.any(Function));
+      expect(removeEventListenerSpy).toHaveBeenCalledWith('scroll', expect.any(Function), true);
+    });
+  });
+
+  describe('edge cases', () => {
+    it('should handle null triggerRef', () => {
+      const nullRef = { current: null } as unknown as RefObject<HTMLElement>;
+
+      const { result } = renderInfoBoxPosition({
+        isOpen: true,
+        triggerRef: nullRef,
+      });
+
+      result.current.updateContentPosition();
+
+      // Should not throw - test passes if no error
+      expect(result.current.calculatedPosition).toBe(POSITION_BOTTOM_RIGHT);
+    });
+  });
+});

package/src/components/InfoBox/hooks/useInfoBoxPosition.ts

@@ -0,0 +1,69 @@
+import { useCallback, useEffect, useState, type RefObject } from 'react';
+
+import type { Position } from '../types';
+import { POSITION_BOTTOM_RIGHT } from '../types';
+import { calculatePosition, calculateContentPosition } from '../utils/positionUtils';
+
+type UseInfoBoxPositionProps = {
+  isOpen: boolean;
+  triggerRef: RefObject<HTMLElement | null>;
+  forcedPosition?: Position;
+};
+
+type UseInfoBoxPositionReturn = {
+  calculatedPosition: Position;
+  contentPosition: { top: number; left: number };
+  updateContentPosition: () => void;
+};
+
+/**
+ * Hook to manage InfoBox positioning relative to trigger and viewport
+ */
+export const useInfoBoxPosition = ({
+  isOpen,
+  triggerRef,
+  forcedPosition,
+}: UseInfoBoxPositionProps): UseInfoBoxPositionReturn => {
+  const [calculatedPosition, setCalculatedPosition] = useState<Position>(POSITION_BOTTOM_RIGHT);
+  const [contentPosition, setContentPosition] = useState({ top: 0, left: 0 });
+
+  const updateContentPosition = useCallback(() => {
+    if (!triggerRef.current) {
+      return;
+    }
+
+    const position = calculatePosition(triggerRef.current, forcedPosition);
+    const { top, left } = calculateContentPosition(triggerRef.current, position);
+
+    setCalculatedPosition(position);
+    setContentPosition({ top, left });
+  }, [triggerRef, forcedPosition]);
+
+  // Update position when opening
+  useEffect(() => {
+    if (isOpen) {
+      updateContentPosition();
+    }
+  }, [isOpen, updateContentPosition]);
+
+  // Handle window resize and scroll while open
+  useEffect(() => {
+    if (!isOpen) {
+      return;
+    }
+
+    window.addEventListener('resize', updateContentPosition);
+    window.addEventListener('scroll', updateContentPosition, true);
+
+    return () => {
+      window.removeEventListener('resize', updateContentPosition);
+      window.removeEventListener('scroll', updateContentPosition, true);
+    };
+  }, [isOpen, updateContentPosition]);
+
+  return {
+    calculatedPosition,
+    contentPosition,
+    updateContentPosition,
+  };
+};

package/src/components/InfoBox/hooks/useInfoBoxState.test.ts

@@ -0,0 +1,168 @@
+import { useInfoBoxState } from './useInfoBoxState';
+import { renderHook, act } from '../../../test/renderers';
+
+// Helper to avoid deep nesting in tests
+const renderInfoBoxState = (props = {}) => renderHook(() => useInfoBoxState(props));
+
+describe('useInfoBoxState', () => {
+  describe('initialization', () => {
+    it('should start closed by default', () => {
+      const { result } = renderInfoBoxState({});
+
+      expect(result.current.isOpen).toBe(false);
+      expect(result.current.isTrapActive).toBe(false);
+    });
+
+    it('should respect defaultOpen prop', () => {
+      const { result } = renderInfoBoxState({ defaultOpen: true });
+
+      expect(result.current.isOpen).toBe(true);
+    });
+
+    it('should initialize refs correctly', () => {
+      const { result } = renderInfoBoxState({});
+
+      expect(result.current.isOpenRef.current).toBe(false);
+      expect(result.current.deactivatedByClick.current).toBe(false);
+    });
+  });
+
+  describe('opening and closing', () => {
+    it('should open when handleOpen is called', () => {
+      const { result } = renderInfoBoxState({});
+
+      act(() => {
+        result.current.handleOpen();
+      });
+
+      expect(result.current.isOpen).toBe(true);
+    });
+
+    it('should close when handleClose is called', () => {
+      const { result } = renderInfoBoxState({ defaultOpen: true });
+
+      act(() => {
+        result.current.handleClose();
+      });
+
+      expect(result.current.isOpen).toBe(false);
+      expect(result.current.isTrapActive).toBe(false);
+    });
+
+    it('should toggle state when toggleOpen is called', () => {
+      const { result } = renderInfoBoxState({});
+
+      act(() => {
+        result.current.toggleOpen();
+      });
+
+      expect(result.current.isOpen).toBe(true);
+
+      act(() => {
+        result.current.toggleOpen();
+      });
+
+      expect(result.current.isOpen).toBe(false);
+    });
+  });
+
+  describe('focus trap activation', () => {
+    it('should activate trap when opened', () => {
+      const { result } = renderInfoBoxState({});
+
+      act(() => {
+        result.current.handleOpen();
+      });
+
+      expect(result.current.isTrapActive).toBe(true);
+    });
+
+    it('should deactivate trap when closed', () => {
+      const { result } = renderInfoBoxState({ defaultOpen: true });
+
+      act(() => {
+        result.current.handleClose();
+      });
+
+      expect(result.current.isTrapActive).toBe(false);
+    });
+
+    it('should allow manual trap control', () => {
+      const { result } = renderInfoBoxState({});
+
+      act(() => {
+        result.current.setIsTrapActive(true);
+      });
+
+      expect(result.current.isTrapActive).toBe(true);
+
+      act(() => {
+        result.current.setIsTrapActive(false);
+      });
+
+      expect(result.current.isTrapActive).toBe(false);
+    });
+  });
+
+  describe('callbacks', () => {
+    it('should call onOpenChange when opening', () => {
+      const onOpenChange = vi.fn();
+      const { result } = renderInfoBoxState({ onOpenChange });
+
+      act(() => {
+        result.current.handleOpen();
+      });
+
+      expect(onOpenChange).toHaveBeenCalledWith(true);
+    });
+
+    it('should call onOpenChange when closing', () => {
+      const onOpenChange = vi.fn();
+      const { result } = renderInfoBoxState({ defaultOpen: true, onOpenChange });
+
+      act(() => {
+        result.current.handleClose();
+      });
+
+      expect(onOpenChange).toHaveBeenCalledWith(false);
+    });
+
+    it('should not call onOpenChange if not provided', () => {
+      const { result } = renderInfoBoxState({});
+
+      // Should not throw
+      act(() => {
+        result.current.handleOpen();
+      });
+
+      expect(result.current.isOpen).toBe(true);
+    });
+  });
+
+  describe('ref synchronization', () => {
+    it('should keep isOpenRef in sync with isOpen state', () => {
+      const { result, rerender } = renderInfoBoxState({});
+
+      expect(result.current.isOpenRef.current).toBe(false);
+
+      act(() => {
+        result.current.handleOpen();
+      });
+
+      rerender();
+
+      expect(result.current.isOpenRef.current).toBe(true);
+    });
+
+    it('should reset deactivatedByClick when state changes', () => {
+      const { result } = renderInfoBoxState({});
+
+      act(() => {
+        result.current.deactivatedByClick.current = true;
+        result.current.handleOpen();
+      });
+
+      expect(result.current.deactivatedByClick.current).toBe(false);
+    });
+  });
+});

package/src/components/InfoBox/hooks/useInfoBoxState.ts

@@ -0,0 +1,71 @@
+import { useCallback, useEffect, useRef, useState } from 'react';
+
+type UseInfoBoxStateProps = {
+  defaultOpen?: boolean;
+  onOpenChange?: (isOpen: boolean) => void;
+};
+
+type UseInfoBoxStateReturn = {
+  isOpen: boolean;
+  isTrapActive: boolean;
+  setIsTrapActive: (active: boolean) => void;
+  isOpenRef: { current: boolean };
+  deactivatedByClick: { current: boolean };
+  handleOpen: () => void;
+  handleClose: () => void;
+  toggleOpen: () => void;
+};
+
+/**
+ * Hook to manage InfoBox open/close state and focus trap lifecycle
+ */
+export const useInfoBoxState = ({
+  defaultOpen = false,
+  onOpenChange,
+}: UseInfoBoxStateProps): UseInfoBoxStateReturn => {
+  const [isOpen, setIsOpen] = useState(defaultOpen);
+  const [isTrapActive, setIsTrapActive] = useState(false);
+
+  const isOpenRef = useRef(isOpen);
+  const deactivatedByClick = useRef(false);
+
+  // Keep ref in sync with state
+  useEffect(() => {
+    isOpenRef.current = isOpen;
+    deactivatedByClick.current = false;
+
+    if (isOpen) {
+      setIsTrapActive(true);
+    }
+  }, [isOpen]);
+
+  const handleOpen = useCallback(() => {
+    setIsOpen(true);
+    onOpenChange?.(true);
+  }, [onOpenChange]);
+
+  const handleClose = useCallback(() => {
+    setIsOpen(false);
+    setIsTrapActive(false);
+    onOpenChange?.(false);
+  }, [onOpenChange]);
+
+  const toggleOpen = useCallback(() => {
+    if (isOpen) {
+      handleClose();
+    } else {
+      handleOpen();
+    }
+  }, [isOpen, handleOpen, handleClose]);
+
+  return {
+    isOpen,
+    isTrapActive,
+    setIsTrapActive,
+    isOpenRef,
+    deactivatedByClick,
+    handleOpen,
+    handleClose,
+    toggleOpen,
+  };
+};

package/src/components/InfoBox/hooks/usePortalMount.test.ts

@@ -0,0 +1,62 @@
+import { usePortalMount } from './usePortalMount';
+import { renderHook } from '../../../test/renderers';
+
+// Helper to avoid deep nesting in tests
+const renderPortalMount = () => renderHook(() => usePortalMount());
+
+describe('usePortalMount', () => {
+  describe('initialization', () => {
+    it('should return false initially in SSR context', () => {
+      const { result } = renderPortalMount();
+
+      // In test environment, useEffect runs immediately, so it will be true
+      // In real SSR, this would be false on server and true on client
+      expect(result.current).toBe(true);
+    });
+  });
+
+  describe('mounting', () => {
+    it('should return true after mount', () => {
+      const { result, rerender } = renderPortalMount();
+
+      // In test environment, useEffect runs immediately
+      expect(result.current).toBe(true);
+
+      // Trigger effect by rerendering
+      rerender();
+
+      // Should remain true
+      expect(result.current).toBe(true);
+    });
+
+    it('should remain true on subsequent rerenders', () => {
+      const { result, rerender } = renderPortalMount();
+
+      rerender();
+      expect(result.current).toBe(true);
+
+      rerender();
+      expect(result.current).toBe(true);
+    });
+  });
+
+  describe('SSR safety', () => {
+    it('should not throw when rendered', () => {
+      expect(() => renderPortalMount()).not.toThrow();
+    });
+
+    it('should always return boolean', () => {
+      const { result } = renderPortalMount();
+
+      expect(typeof result.current).toBe('boolean');
+    });
+  });
+
+  describe('cleanup', () => {
+    it('should not throw on unmount', () => {
+      const { unmount } = renderPortalMount();
+
+      expect(() => unmount()).not.toThrow();
+    });
+  });
+});

package/src/components/InfoBox/hooks/usePortalMount.ts

@@ -0,0 +1,15 @@
+import { useEffect, useState } from 'react';
+
+/**
+ * Hook to handle SSR-safe portal mounting
+ * Ensures portal only renders after component mounts on client
+ */
+export const usePortalMount = (): boolean => {
+  const [isMounted, setIsMounted] = useState(false);
+
+  useEffect(() => {
+    setIsMounted(true);
+  }, []);
+
+  return isMounted;
+};

package/src/components/InfoBox/types.ts

@@ -0,0 +1,6 @@
+export type Position = 'top-left' | 'top-right' | 'bottom-left' | 'bottom-right';
+
+export const POSITION_TOP_LEFT: Position = 'top-left';
+export const POSITION_TOP_RIGHT: Position = 'top-right';
+export const POSITION_BOTTOM_LEFT: Position = 'bottom-left';
+export const POSITION_BOTTOM_RIGHT: Position = 'bottom-right';