@multiplatform.one/table 6.1.0 → 6.3.0

package/src/hooks/useDataTable.ts

@@ -18,6 +18,7 @@ import {
   getSortedRowModel,
   useReactTable,
 } from "@tanstack/react-table";
+import { useTableSelection } from "./useTableSelection";
 import { useSearchParams, useUrlState as useUrlStateFromRouter } from "@multiplatform.one/router";
 const useUrlState: typeof useUrlStateFromRouter = useUrlStateFromRouter;
 
@@ -167,20 +168,28 @@ export const createUrlStrategy = {
   custom: (strategy: UrlStateStrategy) => strategy,
 };
 
-import React, { useMemo, useState, useCallback, useEffect } from "react";
+import React, { useMemo, useState, useCallback, useEffect, useRef } from "react";
 import type {
   DataTableData,
+  DataTableInfiniteState,
   DataTableState,
   UseDataTableOptions,
   UseDataTableReturn,
 } from "../types";
+import {
+  applyFiltersToData,
+  getFilterFieldType,
+  isFilterValueShape,
+  resolveFilterFields,
+} from "../utils/filterFields";
+import { applyFilterToValue } from "../utils/filterUtils";
+import { DEFAULT_PAGE_SIZE } from "../utils/paginationDefaults";
 import { deserializeTableState, serializeTableState } from "../utils/urlStateUtils";
+import { useInfiniteRows } from "./useInfiniteRows";
 import { useTableFiltering } from "./useTableFiltering";
 import { useTableSorting } from "./useTableSorting";
 import { useTableViews } from "./useTableViews";
 
