@hexclave/dashboard-ui-components 1.0.51 → 1.0.52

package/src/components/data-grid/use-data-source.test.tsx

@@ -0,0 +1,289 @@
+// @vitest-environment jsdom
+
+import { act, cleanup, fireEvent, render, waitFor } from "@testing-library/react";
+import { afterEach, describe, expect, it } from "vitest";
+import { useDataSource } from "./use-data-source";
+import type { DataGridColumnDef, DataGridDataPaginationMode, DataGridDataSource } from "./types";
+
+type Row = {
+  id: string,
+  name: string,
+};
+
+const columns: DataGridColumnDef<Row>[] = [
+  {
+    id: "name",
+    header: "Name",
+    accessor: (row) => row.name,
+    width: 160,
+  },
+];
+
+function DataSourceHarness({
+  dataSource,
+  paginationMode = "infinite",
+}: {
+  dataSource: DataGridDataSource<Row>,
+  paginationMode?: DataGridDataPaginationMode,
+}) {
+  const gridData = useDataSource({
+    dataSource,
+    columns,
+    getRowId: (row) => row.id,
+    sorting: [],
+    quickSearch: "",
+    pagination: { pageIndex: 0, pageSize: 25 },
+    paginationMode,
+  });
+
+  return (
+    <>
+      <button onClick={gridData.loadMore}>Load more</button>
+      <span data-testid="row-count">{gridData.rows.length}</span>
+      <span data-testid="row-name">{gridData.rows[0]?.name ?? ""}</span>
+      <span data-testid="error">{gridData.error?.message ?? ""}</span>
+    </>
+  );
+}
+
+afterEach(() => {
+  cleanup();
+});
+
+describe("useDataSource infinite pagination", () => {
+  it("defers loadMore during the initial fetch and replays it once settled", async () => {
+    const calls: Array<{ cursor: unknown }> = [];
+    let resolveInitial: (value: void) => void = () => {};
+    const initialFetch = new Promise<void>((resolve) => {
+      resolveInitial = resolve;
+    });
+    const dataSource: DataGridDataSource<Row> = async function* (params) {
+      calls.push({ cursor: params.cursor });
+      if (calls.length === 1) {
+        await initialFetch;
+        yield {
+          rows: [{ id: "row-1", name: "Row 1" }],
+          nextCursor: "cursor-1",
+          hasMore: true,
+        };
+        return;
+      }
+      yield {
+        rows: [{ id: "row-2", name: "Row 2" }],
+        nextCursor: null,
+        hasMore: false,
+      };
+    };
+
+    const { getByRole } = render(<DataSourceHarness dataSource={dataSource} />);
+    await waitFor(() => expect(calls).toHaveLength(1));
+
+    fireEvent.click(getByRole("button", { name: "Load more" }));
+    // Not started concurrently — queued behind the in-flight initial fetch.
+    expect(calls).toHaveLength(1);
+
+    await act(async () => {
+      resolveInitial();
+    });
+    // The queued loadMore replays automatically with the completed cursor,
+    // so a sentinel that fired during the fetch is not silently dropped.
+    await waitFor(() => expect(calls).toHaveLength(2));
+    expect(calls[1]).toEqual({ cursor: "cursor-1" });
+  });
+
+  it("keeps the committed cursor when an aborted reset is followed by a skipped refetch", async () => {
+    const callsA: Array<{ cursor: unknown }> = [];
+    const dataSourceA: DataGridDataSource<Row> = async function* (params) {
+      callsA.push({ cursor: params.cursor });
+      if (callsA.length === 1) {
+        yield {
+          rows: [{ id: "row-1", name: "Row 1" }],
+          nextCursor: "cursor-1",
+          hasMore: true,
+        };
+        return;
+      }
+      yield {
+        rows: [{ id: "row-2", name: "Row 2" }],
+        nextCursor: null,
+        hasMore: false,
+      };
+    };
+    // Stays in flight until we resolve it, after the switch back to A has
+    // already aborted it.
+    let resolveB: (value: void) => void = () => {};
+    const dataSourceB: DataGridDataSource<Row> = async function* () {
+      await new Promise<void>((resolve) => {
+        resolveB = resolve;
+      });
+    };
+
+    const { getByRole, getByTestId, rerender } = render(
+      <DataSourceHarness dataSource={dataSourceA} />,
+    );
+    await waitFor(() => expect(getByTestId("row-count").textContent).toBe("1"));
+
+    // Unstable dataSource identity flipping away and back to a completed
+    // reference: the B reset starts (and used to wipe cursor/pageIndex
+    // immediately), then gets aborted; the A effect run matches the
+    // completed-fetch key and skips.
+    rerender(<DataSourceHarness dataSource={dataSourceB} />);
+    rerender(<DataSourceHarness dataSource={dataSourceA} />);
+    await act(async () => {
+      resolveB();
+    });
+
+    fireEvent.click(getByRole("button", { name: "Load more" }));
+    await waitFor(() => expect(getByTestId("row-count").textContent).toBe("2"));
+    // The append must continue from the committed cursor, not restart from
+    // the beginning with cursor === undefined.
+    expect(callsA).toEqual([{ cursor: undefined }, { cursor: "cursor-1" }]);
+  });
+
+  it("does not treat an aborted zero-yield reset as a completed fetch", async () => {
+    const dataSourceA: DataGridDataSource<Row> = async function* () {
+      yield {
+        rows: [{ id: "row-a", name: "A" }],
+        nextCursor: null,
+        hasMore: false,
+      };
+    };
+    let bCalls = 0;
+    let resolveFirstB: (value: void) => void = () => {};
+    const dataSourceB: DataGridDataSource<Row> = async function* () {
+      bCalls++;
+      if (bCalls === 1) {
+        // Aborted before any yield: completing this must not mark B as a
+        // successful skip key, or a later render with B would keep A's rows.
+        await new Promise<void>((resolve) => {
+          resolveFirstB = resolve;
+        });
+        return;
+      }
+      yield {
+        rows: [{ id: "row-b", name: "B" }],
+        nextCursor: null,
+        hasMore: false,
+      };
+    };
+
+    const { getByTestId, rerender } = render(
+      <DataSourceHarness dataSource={dataSourceA} />,
+    );
+    await waitFor(() => expect(getByTestId("row-name").textContent).toBe("A"));
+
+    rerender(<DataSourceHarness dataSource={dataSourceB} />);
+    rerender(<DataSourceHarness dataSource={dataSourceA} />);
+    await act(async () => {
+      resolveFirstB();
+    });
+
+    rerender(<DataSourceHarness dataSource={dataSourceB} />);
+    await waitFor(() => expect(getByTestId("row-name").textContent).toBe("B"));
+    expect(bCalls).toBe(2);
+  });
+
+  it("does not replay a deferred loadMore after the in-flight fetch errors", async () => {
+    const calls: Array<{ cursor: unknown }> = [];
+    let rejectInitial: (err: Error) => void = () => {};
+    const initialFetch = new Promise<void>((_resolve, reject) => {
+      rejectInitial = reject;
+    });
+    const dataSource: DataGridDataSource<Row> = async function* (params) {
+      calls.push({ cursor: params.cursor });
+      await initialFetch;
+      yield { rows: [], nextCursor: null, hasMore: false };
+    };
+
+    const { getByRole, getByTestId } = render(<DataSourceHarness dataSource={dataSource} />);
+    await waitFor(() => expect(calls).toHaveLength(1));
+
+    // Deferred while the (soon-to-fail) fetch is in flight.
+    fireEvent.click(getByRole("button", { name: "Load more" }));
+
+    await act(async () => {
+      rejectInitial(new Error("fetch failed"));
+    });
+
+    // The failed fetch must surface its error and must NOT chain the deferred
+    // append (which would fetch against inconsistent state and clear the
+    // error again via setError(null)).
+    await waitFor(() => expect(getByTestId("error").textContent).toBe("fetch failed"));
+    expect(calls).toHaveLength(1);
+  });
+
+  it("discards a deferred loadMore when pagination mode leaves infinite", async () => {
+    const calls: Array<{ cursor: unknown }> = [];
+    let resolveInitial: (value: void) => void = () => {};
+    const initialFetch = new Promise<void>((resolve) => {
+      resolveInitial = resolve;
+    });
+    const dataSource: DataGridDataSource<Row> = async function* (params) {
+      calls.push({ cursor: params.cursor });
+      if (calls.length === 1) {
+        await initialFetch;
+        yield {
+          rows: [{ id: "row-1", name: "Row 1" }],
+          nextCursor: "cursor-1",
+          hasMore: true,
+        };
+        return;
+      }
+      yield {
+        rows: [{ id: "row-2", name: "Row 2" }],
+        nextCursor: null,
+        hasMore: false,
+      };
+    };
+
+    const { getByRole, rerender } = render(
+      <DataSourceHarness dataSource={dataSource} paginationMode="infinite" />,
+    );
+    await waitFor(() => expect(calls).toHaveLength(1));
+
+    fireEvent.click(getByRole("button", { name: "Load more" }));
+    expect(calls).toHaveLength(1);
+
+    rerender(<DataSourceHarness dataSource={dataSource} paginationMode="server" />);
+
+    await act(async () => {
+      resolveInitial();
+    });
+
+    // Mode left infinite while the deferred loadMore was queued — do not
+    // append against server pagination after the fetch settles.
+    await waitFor(() => expect(calls).toHaveLength(1));
+    await act(async () => {
+      await new Promise((resolve) => setTimeout(resolve, 20));
+    });
+    expect(calls).toHaveLength(1);
+  });
+
+  it("uses the completed page cursor for the next loadMore fetch", async () => {
+    const calls: Array<{ cursor: unknown }> = [];
+    const dataSource: DataGridDataSource<Row> = async function* (params) {
+      calls.push({ cursor: params.cursor });
+      if (calls.length === 1) {
+        yield {
+          rows: [{ id: "row-1", name: "Row 1" }],
+          nextCursor: "cursor-1",
+          hasMore: true,
+        };
+        return;
+      }
+      yield {
+        rows: [{ id: "row-2", name: "Row 2" }],
+        nextCursor: null,
+        hasMore: false,
+      };
+    };
+
+    const { getByRole, getByTestId } = render(<DataSourceHarness dataSource={dataSource} />);
+    await waitFor(() => expect(getByTestId("row-count").textContent).toBe("1"));
+
+    fireEvent.click(getByRole("button", { name: "Load more" }));
+
+    await waitFor(() => expect(getByTestId("row-count").textContent).toBe("2"));
+    expect(calls).toEqual([{ cursor: undefined }, { cursor: "cursor-1" }]);
+  });
+});

