@izumisy-tailor/tailor-data-viewer 0.2.7 → 0.2.8

package/README.md

@@ -5,8 +5,8 @@ A low-level React component library for building data table interfaces with Tail
 ## Features
 
 - **Separation of Concerns**: Data fetching, query parameter management, and UI are fully decoupled
-- **`useCollectionParams` Hook**: Manages filter, sort, and pagination state; outputs Tailor Platform-compatible GraphQL variables
-- **`CollectionParams.Provider`**: Shares query parameters via React Context across sibling components
+- **`useCollection` Hook**: Manages filter, sort, and pagination state; outputs Tailor Platform-compatible GraphQL variables
+- **`Collection.Provider`**: Shares query parameters via React Context across sibling components
 - **`Table.*` Compound Components**: Static, unstyled table primitives (`<table>`, `<thead>`, `<tbody>`, `<tr>`, `<th>`, `<td>`)
 - **`DataTable.*` Compound Components**: Data-bound table with sort indicators, cell renderers, and `useDataTable` integration
 - **`useDataTable` Hook**: Integrates data, column visibility, row operations (optimistic updates), and props generators
@@ -15,7 +15,7 @@ A low-level React component library for building data table interfaces with Tail
 - **Utility Components**: `ColumnSelector`, `CsvButton`, `SearchFilterForm`, `Pagination` — all props-based, spreadable from hooks
 - **Multi-sort Support**: Multiple simultaneous sort fields
 - **Optimistic Updates**: `updateRow`, `deleteRow`, `insertRow` with rollback
-- **Presentation Agnostic**: Same `useCollectionParams` can drive tables, kanbans, calendars, etc.
+- **Presentation Agnostic**: Same `useCollection` can drive tables, kanbans, calendars, etc.
 
 ## Installation
 
@@ -47,9 +47,9 @@ npm install react react-dom
 
 ```tsx
 import {
-  useCollectionParams,
+  useCollection,
   useDataTable,
-  CollectionParams,
+  Collection,
   DataTable,
   Pagination,
   field,
@@ -87,73 +87,76 @@ const columns = [
 
 // 2. Build a page
 function OrdersPage() {
-  const params = useCollectionParams({ pageSize: 20 });
-  const [result] = useQuery({ query: GET_ORDERS, variables: params.variables });
+  const collection = useCollection({ query: GET_ORDERS, params: { pageSize: 20 } });
+  const [result] = useQuery({ ...collection.toQueryArgs() });
 
   const table = useDataTable<Order>({
     columns,
     data: result.data?.orders,
     loading: result.fetching,
-    collectionParams: params,
+    collection,
   });
 
   return (
-    <CollectionParams.Provider value={params}>
+    <Collection.Provider value={collection}>
       <DataTable.Root {...table.rootProps}>
         <DataTable.Headers />
         <DataTable.Body />
       </DataTable.Root>
       <Pagination {...table} />
-    </CollectionParams.Provider>
+    </Collection.Provider>
   );
 }
 ```
 
 ## API Overview
 
-### `useCollectionParams(options?)`
+### `useCollection(options)`
 
-Manages filter, sort, and pagination state. Returns Tailor Platform-compatible `variables` for GraphQL queries.
+Manages filter, sort, and pagination state. Returns `toQueryArgs()` which produces Tailor Platform-compatible arguments for `useQuery()`.
 
 ```tsx
-const params = useCollectionParams({
-  pageSize: 20,
-  initialSort: [{ field: "createdAt", direction: "Desc" }],
+const collection = useCollection({
+  query: GET_ORDERS,
+  params: {
+    pageSize: 20,
+    initialSort: [{ field: "createdAt", direction: "Desc" }],
+  },
 });
 
-// Pass variables to any GraphQL client
-const [result] = useQuery({ query: GET_ORDERS, variables: params.variables });
+// Spread toQueryArgs() into useQuery
+const [result] = useQuery({ ...collection.toQueryArgs() });
 
 // Filter operations
-params.addFilter("status", "ACTIVE", "eq");
-params.setFilters([{ field: "status", fieldType: "enum", operator: "eq", value: "ACTIVE" }]);
-params.removeFilter("status");
-params.clearFilters();
+collection.addFilter("status", "ACTIVE", "eq");
+collection.setFilters([{ field: "status", fieldType: "enum", operator: "eq", value: "ACTIVE" }]);
+collection.removeFilter("status");
+collection.clearFilters();
 
 // Sort operations
-params.setSort("createdAt", "Desc");
-params.setSort("name", "Asc", true); // append for multi-sort
-params.clearSort();
+collection.setSort("createdAt", "Desc");
+collection.setSort("name", "Asc", true); // append for multi-sort
+collection.clearSort();
 
 // Pagination
-params.nextPage(endCursor);
-params.prevPage();
-params.resetPage();
+collection.nextPage(endCursor);
+collection.prevPage();
+collection.resetPage();
 ```
 
-### `CollectionParams.Provider` / `useCollectionParamsContext()`
+### `Collection.Provider` / `useCollectionContext()`
 
