aplance-ui 1.0.1

package/registry/components/ui/data-table/useDataTable.tsx

@@ -0,0 +1,573 @@
+import { useState, useMemo, useCallback, useEffect, useRef } from "react";
+import type {
+  ColumnOrderState,
+  ColumnPinningState,
+  ColumnSizingState,
+  ExpandedState,
+  GroupingState,
+  OnChangeFn,
+  RowSelectionState,
+  SortingState,
+  VisibilityState,
+} from "@tanstack/react-table";
+import type {
+  DataTableProps,
+  PaginationState,
+  PersistArgs,
+  PersistedState,
+  UseDataTableOptions,
+  UseDataTableReturn,
+} from "./types";
+import {
+  applyPersistedState,
+  readLocalStorage,
+  readSearchParams,
+  snapshotPersistedState,
+  writeLocalStorage,
+  writeSearchParams,
+} from "./utils";
+
+// Stable empty-object reference - avoids resetting useState's initializer on
+// every render when the consumer doesn't pass `defaultFilterValues`.
+const EMPTY_FILTERS: Record<string, string> = {};
+
+// ─── Hook ─────────────────────────────────────────────────────────────────────
+
+export function useDataTable<TData extends { id: string }>({
+  data,
+  pageSize: initialPageSize = 10,
+  defaultFilterValues = EMPTY_FILTERS,
+  filterFn,
+  onFilterChange,
+  onPaginationChange: externalOnPaginationChange,
+  onSortingChange: externalOnSortingChange,
+  onRowSelectionChange: externalOnRowSelectionChange,
+  onDataChange,
+  clientSidePagination = true,
+  manualSorting = false,
+  totalCount: externalTotalCount,
+  totalPages: externalTotalPages,
+  defaultColumnOrder,
+  defaultColumnVisibility,
+  defaultColumnPinning,
+  defaultColumnSizing,
+  defaultGrouping,
+  defaultExpanded,
+  persistState,
+}: UseDataTableOptions<TData>): UseDataTableReturn<TData> {
+  // ── Internal state ──────────────────────────────────────────────────────────
+  const [sorting, setSorting] = useState<SortingState>([]);
+  const [pagination, setPagination] = useState<PaginationState>({
+    pageIndex: 0,
+    pageSize: initialPageSize,
+  });
+  const [filterValues, setFilterValues] =
+    useState<Record<string, string>>(defaultFilterValues);
+  const [rowSelection, setRowSelection] = useState<RowSelectionState>({});
+  const [editingRowId, setEditingRowId] = useState<string | null>(null);
+  const [columnOrder, setColumnOrderState] = useState<ColumnOrderState>(
+    defaultColumnOrder ?? [],
+  );
+  const [columnVisibility, setColumnVisibilityState] =
+    useState<VisibilityState>(defaultColumnVisibility ?? {});
+  const [columnPinning, setColumnPinningState] = useState<ColumnPinningState>(
+    defaultColumnPinning ?? {},
+  );
+  const [columnSizing, setColumnSizingState] = useState<ColumnSizingState>(
+    defaultColumnSizing ?? {},
+  );
+  const [grouping, setGroupingState] = useState<GroupingState>(
+    defaultGrouping ?? [],
+  );
+  const [expanded, setExpandedState] = useState<ExpandedState>(
+    defaultExpanded ?? true,
+  );
+  // snapshot for cancel-edit (ref keeps callbacks stable, avoids extra re-renders)
+  const snapshotRef = useRef<TData | null>(null);
+  // mutable data copy for inline editing
+  const [localData, setLocalData] = useState<TData[]>(data);
+  const [prevData, setPrevData] = useState<TData[]>(data);
+  const localDataRef = useRef<TData[]>(data);
+
+  // Latest-value refs - let handlers compute `next` outside of the setState
+  // updater. Firing consumer callbacks inside an updater causes double-fires
+  // under React strict/concurrent rendering (updaters may run twice) which
+  // would trigger duplicate API calls for server-side sort/filter consumers.
+  const sortingRef = useRef(sorting);
+  const rowSelectionRef = useRef(rowSelection);
+  const filterValuesRef = useRef(filterValues);
+  const paginationRef = useRef(pagination);
+  useEffect(() => {
+    sortingRef.current = sorting;
+    rowSelectionRef.current = rowSelection;
+    filterValuesRef.current = filterValues;
+    paginationRef.current = pagination;
+  }, [sorting, rowSelection, filterValues, pagination]);
+
+  // Keep localData in sync when the outer data prop changes (new fetch result
+  // arrives), but only when not editing - overwriting in-progress edits would
+  // discard the user's input. We hold off on advancing `prevData` while
+  // editing so a `data` change *during* an edit isn't forgotten: the next
+  // run after `editingRowId` flips back to null still sees prevData!==data and
+  // syncs.
+  // We do this during render (instead of useEffect) to prevent a micro-second 
+  // jerk/overlap of old data when server-side fetch completes.
+  // A shallow array comparison prevents infinite re-render loops when consumers
+  // pass inline literal arrays (like `data={[]}`) which change reference every render.
+  if (editingRowId === null) {
+    let hasChanged = prevData !== data;
+    if (hasChanged && prevData?.length === data?.length) {
+      hasChanged = false;
+      for (let i = 0; i < (data?.length || 0); i++) {
+        if (prevData[i] !== data[i]) {
+          hasChanged = true;
+          break;
+        }
+      }
+    }
+    if (hasChanged) {
+      setPrevData(data);
+      setLocalData(data);
+    }
+  }
+
+  useEffect(() => {
+    localDataRef.current = localData;
+  }, [localData]);
+
+  // ── Sorting handler ─────────────────────────────────────────────────────────
+  const handleSortingChange: OnChangeFn<SortingState> = useCallback(
+    (updater) => {
+      const next =
+        typeof updater === "function" ? updater(sortingRef.current) : updater;
+      setSorting(next);
+      externalOnSortingChange?.(next);
+    },
+    [externalOnSortingChange],
+  );
+
+  // ── Pagination handler ──────────────────────────────────────────────────────
+  const handlePaginationChange = useCallback(
+    (next: PaginationState) => {
+      setPagination(next);
+      externalOnPaginationChange?.(next);
+    },
+    [externalOnPaginationChange],
+  );
+
+  // ── Row selection handler ───────────────────────────────────────────────────
+  const handleRowSelectionChange: OnChangeFn<RowSelectionState> = useCallback(
+    (updater) => {
+      const next =
+        typeof updater === "function"
+          ? updater(rowSelectionRef.current)
+          : updater;
+      setRowSelection(next);
+      externalOnRowSelectionChange?.(next);
+    },
+    [externalOnRowSelectionChange],
+  );
+
+  // Column-state setters double as tanstack `OnChangeFn`s - React's
+  // `SetStateAction<T>` is structurally identical to tanstack's `Updater<T>`,
+  // so a no-op forwarding wrapper would just add allocations.
+
+  // ── Filter handler ──────────────────────────────────────────────────────────
+  const setFilter = useCallback(
+    (key: string, value: string) => {
+      const next = { ...filterValuesRef.current, [key]: value };
+      setFilterValues(next);
+      onFilterChange?.(key, value, next);
+      
+      const p = paginationRef.current;
+      if (p.pageIndex !== 0) {
+        handlePaginationChange({ ...p, pageIndex: 0 });
+      }
+    },
+    [onFilterChange, handlePaginationChange],
+  );
+
+  const setFilters = useCallback(
+    (values: Record<string, string>) => {
+      const next = { ...filterValuesRef.current, ...values };
+      setFilterValues(next);
+      for (const [k, v] of Object.entries(values)) {
+        onFilterChange?.(k, v, next);
+      }
+      
+      const p = paginationRef.current;
+      if (p.pageIndex !== 0) {
+        handlePaginationChange({ ...p, pageIndex: 0 });
+      }
+    },
+    [onFilterChange, handlePaginationChange],
+  );
+
+  const resetFilters = useCallback(() => {
+    setFilterValues(defaultFilterValues);
+    
+    const p = paginationRef.current;
+    if (p.pageIndex !== 0) {
+      handlePaginationChange({ ...p, pageIndex: 0 });
+    }
+  }, [defaultFilterValues, handlePaginationChange]);
+
+  // ── Inline editing actions ──────────────────────────────────────────────────
+  const startEdit = useCallback((rowId: string) => {
+    const row = localDataRef.current.find((r) => r.id === rowId);
+    snapshotRef.current = row ? { ...row } : null;
+    setEditingRowId(rowId);
+  }, []);
+
+  const cancelEdit = useCallback(() => {
+    const snapshot = snapshotRef.current;
+    if (snapshot) {
+      setLocalData((prev) =>
+        prev.map((r) => (r.id === snapshot.id ? snapshot : r)),
+      );
+    }
+    snapshotRef.current = null;
+    setEditingRowId(null);
+  }, []);
+
+  const confirmSave = useCallback(() => {
+    snapshotRef.current = null;
+    setEditingRowId(null);
+  }, []);
+
+  // Compute `next` from the latest-data ref and fire `onDataChange` outside
+  // the setState updater - see the latest-value-ref note above. The ref is
+  // advanced synchronously so back-to-back calls in the same tick compose
+  // correctly instead of clobbering each other.
+  const updateRowData = useCallback(
+    (rowId: string, columnId: string, value: unknown) => {
+      const next = localDataRef.current.map((r) =>
+        r.id === rowId ? ({ ...r, [columnId]: value } as TData) : r,
+      );
+      localDataRef.current = next;
+      setLocalData(next);
+      onDataChange?.(next);
+    },
+    [onDataChange],
+  );
+
+  const reorderRow = useCallback(
+    (draggedRow: TData, targetRow: TData) => {
+      const prev = localDataRef.current;
+      const draggedIdx = prev.indexOf(draggedRow);
+      const targetIdx = prev.indexOf(targetRow);
+      if (draggedIdx === -1 || targetIdx === -1 || draggedIdx === targetIdx) {
+        return;
+      }
+      const next = [...prev];
+      const [moved] = next.splice(draggedIdx, 1);
+      next.splice(targetIdx, 0, moved);
+      localDataRef.current = next;
+      setLocalData(next);
+      onDataChange?.(next);
+    },
+    [onDataChange],
+  );
+
+  // ── Page helpers ────────────────────────────────────────────────────────────
+  const goToPage = useCallback(
+    (index: number) =>
+      handlePaginationChange({ ...pagination, pageIndex: index }),
+    [handlePaginationChange, pagination],
+  );
+
+  const setPageSize = useCallback(
+    (size: number) => handlePaginationChange({ pageIndex: 0, pageSize: size }),
+    [handlePaginationChange],
+  );
+
+  const clearSelection = useCallback(() => {
+    setRowSelection({});
+  }, []);
+
+  // ── Column-state imperative helpers ────────────────────────────────────────
+  const toggleColumnVisibility = useCallback((columnId: string) => {
+    setColumnVisibilityState((prev) => ({
+      ...prev,
+      [columnId]: prev[columnId] === false,
+    }));
+  }, []);
+
+  // React's useState setters are already stable - no useCallback wrapper needed.
+  const setColumnVisibility = setColumnVisibilityState;
+  const setColumnOrder = setColumnOrderState;
+  const setColumnPinning = setColumnPinningState;
+  const setColumnSizing = setColumnSizingState;
+  const setGrouping = setGroupingState;
+  const setExpanded = setExpandedState;
+
+  const toggleGrouping = useCallback((columnId: string) => {
+    setGroupingState((prev) =>
+      prev.includes(columnId)
+        ? prev.filter((id) => id !== columnId)
+        : [...prev, columnId],
+    );
+  }, []);
+
+  // ── State persistence (URL / localStorage / manual) ─────────────────────────
+  // Lives here (not in <DataTable>) so consumers get a single hook that wires
+  // their state to the chosen destination. The persisted blob shape is mode-
+  // agnostic - switching modes preserves the same data.
+  usePersist({
+    config: persistState,
+    filterKeys: Object.keys(defaultFilterValues),
+    filterValues,
+    setFilterValues,
+    pagination,
+    setPagination,
+    sorting,
+    setSorting,
+    columnOrder,
+    setColumnOrder: setColumnOrderState,
+    columnVisibility,
+    setColumnVisibility: setColumnVisibilityState,
+    columnPinning,
+    setColumnPinning: setColumnPinningState,
+    columnSizing,
+    setColumnSizing: setColumnSizingState,
+    grouping,
+    setGrouping: setGroupingState,
+    expanded,
+    setExpanded: setExpandedState,
+  });
+
+  // ── Derived data ────────────────────────────────────────────────────────────
+  const filteredData = useMemo<TData[]>(() => {
+    if (!filterFn) return localData;
+    return filterFn(localData, filterValues);
+  }, [localData, filterFn, filterValues]);
+
+  const pageData = useMemo<TData[]>(() => {
+    if (!clientSidePagination) return filteredData;
+    const { pageIndex, pageSize } = pagination;
+    return filteredData.slice(pageIndex * pageSize, (pageIndex + 1) * pageSize);
+  }, [filteredData, pagination, clientSidePagination]);
+
+  const totalCount = externalTotalCount ?? filteredData.length;
+  const totalPages =
+    externalTotalPages ?? Math.ceil(filteredData.length / pagination.pageSize);
+
+  const selectedIds = useMemo(() => Object.keys(rowSelection), [rowSelection]);
+  const selectedRows = useMemo(
+    () => localData.filter((r) => rowSelection[r.id]),
+    [localData, rowSelection],
+  );
+
+  // ── Assemble DataTable props ─────────────────────────────────────────────────
+  const props: Omit<
+    DataTableProps<TData>,
+    "columns" | "filters" | "className"
+  > = useMemo(
+    () => ({
+      data: pageData,
+      sorting,
+      onSortingChange: handleSortingChange,
+      manualSorting,
+      filterValues,
+      onFilterChange: setFilter,
+      showPagination: true,
+      pagination,
+      onPaginationChange: handlePaginationChange,
+      totalPages,
+      totalCount,
+      rowSelection,
+      onRowSelectionChange: handleRowSelectionChange,
+      editingRowId,
+      onUpdateData: updateRowData,
+      columnOrder,
+      onColumnOrderChange: setColumnOrderState,
+      columnVisibility,
+      onColumnVisibilityChange: setColumnVisibilityState,
+      columnPinning,
+      onColumnPinningChange: setColumnPinningState,
+      defaultColumnPinning,
+      columnSizing,
+      onColumnSizingChange: setColumnSizingState,
+      grouping,
+      onGroupingChange: setGroupingState,
+      expanded,
+      onExpandedChange: setExpandedState,
+      onRowOrderChange: reorderRow,
+    }),
+    [
+      pageData,
+      sorting,
+      handleSortingChange,
+      manualSorting,
+      filterValues,
+      setFilter,
+      pagination,
+      handlePaginationChange,
+      totalPages,
+      totalCount,
+      rowSelection,
+      handleRowSelectionChange,
+      editingRowId,
+      updateRowData,
+      columnOrder,
+      columnVisibility,
+      columnPinning,
+      defaultColumnPinning,
+      columnSizing,
+      grouping,
+      expanded,
+      reorderRow,
+    ],
+  );
+
+  const actions = useMemo(
+    () => ({
+      setFilter,
+      setFilters,
+      resetFilters,
+      goToPage,
+      setPageSize,
+      clearSelection,
+      startEdit,
+      cancelEdit,
+      confirmSave,
+      updateRowData,
+      reorderRow,
+      toggleColumnVisibility,
+      setColumnVisibility,
+      setColumnOrder,
+      setColumnPinning,
+      setColumnSizing,
+      toggleGrouping,
+      setGrouping,
+      setExpanded,
+    }),
+    [
+      setFilter,
+      setFilters,
+      resetFilters,
+      goToPage,
+      setPageSize,
+      clearSelection,
+      startEdit,
+      cancelEdit,
+      confirmSave,
+      updateRowData,
+      reorderRow,
+      toggleColumnVisibility,
+      setColumnVisibility,
+      setColumnOrder,
+      setColumnPinning,
+      setColumnSizing,
+      toggleGrouping,
+      setGrouping,
+      setExpanded,
+    ],
+  );
+
+  return {
+    props,
+    state: {
+      filterValues,
+      pagination,
+      sorting,
+      rowSelection,
+      editingRowId,
+      columnOrder,
+      columnVisibility,
+      columnPinning,
+      columnSizing,
+      grouping,
+      expanded,
+      pageData,
+      filteredData,
+      selectedIds,
+      selectedRows,
+    },
+    actions,
+  };
+}
+
+// ─── Persist wiring ──────────────────────────────────────────────────────────
+// Pure read/write/snapshot/apply helpers live in `utils.ts`. This hook just
+// orchestrates them - hydrate once on mount, then sync state → destination
+// whenever any persistable slice changes.
+
+function usePersist(args: PersistArgs): void {
+  const enabled = args.config?.enabled ?? false;
+  const mode = args.config?.mode;
+
+  const hydrated = useRef(false);
+  // pageSize at first render - used by search-params mode to keep the URL
+  // clean (only writes ?pageSize=X when it differs from this default).
+  const defaultPageSizeRef = useRef(args.pagination.pageSize);
+
+  // Stable ref for args/config to avoid re-running effects when consumers
+  // pass fresh closures every render.
+  const argsRef = useRef(args);
+  useEffect(() => {
+    argsRef.current = args;
+  });
+
+  // ── Hydrate once on mount ──────────────────────────────────────────────────
+  useEffect(() => {
+    if (!enabled || hydrated.current) return;
+    hydrated.current = true;
+
+    const cfg = argsRef.current.config;
+    if (!cfg) return;
+
+    let initial: PersistedState = {};
+    if (cfg.mode === "search-params") {
+      initial = readSearchParams(
+        argsRef.current.filterKeys,
+        cfg.paramMap ?? {},
+        defaultPageSizeRef.current,
+      );
+    } else if (cfg.mode === "local-storage") {
+      initial = readLocalStorage(cfg.storageKey);
+    } else if (cfg.mode === "manual") {
+      initial = cfg.initialState ?? {};
+    }
+
+    applyPersistedState(initial, argsRef.current);
+  }, [enabled, mode]);
+
+  // ── Sync state → destination on every change ──────────────────────────────
+  useEffect(() => {
+    if (!enabled || !hydrated.current) return;
+    const cfg = argsRef.current.config;
+    if (!cfg) return;
+
+    const snapshot = snapshotPersistedState({
+      ...argsRef.current,
+      defaultPageSize: defaultPageSizeRef.current,
+    });
+
+    if (cfg.mode === "search-params") {
+      writeSearchParams(
+        snapshot,
+        argsRef.current.filterKeys,
+        cfg.paramMap ?? {},
+        defaultPageSizeRef.current,
+      );
+    } else if (cfg.mode === "local-storage") {
+      writeLocalStorage(cfg.storageKey, snapshot);
+    }
+    // Fired for every mode (manual mode's primary side-effect *is* this call;
+    // for URL/storage modes it doubles as a subscribe-to-change hook).
+    cfg.onChange?.(snapshot);
+  }, [
+    enabled,
+    mode,
+    args.filterValues,
+    args.pagination,
+    args.sorting,
+    args.columnOrder,
+    args.columnVisibility,
+    args.columnPinning,
+    args.columnSizing,
+    args.grouping,
+    args.expanded,
+  ]);
+}