@optilogic/core 1.0.0-beta.0

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

@@ -0,0 +1,378 @@
+/**
+ * useColumnResize Hook
+ *
+ * Handles column resizing logic with:
+ * - Mouse drag support
+ * - Min/max width constraints
+ * - Callbacks for resize start/end
+ * - Double-click to auto-fit (optional)
+ */
+
+import { useState, useCallback, useRef, useEffect } from "react";
+import type { ColumnDef } from "../types";
+
+/** Default minimum column width */
+const DEFAULT_MIN_WIDTH = 50;
+
+/** Default maximum column width */
+const DEFAULT_MAX_WIDTH = 1000;
+
+export interface UseColumnResizeOptions {
+  /** Column key being resized */
+  columnKey: string;
+  /** Column definition (for min/max width) */
+  column: ColumnDef;
+  /** Current column width */
+  currentWidth: number;
+  /** Whether resizing is enabled */
+  enabled: boolean;
+  /** Callback when width changes during resize */
+  onResize: (width: number) => void;
+  /** Callback when resize starts */
+  onResizeStart?: () => void;
+  /** Callback when resize ends */
+  onResizeEnd?: (width: number) => void;
+}
+
+export interface UseColumnResizeReturn {
+  /** Whether currently dragging */
+  isDragging: boolean;
+  /** Props to spread on the resize handle element */
+  resizeHandleProps: {
+    onMouseDown: (event: React.MouseEvent) => void;
+    onDoubleClick: (event: React.MouseEvent) => void;
+    style: React.CSSProperties;
+    role: string;
+    "aria-label": string;
+    tabIndex: number;
+  };
+}
+
+/**
+ * Hook to handle column resize drag interactions
+ */
+export function useColumnResize(
+  options: UseColumnResizeOptions
+): UseColumnResizeReturn {
+  const {
+    columnKey,
+    column,
+    currentWidth,
+    enabled,
+    onResize,
+    onResizeStart,
+    onResizeEnd,
+  } = options;
+
+  const [isDragging, setIsDragging] = useState(false);
+  const startXRef = useRef(0);
+  const startWidthRef = useRef(0);
+
+  // Get min/max widths
+  const minWidth = column.minWidth ?? DEFAULT_MIN_WIDTH;
+  const maxWidth = column.maxWidth ?? DEFAULT_MAX_WIDTH;
+
+  /**
+   * Clamp width to min/max bounds
+   */
+  const clampWidth = useCallback(
+    (width: number): number => {
+      return Math.max(minWidth, Math.min(maxWidth, width));
+    },
+    [minWidth, maxWidth]
+  );
+
+  /**
+   * Handle mouse down on resize handle
+   */
+  const handleMouseDown = useCallback(
+    (event: React.MouseEvent) => {
+      if (!enabled) return;
+
+      event.preventDefault();
+      event.stopPropagation();
+
+      setIsDragging(true);
+      startXRef.current = event.clientX;
+      startWidthRef.current = currentWidth;
+
+      // Prevent text selection during drag
+      document.body.style.userSelect = "none";
+      document.body.style.cursor = "col-resize";
+
+      onResizeStart?.();
+    },
+    [enabled, currentWidth, onResizeStart]
+  );
+
+  /**
+   * Handle mouse move during drag
+   */
+  const handleMouseMove = useCallback(
+    (event: MouseEvent) => {
+      if (!isDragging) return;
+
+      const deltaX = event.clientX - startXRef.current;
+      const newWidth = clampWidth(startWidthRef.current + deltaX);
+
+      onResize(newWidth);
+    },
+    [isDragging, clampWidth, onResize]
+  );
+
+  /**
+   * Handle mouse up to end drag
+   */
+  const handleMouseUp = useCallback(() => {
+    if (!isDragging) return;
+
+    setIsDragging(false);
+
+    // Restore styles
+    document.body.style.userSelect = "";
+    document.body.style.cursor = "";
+
+    // Calculate final width
+    const finalWidth = clampWidth(currentWidth);
+    onResizeEnd?.(finalWidth);
+  }, [isDragging, currentWidth, clampWidth, onResizeEnd]);
+
+  /**
+   * Handle double-click to auto-fit column width
+   * For now, this resets to the column's default width
+   */
+  const handleDoubleClick = useCallback(
+    (event: React.MouseEvent) => {
+      if (!enabled) return;
+
+      event.preventDefault();
+      event.stopPropagation();
+
+      // Reset to column's defined width or default
+      const defaultWidth = column.width ?? 200;
+      const clampedWidth = clampWidth(defaultWidth);
+      onResize(clampedWidth);
+      onResizeEnd?.(clampedWidth);
+    },
+    [enabled, column.width, clampWidth, onResize, onResizeEnd]
+  );
+
+  // Attach global mouse listeners during drag
+  useEffect(() => {
+    if (isDragging) {
+      window.addEventListener("mousemove", handleMouseMove);
+      window.addEventListener("mouseup", handleMouseUp);
+
+      return () => {
+        window.removeEventListener("mousemove", handleMouseMove);
+        window.removeEventListener("mouseup", handleMouseUp);
+      };
+    }
+  }, [isDragging, handleMouseMove, handleMouseUp]);
+
+  // Clean up on unmount
+  useEffect(() => {
+    return () => {
+      if (isDragging) {
+        document.body.style.userSelect = "";
+        document.body.style.cursor = "";
+      }
+    };
+  }, [isDragging]);
+
+  return {
+    isDragging,
+    resizeHandleProps: {
+      onMouseDown: handleMouseDown,
+      onDoubleClick: handleDoubleClick,
+      style: {
+        cursor: enabled ? "col-resize" : "default",
+        touchAction: "none",
+      },
+      role: "separator",
+      "aria-label": `Resize column ${columnKey}`,
+      tabIndex: enabled ? 0 : -1,
+    },
+  };
+}
+
+/**
+ * Hook to manage resize state for all columns
+ */
+export interface UseColumnResizeManagerOptions<T = any> {
+  /** Column definitions */
+  columns: ColumnDef<T>[];
+  /** Current column widths */
+  columnWidths: Record<string, number>;
+  /** Whether resizing is enabled globally */
+  resizableColumns: boolean;
+  /** Callback when a column width changes */
+  onColumnResize: (columnKey: string, width: number) => void;
+  /** Callback when resize starts */
+  onColumnResizeStart?: (columnKey: string) => void;
+  /** Callback when resize ends */
+  onColumnResizeEnd?: (columnKey: string, width: number) => void;
+}
+
+export interface UseColumnResizeManagerReturn {
+  /** Currently resizing column key */
+  resizingColumn: string | null;
+  /** Get resize props for a specific column */
+  getResizeProps: (columnKey: string) => {
+    isDragging: boolean;
+    handleMouseDown: (event: React.MouseEvent) => void;
+    handleDoubleClick: (event: React.MouseEvent) => void;
+  };
+}
+
+/**
+ * Hook to manage column resize state across all columns
+ */
+export function useColumnResizeManager<T = any>(
+  options: UseColumnResizeManagerOptions<T>
+): UseColumnResizeManagerReturn {
+  const {
+    columns,
+    columnWidths,
+    resizableColumns,
+    onColumnResize,
+    onColumnResizeStart,
+    onColumnResizeEnd,
+  } = options;
+
+  const [resizingColumn, setResizingColumn] = useState<string | null>(null);
+  const startXRef = useRef(0);
+  const startWidthRef = useRef(0);
+
+  /**
+   * Get column by key
+   */
+  const getColumn = useCallback(
+    (columnKey: string): ColumnDef<T> | undefined => {
+      return columns.find((c) => c.key === columnKey);
+    },
+    [columns]
+  );
+
+  /**
+   * Clamp width for a specific column
+   */
+  const clampWidth = useCallback(
+    (columnKey: string, width: number): number => {
+      const column = getColumn(columnKey);
+      const minWidth = column?.minWidth ?? DEFAULT_MIN_WIDTH;
+      const maxWidth = column?.maxWidth ?? DEFAULT_MAX_WIDTH;
+      return Math.max(minWidth, Math.min(maxWidth, width));
+    },
+    [getColumn]
+  );
+
+  /**
+   * Handle mouse move during resize
+   */
+  const handleMouseMove = useCallback(
+    (event: MouseEvent) => {
+      if (!resizingColumn) return;
+
+      const deltaX = event.clientX - startXRef.current;
+      const newWidth = clampWidth(
+        resizingColumn,
+        startWidthRef.current + deltaX
+      );
+
+      onColumnResize(resizingColumn, newWidth);
+    },
+    [resizingColumn, clampWidth, onColumnResize]
+  );
+
+  /**
+   * Handle mouse up to end resize
+   */
+  const handleMouseUp = useCallback(() => {
+    if (!resizingColumn) return;
+
+    const finalWidth = columnWidths[resizingColumn] ?? 200;
+
+    setResizingColumn(null);
+    document.body.style.userSelect = "";
+    document.body.style.cursor = "";
+
+    onColumnResizeEnd?.(resizingColumn, finalWidth);
+  }, [resizingColumn, columnWidths, onColumnResizeEnd]);
+
+  // Attach global listeners during resize
+  useEffect(() => {
+    if (resizingColumn) {
+      window.addEventListener("mousemove", handleMouseMove);
+      window.addEventListener("mouseup", handleMouseUp);
+
+      return () => {
+        window.removeEventListener("mousemove", handleMouseMove);
+        window.removeEventListener("mouseup", handleMouseUp);
+      };
+    }
+  }, [resizingColumn, handleMouseMove, handleMouseUp]);
+
+  /**
+   * Get resize props for a specific column
+   */
+  const getResizeProps = useCallback(
+    (columnKey: string) => {
+      const column = getColumn(columnKey);
+      const isResizable =
+        resizableColumns && (column?.resizable !== false);
+
+      const handleMouseDown = (event: React.MouseEvent) => {
+        if (!isResizable) return;
+
+        event.preventDefault();
+        event.stopPropagation();
+
+        setResizingColumn(columnKey);
+        startXRef.current = event.clientX;
+        startWidthRef.current = columnWidths[columnKey] ?? column?.width ?? 200;
+
+        document.body.style.userSelect = "none";
+        document.body.style.cursor = "col-resize";
+
+        onColumnResizeStart?.(columnKey);
+      };
+
+      const handleDoubleClick = (event: React.MouseEvent) => {
+        if (!isResizable) return;
+
+        event.preventDefault();
+        event.stopPropagation();
+
+        // Reset to default width
+        const defaultWidth = column?.width ?? 200;
+        const minWidth = column?.minWidth ?? DEFAULT_MIN_WIDTH;
+        const maxWidth = column?.maxWidth ?? DEFAULT_MAX_WIDTH;
+        const clampedWidth = Math.max(minWidth, Math.min(maxWidth, defaultWidth));
+
+        onColumnResize(columnKey, clampedWidth);
+        onColumnResizeEnd?.(columnKey, clampedWidth);
+      };
+
+      return {
+        isDragging: resizingColumn === columnKey,
+        handleMouseDown,
+        handleDoubleClick,
+      };
+    },
+    [
+      getColumn,
+      resizableColumns,
+      columnWidths,
+      resizingColumn,
+      onColumnResize,
+      onColumnResizeStart,
+      onColumnResizeEnd,
+    ]
+  );
+
+  return {
+    resizingColumn,
+    getResizeProps,
+  };
+}

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

