refactor(core): introduce reducer-based collection state with pluggable synchronizer

- Add collectionReducer with source tracking (init/user/sync) to eliminate ref flags
- Extract useSynchronizerBridge hook for subscribe/write-back logic
- Refactor useCollectionVariables to use useReducer + bridge
- Refactor useCursorPagination to accept external pageSize parameter
- Update useSearchParamsSynchronizer to use subscribe/write pattern
- Update tests for new architecture

Author: IzumiSy

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

@@ -0,0 +1,145 @@
+import { useEffect } from "react";
+import type {
+  CollectionSnapshot,
+  CollectionStateSynchronizer,
+  Filter,
+  SortState,
+} from "@/types/collection";
+
+// =============================================================================
+// State & Action types
+// =============================================================================
+
+export type ChangeSource = "init" | "user" | "sync";
+
+export interface CollectionState {
+  filters: Filter[];
+  sortStates: SortState[];
+  pageSize: number;
+  source: ChangeSource;
+}
+
+export type CollectionAction =
+  | {
+      type: "ADD_FILTER";
+      field: string;
+      operator: string;
+      value: unknown;
+      caseSensitive?: boolean;
+    }
+  | { type: "SET_FILTERS"; filters: Filter[] }
+  | { type: "REMOVE_FILTER"; field: string }
+  | { type: "CLEAR_FILTERS" }
+  | { type: "SET_SORT"; field: string; direction?: "Asc" | "Desc" }
+  | { type: "CLEAR_SORT" }
+  | { type: "SET_PAGE_SIZE"; pageSize: number }
+  | { type: "SYNC"; snapshot: CollectionSnapshot | undefined };
+
+// =============================================================================
+// Reducer
+// =============================================================================
+
+export function collectionReducer(
+  state: CollectionState,
+  action: CollectionAction,
+): CollectionState {
+  switch (action.type) {
+    case "SYNC": {
+      if (!action.snapshot) return state;
+      return {
+        ...state,
+        ...(action.snapshot.filters != null && {
+          filters: action.snapshot.filters,
+        }),
+        ...(action.snapshot.sort != null && {
+          sortStates: action.snapshot.sort,
+        }),
+        ...(action.snapshot.pageSize != null && {
+          pageSize: action.snapshot.pageSize,
+        }),
+        source: "sync",
+      };
+    }
+    case "ADD_FILTER": {
+      const { field, operator, value, caseSensitive } = action;
+      const newFilter: Filter = {
+        field,
+        operator: operator as Filter["operator"],
+        value,
+        caseSensitive,
+      };
+      const existing = state.filters.findIndex((f) => f.field === field);
+      const filters =
+        existing >= 0
+          ? state.filters.map((f, i) => (i === existing ? newFilter : f))
+          : [...state.filters, newFilter];
+      return { ...state, filters, source: "user" };
+    }
+    case "SET_FILTERS":
+      return { ...state, filters: action.filters, source: "user" };
+    case "REMOVE_FILTER":
+      return {
+        ...state,
+        filters: state.filters.filter((f) => f.field !== action.field),
+        source: "user",
+      };
+    case "CLEAR_FILTERS":
+      return { ...state, filters: [], source: "user" };
+    case "SET_SORT": {
+      const { field, direction } = action;
+      if (direction === undefined) {
+        return {
+          ...state,
+          sortStates: state.sortStates.filter((s) => s.field !== field),
+          source: "user",
+        };
+      }
+      const filtered = state.sortStates.filter((s) => s.field !== field);
+      return {
+        ...state,
+        sortStates: [...filtered, { field, direction }],
+        source: "user",
+      };
+    }
+    case "CLEAR_SORT":
+      return { ...state, sortStates: [], source: "user" };
+    case "SET_PAGE_SIZE":
+      return { ...state, pageSize: action.pageSize, source: "user" };
+    default:
+      return state;
+  }
+}
+
+// =============================================================================
+// Synchronizer Bridge Hook
+// =============================================================================
+
+/**
+ * Connects a synchronizer to the collection reducer state.
+ *
+ * - Subscribes to external changes and dispatches `SYNC` actions.
+ * - Writes state back to the synchronizer when changes originate from user actions.
+ */
+export function useSynchronizerBridge(
+  synchronizer: CollectionStateSynchronizer | undefined,
+  state: CollectionState,
+  dispatch: React.Dispatch<CollectionAction>,
+): void {
+  // Subscribe: external changes → dispatch
+  useEffect(() => {
+    if (!synchronizer) return;
+    return synchronizer.subscribe((snapshot) => {
+      dispatch({ type: "SYNC", snapshot });
+    });
+  }, [synchronizer, dispatch]);
+
+  // Write-back: only when source is "user"
+  useEffect(() => {
+    if (state.source !== "user") return;
+    synchronizer?.write({
+      filters: state.filters,
+      sort: state.sortStates,
+      pageSize: state.pageSize,
+    });
+  }, [state.filters, state.sortStates, state.pageSize, state.source, synchronizer]);
+}

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

