feat: add CollectionStateSynchronizer API and useSearchParamsSynchronizer

Introduce a pluggable synchronizer interface for persisting collection
state (filters, sort, pageSize) to external stores.

- Add CollectionSnapshot and CollectionStateSynchronizer types
- Add synchronizer option to UseCollectionOptions / useCollectionVariables
- Implement useSearchParamsSynchronizer (URL search params persistence)
  with prefix and debounce support
- Add tests for synchronizer integration and useSearchParamsSynchronizer

Author: IzumiSy

packages/core/src/hooks/use-collection-variables-synchronizer.test.ts

@@ -0,0 +1,155 @@
+import { renderHook, act } from "@testing-library/react";
+import { describe, it, expect, vi } from "vitest";
+import type { CollectionStateSynchronizer } from "@/types/collection";
+import { useCollectionVariables } from "./use-collection-variables";
+
+describe("useCollectionVariables with synchronizer", () => {
+  function createMockSynchronizer(initial?: ReturnType<CollectionStateSynchronizer["read"]>) {
+    return {
+      read: vi.fn(() => initial),
+      write: vi.fn(),
+    } satisfies CollectionStateSynchronizer;
+  }
+
+  describe("read (initial hydration)", () => {
+    it("uses synchronizer initial state over params defaults", () => {
+      const synchronizer = createMockSynchronizer({
+        filters: [{ field: "status", operator: "eq", value: "ACTIVE" }],
+        sort: [{ field: "name", direction: "Asc" }],
+        pageSize: 50,
+      });
+
+      const { result } = renderHook(() =>
+        useCollectionVariables({
+          params: { pageSize: 20 },
+          synchronizer,
+        }),
+      );
+
+      expect(synchronizer.read).toHaveBeenCalledOnce();
+      expect(result.current.control.filters).toEqual([
+        { field: "status", operator: "eq", value: "ACTIVE" },
+      ]);
+      expect(result.current.control.sortStates).toEqual([{ field: "name", direction: "Asc" }]);
+      expect(result.current.control.pageSize).toBe(50);
+    });
+
+    it("falls back to params when synchronizer returns undefined", () => {
+      const synchronizer = createMockSynchronizer(undefined);
+
+      const { result } = renderHook(() =>
+        useCollectionVariables({
+          params: {
+            pageSize: 30,
+            initialSort: [{ field: "createdAt", direction: "Desc" }],
+          },
+          synchronizer,
+        }),
+      );
+
+      expect(result.current.control.pageSize).toBe(30);
+      expect(result.current.control.sortStates).toEqual([
+        { field: "createdAt", direction: "Desc" },
+      ]);
+      expect(result.current.control.filters).toEqual([]);
+    });
+
+    it("partially overrides params (only pageSize from synchronizer)", () => {
+      const synchronizer = createMockSynchronizer({
+        pageSize: 100,
+      });
+
+      const { result } = renderHook(() =>
+        useCollectionVariables({
+          params: {
+            pageSize: 20,
+            initialSort: [{ field: "name", direction: "Asc" }],
+          },
+          synchronizer,
+        }),
+      );
+
+      expect(result.current.control.pageSize).toBe(100);
+      // Sort falls back to params
+      expect(result.current.control.sortStates).toEqual([{ field: "name", direction: "Asc" }]);
+    });
+  });
+
+  describe("write (state persistence)", () => {
+    it("calls write on filter change", () => {
+      const synchronizer = createMockSynchronizer(undefined);
+
+      const { result } = renderHook(() =>
+        useCollectionVariables({
+          params: { pageSize: 20 },
+          synchronizer,
+        }),
+      );
+
+      act(() => {
+        result.current.control.addFilter("status", "eq", "ACTIVE");
+      });
+
+      expect(synchronizer.write).toHaveBeenCalledWith(
+        expect.objectContaining({
+          filters: [{ field: "status", operator: "eq", value: "ACTIVE" }],
+          pageSize: 20,
+        }),
+      );
+    });
+
+    it("calls write on sort change", () => {
+      const synchronizer = createMockSynchronizer(undefined);
+
+      const { result } = renderHook(() =>
+        useCollectionVariables({
+          params: { pageSize: 20 },
+          synchronizer,
+        }),
+      );
+
+      act(() => {
+        result.current.control.setSort("name", "Desc");
+      });
+
+      expect(synchronizer.write).toHaveBeenCalledWith(
+        expect.objectContaining({
+          sort: [{ field: "name", direction: "Desc" }],
+          pageSize: 20,
+        }),
+      );
+    });
+
+    it("calls write on pageSize change", () => {
+      const synchronizer = createMockSynchronizer(undefined);
+
+      const { result } = renderHook(() =>
+        useCollectionVariables({
+          params: { pageSize: 20 },
+          synchronizer,
+        }),
+      );
+
+      act(() => {
+        result.current.control.setPageSize(50);
+      });
+
+      expect(synchronizer.write).toHaveBeenCalledWith(
+        expect.objectContaining({
+          pageSize: 50,
+        }),
+      );
+    });
+
+    it("does not call write when no synchronizer is provided", () => {
+      const { result } = renderHook(() => useCollectionVariables({ params: { pageSize: 20 } }));
+
+      act(() => {
+        result.current.control.addFilter("status", "eq", "ACTIVE");
+      });
+
+      // No error thrown — just verifying it doesn't crash
+      expect(result.current.control.filters).toHaveLength(1);
+    });
+  });
+});