@@ -0,0 +1,346 @@
+/**
+ * useDataGridState Hook
+ *
+ * Manages internal state for the DataGrid component, supporting both
+ * controlled and uncontrolled modes for sorting, filtering, column widths,
+ * cell focus, and cell editing.
+ */
+
+import { useState, useCallback, useMemo, useRef, useEffect } from "react";
+import type {
+  SortConfig,
+  FilterConfig,
+  CellPosition,
+  EditingCell,
+  DataGridInternalState,
+  DataGridState,
+  ColumnDef,
+  CellValue,
+} from "../types";
+
+export interface UseDataGridStateOptions<T = Record<string, CellValue>> {
+  sorting?: SortConfig[];
+  filters?: FilterConfig[];
+  columnWidths?: Record<string, number>;
+  focusedCell?: CellPosition | null;
+
+  defaultSorting?: SortConfig[];
+  defaultFilters?: FilterConfig[];
+  defaultColumnWidths?: Record<string, number>;
+
+  onSortChange?: (sorting: SortConfig[]) => void;
+  onFilterChange?: (filters: FilterConfig[]) => void;
+  onColumnResize?: (columnKey: string, width: number) => void;
+  onFocusedCellChange?: (cell: CellPosition | null) => void;
+  onStateChange?: (state: DataGridState) => void;
+
+  onCellEdit?: (
+    rowIndex: number,
+    columnKey: string,
+    newValue: CellValue,
+    oldValue: CellValue
+  ) => void;
+  onCellEditStart?: (rowIndex: number, columnKey: string) => boolean | void;
+  onCellEditCancel?: (rowIndex: number, columnKey: string) => void;
+
+  columns: ColumnDef<T>[];
+  data: T[];
+  getCellValue: (row: T, column: ColumnDef<T>) => CellValue;
+}
+
+export interface UseDataGridStateReturn {
+  state: DataGridInternalState;
+  actions: {
+    setSorting: (sorting: SortConfig[]) => void;
+    toggleSort: (columnKey: string) => void;
+    setFilters: (filters: FilterConfig[]) => void;
+    setFilter: (filter: FilterConfig | null, columnKey: string) => void;
+    clearFilters: () => void;
+    setColumnWidth: (columnKey: string, width: number) => void;
+    setFocusedCell: (cell: CellPosition | null) => void;
+    startEditing: (rowIndex: number, columnKey: string) => void;
+    updateEditingValue: (value: CellValue) => void;
+    /** Commit the current edit. Optionally pass a value to commit immediately (for async editors like checkbox/date) */
+    commitEdit: (value?: CellValue) => void;
+    cancelEdit: () => void;
+  };
+  isControlled: {
+    sorting: boolean;
+    filters: boolean;
+    columnWidths: boolean;
+    focusedCell: boolean;
+  };
+}
+
+/**
+ * Hook to manage DataGrid state with controlled/uncontrolled support
+ */
+export function useDataGridState<T = Record<string, CellValue>>(
+  options: UseDataGridStateOptions<T>
+): UseDataGridStateReturn {
+  const {
+    sorting: controlledSorting,
+    filters: controlledFilters,
+    columnWidths: controlledColumnWidths,
+    focusedCell: controlledFocusedCell,
+
+    defaultSorting = [],
+    defaultFilters = [],
+    defaultColumnWidths = {},
+
+    onSortChange,
+    onFilterChange,
+    onColumnResize,
+    onFocusedCellChange,
+    onStateChange,
+    onCellEdit,
+    onCellEditStart,
+    onCellEditCancel,
+
+    columns,
+    data,
+    getCellValue,
+  } = options;
+  const isControlled = useMemo(
+    () => ({
+      sorting: controlledSorting !== undefined,
+      filters: controlledFilters !== undefined,
+      columnWidths: controlledColumnWidths !== undefined,
+      focusedCell: controlledFocusedCell !== undefined,
+    }),
+    [
+      controlledSorting,
+      controlledFilters,
+      controlledColumnWidths,
+      controlledFocusedCell,
+    ]
+  );
+
+  const [internalSorting, setInternalSorting] =
+    useState<SortConfig[]>(defaultSorting);
+  const [internalFilters, setInternalFilters] =
+    useState<FilterConfig[]>(defaultFilters);
+  const [internalColumnWidths, setInternalColumnWidths] =
+    useState<Record<string, number>>(defaultColumnWidths);
+  const [internalFocusedCell, setInternalFocusedCell] =
+    useState<CellPosition | null>(null);
+  const [editingCell, setEditingCell] = useState<EditingCell | null>(null);
+
+  const sorting = isControlled.sorting ? controlledSorting! : internalSorting;
+  const filters = isControlled.filters ? controlledFilters! : internalFilters;
+  const focusedCell = isControlled.focusedCell
+    ? controlledFocusedCell!
+    : internalFocusedCell;
+
+  const columnWidths = useMemo(() => {
+    const controlled = isControlled.columnWidths
+      ? controlledColumnWidths!
+      : internalColumnWidths;
+    const result: Record<string, number> = {};
+
+    for (const column of columns) {
+      result[column.key] = controlled[column.key] ?? column.width ?? 200;
+    }
+
+    return result;
+  }, [isControlled.columnWidths, controlledColumnWidths, internalColumnWidths, columns]);
+
+  const prevStateRef = useRef<DataGridState | null>(null);
+
+  const state: DataGridInternalState = useMemo(
+    () => ({
+      sorting,
+      filters,
+      columnWidths,
+      focusedCell,
+      editingCell,
+    }),
+    [sorting, filters, columnWidths, focusedCell, editingCell]
+  );
+
+  useEffect(() => {
+    if (onStateChange) {
+      const currentState: DataGridState = {
+        sorting,
+        filters,
+        columnWidths,
+        focusedCell,
+        editingCell,
+      };
+
+      if (
+        JSON.stringify(currentState) !== JSON.stringify(prevStateRef.current)
+      ) {
+        prevStateRef.current = currentState;
+        onStateChange(currentState);
+      }
+    }
+  }, [sorting, filters, columnWidths, focusedCell, editingCell, onStateChange]);
+
+  // ============ SORTING ACTIONS ============
+  const setSorting = useCallback(
+    (newSorting: SortConfig[]) => {
+      if (isControlled.sorting) {
+        onSortChange?.(newSorting);
+      } else {
+        setInternalSorting(newSorting);
+        onSortChange?.(newSorting);
+      }
+    },
+    [isControlled.sorting, onSortChange]
+  );
+
+  const toggleSort = useCallback(
+    (columnKey: string) => {
+      const currentSort = sorting.find((s) => s.field === columnKey);
+      let newSorting: SortConfig[];
+
+      if (!currentSort) {
+        newSorting = [{ field: columnKey, direction: "asc" }];
+      } else if (currentSort.direction === "asc") {
+        newSorting = [{ field: columnKey, direction: "desc" }];
+      } else {
+        newSorting = [];
+      }
+
+      setSorting(newSorting);
+    },
+    [sorting, setSorting]
+  );
+
+  // ============ FILTER ACTIONS ============
+  const setFilters = useCallback(
+    (newFilters: FilterConfig[]) => {
+      if (isControlled.filters) {
+        onFilterChange?.(newFilters);
+      } else {
+        setInternalFilters(newFilters);
+        onFilterChange?.(newFilters);
+      }
+    },
+    [isControlled.filters, onFilterChange]
+  );
+
+  const setFilter = useCallback(
+    (filter: FilterConfig | null, columnKey: string) => {
+      const newFilters = filters.filter((f) => f.columnKey !== columnKey);
+      if (filter) {
+        newFilters.push(filter);
+      }
+      setFilters(newFilters);
+    },
+    [filters, setFilters]
+  );
+
+  const clearFilters = useCallback(() => {
+    setFilters([]);
+  }, [setFilters]);
+
+  // ============ COLUMN WIDTH ACTIONS ============
+  const setColumnWidth = useCallback(
+    (columnKey: string, width: number) => {
+      if (isControlled.columnWidths) {
+        onColumnResize?.(columnKey, width);
+      } else {
+        setInternalColumnWidths((prev) => ({
+          ...prev,
+          [columnKey]: width,
+        }));
+        onColumnResize?.(columnKey, width);
+      }
+    },
+    [isControlled.columnWidths, onColumnResize]
+  );
+
+  // ============ FOCUS ACTIONS ============
+  const setFocusedCell = useCallback(
+    (cell: CellPosition | null) => {
+      if (isControlled.focusedCell) {
+        onFocusedCellChange?.(cell);
+      } else {
+        setInternalFocusedCell(cell);
+        onFocusedCellChange?.(cell);
+      }
+    },
+    [isControlled.focusedCell, onFocusedCellChange]
+  );
+
+  // ============ EDITING ACTIONS ============
+  const startEditing = useCallback(
+    (rowIndex: number, columnKey: string) => {
+      if (onCellEditStart) {
+        const allowed = onCellEditStart(rowIndex, columnKey);
+        if (allowed === false) return;
+      }
+
+      const column = columns.find((c) => c.key === columnKey);
+      if (!column || !column.editable) return;
+
+      const row = data[rowIndex];
+      if (!row) return;
+
+      const value = getCellValue(row, column);
+
+      setEditingCell({
+        rowIndex,
+        columnKey,
+        value,
+        originalValue: value,
+      });
+
+      setFocusedCell({ rowIndex, columnKey });
+    },
+    [columns, data, getCellValue, onCellEditStart, setFocusedCell]
+  );
+
+  const updateEditingValue = useCallback((value: CellValue) => {
+    setEditingCell((prev) => (prev ? { ...prev, value } : null));
+  }, []);
+
+  const commitEdit = useCallback((valueOverride?: CellValue) => {
+    if (!editingCell) return;
+
+    const { rowIndex, columnKey, originalValue } = editingCell;
+    const value = valueOverride !== undefined ? valueOverride : editingCell.value;
+
+    const column = columns.find((c) => c.key === columnKey);
+    if (column?.validator) {
+      const row = data[rowIndex];
+      const validationResult = column.validator(value, row);
+      if (validationResult !== true && typeof validationResult === "string") {
+        return;
+      }
+    }
+
+    if (value !== originalValue) {
+      onCellEdit?.(rowIndex, columnKey, value, originalValue);
+    }
+
+    setEditingCell(null);
+  }, [editingCell, columns, data, onCellEdit]);
+
+  const cancelEdit = useCallback(() => {
+    if (editingCell) {
+      onCellEditCancel?.(editingCell.rowIndex, editingCell.columnKey);
+    }
+    setEditingCell(null);
+  }, [editingCell, onCellEditCancel]);
+
+  return {
+    state,
+    actions: {
+      setSorting,
+      toggleSort,
+      setFilters,
+      setFilter,
+      clearFilters,
+      setColumnWidth,
+      setFocusedCell,
+      startEditing,
+      updateEditingValue,
+      commitEdit,
+      cancelEdit,
+    },
+    isControlled,
+  };
+}