package/src/components/data-grid/use-data-source.ts

@@ -1,4 +1,5 @@
 import { useCallback, useEffect, useMemo, useRef, useState } from "react";
+import { runAsynchronously } from "@hexclave/shared/dist/utils/promises";
 import type {
   DataGridColumnDef,
   DataGridDataSource,
@@ -122,10 +123,28 @@ function useAsyncDataSource<TRow>(opts: {
   const [error, setError] = useState<Error | null>(null);
 
   const cursorRef = useRef<unknown>(undefined);
-  const abortRef = useRef<AbortController | null>(null);
+  const inFlightFetchRef = useRef<AbortController | null>(null);
+  // The infinite-scroll sentinel's IntersectionObserver only fires on
+  // intersection *changes* (by design, to avoid auto-loading the whole
+  // dataset). If `loadMore` is called while another fetch is in flight we
+  // can't just drop it: the sentinel won't fire again until the user scrolls
+  // away and back. Remember the request and replay it once the in-flight
+  // fetch settles.
+  const pendingLoadMoreRef = useRef(false);
+  const hasMoreRef = useRef(true);
+  const paginationModeRef = useRef(paginationMode);
+  paginationModeRef.current = paginationMode;
   const pageIndexRef = useRef(0);
   const hasDataRef = useRef(false);
   const hasMountedServerPaginationRef = useRef(false);
+  // Effects can be replayed when a descendant suspends. Only a fetch that
+  // actually delivered results is safe to reuse as a skip key.
+  const lastCompletedNonAppendFetchKeyRef = useRef<{
+    dataSource: DataGridDataSource<TRow>,
+    sortingKey: string,
+    quickSearchKey: string,
+    pageSize: number,
+  } | null>(null);
 
   const latestArgsRef = useRef({
     dataSource,
@@ -141,6 +160,10 @@ function useAsyncDataSource<TRow>(opts: {
 
   const fetchPage = useCallback(
     async (append: boolean) => {
+      if (append && inFlightFetchRef.current != null) {
+        return;
+      }
+
       const {
         dataSource: currentDataSource,
         getRowId: currentGetRowId,
@@ -149,9 +172,15 @@ function useAsyncDataSource<TRow>(opts: {
         pagination: currentPagination,
       } = latestArgsRef.current;
 
-      abortRef.current?.abort();
+      inFlightFetchRef.current?.abort();
       const controller = new AbortController();
-      abortRef.current = controller;
+      inFlightFetchRef.current = controller;
+      const fetchKey = {
+        dataSource: currentDataSource,
+        sortingKey: JSON.stringify(currentSorting),
+        quickSearchKey: currentQuickSearch,
+        pageSize: currentPagination.pageSize,
+      };
 
       if (append) {
         setIsLoadingMore(true);
@@ -162,21 +191,34 @@ function useAsyncDataSource<TRow>(opts: {
         } else {
           setIsLoading(true);
         }
-        cursorRef.current = undefined;
-        pageIndexRef.current = 0;
       }
       // Clear previous error at the start of a new attempt; we'll set it
       // again if this attempt fails.
       setError(null);
 
+      // Cursor/page-index state is tracked locally and only committed to the
+      // shared refs when this fetch actually delivers a result. An aborted
+      // reset must not clobber the committed pagination state: if it did, a
+      // later effect run that skips via `lastCompletedNonAppendFetchKeyRef`
+      // would keep the old rows but leave `cursorRef === undefined`, and the
+      // next loadMore would silently restart from page one.
+      let cursor = append ? cursorRef.current : undefined;
+      let pageIndex = append ? pageIndexRef.current : 0;
+      let failed = false;
+      // The abort guard lives inside the for-await body, so a generator that
+      // completes with zero yields never hits it and would otherwise fall
+      // through to the post-loop completion-key write. Only mark a reset
+      // complete after it has actually delivered (and committed) a result.
+      let committedResult = false;
+
       try {
         const params: DataGridFetchParams = {
           sorting: currentSorting,
           quickSearch: currentQuickSearch,
           pagination: append
-            ? { pageIndex: pageIndexRef.current, pageSize: currentPagination.pageSize }
+            ? { pageIndex, pageSize: currentPagination.pageSize }
             : currentPagination,
-          cursor: cursorRef.current,
+          cursor,
         };
 
         const gen = currentDataSource(params);
@@ -188,9 +230,11 @@ function useAsyncDataSource<TRow>(opts: {
             setTotalRowCount(result.totalRowCount);
           }
           if (result.nextCursor !== undefined) {
-            cursorRef.current = result.nextCursor;
+            cursor = result.nextCursor;
           }
-          setHasMore(result.hasMore !== false);
+          cursorRef.current = cursor;
+          hasMoreRef.current = result.hasMore !== false;
+          setHasMore(hasMoreRef.current);
 
           if (append) {
             setRows((prev) => {
@@ -201,11 +245,20 @@ function useAsyncDataSource<TRow>(opts: {
               return [...prev, ...newRows];
             });
           } else {
+            // The visible rows now belong to this (possibly still incomplete)
+            // reset, so the previously completed fetch key no longer describes
+            // them and must not allow a skip.
+            lastCompletedNonAppendFetchKeyRef.current = null;
             setRows(result.rows);
           }
 
           hasDataRef.current = true;
-          pageIndexRef.current++;
+          committedResult = true;
+          pageIndex++;
+          pageIndexRef.current = pageIndex;
+        }
+        if (!append && committedResult && !controller.signal.aborted) {
+          lastCompletedNonAppendFetchKeyRef.current = fetchKey;
         }
       } catch (err) {
         if (controller.signal.aborted) return;
@@ -214,12 +267,35 @@ function useAsyncDataSource<TRow>(opts: {
         // consumer to wire up error rendering.
         // eslint-disable-next-line no-console
         console.error("[DataGrid] Data source error:", err);
+        failed = true;
         setError(err instanceof Error ? err : new Error(String(err)));
       } finally {
-        if (!controller.signal.aborted) {
+        // Only the owning fetch resets the loading flags; if this fetch was
+        // replaced by a newer one, that fetch manages them instead. This also
+        // covers cleanup-initiated aborts, which would otherwise leave
+        // `isLoadingMore` stuck and block all future loadMore calls.
+        if (inFlightFetchRef.current === controller) {
+          inFlightFetchRef.current = null;
           setIsLoading(false);
           setIsRefetching(false);
           setIsLoadingMore(false);
+          // Replay a loadMore that was requested (and deferred) while this
+          // fetch was in flight — but only if this fetch succeeded while we
+          // are still in infinite mode. Skip on failure (the append would run
+          // against inconsistent state and its setError(null) would hide this
+          // fetch's error), when pagination mode changed away from infinite,
+          // and on unmount-cleanup aborts — `inFlightFetchRef.current ===
+          // controller` with an aborted signal only happens then.
+          const shouldChainLoadMore =
+            pendingLoadMoreRef.current
+            && !failed
+            && !controller.signal.aborted
+            && hasMoreRef.current
+            && paginationModeRef.current === "infinite";
+          pendingLoadMoreRef.current = false;
+          if (shouldChainLoadMore) {
+            runAsynchronously(fetchPage(true));
+          }
         }
       }
     },
@@ -227,8 +303,26 @@ function useAsyncDataSource<TRow>(opts: {
   );
 
   useEffect(() => {
-    fetchPage(false).catch(() => {});
-    return () => abortRef.current?.abort();
+    // Deferred loadMore is only meaningful for infinite scroll; drop it when
+    // the consumer leaves that mode so a later settle cannot append wrongly.
+    if (paginationMode !== "infinite") {
+      pendingLoadMoreRef.current = false;
+    }
+  }, [paginationMode]);
+
+  useEffect(() => {
+    const lastCompletedKey = lastCompletedNonAppendFetchKeyRef.current;
+    const isSameCompletedFetch = hasDataRef.current
+      && lastCompletedKey?.dataSource === dataSource
+      && lastCompletedKey.sortingKey === sortingKey
+      && lastCompletedKey.quickSearchKey === quickSearchKey
+      && lastCompletedKey.pageSize === pagination.pageSize;
+    if (!isSameCompletedFetch) {
+      runAsynchronously(fetchPage(false));
+    }
+    // Always return the abort cleanup (even when the fetch is skipped) so an
+    // in-flight append is cancelled on unmount.
+    return () => inFlightFetchRef.current?.abort();
     // Also refetches when `dataSource` identity changes — consumers encode
     // external filter state into the generator's closure, so a new
     // generator reference is the signal that the query changed.
@@ -243,17 +337,25 @@ function useAsyncDataSource<TRow>(opts: {
       hasMountedServerPaginationRef.current = true;
       return;
     }
-    fetchPage(false).catch(() => {});
+    runAsynchronously(fetchPage(false));
   }, [fetchPage, paginationMode, pagination.pageIndex]);
 
   const loadMore = useCallback(() => {
-    if (!isLoadingMore && hasMore && paginationMode === "infinite") {
-      fetchPage(true).catch(() => {});
+    if (paginationMode !== "infinite" || !hasMore) {
+      return;
+    }
+    // Keep pagination single-flight. In particular, do not let the sentinel
+    // start an append against a cursor that a concurrent reset is replacing.
+    // Queue the request instead of dropping it (see pendingLoadMoreRef).
+    if (inFlightFetchRef.current != null) {
+      pendingLoadMoreRef.current = true;
+      return;
     }
-  }, [isLoadingMore, hasMore, paginationMode, fetchPage]);
+    runAsynchronously(fetchPage(true));
+  }, [hasMore, paginationMode, fetchPage]);
 
   const reload = useCallback(() => {
-    fetchPage(false).catch(() => {});
+    runAsynchronously(fetchPage(false));
   }, [fetchPage]);
 
   return {