-Shares `useCollectionParams` return value via Context. Child components access it with `useCollectionParamsContext()`.
+Shares `useCollection` return value via Context. Child components access it with `useCollectionContext()`.
 
 ```tsx
-<CollectionParams.Provider value={params}>
-  <StatusFilter />   {/* useCollectionParamsContext() inside */}
+<Collection.Provider value={collection}>
+  <StatusFilter />   {/* useCollectionContext() inside */}
   <DataTable.Root {...table.rootProps}>
     <DataTable.Headers />
     <DataTable.Body />
   </DataTable.Root>
   <Pagination {...table} />
-</CollectionParams.Provider>
+</Collection.Provider>
 ```
 
 Provider is optional — for simple cases, pass params directly via props.
@@ -246,7 +249,7 @@ const table = useDataTable<Order>({
   data: result.data?.orders,   // CollectionResult<Order>
   loading: result.fetching,
   error: result.error,
-  collectionParams: params,
+  collection,
 });
 
 // Spread props to components
@@ -320,17 +323,17 @@ Pair with `useDataTable` for automatic header sorting, cell rendering, and row o
 
 ### Utility Components
 
-All utility components are props-based and designed to be used with spread from `useDataTable` / `useCollectionParams`.
+All utility components are props-based and designed to be used with spread from `useDataTable` / `useCollection`.
 
 | Component | Spread from | Description |
 |-----------|------------|-------------|
 | `ColumnSelector` | `{...table}` | Column visibility toggle UI |
 | `CsvButton` | `{...table}` | Export visible data as CSV |
