feat: add URL state persistence of CollectionControl

.changeset/witty-mice-drum.md

@@ -0,0 +1,12 @@
+---
+"@tailor-platform/app-shell": minor
+---
+
+Add `withURLCollectionState` for wiring collection state to the URL in `useCollectionVariables`.
+
+```tsx
+const searchParams = useSearchParams();
+const { variables, control } = useCollectionVariables(
+  withURLCollectionState({ tableMetadata, params: { pageSize: 20 } }, searchParams),
+);
+```

examples/nextjs-app/src/modules/pages/data-table-demo.tsx

@@ -3,6 +3,8 @@ import {
   DataTable,
   useDataTable,
   useCollectionVariables,
+  withURLCollectionState,
+  useSearchParams,
   createColumnHelper,
   Layout,
   type RowAction,
@@ -140,10 +142,16 @@ const productRowActions: RowAction<Product>[] = [
 // ---------------------------------------------------------------------------
 
 const DataTableDemoPage = () => {
-  const { variables, control } = useCollectionVariables({
-    params: { pageSize: 5 },
-    tableMetadata: productMetadata,
-  });
+  const searchParams = useSearchParams();
+  const { variables, control } = useCollectionVariables(
+    withURLCollectionState(
+      {
+        params: { pageSize: 5 },
+        tableMetadata: productMetadata,
+      },
+      searchParams,
+    ),
+  );
   const { data, loading } = useProductsQuery(variables);
   const [selectedIds, setSelectedIds] = useState<string[]>([]);
 

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

@@ -10,9 +10,11 @@
 import { describe, it, expectTypeOf } from "vitest";
 import type {
   BuildQueryVariables,
+  CollectionVariables,
   TableFieldName,
   TableMetadata,
   TableOrderableFieldName,
+  TypedCollectionVariables,
 } from "@/types/collection";
 
 type TestTable = {
@@ -56,6 +58,7 @@ type TestTable = {
 };
 
 type TestQuery = BuildQueryVariables<TestTable>;
+type TestTypedCollectionVariables = TypedCollectionVariables<TestTable>;
 
 describe("BuildQueryVariables", () => {
   it("TestTable is assignable to TableMetadata", () => {
@@ -121,6 +124,16 @@ describe("BuildQueryVariables", () => {
   });
 });
 
+describe("TypedCollectionVariables", () => {
+  it("extends CollectionVariables while keeping typed query fields", () => {
+    expectTypeOf<TestTypedCollectionVariables>().toExtend<CollectionVariables>();
+    expectTypeOf<NonNullable<TestTypedCollectionVariables["query"]>>().toExtend<{
+      title?: { eq?: string; contains?: string };
+      status?: { eq?: "active" | "inactive" };
+    }>();
+  });
+});
+
 describe("TableFieldName", () => {
   it("extracts all field names", () => {
     type AllNames =

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

@@ -1,5 +1,5 @@
 import { renderHook, act } from "@testing-library/react";
-import { describe, it, expect } from "vitest";
+import { describe, it, expect, vi } from "vitest";
 import type { TableMetadataMap } from "@/types/collection";
 import { useCollectionVariables } from "./use-collection-variables";
 
@@ -55,6 +55,71 @@ describe("useCollectionVariables", () => {
         status: { eq: "ACTIVE" },
       });
     });
+
+    it("prefers initialState over params", () => {
+      const { result } = renderHook(() =>
+        useCollectionVariables({
+          params: {
+            initialFilters: [{ field: "status", operator: "eq", value: "ACTIVE" }],
+            initialSort: [{ field: "createdAt", direction: "Desc" }],
+            pageSize: 20,
+          },
+          initialState: {
+            filters: [{ field: "status", operator: "eq", value: "INACTIVE" }],
+            sortStates: [{ field: "name", direction: "Asc" }],
+            pageSize: 50,
+          },
+        }),
+      );
+
+      expect(result.current.control.filters).toEqual([
+        { field: "status", operator: "eq", value: "INACTIVE" },
+      ]);
+      expect(result.current.control.sortStates).toEqual([{ field: "name", direction: "Asc" }]);
+      expect(result.current.variables.pagination).toEqual({ first: 50 });
+    });
+
+    it("falls back to params for keys missing from initialState", () => {
+      const { result } = renderHook(() =>
+        useCollectionVariables({
+          params: {
+            initialSort: [{ field: "createdAt", direction: "Desc" }],
+            pageSize: 20,
+          },
+          initialState: {
+            pageSize: 50,
+          },
+        }),
+      );
+
+      expect(result.current.control.sortStates).toEqual([
+        { field: "createdAt", direction: "Desc" },
+      ]);
+      expect(result.current.variables.pagination).toEqual({ first: 50 });
+    });
+  });
+
+  describe("saver", () => {
+    it("does not save on initial render", () => {
+      const saver = { save: vi.fn() };
+      renderHook(() => useCollectionVariables({ saver }));
+      expect(saver.save).not.toHaveBeenCalled();
+    });
+
+    it("saves persisted state after changes", () => {
+      const saver = { save: vi.fn() };
+      const { result } = renderHook(() => useCollectionVariables({ saver }));
+
+      act(() => {
+        result.current.control.addFilter("status", "eq", "ACTIVE");
+      });
+
+      expect(saver.save).toHaveBeenLastCalledWith({
+        filters: [{ field: "status", operator: "eq", value: "ACTIVE", caseSensitive: undefined }],
+        sortStates: [],
+        pageSize: 20,
+      });
+    });
   });
 
   // ---------------------------------------------------------------------------

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

@@ -1,16 +1,15 @@
-import { useCallback, useMemo, useState } from "react";
+import { useCallback, useEffect, useMemo, useRef, useState } from "react";
 import type {
-  BuildQueryVariables,
   CollectionControl,
+  CollectionPersistedState,
   CollectionVariables,
   Filter,
   FilterOperator,
-  PaginationVariables,
   SortState,
   TableFieldName,
   TableMetadata,
   TableMetadataFilter,
-  TableOrderableFieldName,
+  TypedCollectionVariables,
   UseCollectionOptions,
   UseCollectionReturn,
 } from "@/types/collection";
@@ -85,16 +84,7 @@ export function useCollectionVariables<const TTable extends TableMetadata>(
   },
 ): UseCollectionReturn<
   TableFieldName<TTable>,
-  {
-    query: BuildQueryVariables<TTable> | undefined;
-    order:
-      | {
-          field: TableOrderableFieldName<TTable>;
-          direction: "Asc" | "Desc";
-        }[]
-      | undefined;
-    pagination: PaginationVariables;
-  },
+  TypedCollectionVariables<TTable>,
   TableMetadataFilter<TTable>
 >;
 
@@ -130,8 +120,10 @@ export function useCollectionVariables(
 export function useCollectionVariables(
   options: UseCollectionOptions & { tableMetadata?: TableMetadata },
 ): unknown {
-  const { params = {} } = options;
-  const { initialFilters = [], initialSort = [], pageSize: initialPageSize = 20 } = params;
+  const { params = {}, initialState, saver } = options;
+  const initialFilters = initialState?.filters ?? params.initialFilters ?? [];
+  const initialSort = initialState?.sortStates ?? params.initialSort ?? [];
+  const initialPageSize = initialState?.pageSize ?? params.pageSize ?? 20;
 
   // ---------------------------------------------------------------------------
   // State
@@ -152,6 +144,8 @@ export function useCollectionVariables(
     getHasNextPage,
     resetCount,
   } = useCursorPagination(initialPageSize);
+  const saverRef = useRef(saver);
+  const didMountRef = useRef(false);
 
   // ---------------------------------------------------------------------------
   // Filter operations
@@ -262,6 +256,23 @@ export function useCollectionVariables(
     [queryVars, orderVars, paginationVariables],
   );
 
+  useEffect(() => {
+    saverRef.current = saver;
+  }, [saver]);
+
+  useEffect(() => {
+    if (!didMountRef.current) {
+      didMountRef.current = true;
+      return;
+    }
+
+    saverRef.current?.save({
+      filters,
+      sortStates: sortStates as CollectionPersistedState["sortStates"],
+      pageSize,
+    });
+  }, [filters, sortStates, pageSize]);
+
   // ---------------------------------------------------------------------------
   // Return
   // ---------------------------------------------------------------------------

packages/core/src/index.ts

@@ -154,7 +154,10 @@ export {
   type PageInfo,
   type CollectionVariables,
   type CollectionControl,
+  type CollectionInitialState,
+  type CollectionPersistedState,
   type CollectionResult,
+  type CollectionSaver,
   type NodeType,
   type PaginationVariables,
   type UseCollectionOptions,
@@ -186,6 +189,7 @@ export {
   type DataTableContextValue,
 } from "./components/data-table";
 export { useCollectionVariables } from "./hooks/use-collection-variables";
+export { withURLCollectionState } from "./lib/collection-url-state";
 export {
   CollectionControlProvider,
   useCollectionControl,