@@ -1,17 +1,32 @@
 import { renderHook, act } from "@testing-library/react";
 import { describe, it, expect, vi } from "vitest";
-import type { CollectionStateSynchronizer } from "@/types/collection";
+import type { CollectionSnapshot, CollectionStateSynchronizer } from "@/types/collection";
 import { useCollectionVariables } from "./use-collection-variables";
 
 describe("useCollectionVariables with synchronizer", () => {
-  function createMockSynchronizer(initial?: ReturnType<CollectionStateSynchronizer["read"]>) {
+  function createMockSynchronizer(initial?: CollectionSnapshot) {
+    const subscribers: Array<(snapshot: CollectionSnapshot | undefined) => void> = [];
     return {
-      read: vi.fn(() => initial),
+      subscribe: vi.fn((onChange) => {
+        subscribers.push(onChange);
+        // BehaviorSubject: emit immediately
+        onChange(initial);
+        return () => {
+          const idx = subscribers.indexOf(onChange);
+          if (idx >= 0) subscribers.splice(idx, 1);
+        };
+      }),
       write: vi.fn(),
-    } satisfies CollectionStateSynchronizer;
+      // Test helper to simulate external change
+      emit(snapshot: CollectionSnapshot | undefined) {
+        for (const cb of subscribers) cb(snapshot);
+      },
+    } satisfies CollectionStateSynchronizer & {
+      emit: (s: CollectionSnapshot | undefined) => void;
+    };
   }
 
-  describe("read (initial hydration)", () => {
+  describe("subscribe (initial hydration)", () => {
     it("uses synchronizer initial state over params defaults", () => {
       const synchronizer = createMockSynchronizer({
         filters: [{ field: "status", operator: "eq", value: "ACTIVE" }],
@@ -26,15 +41,15 @@ describe("useCollectionVariables with synchronizer", () => {
         }),
       );
 
-      expect(synchronizer.read).toHaveBeenCalledOnce();
+      expect(synchronizer.subscribe).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", () => {
+    it("falls back to params when synchronizer emits undefined", () => {
       const synchronizer = createMockSynchronizer(undefined);
 
       const { result } = renderHook(() =>
@@ -70,12 +85,53 @@ describe("useCollectionVariables with synchronizer", () => {
       );
 
       expect(result.current.control.pageSize).toBe(100);
-      // Sort falls back to params
+      // Sort remains from params since synchronizer didn't provide it
       expect(result.current.control.sortStates).toEqual([{ field: "name", direction: "Asc" }]);
     });
   });
 
+  describe("subscribe (external changes)", () => {
+    it("updates state when synchronizer emits external change", () => {
+      const synchronizer = createMockSynchronizer(undefined);
+
+      const { result } = renderHook(() =>
+        useCollectionVariables({
+          params: { pageSize: 20 },
+          synchronizer,
+        }),
+      );
+
+      act(() => {
+        synchronizer.emit({
+          filters: [{ field: "name", operator: "contains", value: "test" }],
+          pageSize: 50,
+        });
+      });
+
+      expect(result.current.control.filters).toEqual([
+        { field: "name", operator: "contains", value: "test" },
+      ]);
+      expect(result.current.control.pageSize).toBe(50);
+    });
+  });
+
   describe("write (state persistence)", () => {
+    it("does not call write on initial mount (skip first write)", () => {
+      const synchronizer = createMockSynchronizer({
+        filters: [{ field: "status", operator: "eq", value: "ACTIVE" }],
+        pageSize: 50,
+      });
+
+      renderHook(() =>
+        useCollectionVariables({
+          params: { pageSize: 20 },
+          synchronizer,
+        }),
+      );
+
+      expect(synchronizer.write).not.toHaveBeenCalled();
+    });
+
     it("calls write on filter change", () => {
       const synchronizer = createMockSynchronizer(undefined);
 
@@ -141,14 +197,13 @@ describe("useCollectionVariables with synchronizer", () => {
       );
     });
 
-    it("does not call write when no synchronizer is provided", () => {
+    it("does not crash 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);
     });
   });