@jmruthers/pace-core 0.6.8 → 0.6.10

package/src/components/DataTable/hooks/__tests__/useKeyboardNavigation.test.ts

@@ -0,0 +1,787 @@
+/**
+ * @file Unit Tests for useKeyboardNavigation Hook
+ * @package @jmruthers/pace-core
+ * @module Components/DataTable/Hooks/__tests__
+ * @since 0.4.0
+ * 
+ * Comprehensive test suite for keyboard navigation hook following testing guidelines.
+ * Tests cover navigation behavior, focus management, and accessibility features.
+ */
+
+import { describe, it, expect, beforeEach, vi } from 'vitest';
+import { renderHook, act } from '@testing-library/react';
+import { useKeyboardNavigation } from '../useKeyboardNavigation';
+
+// Mock announce utility
+const mockAnnounce = vi.fn();
+vi.mock('../../utils/a11yUtils', () => ({
+  announce: (...args: unknown[]) => mockAnnounce(...args),
+}));
+
+describe('[unit] useKeyboardNavigation', () => {
+  beforeEach(() => {
+    vi.clearAllMocks();
+  });
+
+  describe('Initialization', () => {
+    it('initializes with default state', () => {
+      const { result } = renderHook(() =>
+        useKeyboardNavigation(5, 3)
+      );
+
+      expect(result.current.state.focusedRowIndex).toBe(0);
+      expect(result.current.state.focusedColumnIndex).toBe(0);
+      expect(result.current.state.isNavigating).toBe(false);
+    });
+
+    it('initializes with custom options', () => {
+      const onFocusChange = vi.fn();
+      const { result } = renderHook(() =>
+        useKeyboardNavigation(5, 3, {
+          enabled: true,
+          announceNavigation: true,
+          onFocusChange,
+        })
+      );
+
+      expect(result.current.state.focusedRowIndex).toBe(0);
+      expect(result.current.state.focusedColumnIndex).toBe(0);
+    });
+  });
+
+  describe('Focus Management', () => {
+    it('focuses a specific cell', () => {
+      const { result } = renderHook(() =>
+        useKeyboardNavigation(5, 3)
+      );
+
+      act(() => {
+        result.current.focusCell(2, 1);
+      });
+
+      expect(result.current.state.focusedRowIndex).toBe(2);
+      expect(result.current.state.focusedColumnIndex).toBe(1);
+    });
+
+    it('clamps row index to valid range', () => {
+      const { result } = renderHook(() =>
+        useKeyboardNavigation(5, 3)
+      );
+
+      act(() => {
+        result.current.focusCell(10, 1); // Out of range
+      });
+
+      expect(result.current.state.focusedRowIndex).toBe(4); // Clamped to max
+    });
+
+    it('clamps column index to valid range', () => {
+      const { result } = renderHook(() =>
+        useKeyboardNavigation(5, 3)
+      );
+
+      act(() => {
+        result.current.focusCell(2, 10); // Out of range
+      });
+
+      expect(result.current.state.focusedColumnIndex).toBe(2); // Clamped to max
+    });
+
+    it('calls onFocusChange callback when provided', () => {
+      const onFocusChange = vi.fn();
+      const { result } = renderHook(() =>
+        useKeyboardNavigation(5, 3, { onFocusChange })
+      );
+
+      act(() => {
+        result.current.focusCell(2, 1);
+      });
+
+      expect(onFocusChange).toHaveBeenCalledWith(2, 1);
+    });
+
+    it('announces navigation when enabled', () => {
+      const { result } = renderHook(() =>
+        useKeyboardNavigation(5, 3, { announceNavigation: true })
+      );
+
+      act(() => {
+        result.current.focusCell(2, 1);
+      });
+
+      expect(mockAnnounce).toHaveBeenCalledWith('Row 3, Column 2');
+    });
+  });
+
+  describe('Navigation Functions', () => {
+    it('moves focus to next cell', () => {
+      const { result } = renderHook(() =>
+        useKeyboardNavigation(5, 3)
+      );
+
+      act(() => {
+        result.current.focusCell(0, 0);
+      });
+
+      act(() => {
+        result.current.focusNext();
+      });
+
+      expect(result.current.state.focusedColumnIndex).toBe(1);
+    });
+
+    it('wraps to next row when at end of row', () => {
+      const { result } = renderHook(() =>
+        useKeyboardNavigation(5, 3)
+      );
+
+      act(() => {
+        result.current.focusCell(0, 2); // Last column
+      });
+
+      act(() => {
+        result.current.focusNext();
+      });
+
+      expect(result.current.state.focusedRowIndex).toBe(1);
+      expect(result.current.state.focusedColumnIndex).toBe(0);
+    });
+
+    it('moves focus to previous cell', () => {
+      const { result } = renderHook(() =>
+        useKeyboardNavigation(5, 3)
+      );
+
+      act(() => {
+        result.current.focusCell(1, 1);
+      });
+
+      act(() => {
+        result.current.focusPrevious();
+      });
+
+      expect(result.current.state.focusedColumnIndex).toBe(0);
+    });
+
+    it('wraps to previous row when at start of row', () => {
+      const { result } = renderHook(() =>
+        useKeyboardNavigation(5, 3)
+      );
+
+      act(() => {
+        result.current.focusCell(1, 0);
+      });
+
+      act(() => {
+        result.current.focusPrevious();
+      });
+
+      expect(result.current.state.focusedRowIndex).toBe(0);
+      expect(result.current.state.focusedColumnIndex).toBe(2); // Last column of previous row
+    });
+
+    it('moves focus up one row', () => {
+      const { result } = renderHook(() =>
+        useKeyboardNavigation(5, 3)
+      );
+
+      act(() => {
+        result.current.focusCell(2, 1);
+      });
+
+      act(() => {
+        result.current.focusUp();
+      });
+
+      expect(result.current.state.focusedRowIndex).toBe(1);
+      expect(result.current.state.focusedColumnIndex).toBe(1);
+    });
+
+    it('does not move up when at first row', () => {
+      const { result } = renderHook(() =>
+        useKeyboardNavigation(5, 3)
+      );
+
+      act(() => {
+        result.current.focusCell(0, 1);
+      });
+
+      act(() => {
+        result.current.focusUp();
+      });
+
+      expect(result.current.state.focusedRowIndex).toBe(0);
+    });
+
+    it('moves focus down one row', () => {
+      const { result } = renderHook(() =>
+        useKeyboardNavigation(5, 3)
+      );
+
+      act(() => {
+        result.current.focusCell(1, 1);
+      });
+
+      act(() => {
+        result.current.focusDown();
+      });
+
+      expect(result.current.state.focusedRowIndex).toBe(2);
+      expect(result.current.state.focusedColumnIndex).toBe(1);
+    });
+
+    it('does not move down when at last row', () => {
+      const { result } = renderHook(() =>
+        useKeyboardNavigation(5, 3)
+      );
+
+      act(() => {
+        result.current.focusCell(4, 1);
+      });
+
+      act(() => {
+        result.current.focusDown();
+      });
+
+      expect(result.current.state.focusedRowIndex).toBe(4);
+    });
+
+    it('moves focus to start of row', () => {
+      const { result } = renderHook(() =>
+        useKeyboardNavigation(5, 3)
+      );
+
+      act(() => {
+        result.current.focusCell(2, 2);
+      });
+
+      act(() => {
+        result.current.focusRowStart();
+      });
+
+      expect(result.current.state.focusedColumnIndex).toBe(0);
+    });
+
+    it('moves focus to end of row', () => {
+      const { result } = renderHook(() =>
+        useKeyboardNavigation(5, 3)
+      );
+
+      act(() => {
+        result.current.focusCell(2, 0);
+      });
+
+      act(() => {
+        result.current.focusRowEnd();
+      });
+
+      expect(result.current.state.focusedColumnIndex).toBe(2);
+    });
+
+    it('moves focus to table start', () => {
+      const { result } = renderHook(() =>
+        useKeyboardNavigation(5, 3)
+      );
+
+      act(() => {
+        result.current.focusCell(3, 2);
+        result.current.focusTableStart();
+      });
+
+      expect(result.current.state.focusedRowIndex).toBe(0);
+      expect(result.current.state.focusedColumnIndex).toBe(0);
+    });
+
+    it('moves focus to table end', () => {
+      const { result } = renderHook(() =>
+        useKeyboardNavigation(5, 3)
+      );
+
+      act(() => {
+        result.current.focusCell(1, 1);
+        result.current.focusTableEnd();
+      });
+
+      expect(result.current.state.focusedRowIndex).toBe(4);
+      expect(result.current.state.focusedColumnIndex).toBe(2);
+    });
+  });
+
+  describe('Tabindex Management', () => {
+    it('returns 0 for focused cell', () => {
+      const { result } = renderHook(() =>
+        useKeyboardNavigation(5, 3)
+      );
+
+      act(() => {
+        result.current.focusCell(2, 1);
+      });
+
+      expect(result.current.getCellTabIndex(2, 1)).toBe(0);
+    });
+
+    it('returns -1 for non-focused cells', () => {
+      const { result } = renderHook(() =>
+        useKeyboardNavigation(5, 3)
+      );
+
+      act(() => {
+        result.current.focusCell(2, 1);
+      });
+
+      expect(result.current.getCellTabIndex(0, 0)).toBe(-1);
+      expect(result.current.getCellTabIndex(2, 0)).toBe(-1);
+    });
+
+    it('returns -1 when navigation is disabled', () => {
+      const { result } = renderHook(() =>
+        useKeyboardNavigation(5, 3, { enabled: false })
+      );
+
+      expect(result.current.getCellTabIndex(0, 0)).toBe(-1);
+    });
+  });
+
+  describe('Keyboard Event Handlers', () => {
+    it('handles ArrowRight key', () => {
+      const { result } = renderHook(() =>
+        useKeyboardNavigation(5, 3)
+      );
+
+      act(() => {
+        result.current.focusCell(1, 1);
+      });
+
+      const handlers = result.current.getCellKeyboardHandlers(1, 1);
+      const mockEvent = {
+        key: 'ArrowRight',
+        preventDefault: vi.fn(),
+      } as unknown as React.KeyboardEvent;
+
+      act(() => {
+        handlers.onKeyDown(mockEvent);
+      });
+
+      expect(mockEvent.preventDefault).toHaveBeenCalled();
+      // Navigation happens via focusCell which updates state
+      expect(result.current.state.focusedColumnIndex).toBe(2);
+    });
+
+    it('handles ArrowRight with Ctrl/Meta to move to row end', () => {
+      const { result } = renderHook(() =>
+        useKeyboardNavigation(5, 3)
+      );
+
+      act(() => {
+        result.current.focusCell(1, 1);
+      });
+
+      const handlers = result.current.getCellKeyboardHandlers(1, 1);
+      const mockEvent = {
+        key: 'ArrowRight',
+        ctrlKey: true,
+        preventDefault: vi.fn(),
+      } as unknown as React.KeyboardEvent;
+
+      act(() => {
+        handlers.onKeyDown(mockEvent);
+      });
+
+      expect(mockEvent.preventDefault).toHaveBeenCalled();
+      expect(result.current.state.focusedColumnIndex).toBe(2); // Row end
+    });
+
+    it('handles ArrowLeft key', () => {
+      const { result } = renderHook(() =>
+        useKeyboardNavigation(5, 3)
+      );
+
+      act(() => {
+        result.current.focusCell(1, 2);
+      });
+
+      const handlers = result.current.getCellKeyboardHandlers(1, 2);
+      const mockEvent = {
+        key: 'ArrowLeft',
+        preventDefault: vi.fn(),
+      } as unknown as React.KeyboardEvent;
+
+      act(() => {
+        handlers.onKeyDown(mockEvent);
+      });
+
+      expect(mockEvent.preventDefault).toHaveBeenCalled();
+      expect(result.current.state.focusedColumnIndex).toBe(1);
+    });
+
+    it('handles ArrowDown key', () => {
+      const { result } = renderHook(() =>
+        useKeyboardNavigation(5, 3)
+      );
+
+      act(() => {
+        result.current.focusCell(1, 1);
+      });
+
+      const handlers = result.current.getCellKeyboardHandlers(1, 1);
+      const mockEvent = {
+        key: 'ArrowDown',
+        preventDefault: vi.fn(),
+      } as unknown as React.KeyboardEvent;
+
+      act(() => {
+        handlers.onKeyDown(mockEvent);
+      });
+
+      expect(mockEvent.preventDefault).toHaveBeenCalled();
+      expect(result.current.state.focusedRowIndex).toBe(2);
+    });
+
+    it('handles ArrowUp key', () => {
+      const { result } = renderHook(() =>
+        useKeyboardNavigation(5, 3)
+      );
+
+      act(() => {
+        result.current.focusCell(2, 1);
+      });
+
+      const handlers = result.current.getCellKeyboardHandlers(2, 1);
+      const mockEvent = {
+        key: 'ArrowUp',
+        preventDefault: vi.fn(),
+      } as unknown as React.KeyboardEvent;
+
+      act(() => {
+        handlers.onKeyDown(mockEvent);
+      });
+
+      expect(mockEvent.preventDefault).toHaveBeenCalled();
+      expect(result.current.state.focusedRowIndex).toBe(1);
+    });
+
+    it('handles Home key', () => {
+      const { result } = renderHook(() =>
+        useKeyboardNavigation(5, 3)
+      );
+
+      act(() => {
+        result.current.focusCell(2, 2);
+      });
+
+      const handlers = result.current.getCellKeyboardHandlers(2, 2);
+      const mockEvent = {
+        key: 'Home',
+        preventDefault: vi.fn(),
+      } as unknown as React.KeyboardEvent;
+
+      act(() => {
+        handlers.onKeyDown(mockEvent);
+      });
+
+      expect(mockEvent.preventDefault).toHaveBeenCalled();
+      expect(result.current.state.focusedColumnIndex).toBe(0);
+    });
+
+    it('handles Home with Ctrl/Meta to move to table start', () => {
+      const { result } = renderHook(() =>
+        useKeyboardNavigation(5, 3)
+      );
+
+      act(() => {
+        result.current.focusCell(2, 2);
+      });
+
+      const handlers = result.current.getCellKeyboardHandlers(2, 2);
+      const mockEvent = {
+        key: 'Home',
+        ctrlKey: true,
+        preventDefault: vi.fn(),
+      } as unknown as React.KeyboardEvent;
+
+      act(() => {
+        handlers.onKeyDown(mockEvent);
+      });
+
+      expect(mockEvent.preventDefault).toHaveBeenCalled();
+      expect(result.current.state.focusedRowIndex).toBe(0);
+      expect(result.current.state.focusedColumnIndex).toBe(0);
+    });
+
+    it('handles End key', () => {
+      const { result } = renderHook(() =>
+        useKeyboardNavigation(5, 3)
+      );
+
+      act(() => {
+        result.current.focusCell(2, 0);
+      });
+
+      const handlers = result.current.getCellKeyboardHandlers(2, 0);
+      const mockEvent = {
+        key: 'End',
+        preventDefault: vi.fn(),
+      } as unknown as React.KeyboardEvent;
+
+      act(() => {
+        handlers.onKeyDown(mockEvent);
+      });
+
+      expect(mockEvent.preventDefault).toHaveBeenCalled();
+      expect(result.current.state.focusedColumnIndex).toBe(2);
+    });
+
+    it('does not prevent default for Tab key', () => {
+      const { result } = renderHook(() =>
+        useKeyboardNavigation(5, 3)
+      );
+
+      const handlers = result.current.getCellKeyboardHandlers(1, 1);
+      const mockEvent = {
+        key: 'Tab',
+        preventDefault: vi.fn(),
+      } as unknown as React.KeyboardEvent;
+
+      act(() => {
+        handlers.onKeyDown(mockEvent);
+      });
+
+      expect(mockEvent.preventDefault).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('Focus Event Handlers', () => {
+    it('updates state on focus', () => {
+      const { result } = renderHook(() =>
+        useKeyboardNavigation(5, 3)
+      );
+
+      const handlers = result.current.getCellKeyboardHandlers(2, 1);
+      const mockEvent = {
+        target: {},
+      } as React.FocusEvent;
+
+      act(() => {
+        handlers.onFocus(mockEvent);
+      });
+
+      expect(result.current.state.focusedRowIndex).toBe(2);
+      expect(result.current.state.focusedColumnIndex).toBe(1);
+      expect(result.current.state.isNavigating).toBe(true);
+    });
+
+    it('clears navigation state on blur after delay', async () => {
+      vi.useFakeTimers();
+      const { result } = renderHook(() =>
+        useKeyboardNavigation(5, 3)
+      );
+
+      act(() => {
+        result.current.focusCell(2, 1);
+      });
+
+      const handlers = result.current.getCellKeyboardHandlers(2, 1);
+      const mockEvent = {
+        target: {},
+      } as React.FocusEvent;
+
+      act(() => {
+        handlers.onBlur(mockEvent);
+      });
+
+      expect(result.current.state.isNavigating).toBe(true);
+
+      act(() => {
+        vi.advanceTimersByTime(100);
+      });
+
+      expect(result.current.state.isNavigating).toBe(false);
+
+      vi.useRealTimers();
+    });
+  });
+
+  describe('Header Keyboard Handlers', () => {
+    it('handles Enter key for sorting', () => {
+      const onSort = vi.fn();
+      const { result } = renderHook(() =>
+        useKeyboardNavigation(5, 3)
+      );
+
+      const handlers = result.current.getHeaderKeyboardHandlers(1, onSort);
+      const mockEvent = {
+        key: 'Enter',
+        preventDefault: vi.fn(),
+      } as unknown as React.KeyboardEvent;
+
+      act(() => {
+        handlers.onKeyDown(mockEvent);
+      });
+
+      expect(mockEvent.preventDefault).toHaveBeenCalled();
+      expect(onSort).toHaveBeenCalled();
+    });
+
+    it('handles Space key for sorting', () => {
+      const onSort = vi.fn();
+      const { result } = renderHook(() =>
+        useKeyboardNavigation(5, 3)
+      );
+
+      const handlers = result.current.getHeaderKeyboardHandlers(1, onSort);
+      const mockEvent = {
+        key: ' ',
+        preventDefault: vi.fn(),
+      } as unknown as React.KeyboardEvent;
+
+      act(() => {
+        handlers.onKeyDown(mockEvent);
+      });
+
+      expect(onSort).toHaveBeenCalled();
+    });
+
+    it('handles ArrowRight in header to move to next header', () => {
+      const { result } = renderHook(() =>
+        useKeyboardNavigation(5, 3)
+      );
+
+      const handlers = result.current.getHeaderKeyboardHandlers(1);
+      const mockEvent = {
+        key: 'ArrowRight',
+        preventDefault: vi.fn(),
+      } as unknown as React.KeyboardEvent;
+
+      act(() => {
+        handlers.onKeyDown(mockEvent);
+      });
+
+      expect(mockEvent.preventDefault).toHaveBeenCalled();
+    });
+  });
+
+  describe('Focus Storage and Restoration', () => {
+    it('stores and restores focus position', () => {
+      const { result } = renderHook(() =>
+        useKeyboardNavigation(5, 3)
+      );
+
+      act(() => {
+        result.current.focusCell(2, 1);
+      });
+
+      act(() => {
+        result.current.storeFocus();
+      });
+
+      act(() => {
+        result.current.focusCell(0, 0);
+      });
+
+      act(() => {
+        result.current.restoreFocus();
+      });
+
+      expect(result.current.state.focusedRowIndex).toBe(2);
+      expect(result.current.state.focusedColumnIndex).toBe(1);
+    });
+
+    it('resets focus to origin', () => {
+      const { result } = renderHook(() =>
+        useKeyboardNavigation(5, 3)
+      );
+
+      act(() => {
+        result.current.focusCell(3, 2);
+        result.current.resetFocus();
+      });
+
+      expect(result.current.state.focusedRowIndex).toBe(0);
+      expect(result.current.state.focusedColumnIndex).toBe(0);
+      expect(result.current.state.isNavigating).toBe(false);
+    });
+  });
+
+  describe('Disabled State', () => {
+    it('does not update state when disabled', () => {
+      const { result } = renderHook(() =>
+        useKeyboardNavigation(5, 3, { enabled: false })
+      );
+
+      act(() => {
+        result.current.focusCell(2, 1);
+      });
+
+      expect(result.current.state.focusedRowIndex).toBe(0);
+      expect(result.current.state.focusedColumnIndex).toBe(0);
+    });
+
+    it('does not handle keyboard events when disabled', () => {
+      const { result } = renderHook(() =>
+        useKeyboardNavigation(5, 3, { enabled: false })
+      );
+
+      const handlers = result.current.getCellKeyboardHandlers(1, 1);
+      const mockEvent = {
+        key: 'ArrowRight',
+        preventDefault: vi.fn(),
+      } as unknown as React.KeyboardEvent;
+
+      act(() => {
+        handlers.onKeyDown(mockEvent);
+      });
+
+      expect(mockEvent.preventDefault).not.toHaveBeenCalled();
+    });
+  });
+
+  describe('Edge Cases', () => {
+    it('handles single row table', () => {
+      const { result } = renderHook(() =>
+        useKeyboardNavigation(1, 3)
+      );
+
+      act(() => {
+        result.current.focusDown();
+      });
+
+      expect(result.current.state.focusedRowIndex).toBe(0);
+    });
+
+    it('handles single column table', () => {
+      const { result } = renderHook(() =>
+        useKeyboardNavigation(5, 1)
+      );
+
+      act(() => {
+        result.current.focusNext();
+      });
+
+      expect(result.current.state.focusedColumnIndex).toBe(0);
+    });
+
+    it('handles zero rows', () => {
+      const { result } = renderHook(() =>
+        useKeyboardNavigation(0, 3)
+      );
+
+      act(() => {
+        result.current.focusCell(0, 1);
+      });
+
+      expect(result.current.state.focusedRowIndex).toBe(0);
+    });
+
+    it('handles zero columns', () => {
+      const { result } = renderHook(() =>
+        useKeyboardNavigation(5, 0)
+      );
+
+      act(() => {
+        result.current.focusCell(2, 0);
+      });
+
+      expect(result.current.state.focusedColumnIndex).toBe(0);
+    });
+  });
+});