@izumisy-tailor/tailor-data-viewer 0.3.1 → 0.3.2

package/package.json

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

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

@@ -1,69 +1,66 @@
 import { createContext, useContext, type ReactNode } from "react";
-import type { UseCollectionReturn } from "../types";
+import type { CollectionControl } from "../types";
 
-const CollectionVariablesContext = createContext<UseCollectionReturn<
-  string,
-  unknown
-> | null>(null);
+const CollectionControlContext = createContext<CollectionControl | null>(null);
 
 /**
- * Provider that shares collection query parameters via React Context.
+ * Provider that shares collection control state via React Context.
  *
  * @example
  * ```tsx
- * const { variables, ...collection } = useCollectionVariables({ params: { pageSize: 20 } });
+ * const { variables, control } = useCollectionVariables({ params: { pageSize: 20 } });
  *
- * <CollectionVariablesProvider value={collection}>
+ * <CollectionControlProvider value={control}>
  *   <FilterPanel />
  *   <DataTable.Root>...</DataTable.Root>
  *   <Pagination />
- * </CollectionVariablesProvider>
+ * </CollectionControlProvider>
  * ```
  */
-export function CollectionVariablesProvider({
+export function CollectionControlProvider({
   value,
   children,
 }: {
-  value: UseCollectionReturn<string, unknown>;
+  value: CollectionControl;
   children: ReactNode;
 }) {
   return (
-    <CollectionVariablesContext.Provider value={value}>
+    <CollectionControlContext.Provider value={value}>
       {children}
-    </CollectionVariablesContext.Provider>
+    </CollectionControlContext.Provider>
   );
 }
 
 /**
- * Hook to access collection state from the nearest `CollectionVariablesProvider`.
+ * Hook to access collection control from the nearest `CollectionControlProvider`.
  *
- * Returns the same interface as `useCollectionVariables()`.  Pass a `TFieldName`
+ * Returns the `CollectionControl` interface.  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 `CollectionVariablesProvider`.
+ * @throws Error if used outside of `CollectionControlProvider`.
  *
  * @example
  * ```tsx
  * function StatusFilter() {
- *   const { filters, addFilter, removeFilter } = useCollectionVariablesContext();
+ *   const { filters, addFilter, removeFilter } = useCollectionControl();
  *   // ...
  * }
  *
  * // With typed field names:
  * type TaskField = FieldName<typeof tableMetadata, "task">;
- * const { addFilter } = useCollectionVariablesContext<TaskField>();
+ * const { addFilter } = useCollectionControl<TaskField>();
  * ```
  */
-export function useCollectionVariablesContext<
+export function useCollectionControl<
   TFieldName extends string = string,
->(): UseCollectionReturn<TFieldName> {
-  const ctx = useContext(CollectionVariablesContext);
+>(): CollectionControl<TFieldName> {
+  const ctx = useContext(CollectionControlContext);
   if (!ctx) {
     throw new Error(
-      "useCollectionVariablesContext must be used within <CollectionVariablesProvider>",
+      "useCollectionControl must be used within <CollectionControlProvider>",
     );
   }
-  return ctx as UseCollectionReturn<TFieldName>;
+  return ctx as CollectionControl<TFieldName>;
 }

package/src/component/collection/use-collection.test.ts

@@ -13,10 +13,10 @@ describe("useCollectionVariables", () => {
       expect(result.current.variables.pagination).toEqual({ first: 20 });
       expect(result.current.variables.query).toBeUndefined();
       expect(result.current.variables.order).toBeUndefined();
-      expect(result.current.filters).toEqual([]);
-      expect(result.current.sortStates).toEqual([]);
-      expect(result.current.cursor).toBeNull();
-      expect(result.current.hasPrevPage).toBe(false);
+      expect(result.current.control.filters).toEqual([]);
+      expect(result.current.control.sortStates).toEqual([]);
+      expect(result.current.control.cursor).toBeNull();
+      expect(result.current.control.hasPrevPage).toBe(false);
     });
 
     it("uses custom pageSize", () => {
@@ -34,7 +34,7 @@ describe("useCollectionVariables", () => {
           },
         }),
       );
-      expect(result.current.sortStates).toEqual([
+      expect(result.current.control.sortStates).toEqual([
         { field: "createdAt", direction: "Desc" },
       ]);
       expect(result.current.variables.order).toEqual([
@@ -56,7 +56,7 @@ describe("useCollectionVariables", () => {
           },
         }),
       );
-      expect(result.current.filters).toHaveLength(1);
+      expect(result.current.control.filters).toHaveLength(1);
       expect(result.current.variables.query).toEqual({
         status: { eq: "ACTIVE" },
       });
@@ -71,11 +71,11 @@ describe("useCollectionVariables", () => {
       const { result } = renderHook(() => useCollectionVariables({}));
 
       act(() => {
-        result.current.addFilter("status", "eq", "ACTIVE");
+        result.current.control.addFilter("status", "eq", "ACTIVE");
       });
 
-      expect(result.current.filters).toHaveLength(1);
-      expect(result.current.filters[0]).toMatchObject({
+      expect(result.current.control.filters).toHaveLength(1);
+      expect(result.current.control.filters[0]).toMatchObject({
         field: "status",
         operator: "eq",
         value: "ACTIVE",
@@ -89,21 +89,21 @@ describe("useCollectionVariables", () => {
       const { result } = renderHook(() => useCollectionVariables({}));
 
       act(() => {
-        result.current.addFilter("status", "eq", "ACTIVE");
+        result.current.control.addFilter("status", "eq", "ACTIVE");
       });
       act(() => {
-        result.current.addFilter("status", "eq", "INACTIVE");
+        result.current.control.addFilter("status", "eq", "INACTIVE");
       });
 
-      expect(result.current.filters).toHaveLength(1);
-      expect(result.current.filters[0].value).toBe("INACTIVE");
+      expect(result.current.control.filters).toHaveLength(1);
+      expect(result.current.control.filters[0].value).toBe("INACTIVE");
     });
 
     it("sets filters in bulk", () => {
       const { result } = renderHook(() => useCollectionVariables({}));
 
       act(() => {
-        result.current.setFilters([
+        result.current.control.setFilters([
           {
             field: "status",
             operator: "eq",
@@ -117,7 +117,7 @@ describe("useCollectionVariables", () => {
         ]);
       });
 
-      expect(result.current.filters).toHaveLength(2);
+      expect(result.current.control.filters).toHaveLength(2);
       expect(result.current.variables.query).toEqual({
         status: { eq: "ACTIVE" },
         amount: { gte: 1000 },
@@ -128,29 +128,29 @@ describe("useCollectionVariables", () => {
       const { result } = renderHook(() => useCollectionVariables({}));
 
       act(() => {
-        result.current.addFilter("status", "eq", "ACTIVE");
-        result.current.addFilter("amount", "gte", 1000);
+        result.current.control.addFilter("status", "eq", "ACTIVE");
+        result.current.control.addFilter("amount", "gte", 1000);
       });
       act(() => {
-        result.current.removeFilter("status");
+        result.current.control.removeFilter("status");
       });
 
-      expect(result.current.filters).toHaveLength(1);
-      expect(result.current.filters[0].field).toBe("amount");
+      expect(result.current.control.filters).toHaveLength(1);
+      expect(result.current.control.filters[0].field).toBe("amount");
     });
 
     it("clears all filters", () => {
       const { result } = renderHook(() => useCollectionVariables({}));
 
       act(() => {
-        result.current.addFilter("status", "eq", "ACTIVE");
-        result.current.addFilter("amount", "gte", 1000);
+        result.current.control.addFilter("status", "eq", "ACTIVE");
+        result.current.control.addFilter("amount", "gte", 1000);
       });
       act(() => {
-        result.current.clearFilters();
+        result.current.control.clearFilters();
       });
 
-      expect(result.current.filters).toHaveLength(0);
+      expect(result.current.control.filters).toHaveLength(0);
       expect(result.current.variables.query).toBeUndefined();
     });
 
@@ -159,16 +159,16 @@ describe("useCollectionVariables", () => {
 
       // Navigate to next page
       act(() => {
-        result.current.nextPage("cursor1");
+        result.current.control.nextPage("cursor1");
       });
-      expect(result.current.cursor).toBe("cursor1");
+      expect(result.current.control.cursor).toBe("cursor1");
 
       // Adding filter should reset pagination
       act(() => {
-        result.current.addFilter("status", "eq", "ACTIVE");
+        result.current.control.addFilter("status", "eq", "ACTIVE");
       });
-      expect(result.current.cursor).toBeNull();
-      expect(result.current.hasPrevPage).toBe(false);
+      expect(result.current.control.cursor).toBeNull();
+      expect(result.current.control.hasPrevPage).toBe(false);
     });
   });
 
@@ -180,10 +180,10 @@ describe("useCollectionVariables", () => {
       const { result } = renderHook(() => useCollectionVariables({}));
 
       act(() => {
-        result.current.setSort("createdAt", "Desc");
+        result.current.control.setSort("createdAt", "Desc");
       });
 
-      expect(result.current.sortStates).toEqual([
+      expect(result.current.control.sortStates).toEqual([
         { field: "createdAt", direction: "Desc" },
       ]);
       expect(result.current.variables.order).toEqual([
@@ -195,13 +195,13 @@ describe("useCollectionVariables", () => {
       const { result } = renderHook(() => useCollectionVariables({}));
 
       act(() => {
-        result.current.setSort("createdAt", "Desc");
+        result.current.control.setSort("createdAt", "Desc");
       });
       act(() => {
-        result.current.setSort("name", "Asc");
+        result.current.control.setSort("name", "Asc");
       });
 
-      expect(result.current.sortStates).toEqual([
+      expect(result.current.control.sortStates).toEqual([
         { field: "createdAt", direction: "Desc" },
         { field: "name", direction: "Asc" },
       ]);
@@ -211,16 +211,16 @@ describe("useCollectionVariables", () => {
       const { result } = renderHook(() => useCollectionVariables({}));
 
       act(() => {
-        result.current.setSort("createdAt", "Desc");
+        result.current.control.setSort("createdAt", "Desc");
       });
       act(() => {
-        result.current.setSort("name", "Asc");
+        result.current.control.setSort("name", "Asc");
       });
       act(() => {
-        result.current.setSort("createdAt", "Asc");
+        result.current.control.setSort("createdAt", "Asc");
       });
 
-      expect(result.current.sortStates).toEqual([
+      expect(result.current.control.sortStates).toEqual([
         { field: "name", direction: "Asc" },
         { field: "createdAt", direction: "Asc" },
       ]);
@@ -230,16 +230,16 @@ describe("useCollectionVariables", () => {
       const { result } = renderHook(() => useCollectionVariables({}));
 
       act(() => {
-        result.current.setSort("createdAt", "Desc");
+        result.current.control.setSort("createdAt", "Desc");
       });
       act(() => {
-        result.current.setSort("name", "Asc");
+        result.current.control.setSort("name", "Asc");
       });
       act(() => {
-        result.current.setSort("createdAt");
+        result.current.control.setSort("createdAt");
       });
 
-      expect(result.current.sortStates).toEqual([
+      expect(result.current.control.sortStates).toEqual([
         { field: "name", direction: "Asc" },
       ]);
     });
@@ -248,13 +248,13 @@ describe("useCollectionVariables", () => {
       const { result } = renderHook(() => useCollectionVariables({}));
 
       act(() => {
-        result.current.setSort("createdAt", "Desc");
+        result.current.control.setSort("createdAt", "Desc");
       });
       act(() => {
-        result.current.clearSort();
+        result.current.control.clearSort();
       });
 
-      expect(result.current.sortStates).toEqual([]);
+      expect(result.current.control.sortStates).toEqual([]);
       expect(result.current.variables.order).toBeUndefined();
     });
   });
@@ -267,11 +267,11 @@ describe("useCollectionVariables", () => {
       const { result } = renderHook(() => useCollectionVariables({}));
 
       act(() => {
-        result.current.nextPage("cursor1");
+        result.current.control.nextPage("cursor1");
       });
 
-      expect(result.current.cursor).toBe("cursor1");
-      expect(result.current.paginationDirection).toBe("forward");
+      expect(result.current.control.cursor).toBe("cursor1");
+      expect(result.current.control.paginationDirection).toBe("forward");
       expect(result.current.variables.pagination.after).toBe("cursor1");
       expect(result.current.variables.pagination.first).toBe(20);
       expect(result.current.variables.pagination.last).toBeUndefined();
@@ -282,11 +282,11 @@ describe("useCollectionVariables", () => {
       const { result } = renderHook(() => useCollectionVariables({}));
 
       act(() => {
-        result.current.prevPage("cursor1");
+        result.current.control.prevPage("cursor1");
       });
 
-      expect(result.current.cursor).toBe("cursor1");
-      expect(result.current.paginationDirection).toBe("backward");
+      expect(result.current.control.cursor).toBe("cursor1");
+      expect(result.current.control.paginationDirection).toBe("backward");
       expect(result.current.variables.pagination.before).toBe("cursor1");
       expect(result.current.variables.pagination.last).toBe(20);
       expect(result.current.variables.pagination.first).toBeUndefined();
@@ -297,14 +297,14 @@ describe("useCollectionVariables", () => {
       const { result } = renderHook(() => useCollectionVariables({}));
 
       act(() => {
-        result.current.prevPage("cursorB");
+        result.current.control.prevPage("cursorB");
       });
-      expect(result.current.paginationDirection).toBe("backward");
+      expect(result.current.control.paginationDirection).toBe("backward");
 
       act(() => {
-        result.current.nextPage("cursorA");
+        result.current.control.nextPage("cursorA");
       });
-      expect(result.current.paginationDirection).toBe("forward");
+      expect(result.current.control.paginationDirection).toBe("forward");
       expect(result.current.variables.pagination.after).toBe("cursorA");
       expect(result.current.variables.pagination.first).toBe(20);
     });
@@ -313,33 +313,33 @@ describe("useCollectionVariables", () => {
       const { result } = renderHook(() => useCollectionVariables({}));
 
       act(() => {
-        result.current.prevPage("cursor1");
+        result.current.control.prevPage("cursor1");
       });
       act(() => {
-        result.current.resetPage();
+        result.current.control.resetPage();
       });
 
-      expect(result.current.cursor).toBeNull();
-      expect(result.current.paginationDirection).toBe("forward");
+      expect(result.current.control.cursor).toBeNull();
+      expect(result.current.control.paginationDirection).toBe("forward");
     });
 
     it("tracks hasPrevPage from currentPage and hasNextPage from setPageInfo", () => {
       const { result } = renderHook(() => useCollectionVariables({}));
 
       // Initially on page 1: no prev, no next
-      expect(result.current.hasPrevPage).toBe(false);
-      expect(result.current.hasNextPage).toBe(false);
+      expect(result.current.control.hasPrevPage).toBe(false);
+      expect(result.current.control.hasNextPage).toBe(false);
 
       // After navigating to next page, hasPrevPage becomes true
       act(() => {
-        result.current.nextPage("cursor-end");
+        result.current.control.nextPage("cursor-end");
       });
 
-      expect(result.current.hasPrevPage).toBe(true);
+      expect(result.current.control.hasPrevPage).toBe(true);
 
       // hasNextPage comes from setPageInfo when totalPages is null
       act(() => {
-        result.current.setPageInfo({
+        result.current.control.setPageInfo({
           hasNextPage: true,
           endCursor: "end",
           hasPreviousPage: false,
@@ -347,7 +347,7 @@ describe("useCollectionVariables", () => {
         });
       });
 
-      expect(result.current.hasNextPage).toBe(true);
+      expect(result.current.control.hasNextPage).toBe(true);
     });
   });
 
@@ -373,7 +373,7 @@ describe("useCollectionVariables", () => {
       );
 
       act(() => {
-        result.current.nextPage("abc123");
+        result.current.control.nextPage("abc123");
       });
 
       expect(result.current.variables).toEqual({
@@ -449,7 +449,7 @@ describe("useCollectionVariables", () => {
         }),
       );
 
-      expect(result.current.sortStates).toEqual([
+      expect(result.current.control.sortStates).toEqual([
         { field: "dueDate", direction: "Desc" },
       ]);
     });

package/src/component/collection/use-collection.ts

@@ -2,6 +2,7 @@ import { useCallback, useMemo, useState } from "react";
 import type { TableMetadata } from "../../generator/metadata-generator";
 import type {
   BuildQueryVariables,
+  CollectionControl,
   CollectionVariables,
   Filter,
   FilterOperator,
@@ -298,30 +299,32 @@ export function useCollectionVariables(
   // ---------------------------------------------------------------------------
   return {
     variables,
-    filters,
-    // Cast needed: implementation accepts FilterOperator (widest),
-    // but overload signatures narrow via OperatorForField<TFilter, F>.
-    addFilter: addFilter as UseCollectionReturn["addFilter"],
-    setFilters,
-    removeFilter,
-    clearFilters,
-    sortStates,
-    setSort,
-    clearSort,
-    pageSize,
-    setPageSize,
-    cursor,
-    paginationDirection,
-    nextPage,
-    prevPage,
-    resetPage,
-    hasPrevPage,
-    hasNextPage,
-    setPageInfo,
-    currentPage,
-    totalPages,
-    goToFirstPage,
-    goToLastPage,
-    setTotal,
+    control: {
+      filters,
+      // Cast needed: implementation accepts FilterOperator (widest),
+      // but overload signatures narrow via OperatorForField<TFilter, F>.
+      addFilter: addFilter as CollectionControl["addFilter"],
+      setFilters,
+      removeFilter,
+      clearFilters,
+      sortStates,
+      setSort,
+      clearSort,
+      pageSize,
+      setPageSize,
+      cursor,
+      paginationDirection,
+      nextPage,
+      prevPage,
+      resetPage,
+      hasPrevPage,
+      hasNextPage,
+      setPageInfo,
+      currentPage,
+      totalPages,
+      goToFirstPage,
+      goToLastPage,
+      setTotal,
+    },
   };
 }

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

@@ -8,7 +8,7 @@ import {
   type ReactNode,
 } from "react";
 import { cn } from "../lib/utils";
-import { CollectionVariablesProvider } from "../collection/collection-provider";
+import { CollectionControlProvider } from "../collection/collection-provider";
 import { Table } from "../table";
 import type { RowAction, SortConfig, UseDataTableReturn } from "../types";
 import {
@@ -102,7 +102,7 @@ function DataTableProviderComponent<TRow extends Record<string, unknown>>({
     locale: value.locale,
   };
 
-  const collectionValue = value.collection ?? null;
+  const controlValue = value.control ?? null;
 
   const inner = (
     <DataTableContext.Provider value={dataTableValue}>
@@ -110,12 +110,12 @@ function DataTableProviderComponent<TRow extends Record<string, unknown>>({
     </DataTableContext.Provider>
   );
 
-  // Wrap with CollectionVariablesContext when collection is available
-  if (collectionValue) {
+  // Wrap with CollectionControlProvider when control is available
+  if (controlValue) {
     return (
-      <CollectionVariablesProvider value={collectionValue}>
+      <CollectionControlProvider value={controlValue}>
         {inner}
-      </CollectionVariablesProvider>
+      </CollectionControlProvider>
     );
   }
 

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

@@ -1,5 +1,5 @@
 import { useDataTableContext } from "./data-table-context";
-import { useCollectionVariablesContext } from "../collection/collection-provider";
+import { useCollectionControl } from "../collection/collection-provider";
 import { getLabels } from "./i18n";
 
 // =============================================================================
@@ -139,7 +139,7 @@ export function Pagination({ labels, pageSizeOptions }: PaginationProps = {}) {
     goToLastPage,
     pageSize,
     setPageSize,
-  } = useCollectionVariablesContext();
+  } = useCollectionControl();
 
   const pl = getLabels(locale).pagination;
   const firstLabel = labels?.first ?? pl.first;

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

@@ -14,7 +14,7 @@ import type {
 } from "../types";
 import { OPERATORS_BY_FILTER_TYPE } from "../types";
 import { useDataTableContext } from "./data-table-context";
-import { useCollectionVariablesContext } from "../collection/collection-provider";
+import { useCollectionControl } from "../collection/collection-provider";
 import { getLabels } from "./i18n";
 
 /**
@@ -46,7 +46,7 @@ export function SearchFilterForm({
 } = {}) {
   const { columns, locale } = useDataTableContext();
   const { filters, addFilter, removeFilter, clearFilters } =
-    useCollectionVariablesContext();
+    useCollectionControl();
   const sf = getLabels(locale).searchFilter;
   const filterableColumns = columns.filter((col) => !!col.filter);
 

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

@@ -234,7 +234,7 @@ describe("useDataTable", () => {
   // Sort state
   // ---------------------------------------------------------------------------
   describe("sort state", () => {
-    it("sortStates is empty when no collection is provided", () => {
+    it("sortStates is empty when no control is provided", () => {
       const { result } = renderHook(() =>
         useDataTable<TestRow>({ columns: testColumns, data: testData }),
       );
@@ -242,7 +242,7 @@ describe("useDataTable", () => {
       expect(result.current.sortStates).toEqual([]);
     });
 
-    it("onSort is undefined when no collection is provided", () => {
+    it("onSort is undefined when no control is provided", () => {
       const { result } = renderHook(() =>
         useDataTable<TestRow>({ columns: testColumns, data: testData }),
       );

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

@@ -13,7 +13,7 @@ import type {
  *
  * @example
  * ```tsx
- * const { variables, ...collection } = useCollectionVariables({ params: { pageSize: 20 } });
+ * const { variables, control } = useCollectionVariables({ params: { pageSize: 20 } });
  * const { query, order, pagination } = variables;
  * const [result] = useQuery({
  *   query: GET_ORDERS,
@@ -24,7 +24,7 @@ import type {
  *   columns,
  *   data: result.data?.orders,
  *   loading: result.fetching,
- *   collection,
+ *   control,
  * });
  *
  * <DataTable.Provider value={table}>
@@ -43,7 +43,7 @@ export function useDataTable<TRow extends Record<string, unknown>>(
     data,
     loading = false,
     error = null,
-    collection,
+    control,
     onClickRow,
     rowActions,
     locale = "en",
@@ -76,20 +76,15 @@ export function useDataTable<TRow extends Record<string, unknown>>(
     );
   }, [data]);
 
-  // Sync pageInfo to collection so hasPrevPage/hasNextPage are up-to-date
+  // Sync pageInfo to control so hasPrevPage/hasNextPage are up-to-date
   useEffect(() => {
     if (data?.pageInfo) {
-      collection?.setPageInfo(data.pageInfo);
+      control?.setPageInfo(data.pageInfo);
     }
     if (data?.total != null) {
-      collection?.setTotal(data.total);
+      control?.setTotal(data.total);
     }
-  }, [
-    data?.pageInfo,
-    data?.total,
-    collection?.setPageInfo,
-    collection?.setTotal,
-  ]);
+  }, [data?.pageInfo, data?.total, control?.setPageInfo, control?.setTotal]);
 
   // ---------------------------------------------------------------------------
   // Column visibility management
@@ -131,24 +126,24 @@ export function useDataTable<TRow extends Record<string, unknown>>(
   );
 
   // ---------------------------------------------------------------------------
-  // Pagination (delegated from collection)
+  // Pagination (delegated from control)
   // ---------------------------------------------------------------------------
   const nextPage = useCallback(
     (endCursor: string) => {
-      collection?.nextPage(endCursor);
+      control?.nextPage(endCursor);
     },
-    [collection],
+    [control],
   );
 
   const prevPage = useCallback(
     (startCursor: string) => {
-      collection?.prevPage(startCursor);
+      control?.prevPage(startCursor);
     },
-    [collection],
+    [control],
   );
 
-  const hasPrevPage = collection?.hasPrevPage ?? false;
-  const hasNextPage = collection?.hasNextPage ?? false;
+  const hasPrevPage = control?.hasPrevPage ?? false;
+  const hasNextPage = control?.hasNextPage ?? false;
 
   // ---------------------------------------------------------------------------
   // Row Operations (Optimistic Updates)
@@ -209,19 +204,19 @@ export function useDataTable<TRow extends Record<string, unknown>>(
   );
 
   // ---------------------------------------------------------------------------
-  // Sort (delegated from collection)
+  // Sort (delegated from control)
   // ---------------------------------------------------------------------------
   const sortStates = useMemo<SortState[]>(() => {
-    return collection?.sortStates ?? [];
-  }, [collection?.sortStates]);
+    return control?.sortStates ?? [];
+  }, [control?.sortStates]);
 
   const onSort = useMemo<
     ((field: string, direction?: "Asc" | "Desc") => void) | undefined
   >(() => {
-    if (!collection) return undefined;
+    if (!control) return undefined;
     return (field: string, direction?: "Asc" | "Desc") =>
-      collection.setSort(field, direction);
-  }, [collection]);
+      control.setSort(field, direction);
+  }, [control]);
 
   // ---------------------------------------------------------------------------
   // Return
@@ -254,8 +249,8 @@ export function useDataTable<TRow extends Record<string, unknown>>(
     deleteRow,
     insertRow,
 
-    // Collection (passthrough for DataTable.Provider)
-    collection,
+    // Control (passthrough for DataTable.Provider)
+    control,
 
     // Row interaction (passthrough for DataTable.Provider)
     onClickRow,

package/src/component/index.ts

@@ -18,6 +18,7 @@ export type {
   ColumnDefinition,
   UseCollectionOptions,
   UseCollectionReturn,
+  CollectionControl,
   UseDataTableOptions,
   UseDataTableReturn,
   RowAction,
@@ -44,8 +45,8 @@ export {
 // Collection
 export { useCollectionVariables } from "./collection/use-collection";
 export {
-  CollectionVariablesProvider,
-  useCollectionVariablesContext,
+  CollectionControlProvider,
+  useCollectionControl,
 } from "./collection/collection-provider";
 
 // Table (static)

package/src/component/types.ts

@@ -466,40 +466,25 @@ export interface UseCollectionOptions<
 }
 
 /**
- * Return type of `useCollectionVariables` hook.
+ * Collection control interface for UI components to interact with
+ * filter, sort, and pagination state.
  *
  * Methods that accept a field name are typed with `TFieldName` so that
  * auto-completion works when a concrete union is supplied.
  *
  * **Note:** Methods that accept `TFieldName` use *method syntax* intentionally
- * so that `UseCollectionReturn<"a" | "b">` remains assignable to
- * `UseCollectionReturn<string>` (bivariant method check).
+ * so that `CollectionControl<"a" | "b">` remains assignable to
+ * `CollectionControl<string>` (bivariant method check).
  * Methods that don't depend on `TFieldName` use property syntax so they
  * can be safely destructured without triggering `unbound-method` lint rules.
  *
  * @typeParam TFieldName - Union of allowed field name strings (default: `string`).
- * @typeParam TVariables - Type of `variables` property.
+ * @typeParam TFilter - Filter type (default: `Filter<TFieldName>`).
  */
-export interface UseCollectionReturn<
+export interface CollectionControl<
   TFieldName extends string = string,
-  TVariables = CollectionVariables,
   TFilter = Filter<TFieldName>,
 > {
-  /**
-   * Collection variables split into explicit sub-properties
-   * for direct mapping to GraphQL query variables.
-   *
-   * @example
-   * ```tsx
-   * const { query, order, pagination } = collection.variables;
-   * const [result] = useQuery({
-   *   query: GET_TASKS,
-   *   variables: { ...pagination, query, order },
-   * });
-   * ```
-   */
-  variables: TVariables;
-
   // Filter operations
   /** Current active filters */
   filters: Filter[];
@@ -557,6 +542,49 @@ export interface UseCollectionReturn<
   setTotal: (total: number) => void;
 }
 
+/**
+ * Return type of `useCollectionVariables` hook.
+ *
+ * @typeParam TFieldName - Union of allowed field name strings (default: `string`).
+ * @typeParam TVariables - Type of `variables` property.
+ * @typeParam TFilter - Filter type (default: `Filter<TFieldName>`).
+ */
+export interface UseCollectionReturn<
+  TFieldName extends string = string,
+  TVariables = CollectionVariables,
+  TFilter = Filter<TFieldName>,
+> {
+  /**
+   * Collection variables split into explicit sub-properties
+   * for direct mapping to GraphQL query variables.
+   *
+   * @example
+   * ```tsx
+   * const { variables, control } = useCollectionVariables({ params: { pageSize: 20 } });
+   * const { query, order, pagination } = variables;
+   * const [result] = useQuery({
+   *   query: GET_TASKS,
+   *   variables: { ...pagination, query, order },
+   * });
+   * ```
+   */
+  variables: TVariables;
+
+  /**
+   * Collection control interface for UI components.
+   *
+   * Pass this to `useDataTable({ control })` to connect filter, sort,
+   * and pagination state to the data table.
+   *
+   * @example
+   * ```tsx
+   * const { variables, control } = useCollectionVariables({ params: { pageSize: 20 } });
+   * const table = useDataTable({ columns, data: result.data?.orders, control });
+   * ```
+   */
+  control: CollectionControl<TFieldName, TFilter>;
+}
+
 // =============================================================================
 // useDataTable Types
 // =============================================================================
@@ -573,8 +601,8 @@ export interface UseDataTableOptions<TRow extends Record<string, unknown>> {
   loading?: boolean;
   /** Error */
   error?: Error | null;
-  /** Collection state for sort/pagination integration */
-  collection?: UseCollectionReturn<string, unknown>;
+  /** Collection control for sort/filter/pagination integration */
+  control?: CollectionControl;
   /** Handler called when a row is clicked */
   onClickRow?: (row: TRow) => void;
   /** Row action definitions for the actions column */
@@ -680,9 +708,9 @@ export interface UseDataTableReturn<TRow extends Record<string, unknown>> {
   /** Optimistically insert a row */
   insertRow: (row: TRow) => { rollback: () => void };
 
-  // Collection (passthrough for DataTable.Provider)
-  /** Collection state passed through from options */
-  collection: UseCollectionReturn<string, unknown> | undefined;
+  // Control (passthrough for DataTable.Provider)
+  /** Collection control passed through from options */
+  control: CollectionControl | undefined;
 
   // Row interaction (passthrough for DataTable.Provider)
   /** Handler called when a row is clicked */

package/src/tests/helpers.tsx

@@ -1,9 +1,9 @@
 import type { ReactNode } from "react";
 import { vi } from "vitest";
-import type { Column, UseCollectionReturn } from "../component/types";
+import type { Column, CollectionControl } from "../component/types";
 import { DataTableContext } from "../component/data-table/data-table-context";
 import type { DataTableContextValue } from "../component/data-table/data-table-context";
-import { CollectionVariablesProvider } from "../component/collection/collection-provider";
+import { CollectionControlProvider } from "../component/collection/collection-provider";
 
 // =============================================================================
 // Mock factory: DataTableContext
@@ -47,14 +47,9 @@ export function createMockDataTableContext<T extends Record<string, unknown>>(
 // =============================================================================
 
 export function createMockCollectionContext(
-  overrides?: Partial<UseCollectionReturn<string, unknown>>,
-): UseCollectionReturn<string, unknown> {
+  overrides?: Partial<CollectionControl>,
+): CollectionControl {
   return {
-    variables: {
-      query: undefined,
-      order: undefined,
-      pagination: { first: 20 },
-    },
     filters: [],
     addFilter: vi.fn(),
     setFilters: vi.fn(),
@@ -110,7 +105,7 @@ export function createTestProviders<
   columns: Column<T>[];
   rows: T[];
   dataTableDefaults?: Partial<DataTableContextValue<T>>;
-  collectionDefaults?: Partial<UseCollectionReturn<string, unknown>>;
+  collectionDefaults?: Partial<CollectionControl>;
 }) {
   return function TestProviders({
     children,
@@ -119,10 +114,10 @@ export function createTestProviders<
   }: {
     children: ReactNode;
     dataTable?: Partial<DataTableContextValue<T>>;
-    collection?: Partial<UseCollectionReturn<string, unknown>>;
+    collection?: Partial<CollectionControl>;
   }) {
     return (
-      <CollectionVariablesProvider
+      <CollectionControlProvider
         value={createMockCollectionContext({
           ...defaults.collectionDefaults,
           ...collection,
@@ -136,7 +131,7 @@ export function createTestProviders<
         >
           {children}
         </DataTableContext.Provider>
-      </CollectionVariablesProvider>
+      </CollectionControlProvider>
     );
   };
 }