packages/core/src/hooks/use-collection-variables.ts

@@ -1,4 +1,4 @@
-import { useCallback, useMemo, useState } from "react";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import type {
   BuildQueryVariables,
   CollectionControl,
@@ -130,14 +130,22 @@ export function useCollectionVariables(
 export function useCollectionVariables(
   options: UseCollectionOptions & { tableMetadata?: TableMetadata },
 ): unknown {
-  const { params = {} } = options;
+  const { params = {}, synchronizer } = options;
   const { initialFilters = [], initialSort = [], pageSize: initialPageSize = 20 } = params;
 
+  // ---------------------------------------------------------------------------
+  // Hydrate initial state from synchronizer (read once on mount)
+  // ---------------------------------------------------------------------------
+  const syncInitial = useRef(() => synchronizer?.read()).current();
+  const resolvedInitialFilters = syncInitial?.filters ?? initialFilters;
+  const resolvedInitialSort = syncInitial?.sort ?? initialSort;
+  const resolvedInitialPageSize = syncInitial?.pageSize ?? initialPageSize;
+
   // ---------------------------------------------------------------------------
   // State
   // ---------------------------------------------------------------------------
-  const [filters, setFiltersState] = useState<Filter[]>(initialFilters);
-  const [sortStates, setSortStates] = useState<SortState[]>(initialSort);
+  const [filters, setFiltersState] = useState<Filter[]>(resolvedInitialFilters);
+  const [sortStates, setSortStates] = useState<SortState[]>(resolvedInitialSort);
 
   const {
     pageSize,
@@ -151,7 +159,21 @@ export function useCollectionVariables(
     getHasPrevPage,
     getHasNextPage,
     resetCount,
-  } = useCursorPagination(initialPageSize);
+  } = useCursorPagination(resolvedInitialPageSize);
+
+  // ---------------------------------------------------------------------------
+  // Synchronizer write-back
+  // ---------------------------------------------------------------------------
+  const synchronizerRef = useRef(synchronizer);
+  synchronizerRef.current = synchronizer;
+
+  useEffect(() => {
+    synchronizerRef.current?.write({
+      filters,
+      sort: sortStates,
+      pageSize,
+    });
+  }, [filters, sortStates, pageSize]);
 
   // ---------------------------------------------------------------------------
   // Filter operations