@optilogic/core 1.0.0-beta.0

package/src/components/data-grid/hooks/useKeyboardNavigation.ts

@@ -0,0 +1,361 @@
+/**
+ * useKeyboardNavigation Hook
+ *
+ * Handles keyboard navigation for the DataGrid component including:
+ * - Arrow keys: Move between cells
+ * - Enter: Start editing / commit edit
+ * - Escape: Cancel edit
+ * - Tab/Shift+Tab: Move to next/previous cell
+ * - Home/End: Jump to first/last cell in row
+ * - Ctrl+Home/End: Jump to first/last cell in grid
+ * - Page Up/Down: Scroll by visible page
+ */
+
+import { useCallback, useRef } from "react";
+import type { CellPosition, ColumnDef, EditingCell } from "../types";
+
+export interface UseKeyboardNavigationOptions<T = any> {
+  /** Whether keyboard navigation is enabled */
+  enabled: boolean;
+  /** Current focused cell */
+  focusedCell: CellPosition | null;
+  /** Current editing cell */
+  editingCell: EditingCell | null;
+  /** Column definitions (for determining visible columns) */
+  columns: ColumnDef<T>[];
+  /** Total number of rows */
+  rowCount: number;
+  /** Number of visible rows (for page up/down) */
+  visibleRowCount?: number;
+  /** Callback to set focused cell */
+  onFocusedCellChange: (cell: CellPosition | null) => void;
+  /** Callback to start editing */
+  onStartEditing: (rowIndex: number, columnKey: string) => void;
+  /** Callback to commit edit */
+  onCommitEdit: () => void;
+  /** Callback to cancel edit */
+  onCancelEdit: () => void;
+  /** Callback to scroll a row into view */
+  onScrollToRow?: (rowIndex: number) => void;
+  /** Callback to scroll a column into view */
+  onScrollToColumn?: (columnKey: string) => void;
+}
+
+export interface UseKeyboardNavigationReturn {
+  /** Handler to attach to the grid container */
+  handleKeyDown: (event: React.KeyboardEvent) => void;
+  /** Ref to attach to the grid container for focus management */
+  containerRef: React.RefObject<HTMLDivElement>;
+  /** Focus the container (useful after clicking a cell) */
+  focusContainer: () => void;
+}
+
+/**
+ * Get visible (non-hidden) columns
+ */
+function getVisibleColumns<T>(columns: ColumnDef<T>[]): ColumnDef<T>[] {
+  return columns.filter((col) => !col.hidden);
+}
+
+/**
+ * Hook to handle keyboard navigation in the DataGrid
+ */
+export function useKeyboardNavigation<T = any>(
+  options: UseKeyboardNavigationOptions<T>
+): UseKeyboardNavigationReturn {
+  const {
+    enabled,
+    focusedCell,
+    editingCell,
+    columns,
+    rowCount,
+    visibleRowCount = 10,
+    onFocusedCellChange,
+    onStartEditing,
+    onCommitEdit,
+    onCancelEdit,
+    onScrollToRow,
+    onScrollToColumn,
+  } = options;
+
+  const containerRef = useRef<HTMLDivElement>(null);
+
+  // Get visible columns for navigation
+  const visibleColumns = getVisibleColumns(columns);
+
+  /**
+   * Get column index from column key
+   */
+  const getColumnIndex = useCallback(
+    (columnKey: string): number => {
+      return visibleColumns.findIndex((col) => col.key === columnKey);
+    },
+    [visibleColumns]
+  );
+
+  /**
+   * Get column key from index
+   */
+  const getColumnKey = useCallback(
+    (index: number): string | null => {
+      const column = visibleColumns[index];
+      return column ? column.key : null;
+    },
+    [visibleColumns]
+  );
+
+  /**
+   * Navigate to a new cell position
+   */
+  const navigateToCell = useCallback(
+    (rowIndex: number, columnKey: string) => {
+      // Clamp row index
+      const clampedRow = Math.max(0, Math.min(rowIndex, rowCount - 1));
+
+      onFocusedCellChange({ rowIndex: clampedRow, columnKey });
+      onScrollToRow?.(clampedRow);
+      onScrollToColumn?.(columnKey);
+    },
+    [rowCount, onFocusedCellChange, onScrollToRow, onScrollToColumn]
+  );
+
+  /**
+   * Move focus by delta
+   */
+  const moveFocus = useCallback(
+    (rowDelta: number, colDelta: number) => {
+      if (!focusedCell || visibleColumns.length === 0 || rowCount === 0) return;
+
+      const currentColIndex = getColumnIndex(focusedCell.columnKey);
+      if (currentColIndex === -1) return;
+
+      let newRowIndex = focusedCell.rowIndex + rowDelta;
+      let newColIndex = currentColIndex + colDelta;
+
+      // Handle wrapping for Tab navigation
+      if (colDelta !== 0) {
+        if (newColIndex < 0) {
+          // Wrap to previous row, last column
+          if (newRowIndex > 0) {
+            newRowIndex--;
+            newColIndex = visibleColumns.length - 1;
+          } else {
+            newColIndex = 0;
+          }
+        } else if (newColIndex >= visibleColumns.length) {
+          // Wrap to next row, first column
+          if (newRowIndex < rowCount - 1) {
+            newRowIndex++;
+            newColIndex = 0;
+          } else {
+            newColIndex = visibleColumns.length - 1;
+          }
+        }
+      }
+
+      // Clamp values
+      newRowIndex = Math.max(0, Math.min(newRowIndex, rowCount - 1));
+      newColIndex = Math.max(0, Math.min(newColIndex, visibleColumns.length - 1));
+
+      const newColumnKey = getColumnKey(newColIndex);
+      if (newColumnKey) {
+        navigateToCell(newRowIndex, newColumnKey);
+      }
+    },
+    [
+      focusedCell,
+      visibleColumns,
+      rowCount,
+      getColumnIndex,
+      getColumnKey,
+      navigateToCell,
+    ]
+  );
+
+  /**
+   * Jump to first cell in row
+   */
+  const jumpToRowStart = useCallback(() => {
+    if (!focusedCell || visibleColumns.length === 0) return;
+    const firstColumnKey = getColumnKey(0);
+    if (firstColumnKey) {
+      navigateToCell(focusedCell.rowIndex, firstColumnKey);
+    }
+  }, [focusedCell, visibleColumns.length, getColumnKey, navigateToCell]);
+
+  /**
+   * Jump to last cell in row
+   */
+  const jumpToRowEnd = useCallback(() => {
+    if (!focusedCell || visibleColumns.length === 0) return;
+    const lastColumnKey = getColumnKey(visibleColumns.length - 1);
+    if (lastColumnKey) {
+      navigateToCell(focusedCell.rowIndex, lastColumnKey);
+    }
+  }, [focusedCell, visibleColumns.length, getColumnKey, navigateToCell]);
+
+  /**
+   * Jump to first cell in grid
+   */
+  const jumpToGridStart = useCallback(() => {
+    if (visibleColumns.length === 0 || rowCount === 0) return;
+    const firstColumnKey = getColumnKey(0);
+    if (firstColumnKey) {
+      navigateToCell(0, firstColumnKey);
+    }
+  }, [visibleColumns.length, rowCount, getColumnKey, navigateToCell]);
+
+  /**
+   * Jump to last cell in grid
+   */
+  const jumpToGridEnd = useCallback(() => {
+    if (visibleColumns.length === 0 || rowCount === 0) return;
+    const lastColumnKey = getColumnKey(visibleColumns.length - 1);
+    if (lastColumnKey) {
+      navigateToCell(rowCount - 1, lastColumnKey);
+    }
+  }, [visibleColumns.length, rowCount, getColumnKey, navigateToCell]);
+
+  /**
+   * Handle key down events
+   */
+  const handleKeyDown = useCallback(
+    (event: React.KeyboardEvent) => {
+      if (!enabled) return;
+
+      const { key, ctrlKey, metaKey, shiftKey } = event;
+      const isModifierKey = ctrlKey || metaKey;
+
+      // If editing, only handle Enter and Escape
+      if (editingCell) {
+        switch (key) {
+          case "Enter":
+            event.preventDefault();
+            onCommitEdit();
+            break;
+          case "Escape":
+            event.preventDefault();
+            onCancelEdit();
+            break;
+          case "Tab":
+            // Commit and move to next cell
+            event.preventDefault();
+            onCommitEdit();
+            moveFocus(0, shiftKey ? -1 : 1);
+            break;
+        }
+        return;
+      }
+
+      // Navigation when not editing
+      switch (key) {
+        case "ArrowUp":
+          event.preventDefault();
+          moveFocus(-1, 0);
+          break;
+
+        case "ArrowDown":
+          event.preventDefault();
+          moveFocus(1, 0);
+          break;
+
+        case "ArrowLeft":
+          event.preventDefault();
+          moveFocus(0, -1);
+          break;
+
+        case "ArrowRight":
+          event.preventDefault();
+          moveFocus(0, 1);
+          break;
+
+        case "Tab":
+          event.preventDefault();
+          moveFocus(0, shiftKey ? -1 : 1);
+          break;
+
+        case "Home":
+          event.preventDefault();
+          if (isModifierKey) {
+            jumpToGridStart();
+          } else {
+            jumpToRowStart();
+          }
+          break;
+
+        case "End":
+          event.preventDefault();
+          if (isModifierKey) {
+            jumpToGridEnd();
+          } else {
+            jumpToRowEnd();
+          }
+          break;
+
+        case "PageUp":
+          event.preventDefault();
+          moveFocus(-visibleRowCount, 0);
+          break;
+
+        case "PageDown":
+          event.preventDefault();
+          moveFocus(visibleRowCount, 0);
+          break;
+
+        case "Enter":
+        case "F2":
+          // Start editing the focused cell
+          if (focusedCell) {
+            event.preventDefault();
+            const column = columns.find(
+              (c) => c.key === focusedCell.columnKey
+            );
+            if (column?.editable) {
+              onStartEditing(focusedCell.rowIndex, focusedCell.columnKey);
+            }
+          }
+          break;
+
+        case "Escape":
+          // Clear focus
+          event.preventDefault();
+          onFocusedCellChange(null);
+          break;
+      }
+    },
+    [
+      enabled,
+      editingCell,
+      focusedCell,
+      columns,
+      visibleRowCount,
+      moveFocus,
+      jumpToRowStart,
+      jumpToRowEnd,
+      jumpToGridStart,
+      jumpToGridEnd,
+      onCommitEdit,
+      onCancelEdit,
+      onStartEditing,
+      onFocusedCellChange,
+    ]
+  );
+
+  /**
+   * Focus the container element
+   */
+  const focusContainer = useCallback(() => {
+    containerRef.current?.focus();
+  }, []);
+
+  // Note: We intentionally don't auto-focus the container when focusedCell changes.
+  // This allows focus to naturally move to other elements (like search inputs) when
+  // the user clicks outside the grid. The container is focused explicitly via
+  // focusContainer() when the user clicks on a cell.
+
+  return {
+    handleKeyDown,
+    containerRef,
+    focusContainer,
+  };
+}