-| `SearchFilterForm` | `{...table, ...params}` | Multi-field filter form with operator selection |
+| `SearchFilterForm` | `{...table, ...collection}` | Multi-field filter form with operator selection |
 | `Pagination` | `{...table}` | Previous/Next page controls |
 
 ```tsx
-<SearchFilterForm {...table} {...params} />
+<SearchFilterForm {...table} {...collection} />
 <ColumnSelector {...table} />
 <CsvButton {...table} filename="orders-export" />
 <Pagination {...table} />

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@izumisy-tailor/tailor-data-viewer",
   "private": false,
-  "version": "0.2.7",
+  "version": "0.2.8",
   "type": "module",
   "description": "Flexible data viewer component for Tailor Platform",
   "files": [

package/src/component/collection/collection-provider.tsx

@@ -0,0 +1,90 @@
+import { createContext, useContext, type ReactNode } from "react";
+import type { UseCollectionReturn } from "../types";
+
+const CollectionContext = createContext<UseCollectionReturn<
+  string,
+  unknown,
+  unknown
+> | null>(null);
+
+/**
+ * Provider that shares collection query parameters via React Context.
+ *
+ * @example
+ * ```tsx
+ * const collection = useCollection({ params: { pageSize: 20 } });
+ *
+ * <CollectionProvider value={collection}>
+ *   <FilterPanel />
+ *   <DataTable.Root {...table.rootProps}>...</DataTable.Root>
+ *   <Pagination {...table} />
+ * </CollectionProvider>
+ * ```
+ */
+export function CollectionProvider({
+  value,
+  children,
+}: {
+  value: UseCollectionReturn<string, unknown, unknown>;
+  children: ReactNode;
+}) {
+  return (
+    <CollectionContext.Provider value={value}>
+      {children}
+    </CollectionContext.Provider>
+  );
+}
+
+
+
+/**
+ * Hook to access collection state from the nearest `Collection.Provider`.
+ *
+ * Returns the same interface as `useCollection()`.  Pass a `TFieldName`
+ * type parameter to narrow method arguments like `addFilter` / `setSort`.
+ *
+ * @typeParam TFieldName - Union of allowed field name strings (default: `string`).
+ *
+ * @throws Error if used outside of `Collection.Provider`.
+ *
+ * @example
+ * ```tsx
+ * function StatusFilter() {
+ *   const { filters, addFilter, removeFilter } = useCollectionContext();
+ *   // ...
+ * }
+ *
+ * // With typed field names:
+ * type TaskField = FieldName<typeof tableMetadata, "task">;
+ * const { addFilter } = useCollectionContext<TaskField>();
+ * ```
+ */
+export function useCollectionContext<
+  TFieldName extends string = string,
+>(): UseCollectionReturn<TFieldName> {
+  const ctx = useContext(CollectionContext);
+  if (!ctx) {
+    throw new Error(
+      "useCollectionContext must be used within <Collection.Provider>",
+    );
+  }
+  return ctx as UseCollectionReturn<TFieldName>;
+}
+
+
+
+/**
+ * `Collection` namespace object providing the Provider component.
+ *
+ * @example
+ * ```tsx
+ * <Collection.Provider value={collection}>
+ *   ...
+ * </Collection.Provider>
+ * ```
+ */
+export const Collection = {
+  Provider: CollectionProvider,
+} as const;
+
+

package/src/component/{collection-params/use-collection-params.test.ts → collection/use-collection.test.ts}

@@ -1,16 +1,18 @@
 import { renderHook, act } from "@testing-library/react";
 import { describe, it, expect } from "vitest";
 import type { TableMetadataMap } from "../../generator/metadata-generator";
-import { useCollectionParams } from "./use-collection-params";
+import { useCollection } from "./use-collection";
 
-describe("useCollectionParams", () => {
+const FAKE_QUERY = { kind: "Document" } as const;
+
+describe("useCollection", () => {
   // ---------------------------------------------------------------------------
   // Initial state
   // ---------------------------------------------------------------------------
   describe("initial state", () => {
     it("returns default variables with pageSize 20", () => {
-      const { result } = renderHook(() => useCollectionParams());
-      expect(result.current.variables).toEqual({ first: 20 });
+      const { result } = renderHook(() => useCollection({ query: FAKE_QUERY }));
+      expect(result.current.toQueryArgs().variables).toEqual({ first: 20 });
       expect(result.current.filters).toEqual([]);
       expect(result.current.sortStates).toEqual([]);
       expect(result.current.cursor).toBeNull();
@@ -19,39 +21,45 @@ describe("useCollectionParams", () => {
 
     it("uses custom pageSize", () => {
       const { result } = renderHook(() =>
-        useCollectionParams({ pageSize: 50 }),
+        useCollection({ query: FAKE_QUERY, params: { pageSize: 50 } }),
       );
-      expect(result.current.variables.first).toBe(50);
+      expect(result.current.toQueryArgs().variables.first).toBe(50);
     });
 
     it("applies initial sort", () => {
       const { result } = renderHook(() =>
-        useCollectionParams({
-          initialSort: [{ field: "createdAt", direction: "Desc" }],
+        useCollection({
+          query: FAKE_QUERY,
+          params: {
+            initialSort: [{ field: "createdAt", direction: "Desc" }],
+          },
         }),
       );
       expect(result.current.sortStates).toEqual([
         { field: "createdAt", direction: "Desc" },
       ]);
-      expect(result.current.variables.order).toEqual([
+      expect(result.current.toQueryArgs().variables.order).toEqual([
         { field: "createdAt", direction: "Desc" },
       ]);
     });
 
     it("applies initial filters", () => {
       const { result } = renderHook(() =>
-        useCollectionParams({
-          initialFilters: [
-            {
-              field: "status",
-              operator: "eq",
-              value: "ACTIVE",
-            },
-          ],
+        useCollection({
+          query: FAKE_QUERY,
+          params: {
+            initialFilters: [
+              {
+                field: "status",
+                operator: "eq",
+                value: "ACTIVE",
+              },
+            ],
+          },
         }),
       );
       expect(result.current.filters).toHaveLength(1);
-      expect(result.current.variables.query).toEqual({
+      expect(result.current.toQueryArgs().variables.query).toEqual({
         status: { eq: "ACTIVE" },
       });
     });
@@ -62,7 +70,7 @@ describe("useCollectionParams", () => {
   // ---------------------------------------------------------------------------
   describe("filter operations", () => {
     it("adds a filter", () => {
-      const { result } = renderHook(() => useCollectionParams());
+      const { result } = renderHook(() => useCollection({ query: FAKE_QUERY }));
 
       act(() => {
         result.current.addFilter("status", "ACTIVE", "eq");
@@ -74,13 +82,13 @@ describe("useCollectionParams", () => {
         operator: "eq",
         value: "ACTIVE",
       });
-      expect(result.current.variables.query).toEqual({
+      expect(result.current.toQueryArgs().variables.query).toEqual({
         status: { eq: "ACTIVE" },
       });
     });
 
     it("replaces filter for same field", () => {
-      const { result } = renderHook(() => useCollectionParams());
+      const { result } = renderHook(() => useCollection({ query: FAKE_QUERY }));
 
       act(() => {
         result.current.addFilter("status", "ACTIVE", "eq");
@@ -94,7 +102,7 @@ describe("useCollectionParams", () => {
     });
 
     it("sets filters in bulk", () => {
-      const { result } = renderHook(() => useCollectionParams());
+      const { result } = renderHook(() => useCollection({ query: FAKE_QUERY }));
 
       act(() => {
         result.current.setFilters([
@@ -112,14 +120,14 @@ describe("useCollectionParams", () => {
       });
 
       expect(result.current.filters).toHaveLength(2);
-      expect(result.current.variables.query).toEqual({
+      expect(result.current.toQueryArgs().variables.query).toEqual({
         status: { eq: "ACTIVE" },
         amount: { gte: 1000 },
       });
     });
 
     it("removes a filter", () => {
-      const { result } = renderHook(() => useCollectionParams());
+      const { result } = renderHook(() => useCollection({ query: FAKE_QUERY }));
 
       act(() => {
         result.current.addFilter("status", "ACTIVE", "eq");
@@ -134,7 +142,7 @@ describe("useCollectionParams", () => {
     });
 
     it("clears all filters", () => {
-      const { result } = renderHook(() => useCollectionParams());
+      const { result } = renderHook(() => useCollection({ query: FAKE_QUERY }));
 
       act(() => {
         result.current.addFilter("status", "ACTIVE", "eq");
@@ -145,11 +153,11 @@ describe("useCollectionParams", () => {
       });
 
       expect(result.current.filters).toHaveLength(0);
-      expect(result.current.variables.query).toBeUndefined();
+      expect(result.current.toQueryArgs().variables.query).toBeUndefined();
     });
 
     it("resets pagination when filters change", () => {
-      const { result } = renderHook(() => useCollectionParams());
+      const { result } = renderHook(() => useCollection({ query: FAKE_QUERY }));
 
       // Navigate to next page
       act(() => {
@@ -171,7 +179,7 @@ describe("useCollectionParams", () => {
   // ---------------------------------------------------------------------------
   describe("sort operations", () => {
     it("sets sort", () => {
-      const { result } = renderHook(() => useCollectionParams());
+      const { result } = renderHook(() => useCollection({ query: FAKE_QUERY }));
 
       act(() => {
         result.current.setSort("createdAt", "Desc");
@@ -180,13 +188,13 @@ describe("useCollectionParams", () => {
       expect(result.current.sortStates).toEqual([
         { field: "createdAt", direction: "Desc" },
       ]);
-      expect(result.current.variables.order).toEqual([
+      expect(result.current.toQueryArgs().variables.order).toEqual([
         { field: "createdAt", direction: "Desc" },
       ]);
     });
 
     it("replaces sort by default", () => {
-      const { result } = renderHook(() => useCollectionParams());
+      const { result } = renderHook(() => useCollection({ query: FAKE_QUERY }));
 
       act(() => {
         result.current.setSort("createdAt", "Desc");
@@ -201,7 +209,7 @@ describe("useCollectionParams", () => {
     });
 
     it("appends sort with append=true (multi-sort)", () => {
-      const { result } = renderHook(() => useCollectionParams());
+      const { result } = renderHook(() => useCollection({ query: FAKE_QUERY }));
 
       act(() => {
         result.current.setSort("createdAt", "Desc");
@@ -217,7 +225,7 @@ describe("useCollectionParams", () => {
     });
 
     it("clears sort", () => {
-      const { result } = renderHook(() => useCollectionParams());
+      const { result } = renderHook(() => useCollection({ query: FAKE_QUERY }));
 
       act(() => {
         result.current.setSort("createdAt", "Desc");
@@ -227,7 +235,7 @@ describe("useCollectionParams", () => {
       });
 
       expect(result.current.sortStates).toEqual([]);
-      expect(result.current.variables.order).toBeUndefined();
+      expect(result.current.toQueryArgs().variables.order).toBeUndefined();
     });
   });
 
@@ -236,7 +244,7 @@ describe("useCollectionParams", () => {
   // ---------------------------------------------------------------------------
   describe("pagination operations", () => {
     it("navigates to next page", () => {
-      const { result } = renderHook(() => useCollectionParams());
+      const { result } = renderHook(() => useCollection({ query: FAKE_QUERY }));
 
       act(() => {
         result.current.nextPage("cursor1");
@@ -244,11 +252,11 @@ describe("useCollectionParams", () => {
 
       expect(result.current.cursor).toBe("cursor1");
       expect(result.current.hasPrevPage).toBe(true);
-      expect(result.current.variables.after).toBe("cursor1");
+      expect(result.current.toQueryArgs().variables.after).toBe("cursor1");
     });
 
     it("navigates back to previous page", () => {
-      const { result } = renderHook(() => useCollectionParams());
+      const { result } = renderHook(() => useCollection({ query: FAKE_QUERY }));
 
       act(() => {
         result.current.nextPage("cursor1");
@@ -265,7 +273,7 @@ describe("useCollectionParams", () => {
     });
 
     it("navigates back to first page", () => {
-      const { result } = renderHook(() => useCollectionParams());
+      const { result } = renderHook(() => useCollection({ query: FAKE_QUERY }));
 
       act(() => {
         result.current.nextPage("cursor1");
@@ -279,7 +287,7 @@ describe("useCollectionParams", () => {
     });
 
     it("resets page", () => {
-      const { result } = renderHook(() => useCollectionParams());
+      const { result } = renderHook(() => useCollection({ query: FAKE_QUERY }));
 
       act(() => {
         result.current.nextPage("cursor1");
@@ -295,21 +303,24 @@ describe("useCollectionParams", () => {
   });
 
   // ---------------------------------------------------------------------------
-  // variables generation
+  // toQueryArgs
   // ---------------------------------------------------------------------------
-  describe("variables generation", () => {
+  describe("toQueryArgs", () => {
     it("generates complete variables with filters, sort, and cursor", () => {
       const { result } = renderHook(() =>
-        useCollectionParams({
-          pageSize: 10,
-          initialFilters: [
-            {
-              field: "status",
-              operator: "eq",
-              value: "ACTIVE",
-            },
-          ],
-          initialSort: [{ field: "createdAt", direction: "Desc" }],
+        useCollection({
+          query: FAKE_QUERY,
+          params: {
+            pageSize: 10,
+            initialFilters: [
+              {
+                field: "status",
+                operator: "eq",
+                value: "ACTIVE",
+              },
+            ],
+            initialSort: [{ field: "createdAt", direction: "Desc" }],
+          },
         }),
       );
 
@@ -317,21 +328,37 @@ describe("useCollectionParams", () => {
         result.current.nextPage("abc123");
       });
 
-      expect(result.current.variables).toEqual({
-        first: 10,
-        query: { status: { eq: "ACTIVE" } },
-        order: [{ field: "createdAt", direction: "Desc" }],
-        after: "abc123",
+      expect(result.current.toQueryArgs()).toEqual({
+        query: FAKE_QUERY,
+        variables: {
+          first: 10,
+          query: { status: { eq: "ACTIVE" } },
+          order: [{ field: "createdAt", direction: "Desc" }],
+          after: "abc123",
+        },
       });
     });
 
     it("omits undefined fields from variables", () => {
-      const { result } = renderHook(() => useCollectionParams());
-      const vars = result.current.variables;
-      expect(vars).toEqual({ first: 20 });
-      expect("query" in vars).toBe(false);
-      expect("order" in vars).toBe(false);
-      expect("after" in vars).toBe(false);
+      const { result } = renderHook(() => useCollection({ query: FAKE_QUERY }));
+      const { variables } = result.current.toQueryArgs();
+      expect(variables).toEqual({ first: 20 });
+      expect("query" in variables).toBe(false);
+      expect("order" in variables).toBe(false);
+      expect("after" in variables).toBe(false);
+    });
+
+    it("includes query in toQueryArgs result", () => {
+      const fakeQuery = { kind: "Document" } as const;
+      const { result } = renderHook(() =>
+        useCollection({ query: fakeQuery, params: { pageSize: 10 } }),
+      );
+
+      const args = result.current.toQueryArgs();
+      expect(args).toEqual({
+        query: fakeQuery,
+        variables: { first: 10 },
+      });
     });
   });
 
@@ -361,21 +388,25 @@ describe("useCollectionParams", () => {
 
     it("works with metadata and tableName", () => {
       const { result } = renderHook(() =>
-        useCollectionParams({
+        useCollection({
           metadata: testMetadata,
           tableName: "task",
-          pageSize: 10,
+          query: FAKE_QUERY,
+          params: { pageSize: 10 },
         }),
       );
-      expect(result.current.variables).toEqual({ first: 10 });
+      expect(result.current.toQueryArgs().variables).toEqual({ first: 10 });
     });
 
     it("applies typed initialSort", () => {
       const { result } = renderHook(() =>
-        useCollectionParams({
+        useCollection({
           metadata: testMetadata,
           tableName: "task",
-          initialSort: [{ field: "dueDate", direction: "Desc" }],
+          query: FAKE_QUERY,
+          params: {
+            initialSort: [{ field: "dueDate", direction: "Desc" }],
+          },
         }),
       );
 

package/src/component/{collection-params/use-collection-params.ts → collection/use-collection.ts}

@@ -6,12 +6,22 @@ import type {
   MetadataFilter,
   QueryVariables,
   SortState,
-  UseCollectionParamsOptions,
-  UseCollectionParamsReturn,
+  UseCollectionOptions,
+  UseCollectionReturn,
   ExtractQueryVariables,
 } from "../types";
 import type { FieldName } from "../types";
 
+/**
+ * Resolves query variables type: uses `ExtractQueryVariables<TQuery>` when
+ * the query document carries a `__variablesType` brand (e.g. gql-tada),
+ * otherwise falls back to `QueryVariables<TFieldName>`.
+ */
+type ResolveVariables<TQuery, TFieldName extends string = string> =
+  ExtractQueryVariables<TQuery> extends never
+    ? QueryVariables<TFieldName>
+    : ExtractQueryVariables<TQuery>;
+
 // -----------------------------------------------------------------------------
 // Overload signatures
 // -----------------------------------------------------------------------------
@@ -20,93 +30,91 @@ import type { FieldName } from "../types";
  * Hook for managing collection query parameters (filters, sort, pagination)
  * with metadata-based field name typing and automatic `fieldType` detection.
  *
- * When `query` is provided, the output `variables` is typed to match
- * the GraphQL query's expected variables (e.g. `VariablesOf<typeof QUERY>`).
- * The `query` value is only used for type inference and ignored at runtime.
+ * `toQueryArgs()` returns `{ query, variables }` so the result can be
+ * spread directly into `useQuery()`.
  *
  * @example
  * ```tsx
  * import { tableMetadata } from "./generated/data-viewer-metadata.generated";
  *
