@izumisy-tailor/tailor-data-viewer 0.3.0-preview.0 → 0.3.0

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
-- **`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
+- **`useCollectionVariables` Hook**: Manages filter, sort, and pagination state; outputs Tailor Platform-compatible GraphQL variables
+- **`CollectionVariablesProvider`**: 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 `useCollection` can drive tables, kanbans, calendars, etc.
+- **Presentation Agnostic**: Same `useCollectionVariables` can drive tables, kanbans, calendars, etc.
 
 ## Installation
 
@@ -47,7 +47,7 @@ npm install react react-dom
 
 ```tsx
 import {
-  useCollection,
+  useCollectionVariables,
   useDataTable,
   DataTable,
   Pagination,
@@ -95,8 +95,15 @@ const columns = [
 
 // 2. Build a page
 function OrdersPage() {
-  const collection = useCollection({ params: { pageSize: 20 } });
-  const [result] = useQuery({ query: GET_ORDERS, variables: { ...collection.variables.pagination, query: collection.variables.query, order: collection.variables.order } });
+  const { variables } = useCollectionVariables({ params: { pageSize: 20 } });
+  const [result] = useQuery({
+    query: GET_ORDERS,
+    variables: {
+      ...variables.pagination,
+      query: variables.query,
+      order: variables.order
+    }
+  });
 
   const table = useDataTable<Order>({
     columns,
@@ -119,12 +126,12 @@ function OrdersPage() {
 
 ## API Overview
 
-### `useCollection(options)`
+### `useCollectionVariables(options)`
 
 Manages filter, sort, and pagination state. Returns `variables` containing `query`, `order`, and `pagination` sub-properties in Tailor Platform-compatible format.
 
 ```tsx
-const collection = useCollection({
+const { variables, ...collection } = useCollectionVariables({
   params: {
     pageSize: 20,
     initialSort: [{ field: "createdAt", direction: "Desc" }],
@@ -135,9 +142,9 @@ const collection = useCollection({
 const [result] = useQuery({
   query: GET_ORDERS,
   variables: {
-    ...collection.variables.pagination,
-    query: collection.variables.query,
-    order: collection.variables.order,
+    ...variables.pagination,
+    query: variables.query,
+    order: variables.order,
   },
 });
 
@@ -163,15 +170,15 @@ collection.hasPrevPage;  // boolean
 collection.hasNextPage;  // boolean
 ```
 
-### `DataTable.Provider` / `useDataTableContext()` / `useCollectionContext()`
+### `DataTable.Provider` / `useDataTableContext()` / `useCollectionVariablesContext()`
 
 `DataTable.Provider` wraps the table UI and provides both data table and collection context. All utility components (`Pagination`, `ColumnSelector`, `CsvButton`, `SearchFilterForm`) read from this context — no prop spreading needed.
 
-When `collection` is passed to `useDataTable`, `DataTable.Provider` automatically wraps a `Collection.Provider` so child components can use `useCollectionContext()`.
+When `collection` is passed to `useDataTable`, `DataTable.Provider` automatically wraps a `CollectionVariablesProvider` so child components can use `useCollectionVariablesContext()`.
 
 ```tsx
 <DataTable.Provider value={table}>
-  <StatusFilter />   {/* useCollectionContext() inside */}
+  <StatusFilter />   {/* useCollectionVariablesContext() inside */}
   <DataTable.Root>
     <DataTable.Headers />
     <DataTable.Body />
@@ -180,13 +187,13 @@ When `collection` is passed to `useDataTable`, `DataTable.Provider` automaticall
 </DataTable.Provider>
 ```
 
-For cases where you need `Collection.Provider` without `DataTable.Provider` (e.g., non-table UIs), you can use it standalone:
+For cases where you need `CollectionVariablesProvider` without `DataTable.Provider` (e.g., non-table UIs), you can use it standalone:
 
 ```tsx
-<Collection.Provider value={collection}>
+<CollectionVariablesProvider value={collection}>
   <StatusFilter />
   <CustomKanbanBoard />
-</Collection.Provider>
+</CollectionVariablesProvider>
 ```
 
 ### Column Definition Helper

package/package.json

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

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

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

@@ -1,15 +1,15 @@
 import { renderHook, act } from "@testing-library/react";
 import { describe, it, expect } from "vitest";
 import type { TableMetadataMap } from "../../generator/metadata-generator";
-import { useCollection } from "./use-collection";
+import { useCollectionVariables } from "./use-collection";
 
-describe("useCollection", () => {
+describe("useCollectionVariables", () => {
   // ---------------------------------------------------------------------------
   // Initial state
   // ---------------------------------------------------------------------------
   describe("initial state", () => {
     it("returns default variables with pageSize 20", () => {
-      const { result } = renderHook(() => useCollection({}));
+      const { result } = renderHook(() => useCollectionVariables({}));
       expect(result.current.variables.pagination).toEqual({ first: 20 });
       expect(result.current.variables.query).toBeUndefined();
       expect(result.current.variables.order).toBeUndefined();
@@ -21,14 +21,14 @@ describe("useCollection", () => {
 
     it("uses custom pageSize", () => {
       const { result } = renderHook(() =>
-        useCollection({ params: { pageSize: 50 } }),
+        useCollectionVariables({ params: { pageSize: 50 } }),
       );
       expect(result.current.variables.pagination.first).toBe(50);
     });
 
     it("applies initial sort", () => {
       const { result } = renderHook(() =>
-        useCollection({
+        useCollectionVariables({
           params: {
             initialSort: [{ field: "createdAt", direction: "Desc" }],
           },
@@ -44,7 +44,7 @@ describe("useCollection", () => {
 
     it("applies initial filters", () => {
       const { result } = renderHook(() =>
-        useCollection({
+        useCollectionVariables({
           params: {
             initialFilters: [
               {
@@ -68,7 +68,7 @@ describe("useCollection", () => {
   // ---------------------------------------------------------------------------
   describe("filter operations", () => {
     it("adds a filter", () => {
-      const { result } = renderHook(() => useCollection({}));
+      const { result } = renderHook(() => useCollectionVariables({}));
 
       act(() => {
         result.current.addFilter("status", "eq", "ACTIVE");
@@ -86,7 +86,7 @@ describe("useCollection", () => {
     });
 
     it("replaces filter for same field", () => {
-      const { result } = renderHook(() => useCollection({}));
+      const { result } = renderHook(() => useCollectionVariables({}));
 
       act(() => {
         result.current.addFilter("status", "eq", "ACTIVE");
@@ -100,7 +100,7 @@ describe("useCollection", () => {
     });
 
     it("sets filters in bulk", () => {
-      const { result } = renderHook(() => useCollection({}));
+      const { result } = renderHook(() => useCollectionVariables({}));
 
       act(() => {
         result.current.setFilters([
@@ -125,7 +125,7 @@ describe("useCollection", () => {
     });
 
     it("removes a filter", () => {
-      const { result } = renderHook(() => useCollection({}));
+      const { result } = renderHook(() => useCollectionVariables({}));
 
       act(() => {
         result.current.addFilter("status", "eq", "ACTIVE");
@@ -140,7 +140,7 @@ describe("useCollection", () => {
     });
 
     it("clears all filters", () => {
-      const { result } = renderHook(() => useCollection({}));
+      const { result } = renderHook(() => useCollectionVariables({}));
 
       act(() => {
         result.current.addFilter("status", "eq", "ACTIVE");
@@ -155,7 +155,7 @@ describe("useCollection", () => {
     });
 
     it("resets pagination when filters change", () => {
-      const { result } = renderHook(() => useCollection({}));
+      const { result } = renderHook(() => useCollectionVariables({}));
 
       // Navigate to next page
       act(() => {
@@ -177,7 +177,7 @@ describe("useCollection", () => {
   // ---------------------------------------------------------------------------
   describe("sort operations", () => {
     it("sets sort", () => {
-      const { result } = renderHook(() => useCollection({}));
+      const { result } = renderHook(() => useCollectionVariables({}));
 
       act(() => {
         result.current.setSort("createdAt", "Desc");
@@ -192,7 +192,7 @@ describe("useCollection", () => {
     });
 
     it("appends sort for different fields", () => {
-      const { result } = renderHook(() => useCollection({}));
+      const { result } = renderHook(() => useCollectionVariables({}));
 
       act(() => {
         result.current.setSort("createdAt", "Desc");
@@ -208,7 +208,7 @@ describe("useCollection", () => {
     });
 
     it("replaces direction for existing field", () => {
-      const { result } = renderHook(() => useCollection({}));
+      const { result } = renderHook(() => useCollectionVariables({}));
 
       act(() => {
         result.current.setSort("createdAt", "Desc");
@@ -227,7 +227,7 @@ describe("useCollection", () => {
     });
 
     it("removes sort when direction is undefined", () => {
-      const { result } = renderHook(() => useCollection({}));
+      const { result } = renderHook(() => useCollectionVariables({}));
 
       act(() => {
         result.current.setSort("createdAt", "Desc");
@@ -245,7 +245,7 @@ describe("useCollection", () => {
     });
 
     it("clears sort", () => {
-      const { result } = renderHook(() => useCollection({}));
+      const { result } = renderHook(() => useCollectionVariables({}));
 
       act(() => {
         result.current.setSort("createdAt", "Desc");
@@ -264,7 +264,7 @@ describe("useCollection", () => {
   // ---------------------------------------------------------------------------
   describe("pagination operations", () => {
     it("navigates to next page (forward)", () => {
-      const { result } = renderHook(() => useCollection({}));
+      const { result } = renderHook(() => useCollectionVariables({}));
 
       act(() => {
         result.current.nextPage("cursor1");
@@ -279,7 +279,7 @@ describe("useCollection", () => {
     });
 
     it("navigates to previous page (backward)", () => {
-      const { result } = renderHook(() => useCollection({}));
+      const { result } = renderHook(() => useCollectionVariables({}));
 
       act(() => {
         result.current.prevPage("cursor1");
@@ -294,7 +294,7 @@ describe("useCollection", () => {
     });
 
     it("switches direction on nextPage after prevPage", () => {
-      const { result } = renderHook(() => useCollection({}));
+      const { result } = renderHook(() => useCollectionVariables({}));
 
       act(() => {
         result.current.prevPage("cursorB");
@@ -310,7 +310,7 @@ describe("useCollection", () => {
     });
 
     it("resets page to forward direction", () => {
-      const { result } = renderHook(() => useCollection({}));
+      const { result } = renderHook(() => useCollectionVariables({}));
 
       act(() => {
         result.current.prevPage("cursor1");
@@ -324,7 +324,7 @@ describe("useCollection", () => {
     });
 
     it("tracks hasPrevPage from currentPage and hasNextPage from setPageInfo", () => {
-      const { result } = renderHook(() => useCollection({}));
+      const { result } = renderHook(() => useCollectionVariables({}));
 
       // Initially on page 1: no prev, no next
       expect(result.current.hasPrevPage).toBe(false);
@@ -357,7 +357,7 @@ describe("useCollection", () => {
   describe("variables", () => {
     it("generates complete variables with filters, sort, and cursor", () => {
       const { result } = renderHook(() =>
-        useCollection({
+        useCollectionVariables({
           params: {
             pageSize: 10,
             initialFilters: [
@@ -387,7 +387,7 @@ describe("useCollection", () => {
     });
 
     it("omits undefined fields from pagination", () => {
-      const { result } = renderHook(() => useCollection({}));
+      const { result } = renderHook(() => useCollectionVariables({}));
       const { pagination } = result.current.variables;
       expect(pagination).toEqual({ first: 20 });
       expect("after" in pagination).toBe(false);
@@ -397,7 +397,7 @@ describe("useCollection", () => {
 
     it("returns undefined for query and order when empty", () => {
       const { result } = renderHook(() =>
-        useCollection({ params: { pageSize: 10 } }),
+        useCollectionVariables({ params: { pageSize: 10 } }),
       );
 
       expect(result.current.variables.query).toBeUndefined();
@@ -432,7 +432,7 @@ describe("useCollection", () => {
 
     it("works with tableMetadata", () => {
       const { result } = renderHook(() =>
-        useCollection({
+        useCollectionVariables({
           tableMetadata: testMetadata.task,
           params: { pageSize: 10 },
         }),
@@ -442,7 +442,7 @@ describe("useCollection", () => {
 
     it("applies typed initialSort", () => {
       const { result } = renderHook(() =>
-        useCollection({
+        useCollectionVariables({
           tableMetadata: testMetadata.task,
           params: {
             initialSort: [{ field: "dueDate", direction: "Desc" }],

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

@@ -29,18 +29,18 @@ import type { TableFieldName, TableOrderableFieldName } from "../types";
  * ```tsx
  * import { tableMetadata } from "./generated/data-viewer-metadata.generated";
  *
- * const collection = useCollection({
+ * const { variables } = useCollectionVariables({
  *   tableMetadata: tableMetadata.task,
  *   params: { pageSize: 20 },
  * });
- * const { query, order, pagination } = collection.variables;
+ * const { query, order, pagination } = variables;
  * const [result] = useQuery({
  *   query: GET_TASKS,
  *   variables: { ...pagination, query, order },
  * });
  * ```
  */
-export function useCollection<const TTable extends TableMetadata>(
+export function useCollectionVariables<const TTable extends TableMetadata>(
   options: UseCollectionOptions<
     TableFieldName<TTable>,
     TableMetadataFilter<TTable>
@@ -70,15 +70,15 @@ export function useCollection<const TTable extends TableMetadata>(
  *
  * @example
  * ```tsx
- * const collection = useCollection({ params: { pageSize: 20 } });
- * const { query, order, pagination } = collection.variables;
+ * const { variables } = useCollectionVariables({ params: { pageSize: 20 } });
+ * const { query, order, pagination } = variables;
  * const [result] = useQuery({
  *   query: GET_ORDERS,
  *   variables: { ...pagination, query, order },
  * });
  * ```
  */
-export function useCollection(
+export function useCollectionVariables(
   options: UseCollectionOptions & {
     tableMetadata?: never;
   },
@@ -87,7 +87,7 @@ export function useCollection(
 // -----------------------------------------------------------------------------
 // Implementation
 // -----------------------------------------------------------------------------
-export function useCollection(
+export function useCollectionVariables(
   options: UseCollectionOptions & {
     tableMetadata?: TableMetadata;
   },

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

@@ -8,7 +8,7 @@ import {
   type ReactNode,
 } from "react";
 import { cn } from "../lib/utils";
-import { CollectionProvider } from "../collection/collection-provider";
+import { CollectionVariablesProvider } from "../collection/collection-provider";
 import { Table } from "../table";
 import type { RowAction, SortConfig, UseDataTableReturn } from "../types";
 import {
@@ -53,14 +53,14 @@ function DataTableRoot({
 /**
  * Provider that shares `useDataTable()` state via React Context.
  *
- * Internally provides both `DataTableContext` and `CollectionContext`
+ * Internally provides both `DataTableContext` and `CollectionVariablesContext`
  * so that utility components (`Pagination`, `ColumnSelector`,
  * `SearchFilterForm`, `CsvButton`) can consume data without explicit props.
  *
  * @example
  * ```tsx
- * const collection = useCollection({ params: { pageSize: 20 } });
- * const [result] = useQuery({ query: GET_ORDERS, variables: { ...collection.variables.pagination, query: collection.variables.query, order: collection.variables.order } });
+ * const { variables, ...collection } = useCollectionVariables({ params: { pageSize: 20 } });
+ * const [result] = useQuery({ query: GET_ORDERS, variables: { ...variables.pagination, query: variables.query, order: variables.order } });
  * const table = useDataTable({ columns, data: result.data?.orders, collection });
  *
  * <DataTable.Provider value={table}>
@@ -110,10 +110,12 @@ function DataTableProviderComponent<TRow extends Record<string, unknown>>({
     </DataTableContext.Provider>
   );
 
-  // Wrap with CollectionContext when collection is available
+  // Wrap with CollectionVariablesContext when collection is available
   if (collectionValue) {
     return (
-      <CollectionProvider value={collectionValue}>{inner}</CollectionProvider>
+      <CollectionVariablesProvider value={collectionValue}>
+        {inner}
+      </CollectionVariablesProvider>
     );
   }
 

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

@@ -1,5 +1,5 @@
 import { useDataTableContext } from "./data-table-context";
-import { useCollectionContext } from "../collection/collection-provider";
+import { useCollectionVariablesContext } from "../collection/collection-provider";
 import { getLabels } from "./i18n";
 
 // =============================================================================
@@ -112,7 +112,7 @@ const btnClass =
 /**
  * Pagination controls with first/prev/next/last navigation and page indicator.
  *
- * Reads pagination state from `DataTableContext` and `CollectionContext`.
+ * Reads pagination state from `DataTableContext` and `CollectionVariablesContext`.
  * Must be rendered inside `DataTable.Provider` but **outside** `DataTable.Root`.
  *
  * @example
@@ -139,7 +139,7 @@ export function Pagination({ labels, pageSizeOptions }: PaginationProps = {}) {
     goToLastPage,
     pageSize,
     setPageSize,
-  } = useCollectionContext();
+  } = useCollectionVariablesContext();
 
   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 { useCollectionContext } from "../collection/collection-provider";
+import { useCollectionVariablesContext } from "../collection/collection-provider";
 import { getLabels } from "./i18n";
 
 /**
@@ -22,7 +22,7 @@ import { getLabels } from "./i18n";
  *
  * Renders a dropdown panel with type-specific filter inputs, operator
  * selectors, and active filter badges.  Reads `columns` from
- * `DataTableContext` and filter state from `CollectionContext`.
+ * `DataTableContext` and filter state from `CollectionVariablesContext`.
  * Must be rendered inside `DataTable.Provider`.
  *
  * All text is customisable through the optional `labels` prop (defaults
@@ -46,7 +46,7 @@ export function SearchFilterForm({
 } = {}) {
   const { columns, locale } = useDataTableContext();
   const { filters, addFilter, removeFilter, clearFilters } =
-    useCollectionContext();
+    useCollectionVariablesContext();
   const sf = getLabels(locale).searchFilter;
   const filterableColumns = columns.filter((col) => !!col.filter);
 

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

@@ -13,8 +13,8 @@ import type {
  *
  * @example
  * ```tsx
- * const collection = useCollection({ params: { pageSize: 20 } });
- * const { query, order, pagination } = collection.variables;
+ * const { variables, ...collection } = useCollectionVariables({ params: { pageSize: 20 } });
+ * const { query, order, pagination } = variables;
  * const [result] = useQuery({
  *   query: GET_ORDERS,
  *   variables: { ...pagination, query, order },

package/src/component/index.ts

@@ -42,11 +42,10 @@ export {
 } from "./types";
 
 // Collection
-export { useCollection } from "./collection/use-collection";
+export { useCollectionVariables } from "./collection/use-collection";
 export {
-  Collection,
-  CollectionProvider,
-  useCollectionContext,
+  CollectionVariablesProvider,
+  useCollectionVariablesContext,
 } from "./collection/collection-provider";
 
 // Table (static)

package/src/component/types.ts

@@ -219,13 +219,13 @@ export interface PageInfo {
  * GraphQL query variables in Tailor Platform format.
  *
  * Field-level type safety for `query` and `order` is not enforced here.
- * When `useCollection` is called with metadata, `BuildQueryVariables`
+ * When `useCollectionVariables` is called with metadata, `BuildQueryVariables`
  * produces precise per-field filter types at compile time.
  */
 export interface QueryVariables {
-  /** Filter object built at runtime by `useCollection`. */
+  /** Filter object built at runtime by `useCollectionVariables`. */
   query?: Record<string, unknown>;
-  /** Sort order built at runtime by `useCollection`. */
+  /** Sort order built at runtime by `useCollectionVariables`. */
   order?: { field: string; direction: "Asc" | "Desc" }[];
   /** Forward pagination: number of items to fetch */
   first?: number | null;
@@ -425,11 +425,11 @@ export type ColumnDefinition<TRow extends Record<string, unknown>> =
   Column<TRow>;
 
 // =============================================================================
-// useCollection Types
+// useCollectionVariables Types
 // =============================================================================
 
 /**
- * Options for `useCollection` hook.
+ * Options for `useCollectionVariables` hook.
  *
  * @typeParam TFieldName - Union of allowed field name strings (default: `string`).
  */
@@ -449,7 +449,7 @@ export interface UseCollectionOptions<
 }
 
 /**
- * Return type of `useCollection` hook.
+ * Return type of `useCollectionVariables` hook.
  *
  * Methods that accept a field name are typed with `TFieldName` so that
  * auto-completion works when a concrete union is supplied.

package/src/tests/helpers.tsx

@@ -3,7 +3,7 @@ import { vi } from "vitest";
 import type { Column, UseCollectionReturn } from "../component/types";
 import { DataTableContext } from "../component/data-table/data-table-context";
 import type { DataTableContextValue } from "../component/data-table/data-table-context";
-import { CollectionProvider } from "../component/collection/collection-provider";
+import { CollectionVariablesProvider } from "../component/collection/collection-provider";
 
 // =============================================================================
 // Mock factory: DataTableContext
@@ -43,7 +43,7 @@ export function createMockDataTableContext<T extends Record<string, unknown>>(
 }
 
 // =============================================================================
-// Mock factory: CollectionContext
+// Mock factory: CollectionVariablesContext
 // =============================================================================
 
 export function createMockCollectionContext(
@@ -122,7 +122,7 @@ export function createTestProviders<
     collection?: Partial<UseCollectionReturn<string, unknown>>;
   }) {
     return (
-      <CollectionProvider
+      <CollectionVariablesProvider
         value={createMockCollectionContext({
           ...defaults.collectionDefaults,
           ...collection,
@@ -136,7 +136,7 @@ export function createTestProviders<
         >
           {children}
         </DataTableContext.Provider>
-      </CollectionProvider>
+      </CollectionVariablesProvider>
     );
   };
 }