package/src/components/data-grid/index.ts

@@ -0,0 +1,71 @@
+/**
+ * DataGrid Module
+ *
+ * Export all DataGrid components, hooks, and types
+ */
+
+// Main component
+export { DataGrid } from "./DataGrid";
+
+// Types
+export type {
+  // Column and data types
+  ColumnDef,
+  SelectOption,
+  FilterType,
+  EditorType,
+  
+  // Value types
+  CellValue,
+  FilterValue,
+  
+  // Filter types
+  FilterConfig,
+  FilterOperator,
+  TextFilterOperator,
+  NumberFilterOperator,
+  DateFilterOperator,
+  
+  // Sort types
+  SortConfig,
+  
+  // Cell types
+  CellPosition,
+  EditingCell,
+  CellEditEvent,
+  
+  // Configuration types
+  PaginationConfig,
+  SearchConfig,
+  DataGridState,
+  
+  // Props types
+  DataGridProps,
+  DataGridInternalState,
+  DataGridContextValue,
+  HeaderCellProps,
+  FilterPopoverProps,
+  CellEditorProps,
+  GridCellProps,
+} from "./types";
+
+// Sub-components (for advanced customization)
+export { HeaderCell } from "./components/HeaderCell";
+export { FilterPopover } from "./components/FilterPopover";
+export { CellEditor } from "./components/CellEditor";
+
+// Hooks (for building custom grid implementations)
+export {
+  useDataGridState,
+  useKeyboardNavigation,
+  useColumnResize,
+  useColumnResizeManager,
+} from "./hooks";
+
+// Utilities (for custom data processing)
+export {
+  getCellValue,
+  applySorting,
+  applyFilters,
+  applyFilterOperator,
+} from "./utils";