- * // Without query — variables typed as QueryVariables<FieldName>
- * const params = useCollectionParams({
- *   metadata: tableMetadata,
- *   tableName: "task",
- *   pageSize: 20,
- * });
- *
- * // With query — variables typed as VariablesOf<typeof GET_TASKS>
- * const params = useCollectionParams({
+ * const collection = useCollection({
  *   metadata: tableMetadata,
  *   tableName: "task",
  *   query: GET_TASKS,
- *   pageSize: 20,
+ *   params: { pageSize: 20 },
  * });
+ * const [result] = useQuery({ ...collection.toQueryArgs() });
  * ```
  */
-export function useCollectionParams<
+export function useCollection<
   const TMetadata extends TableMetadataMap,
   TTableName extends string & keyof TMetadata,
-  TQuery = never,
+  TQuery,
 >(
-  options: UseCollectionParamsOptions<
+  options: UseCollectionOptions<
     FieldName<TMetadata, TTableName>,
     MetadataFilter<TMetadata, TTableName>
   > & {
     metadata: TMetadata;
     tableName: TTableName;
-    query?: TQuery;
+    query: TQuery;
   },
-): UseCollectionParamsReturn<
+): UseCollectionReturn<
   FieldName<TMetadata, TTableName>,
-  [TQuery] extends [never]
-    ? QueryVariables<FieldName<TMetadata, TTableName>>
-    : ExtractQueryVariables<TQuery>
+  ResolveVariables<TQuery, FieldName<TMetadata, TTableName>>,
+  {
+    query: TQuery;
+    variables: ResolveVariables<TQuery, FieldName<TMetadata, TTableName>>;
+  }
 >;
 
 /**
  * Hook for managing collection query parameters (filters, sort, pagination).
  *
  * Produces `variables` in Tailor Platform format that can be passed directly
- * to a GraphQL query (e.g. urql's `useQuery`).
+ * to a GraphQL query (e.g. urql's `useQuery`) via `toQueryArgs()`.
  *
- * When `query` is provided, the output `variables` is typed to match
- * the GraphQL query's expected variables.
+ * `toQueryArgs()` returns `{ query, variables }` so the result can be spread
+ * directly into `useQuery()`.
  *
  * @example
  * ```tsx
- * const params = useCollectionParams({ pageSize: 20 });
- * const [result] = useQuery({ query: GET_ORDERS, variables: params.variables });
- *
- * // With query — variables auto-typed
- * const params = useCollectionParams({ query: GET_ORDERS, pageSize: 20 });
+ * const collection = useCollection({ query: GET_ORDERS, params: { pageSize: 20 } });
+ * const [result] = useQuery({ ...collection.toQueryArgs() });
  * ```
  */
-export function useCollectionParams<TQuery = never>(
-  options?: UseCollectionParamsOptions & {
-    query?: TQuery;
+export function useCollection<TQuery>(
+  options: UseCollectionOptions & {
+    query: TQuery;
     metadata?: never;
     tableName?: never;
   },
-): UseCollectionParamsReturn<
+): UseCollectionReturn<
   string,
-  [TQuery] extends [never] ? QueryVariables : ExtractQueryVariables<TQuery>
+  ResolveVariables<TQuery>,
+  { query: TQuery; variables: ResolveVariables<TQuery> }
 >;
 
 // -----------------------------------------------------------------------------
 // Implementation
 // -----------------------------------------------------------------------------
-export function useCollectionParams(
-  options: UseCollectionParamsOptions & {
+export function useCollection(
+  options: UseCollectionOptions & {
     metadata?: TableMetadataMap;
     tableName?: string;
-  } = {},
-): UseCollectionParamsReturn {
+    query: unknown;
+  },
+): UseCollectionReturn<
+  string,
+  QueryVariables,
+  { query: unknown; variables: QueryVariables }
+> {
+  const { params = {}, query: queryDocument } = options;
   const {
     initialFilters = [],
     initialSort = [],
     pageSize: initialPageSize = 20,
-  } = options;
+  } = params;
 
   // ---------------------------------------------------------------------------
   // State
@@ -229,11 +237,11 @@ export function useCollectionParams(
 
     // Build query (filters)
     if (filters.length > 0) {
-      const query: Record<string, unknown> = {};
+      const filterQuery: Record<string, unknown> = {};
       for (const filter of filters) {
-        query[filter.field] = { [filter.operator]: filter.value };
+        filterQuery[filter.field] = { [filter.operator]: filter.value };
       }
-      vars.query = query;
+      vars.query = filterQuery;
     }
 
     // Build order (sort)
@@ -252,11 +260,18 @@ export function useCollectionParams(
     return vars;
   }, [filters, sortStates, pageSize, cursor]);
 
+  // ---------------------------------------------------------------------------
+  // toQueryArgs
+  // ---------------------------------------------------------------------------
+  const toQueryArgs = useCallback(() => {
+    return { query: queryDocument, variables };
+  }, [queryDocument, variables]);
+
   // ---------------------------------------------------------------------------
   // Return
   // ---------------------------------------------------------------------------
   return {
-    variables,
+    toQueryArgs,
     filters,
     addFilter,
     setFilters,

package/src/component/data-table/index.tsx

@@ -302,7 +302,7 @@ function formatValue(value: unknown): ReactNode {
  *
  * @example
  * ```tsx
- * const table = useDataTable({ columns, data, loading, collectionParams: params });
+ * const table = useDataTable({ columns, data, loading, collection });
  *
  * <DataTable.Root {...table.rootProps}>
  *   <DataTable.Headers />

package/src/component/data-table/use-data-table.ts

@@ -15,14 +15,14 @@ import type {
  *
  * @example
  * ```tsx
- * const params = useCollectionParams({ pageSize: 20 });
- * const [result] = useQuery({ query: GET_ORDERS, variables: params.variables });
+ * const collection = useCollection({ query: GET_ORDERS, params: { pageSize: 20 } });
+ * const [result] = useQuery({ ...collection.toQueryArgs() });
  *
  * const table = useDataTable<Order>({
  *   columns,
  *   data: result.data?.orders,
  *   loading: result.fetching,
- *   collectionParams: params,
+ *   collection,
  * });
  *
  * <DataTable.Root {...table.rootProps}>
@@ -39,7 +39,7 @@ export function useDataTable<TRow extends Record<string, unknown>>(
     data,
     loading = false,
     error = null,
-    collectionParams,
+    collection,
   } = options;
 
   // ---------------------------------------------------------------------------
@@ -102,20 +102,20 @@ export function useDataTable<TRow extends Record<string, unknown>>(
   );
 
   // ---------------------------------------------------------------------------
-  // Pagination (delegated from collectionParams)
+  // Pagination (delegated from collection)
   // ---------------------------------------------------------------------------
   const nextPage = useCallback(
     (endCursor: string) => {
-      collectionParams?.nextPage(endCursor);
+      collection?.nextPage(endCursor);
     },
-    [collectionParams],
+    [collection],
   );
 
   const prevPage = useCallback(() => {
-    collectionParams?.prevPage();
-  }, [collectionParams]);
+    collection?.prevPage();
+  }, [collection]);
 
-  const hasPrevPage = collectionParams?.hasPrevPage ?? false;
+  const hasPrevPage = collection?.hasPrevPage ?? false;
 
   // ---------------------------------------------------------------------------
   // Row Operations (Optimistic Updates)
@@ -184,11 +184,11 @@ export function useDataTable<TRow extends Record<string, unknown>>(
       rows,
       loading,
       error,
-      onSort: collectionParams
+      onSort: collection
         ? (field: string, direction?: "Asc" | "Desc") =>
-            collectionParams.setSort(field, direction)
+            collection.setSort(field, direction)
         : undefined,
-      sortStates: collectionParams?.sortStates,
+      sortStates: collection?.sortStates,
       rowOperations: { updateRow, deleteRow, insertRow },
       children: null,
     };
@@ -197,7 +197,7 @@ export function useDataTable<TRow extends Record<string, unknown>>(
     rows,
     loading,
     error,
-    collectionParams,
+    collection,
     updateRow,
     deleteRow,
     insertRow,

package/src/component/index.ts

@@ -19,8 +19,8 @@ export type {
   DisplayColumn,
   Column,
   ColumnDefinition,
-  UseCollectionParamsOptions,
-  UseCollectionParamsReturn,
+  UseCollectionOptions,
+  UseCollectionReturn,
   UseDataTableOptions,
   UseDataTableReturn,
   RowOperations,
@@ -47,13 +47,13 @@ export {
   fieldTypeToFilterConfig,
 } from "./types";
 
-// Collection Params
-export { useCollectionParams } from "./collection-params/use-collection-params";
+// Collection
+export { useCollection } from "./collection/use-collection";
 export {
-  CollectionParams,
-  CollectionParamsProvider,
-  useCollectionParamsContext,
-} from "./collection-params/collection-params-provider";
+  Collection,
+  CollectionProvider,
+  useCollectionContext,
+} from "./collection/collection-provider";
 
 // Table (static)
 export { Table } from "./table";

package/src/component/search-filter-form.tsx

@@ -17,7 +17,7 @@ import { OPERATORS_BY_FILTER_TYPE, DEFAULT_OPERATOR_LABELS } from "./types";
  *
  * Renders a dropdown panel with type-specific filter inputs, operator
  * selectors, and active filter badges.  Designed to receive props via
- * spread from `useDataTable()` / `useCollectionParams()`.
+ * spread from `useDataTable()` / `useCollection()`.
  *
  * All text is customisable through the optional `labels` prop (defaults
  * to English).

package/src/component/types.ts

@@ -172,7 +172,7 @@ export interface PageInfo {
  * GraphQL query variables in Tailor Platform format.
  *
  * @typeParam TFieldName - Union of allowed field name strings (default: `string`).
- *                         When metadata is provided to `useCollectionParams`, this
+ *                         When metadata is provided to `useCollection`, this
  *                         narrows `order[].field` to match the table's field names,
  *                         making the output directly compatible with gql-tada's
  *                         `VariablesOf<>` types.
@@ -320,47 +320,62 @@ export type ColumnDefinition<TRow extends Record<string, unknown>> =
   Column<TRow>;
 
 // =============================================================================
-// useCollectionParams Types
+// useCollection Types
 // =============================================================================
 
 /**
- * Options for `useCollectionParams` hook.
+ * Options for `useCollection` hook.
  *
  * @typeParam TFieldName - Union of allowed field name strings (default: `string`).
  */
-export interface UseCollectionParamsOptions<
+export interface UseCollectionOptions<
   TFieldName extends string = string,
   TFilter extends Filter<TFieldName> = Filter<TFieldName>,
 > {
-  /** Initial filters to apply */
-  initialFilters?: TFilter[];
-  /** Initial sort states */
-  initialSort?: { field: TFieldName; direction: "Asc" | "Desc" }[];
-  /** Number of items per page (default: 20) */
-  pageSize?: number;
+  /** Collection parameters (pagination, sort, filters) */
+  params?: {
+    /** Initial filters to apply */
+    initialFilters?: TFilter[];
+    /** Initial sort states */
+    initialSort?: { field: TFieldName; direction: "Asc" | "Desc" }[];
+    /** Number of items per page (default: 20) */
+    pageSize?: number;
+  };
 }
 
 /**
- * Return type of `useCollectionParams` hook.
+ * Return type of `useCollection` hook.
  *
  * Methods that accept a field name are typed with `TFieldName` so that
  * auto-completion works when a concrete union is supplied.
  *
  * **Note:** Methods use *method syntax* (not property syntax) intentionally
- * so that `UseCollectionParamsReturn<"a" | "b">` remains assignable to
- * `UseCollectionParamsReturn<string>` (bivariant method check).
+ * so that `UseCollectionReturn<"a" | "b">` remains assignable to
+ * `UseCollectionReturn<string>` (bivariant method check).
  *
  * @typeParam TFieldName - Union of allowed field name strings (default: `string`).
  * @typeParam TVariables - Type of the `variables` output (default: `QueryVariables<TFieldName>`).
  *                         Pass `VariablesOf<typeof YOUR_QUERY>` (gql-tada) to get
  *                         exact type compatibility with your GraphQL client.
+ * @typeParam TQueryArgs - Type returned by `toQueryArgs()`. Contains both
+ *                         `query` and `variables`.
  */
-export interface UseCollectionParamsReturn<
+export interface UseCollectionReturn<
   TFieldName extends string = string,
   TVariables = QueryVariables<TFieldName>,
+  TQueryArgs = { query: unknown; variables: TVariables },
 > {
-  /** Query variables in Tailor Platform format */
-  variables: TVariables;
+  /**
+   * Returns query arguments (`{ query, variables }`) that can be spread
+   * directly into `useQuery()`.
+   *
+   * @example
+   * ```tsx
+   * const collection = useCollection({ query: GET_ORDERS, params: { pageSize: 20 } });
+   * const [result] = useQuery({ ...collection.toQueryArgs() });
+   * ```
+   */
+  toQueryArgs(): TQueryArgs;
 
   // Filter operations
   /** Current active filters */
@@ -417,8 +432,8 @@ export interface UseDataTableOptions<TRow extends Record<string, unknown>> {
   loading?: boolean;
   /** Error */
   error?: Error | null;
-  /** Collection params for sort integration */
-  collectionParams?: UseCollectionParamsReturn<string, unknown>;
+  /** Collection state for sort/pagination integration */
+  collection?: UseCollectionReturn<string, unknown, unknown>;
 }
 
 /**
@@ -445,7 +460,7 @@ export interface DataTableRootProps<TRow extends Record<string, unknown>> {
   loading?: boolean;
   /** Error */
   error?: Error | null;
-  /** Sort handler (connected to collectionParams) */
+  /** Sort handler (connected to collection) */
   onSort?: (field: string, direction?: "Asc" | "Desc") => void;
   /** Current sort states */
   sortStates?: SortState[];
@@ -498,7 +513,7 @@ export interface UseDataTableReturn<TRow extends Record<string, unknown>> {
   /** Error */
   error: Error | null;
 
-  // Pagination (delegated from collectionParams)
+  // Pagination (delegated from collection)
   /** Page info from GraphQL response */
   pageInfo: PageInfo;
   /** Navigate to next page */

package/src/component/collection-params/collection-params-provider.tsx

@@ -1,83 +0,0 @@
-import { createContext, useContext, type ReactNode } from "react";
-import type { UseCollectionParamsReturn } from "../types";
-
-const CollectionParamsContext = createContext<UseCollectionParamsReturn<
-  string,
-  unknown
-> | null>(null);
-
-/**
- * Provider that shares collection query parameters via React Context.
- *
- * @example
- * ```tsx
- * const params = useCollectionParams({ pageSize: 20 });
- *
- * <CollectionParamsProvider value={params}>
- *   <FilterPanel />
- *   <DataTable.Root {...table.rootProps}>...</DataTable.Root>
- *   <Pagination {...table} />
- * </CollectionParamsProvider>
- * ```
- */
-export function CollectionParamsProvider({
-  value,
-  children,
-}: {
-  value: UseCollectionParamsReturn<string, unknown>;
-  children: ReactNode;
-}) {
-  return (
-    <CollectionParamsContext.Provider value={value}>
-      {children}
-    </CollectionParamsContext.Provider>
-  );
-}
-
-/**
- * Hook to access collection params from the nearest `CollectionParams.Provider`.
- *
- * Returns the same interface as `useCollectionParams()`.  Pass a `TFieldName`
- * type parameter to narrow method arguments like `addFilter` / `setSort`.
- *
- * @typeParam TFieldName - Union of allowed field name strings (default: `string`).
- *
- * @throws Error if used outside of `CollectionParams.Provider`.
- *
- * @example
- * ```tsx
- * function StatusFilter() {
- *   const { filters, addFilter, removeFilter } = useCollectionParamsContext();
- *   // ...
- * }
- *
- * // With typed field names:
- * type TaskField = FieldName<typeof tableMetadata, "task">;
- * const { addFilter } = useCollectionParamsContext<TaskField>();
- * ```
- */
-export function useCollectionParamsContext<
-  TFieldName extends string = string,
->(): UseCollectionParamsReturn<TFieldName> {
-  const ctx = useContext(CollectionParamsContext);
-  if (!ctx) {
-    throw new Error(
-      "useCollectionParamsContext must be used within <CollectionParams.Provider>",
-    );
-  }
-  return ctx as UseCollectionParamsReturn<TFieldName>;
-}
-
-/**
- * `CollectionParams` namespace object providing the Provider component.
- *
- * @example
- * ```tsx
- * <CollectionParams.Provider value={params}>
- *   ...
- * </CollectionParams.Provider>
- * ```
- */
-export const CollectionParams = {
-  Provider: CollectionParamsProvider,
-} as const;