-const defaultPageSize = 10;
-
 export function useDataTable<TData extends DataTableData = DataTableData>({
   data = [],
   columns = [],
@@ -193,8 +202,11 @@ export function useDataTable<TData extends DataTableData = DataTableData>({
   manualPagination = false,
   manualSorting = false,
   enableFiltering = true,
+  filterableFields,
   enableSorting = true,
   enablePagination: _enablePagination = true,
+  paginationMode = "pages",
+  loadPage,
   enableColumnVisibility = true,
   enableColumnOrdering: _enableColumnOrdering = false,
   enableColumnResizing = false,
@@ -204,6 +216,7 @@ export function useDataTable<TData extends DataTableData = DataTableData>({
   getSubRows,
   enableColumnPinning = false,
   enableGrouping = false,
+  enableRowSelection = false,
   rowCount,
   pageCount,
 }: UseDataTableOptions<TData> & {
@@ -214,7 +227,7 @@ export function useDataTable<TData extends DataTableData = DataTableData>({
   const defaultTableState: Partial<DataTableState> = {
     pagination: {
       pageIndex: 0,
-      pageSize: defaultPageSize,
+      pageSize: DEFAULT_PAGE_SIZE,
     },
     sorting: [],
     filters: [],
@@ -287,6 +300,70 @@ export function useDataTable<TData extends DataTableData = DataTableData>({
 
   const [columnPinning, setColumnPinning] = useState<ColumnPinningState>({ left: [], right: [] });
 
+  const selection = useTableSelection();
+
+  // ---- Infinite pagination (paginationMode="infinite") ----
+
+  const infiniteEnabled = paginationMode === "infinite";
+  const isLoaderMode = infiniteEnabled && loadPage != null;
+
+  const infiniteRows = useInfiniteRows<TData>({
+    enabled: infiniteEnabled,
+    loadPage,
+    pageSize: pagination.pageSize,
+    sorting: sortingHook.sorting,
+    filters: filtering.advancedFilters,
+    columnFilters: filtering.columnFilters,
+    globalFilter: filtering.globalFilter,
+  });
+
+  // Loader mode: accumulated pages replace the data prop; rows arrive
+  // pre-filtered/sorted, so manual modes are forced on. In infinite mode the
+  // pagination row model is never applied (rows accumulate instead of slice).
+  const effectiveData = isLoaderMode ? infiniteRows.rows : data;
+  const effectiveManualFiltering = manualFiltering || isLoaderMode;
+  const effectiveManualSorting = manualSorting || isLoaderMode;
+  const effectiveManualPagination = manualPagination || infiniteEnabled;
+
+  // ---- Filterable Fields (visible columns + declared hidden fields) ----
+
+  const filterFields = useMemo(
+    () => resolveFilterFields(columns as any, filterableFields),
+    [columns, filterableFields],
+  );
+
+  // Advanced filters apply BEFORE TanStack so they work on any row-data key,
+  // including hidden / non-column fields. Server-side tables (manualFiltering)
+  // map the same filters to query params instead.
+  const preFilteredData = useMemo(() => {
+    if (effectiveManualFiltering) return effectiveData;
+    return applyFiltersToData(effectiveData, filtering.advancedFilters, filterFields);
+  }, [effectiveData, effectiveManualFiltering, filtering.advancedFilters, filterFields]);
+
+  // Column-funnel filters store FilterValue objects ({operator, value}) —
+  // interpret them with the shared operator semantics instead of TanStack's
+  // string auto-filter (which stringifies objects).
+  const operatorFilterFn = useCallback(
+    (row: any, columnId: string, filterValue: any) => {
+      if (filterValue == null || filterValue === "") return true;
+      if (isFilterValueShape(filterValue)) {
+        const type = getFilterFieldType(filterFields, columnId);
+        return applyFilterToValue(
+          row.getValue(columnId),
+          filterValue,
+          type === "select" ? "text" : type,
+        );
+      }
+      if (Array.isArray(filterValue)) {
+        return filterValue.length === 0 || filterValue.includes(row.getValue(columnId));
+      }
+      return String(row.getValue(columnId) ?? "")
+        .toLowerCase()
+        .includes(String(filterValue).toLowerCase());
+    },
+    [filterFields],
+  );
+
   // ---- URL State Synchronization ----
 
   useEffect(() => {
@@ -324,14 +401,26 @@ export function useDataTable<TData extends DataTableData = DataTableData>({
 
   // ---- TanStack Table Configuration ----
 
+  const getRowId = useCallback((row: TData, index: number) => {
+    if (row && typeof row === "object" && "id" in row && (row as any).id != null) {
+      return String((row as any).id);
+    }
+    return String(index);
+  }, []);
+
   const table = useReactTable({
-    data,
+    data: preFilteredData,
     columns: columns as ColumnDef<TData>[],
+    defaultColumn: { filterFn: operatorFilterFn as any },
     getCoreRowModel: getCoreRowModel(),
     getExpandedRowModel: enableRowExpansion ? getExpandedRowModel() : undefined,
+    // TanStack getSubRows receives the ORIGINAL data object (not a Row), so
+    // reading `.original` here always yielded undefined — every row reported
+    // getCanExpand() === false and the expansion caret column never rendered.
     getSubRows: getSubRows
-      ? (row) => getSubRows(row.original as TData)
-      : (row) => (row.original as any)?.subRows,
+      ? (originalRow) => getSubRows(originalRow as TData)
+      : (originalRow) => (originalRow as any)?.subRows,
+    getRowId,
 
     state: {
       pagination,
@@ -344,6 +433,7 @@ export function useDataTable<TData extends DataTableData = DataTableData>({
       ...(enableRowExpansion ? { expanded } : {}),
       ...(enableColumnPinning ? { columnPinning } : {}),
       ...(enableGrouping ? { grouping } : {}),
+      ...(enableRowSelection ? { rowSelection: selection.rowSelection } : {}),
     },
 
     onPaginationChange: setPagination,
@@ -356,21 +446,22 @@ export function useDataTable<TData extends DataTableData = DataTableData>({
     ...(enableRowExpansion ? { onExpandedChange: setExpanded } : {}),
     ...(enableColumnPinning ? { onColumnPinningChange: setColumnPinning } : {}),
     ...(enableGrouping ? { onGroupingChange: setGrouping } : {}),
+    ...(enableRowSelection ? { onRowSelectionChange: selection.setRowSelection } : {}),
 
-    getFilteredRowModel: manualFiltering ? undefined : getFilteredRowModel(),
-    getPaginationRowModel: manualPagination ? undefined : getPaginationRowModel(),
-    getSortedRowModel: manualSorting ? undefined : getSortedRowModel(),
+    getFilteredRowModel: effectiveManualFiltering ? undefined : getFilteredRowModel(),
+    getPaginationRowModel: effectiveManualPagination ? undefined : getPaginationRowModel(),
+    getSortedRowModel: effectiveManualSorting ? undefined : getSortedRowModel(),
     getGroupedRowModel: enableGrouping ? getGroupedRowModel() : undefined,
     getFacetedRowModel: enableFiltering ? getFacetedRowModel() : undefined,
     getFacetedUniqueValues: enableFiltering ? getFacetedUniqueValues() : undefined,
     getFacetedMinMaxValues: enableFiltering ? getFacetedMinMaxValues() : undefined,
 
-    manualFiltering,
-    manualPagination,
-    manualSorting,
+    manualFiltering: effectiveManualFiltering,
+    manualPagination: effectiveManualPagination,
+    manualSorting: effectiveManualSorting,
 
-    ...(manualPagination && rowCount != null ? { rowCount } : {}),
-    ...(manualPagination && pageCount != null ? { pageCount } : {}),
+    ...(effectiveManualPagination && rowCount != null ? { rowCount } : {}),
+    ...(effectiveManualPagination && pageCount != null ? { pageCount } : {}),
 
     columnResizeMode: "onChange",
 
@@ -380,6 +471,7 @@ export function useDataTable<TData extends DataTableData = DataTableData>({
     enableGlobalFilter: enableGlobalSearch,
     enableHiding: enableColumnVisibility,
     enableColumnResizing,
+    enableRowSelection,
   });
 
   // ---- View Management ----
@@ -439,28 +531,61 @@ export function useDataTable<TData extends DataTableData = DataTableData>({
   // ---- Computed Values ----
 
   const filteredData = useMemo(() => {
-    if (manualFiltering) return data;
+    if (effectiveManualFiltering) return effectiveData;
     return table.getFilteredRowModel().rows.map((row) => row.original);
-  }, [data, table, manualFiltering]);
+  }, [effectiveData, table, effectiveManualFiltering]);
 
   const paginatedData = useMemo(() => {
-    if (manualPagination) return filteredData;
+    if (effectiveManualPagination) return filteredData;
     return table.getPaginationRowModel().rows.map((row) => row.original);
-  }, [filteredData, table, manualPagination]);
+  }, [filteredData, table, effectiveManualPagination]);
 
   const totalPages =
-    manualPagination && pageCount != null
+    effectiveManualPagination && pageCount != null
       ? pageCount
-      : manualPagination && rowCount != null
+      : effectiveManualPagination && rowCount != null
         ? Math.ceil(rowCount / pagination.pageSize)
         : Math.ceil((table.getFilteredRowModel().rows.length || 0) / pagination.pageSize);
 
+  // ---- Infinite computed state ----
+
+  // Final row-model count (post filter/sort/group/expand): the slicing +
+  // exhaustion base for client mode; loader mode reveals everything loaded.
+  const rowModelCount = table.getRowModel().rows.length;
+  const rowModelCountRef = useRef(rowModelCount);
+  rowModelCountRef.current = rowModelCount;
+
+  const loadMoreInfinite = useCallback(() => {
+    if (isLoaderMode) {
+      infiniteRows.loadMore();
+    } else {
+      infiniteRows.loadMoreClient(rowModelCountRef.current);
+    }
+  }, [isLoaderMode, infiniteRows.loadMore, infiniteRows.loadMoreClient]);
+
+  const infinite: DataTableInfiniteState | undefined = infiniteEnabled
+    ? {
+        visibleRowCount: isLoaderMode
+          ? rowModelCount
+          : Math.min(infiniteRows.loadedPages * pagination.pageSize, rowModelCount),
+        loadedPages: infiniteRows.loadedPages,
+        totalCount: isLoaderMode ? infiniteRows.totalCount : rowModelCount,
+        exhausted: isLoaderMode
+          ? infiniteRows.exhausted
+          : infiniteRows.loadedPages * pagination.pageSize >= rowModelCount,
+        isInitialLoading: infiniteRows.isInitialLoading,
+        isAppending: infiniteRows.isAppending,
+        loadMore: loadMoreInfinite,
+      }
+    : undefined;
+
   // ---- Actions ----
 
   const actions = {
     setGlobalFilter: filtering.setGlobalFilter,
     setFilters: filtering.setFilters,
     addFilter: filtering.addFilter,
+    updateFilter: filtering.updateFilter,
     removeFilter: filtering.removeFilter,
     clearFilters: filtering.clearFilters,
     setPagination,
@@ -488,24 +613,40 @@ export function useDataTable<TData extends DataTableData = DataTableData>({
       if (enableRowExpansion) setExpanded({});
       if (enableColumnPinning) setColumnPinning({ left: [], right: [] });
       if (enableGrouping) setGrouping([]);
+      if (enableRowSelection) selection.clearSelection();
     },
     ...(enableRowExpansion ? { setExpanded } : {}),
     ...(enableGrouping ? { grouping, setGrouping } : {}),
+    ...(enableRowSelection
+      ? {
+          clearSelection: selection.clearSelection,
+          selectAll: selection.selectAll,
+          setRowSelection: selection.setRowSelection,
+        }
+      : {}),
   };
 
+  // Total row count across all pages (post-filter; server total in manual /
+  // loader modes). Consumed by the footer range summary and pagination chrome.
+  const resolvedTotalCount = isLoaderMode
+    ? (infiniteRows.totalCount ?? infiniteRows.rows.length)
+    : effectiveManualPagination && rowCount != null
+      ? rowCount
+      : table.getFilteredRowModel().rows.length;
+
   const computed = {
     filteredData,
     paginatedData,
     totalPages,
+    totalRows: resolvedTotalCount,
     hasActiveFilters: filtering.hasActiveFilters,
     activeFilterCount: filtering.activeFilterCount,
+    filterFields,
+    infinite,
   };
 
   // ---- State Change Callback ----
 
-  const resolvedTotalCount =
-    manualPagination && rowCount != null ? rowCount : table.getFilteredRowModel().rows.length;
-
   const currentState: DataTableState = {
     data,
     columns: columns as any,
@@ -525,6 +666,10 @@ export function useDataTable<TData extends DataTableData = DataTableData>({
     columnSizing,
     views: viewsHook.views,
     activeViewId: viewsHook.activeViewId,
+    isLoading: initialState?.isLoading,
+    // Carried through like isLoading so the root's error chrome is actually
+    // reachable from the public API (DG-ST-01) — previously dropped here.
+    error: initialState?.error,
   };
 
   useEffect(() => {

package/src/hooks/useInfiniteRows.spec.tsx

@@ -0,0 +1,215 @@
+/**
+ * useInfiniteRows — accumulation + prefetch engine specs.
+ *
+ * Covers the infinite pagination contract:
+ * - page 0 load prefetches page 1 while the user is still viewing page 0
+ * - loadMore appends synchronously from the prefetch cache (no skeleton)
+ * - a cache miss / in-flight prefetch flags isAppending (honest tail state)
+ * - sorting/filter/search/pageSize changes reset accumulation + cache
+ * - short last page / totalCount exhaustion stops further prefetch
+ * - client mode reveals chunks and clamps at the row-model count
+ */
+
+import { act, renderHook, waitFor } from "@testing-library/react";
+import { describe, expect, it, vi } from "vitest";
+import type { PageLoadQuery, PageLoadResult } from "../types";
+import { useInfiniteRows } from "./useInfiniteRows";
+
+type Row = { id: number };
+
+const ROWS: Row[] = Array.from({ length: 100 }, (_, i) => ({ id: i + 1 }));
+
+function makeInstantLoader(all: Row[] = ROWS, totalCount = all.length) {
+  return vi.fn(async (query: PageLoadQuery): Promise<PageLoadResult<Row>> => {
+    const start = query.pageIndex * query.pageSize;
+    return { rows: all.slice(start, start + query.pageSize), totalCount };
+  });
+}
+
+function deferred<T>() {
+  let resolve!: (value: T) => void;
+  let reject!: (reason?: unknown) => void;
+  const promise = new Promise<T>((res, rej) => {
+    resolve = res;
+    reject = rej;
+  });
+  return { promise, resolve, reject };
+}
+
+const baseQuery = {
+  enabled: true,
+  pageSize: 20,
+  sorting: [] as any[],
+  filters: [] as any[],
+  columnFilters: [] as any[],
+  globalFilter: "",
+};
+
+describe("useInfiniteRows", () => {
+  describe("loader mode prefetch", () => {
+    it("loads page 0 and prefetches page 1 while page 0 is on screen", async () => {
+      const loader = makeInstantLoader();
+      const { result } = renderHook(() => useInfiniteRows<Row>({ ...baseQuery, loadPage: loader }));
+
+      expect(result.current.isLoaderMode).toBe(true);
+      await waitFor(() => expect(result.current.rows).toHaveLength(20));
+
+      // Only page 0 is appended, but page 1 was already requested.
+      expect(result.current.loadedPages).toBe(1);
+      const requested = loader.mock.calls.map(([q]) => q.pageIndex);
+      expect(requested).toEqual([0, 1]);
+      expect(result.current.totalCount).toBe(100);
+      expect(result.current.exhausted).toBe(false);
+    });
+
+    it("appends instantly from the prefetch cache and prefetches the next page", async () => {
+      const loader = makeInstantLoader();
+      const { result } = renderHook(() => useInfiniteRows<Row>({ ...baseQuery, loadPage: loader }));
+      await waitFor(() => expect(result.current.rows).toHaveLength(20));
+      // Let the page-1 prefetch resolve into the cache.
+      await act(async () => {});
+
+      act(() => result.current.loadMore());
+
+      // Synchronous append (no extra loader call for page 1); page 2 prefetched.
+      expect(result.current.rows).toHaveLength(40);
+      expect(result.current.isAppending).toBe(false);
+      const requested = loader.mock.calls.map(([q]) => q.pageIndex);
+      expect(requested).toEqual([0, 1, 2]);
+    });
+
+    it("flags isAppending while a slow prefetch is still in flight", async () => {
+      const deferreds = new Map<number, ReturnType<typeof deferred<PageLoadResult<Row>>>>();
+      const loader = vi.fn((query: PageLoadQuery) => {
+        const d = deferred<PageLoadResult<Row>>();
+        deferreds.set(query.pageIndex, d);
+        return d.promise;
+      });
+      const { result } = renderHook(() => useInfiniteRows<Row>({ ...baseQuery, loadPage: loader }));
+
+      expect(result.current.isInitialLoading).toBe(true);
+      await act(async () => {
+        deferreds.get(0)!.resolve({ rows: ROWS.slice(0, 20), totalCount: 100 });
+      });
+      expect(result.current.rows).toHaveLength(20);
+      expect(result.current.isInitialLoading).toBe(false);
+      // Prefetch for page 1 started but has NOT resolved.
+      expect(deferreds.has(1)).toBe(true);
+
+      act(() => result.current.loadMore());
+      expect(result.current.isAppending).toBe(true);
+      expect(result.current.rows).toHaveLength(20);
+
+      await act(async () => {
+        deferreds.get(1)!.resolve({ rows: ROWS.slice(20, 40), totalCount: 100 });
+      });
+      expect(result.current.isAppending).toBe(false);
+      expect(result.current.rows).toHaveLength(40);
+    });
+
+    it("resets accumulation and cache when sorting changes", async () => {
+      const loader = makeInstantLoader();
+      const { result, rerender } = renderHook(
+        ({ sorting }: { sorting: any[] }) =>
+          useInfiniteRows<Row>({ ...baseQuery, sorting, loadPage: loader }),
+        { initialProps: { sorting: [] as any[] } },
+      );
+      await waitFor(() => expect(result.current.rows).toHaveLength(20));
+      await act(async () => {});
+      act(() => result.current.loadMore());
+      expect(result.current.rows).toHaveLength(40);
+
+      loader.mockClear();
+      rerender({ sorting: [{ id: "id", desc: true }] });
+
+      // Back to page 0 for the new query; fresh prefetch of page 1.
+      await waitFor(() => expect(result.current.loadedPages).toBe(1));
+      expect(result.current.rows).toHaveLength(20);
+      const requested = loader.mock.calls.map(([q]) => q.pageIndex);
+      expect(requested).toEqual([0, 1]);
+      expect(loader.mock.calls[0][0].sorting).toEqual([{ id: "id", desc: true }]);
+    });
+
+    it("resets when the global filter changes", async () => {
+      const loader = makeInstantLoader();
+      const { result, rerender } = renderHook(
+        ({ globalFilter }: { globalFilter: string }) =>
+          useInfiniteRows<Row>({ ...baseQuery, globalFilter, loadPage: loader }),
+        { initialProps: { globalFilter: "" } },
+      );
+      await waitFor(() => expect(result.current.rows).toHaveLength(20));
+      loader.mockClear();
+
+      rerender({ globalFilter: "abc" });
+      await waitFor(() =>
+        expect(loader.mock.calls.some(([q]) => q.globalFilter === "abc" && q.pageIndex === 0)).toBe(
+          true,
+        ),
+      );
+      await waitFor(() => expect(result.current.loadedPages).toBe(1));
+    });
+
+    it("marks exhausted on a short last page and stops prefetching", async () => {
+      const short = ROWS.slice(0, 30); // 20 + 10 with pageSize 20
+      const loader = makeInstantLoader(short, 30);
+      const { result } = renderHook(() => useInfiniteRows<Row>({ ...baseQuery, loadPage: loader }));
+      await waitFor(() => expect(result.current.rows).toHaveLength(20));
+      await act(async () => {});
+
+      act(() => result.current.loadMore());
+      expect(result.current.rows).toHaveLength(30);
+      expect(result.current.exhausted).toBe(true);
+
+      // No page-2 request: last page was short.
+      const requested = loader.mock.calls.map(([q]) => q.pageIndex);
+      expect(requested).toEqual([0, 1]);
+      act(() => result.current.loadMore());
+      expect(requested).toEqual([0, 1]);
+    });
+
+    it("marks exhausted when totalCount is reached exactly at a page boundary", async () => {
+      const exact = ROWS.slice(0, 40); // exactly two pages of 20
+      const loader = makeInstantLoader(exact, 40);
+      const { result } = renderHook(() => useInfiniteRows<Row>({ ...baseQuery, loadPage: loader }));
+      await waitFor(() => expect(result.current.rows).toHaveLength(20));
+      await act(async () => {});
+      act(() => result.current.loadMore());
+      expect(result.current.rows).toHaveLength(40);
+      expect(result.current.exhausted).toBe(true);
+    });
+  });
+
+  describe("client mode", () => {
+    it("reveals chunks and clamps at the row-model count", () => {
+      const { result } = renderHook(() => useInfiniteRows<Row>({ ...baseQuery }));
+      expect(result.current.isLoaderMode).toBe(false);
+      expect(result.current.loadedPages).toBe(1);
+
+      act(() => result.current.loadMoreClient(50));
+      expect(result.current.loadedPages).toBe(2);
+      act(() => result.current.loadMoreClient(50));
+      expect(result.current.loadedPages).toBe(3);
+      // 3 * 20 = 60 >= 50 — exhausted, no further reveal.
+      act(() => result.current.loadMoreClient(50));
+      expect(result.current.loadedPages).toBe(3);
+    });
+
+    it("resets revealed chunks when the query changes", () => {
+      const { result, rerender } = renderHook(
+        ({ globalFilter }: { globalFilter: string }) =>
+          useInfiniteRows<Row>({ ...baseQuery, globalFilter }),
+        { initialProps: { globalFilter: "" } },
+      );
+      act(() => result.current.loadMoreClient(100));
+      expect(result.current.loadedPages).toBe(2);
+      rerender({ globalFilter: "x" });
+      expect(result.current.loadedPages).toBe(1);
+    });
+
+    it("does nothing when disabled", () => {
+      const { result } = renderHook(() => useInfiniteRows<Row>({ ...baseQuery, enabled: false }));
+      act(() => result.current.loadMoreClient(100));
+      expect(result.current.loadedPages).toBe(1);
+    });
+  });
+});