@izumisy-tailor/tailor-data-viewer 0.2.33 → 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({ query: GET_ORDERS, params: { pageSize: 20 } });
-  const [result] = useQuery({ ...collection.toQueryArgs() });
+  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,21 +126,27 @@ function OrdersPage() {
 
 ## API Overview
 
-### `useCollection(options)`
+### `useCollectionVariables(options)`
 
-Manages filter, sort, and pagination state. Returns `toQueryArgs()` which produces Tailor Platform-compatible arguments for `useQuery()`.
+Manages filter, sort, and pagination state. Returns `variables` containing `query`, `order`, and `pagination` sub-properties in Tailor Platform-compatible format.
 
 ```tsx
-const collection = useCollection({
-  query: GET_ORDERS,
+const { variables, ...collection } = useCollectionVariables({
   params: {
     pageSize: 20,
     initialSort: [{ field: "createdAt", direction: "Desc" }],
   },
 });
 
-// Spread toQueryArgs() into useQuery
-const [result] = useQuery({ ...collection.toQueryArgs() });
+// Use variables in your query
+const [result] = useQuery({
+  query: GET_ORDERS,
+  variables: {
+    ...variables.pagination,
+    query: variables.query,
+    order: variables.order,
+  },
+});
 
 // Filter operations
 collection.addFilter("status", "eq", "ACTIVE");
@@ -157,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 />
@@ -174,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.2.33",
+  "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);
@@ -11,16 +11,16 @@ const CollectionContext = createContext<UseCollectionReturn<
  *
  * @example
  * ```tsx
- * const collection = useCollection({ params: { pageSize: 20 } });
+ * const { variables, ...collection } = useCollectionVariables({ params: { pageSize: 20 } });
  *
- * <CollectionProvider value={collection}>
+ * <CollectionVariablesProvider value={collection}>
  *   <FilterPanel />
  *   <DataTable.Root>...</DataTable.Root>
- *   <Pagination {...table} />
- * </CollectionProvider>
+ *   <Pagination />
+ * </CollectionVariablesProvider>
  * ```
  */
-export function CollectionProvider({
+export function CollectionVariablesProvider({
   value,
   children,
 }: {
@@ -28,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,18 +1,18 @@
 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";
 
-const FAKE_QUERY = { kind: "Document" } as const;
-
-describe("useCollection", () => {
+describe("useCollectionVariables", () => {
   // ---------------------------------------------------------------------------
   // Initial state
   // ---------------------------------------------------------------------------
   describe("initial state", () => {
     it("returns default variables with pageSize 20", () => {
-      const { result } = renderHook(() => useCollection({ query: FAKE_QUERY }));
-      expect(result.current.toQueryArgs().variables).toEqual({ first: 20 });
+      const { result } = renderHook(() => 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();
@@ -21,15 +21,14 @@ describe("useCollection", () => {
 
     it("uses custom pageSize", () => {
       const { result } = renderHook(() =>
-        useCollection({ query: FAKE_QUERY, params: { pageSize: 50 } }),
+        useCollectionVariables({ params: { pageSize: 50 } }),
       );
-      expect(result.current.toQueryArgs().variables.first).toBe(50);
+      expect(result.current.variables.pagination.first).toBe(50);
     });
 
     it("applies initial sort", () => {
       const { result } = renderHook(() =>
-        useCollection({
-          query: FAKE_QUERY,
+        useCollectionVariables({
           params: {
             initialSort: [{ field: "createdAt", direction: "Desc" }],
           },
@@ -38,15 +37,14 @@ describe("useCollection", () => {
       expect(result.current.sortStates).toEqual([
         { field: "createdAt", direction: "Desc" },
       ]);
-      expect(result.current.toQueryArgs().variables.order).toEqual([
+      expect(result.current.variables.order).toEqual([
         { field: "createdAt", direction: "Desc" },
       ]);
     });
 
     it("applies initial filters", () => {
       const { result } = renderHook(() =>
-        useCollection({
-          query: FAKE_QUERY,
+        useCollectionVariables({
           params: {
             initialFilters: [
               {
@@ -59,7 +57,7 @@ describe("useCollection", () => {
         }),
       );
       expect(result.current.filters).toHaveLength(1);
-      expect(result.current.toQueryArgs().variables.query).toEqual({
+      expect(result.current.variables.query).toEqual({
         status: { eq: "ACTIVE" },
       });
     });
@@ -70,7 +68,7 @@ describe("useCollection", () => {
   // ---------------------------------------------------------------------------
   describe("filter operations", () => {
     it("adds a filter", () => {
-      const { result } = renderHook(() => useCollection({ query: FAKE_QUERY }));
+      const { result } = renderHook(() => useCollectionVariables({}));
 
       act(() => {
         result.current.addFilter("status", "eq", "ACTIVE");
@@ -82,13 +80,13 @@ describe("useCollection", () => {
         operator: "eq",
         value: "ACTIVE",
       });
-      expect(result.current.toQueryArgs().variables.query).toEqual({
+      expect(result.current.variables.query).toEqual({
         status: { eq: "ACTIVE" },
       });
     });
 
     it("replaces filter for same field", () => {
-      const { result } = renderHook(() => useCollection({ query: FAKE_QUERY }));
+      const { result } = renderHook(() => useCollectionVariables({}));
 
       act(() => {
         result.current.addFilter("status", "eq", "ACTIVE");
@@ -102,7 +100,7 @@ describe("useCollection", () => {
     });
 
     it("sets filters in bulk", () => {
-      const { result } = renderHook(() => useCollection({ query: FAKE_QUERY }));
+      const { result } = renderHook(() => useCollectionVariables({}));
 
       act(() => {
         result.current.setFilters([
@@ -120,14 +118,14 @@ describe("useCollection", () => {
       });
 
       expect(result.current.filters).toHaveLength(2);
-      expect(result.current.toQueryArgs().variables.query).toEqual({
+      expect(result.current.variables.query).toEqual({
         status: { eq: "ACTIVE" },
         amount: { gte: 1000 },
       });
     });
 
     it("removes a filter", () => {
-      const { result } = renderHook(() => useCollection({ query: FAKE_QUERY }));
+      const { result } = renderHook(() => useCollectionVariables({}));
 
       act(() => {
         result.current.addFilter("status", "eq", "ACTIVE");
@@ -142,7 +140,7 @@ describe("useCollection", () => {
     });
 
     it("clears all filters", () => {
-      const { result } = renderHook(() => useCollection({ query: FAKE_QUERY }));
+      const { result } = renderHook(() => useCollectionVariables({}));
 
       act(() => {
         result.current.addFilter("status", "eq", "ACTIVE");
@@ -153,11 +151,11 @@ describe("useCollection", () => {
       });
 
       expect(result.current.filters).toHaveLength(0);
-      expect(result.current.toQueryArgs().variables.query).toBeUndefined();
+      expect(result.current.variables.query).toBeUndefined();
     });
 
     it("resets pagination when filters change", () => {
-      const { result } = renderHook(() => useCollection({ query: FAKE_QUERY }));
+      const { result } = renderHook(() => useCollectionVariables({}));
 
       // Navigate to next page
       act(() => {
@@ -179,7 +177,7 @@ describe("useCollection", () => {
   // ---------------------------------------------------------------------------
   describe("sort operations", () => {
     it("sets sort", () => {
-      const { result } = renderHook(() => useCollection({ query: FAKE_QUERY }));
+      const { result } = renderHook(() => useCollectionVariables({}));
 
       act(() => {
         result.current.setSort("createdAt", "Desc");
@@ -188,13 +186,13 @@ describe("useCollection", () => {
       expect(result.current.sortStates).toEqual([
         { field: "createdAt", direction: "Desc" },
       ]);
-      expect(result.current.toQueryArgs().variables.order).toEqual([
+      expect(result.current.variables.order).toEqual([
         { field: "createdAt", direction: "Desc" },
       ]);
     });
 
     it("appends sort for different fields", () => {
-      const { result } = renderHook(() => useCollection({ query: FAKE_QUERY }));
+      const { result } = renderHook(() => useCollectionVariables({}));
 
       act(() => {
         result.current.setSort("createdAt", "Desc");
@@ -210,7 +208,7 @@ describe("useCollection", () => {
     });
 
     it("replaces direction for existing field", () => {
-      const { result } = renderHook(() => useCollection({ query: FAKE_QUERY }));
+      const { result } = renderHook(() => useCollectionVariables({}));
 
       act(() => {
         result.current.setSort("createdAt", "Desc");
@@ -229,7 +227,7 @@ describe("useCollection", () => {
     });
 
     it("removes sort when direction is undefined", () => {
-      const { result } = renderHook(() => useCollection({ query: FAKE_QUERY }));
+      const { result } = renderHook(() => useCollectionVariables({}));
 
       act(() => {
         result.current.setSort("createdAt", "Desc");
@@ -247,7 +245,7 @@ describe("useCollection", () => {
     });
 
     it("clears sort", () => {
-      const { result } = renderHook(() => useCollection({ query: FAKE_QUERY }));
+      const { result } = renderHook(() => useCollectionVariables({}));
 
       act(() => {
         result.current.setSort("createdAt", "Desc");
@@ -257,7 +255,7 @@ describe("useCollection", () => {
       });
 
       expect(result.current.sortStates).toEqual([]);
-      expect(result.current.toQueryArgs().variables.order).toBeUndefined();
+      expect(result.current.variables.order).toBeUndefined();
     });
   });
 
@@ -266,7 +264,7 @@ describe("useCollection", () => {
   // ---------------------------------------------------------------------------
   describe("pagination operations", () => {
     it("navigates to next page (forward)", () => {
-      const { result } = renderHook(() => useCollection({ query: FAKE_QUERY }));
+      const { result } = renderHook(() => useCollectionVariables({}));
 
       act(() => {
         result.current.nextPage("cursor1");
@@ -274,14 +272,14 @@ describe("useCollection", () => {
 
       expect(result.current.cursor).toBe("cursor1");
       expect(result.current.paginationDirection).toBe("forward");
-      expect(result.current.toQueryArgs().variables.after).toBe("cursor1");
-      expect(result.current.toQueryArgs().variables.first).toBe(20);
-      expect(result.current.toQueryArgs().variables.last).toBeUndefined();
-      expect(result.current.toQueryArgs().variables.before).toBeUndefined();
+      expect(result.current.variables.pagination.after).toBe("cursor1");
+      expect(result.current.variables.pagination.first).toBe(20);
+      expect(result.current.variables.pagination.last).toBeUndefined();
+      expect(result.current.variables.pagination.before).toBeUndefined();
     });
 
     it("navigates to previous page (backward)", () => {
-      const { result } = renderHook(() => useCollection({ query: FAKE_QUERY }));
+      const { result } = renderHook(() => useCollectionVariables({}));
 
       act(() => {
         result.current.prevPage("cursor1");
@@ -289,14 +287,14 @@ describe("useCollection", () => {
 
       expect(result.current.cursor).toBe("cursor1");
       expect(result.current.paginationDirection).toBe("backward");
-      expect(result.current.toQueryArgs().variables.before).toBe("cursor1");
-      expect(result.current.toQueryArgs().variables.last).toBe(20);
-      expect(result.current.toQueryArgs().variables.first).toBeUndefined();
-      expect(result.current.toQueryArgs().variables.after).toBeUndefined();
+      expect(result.current.variables.pagination.before).toBe("cursor1");
+      expect(result.current.variables.pagination.last).toBe(20);
+      expect(result.current.variables.pagination.first).toBeUndefined();
+      expect(result.current.variables.pagination.after).toBeUndefined();
     });
 
     it("switches direction on nextPage after prevPage", () => {
-      const { result } = renderHook(() => useCollection({ query: FAKE_QUERY }));
+      const { result } = renderHook(() => useCollectionVariables({}));
 
       act(() => {
         result.current.prevPage("cursorB");
@@ -307,12 +305,12 @@ describe("useCollection", () => {
         result.current.nextPage("cursorA");
       });
       expect(result.current.paginationDirection).toBe("forward");
-      expect(result.current.toQueryArgs().variables.after).toBe("cursorA");
-      expect(result.current.toQueryArgs().variables.first).toBe(20);
+      expect(result.current.variables.pagination.after).toBe("cursorA");
+      expect(result.current.variables.pagination.first).toBe(20);
     });
 
     it("resets page to forward direction", () => {
-      const { result } = renderHook(() => useCollection({ query: FAKE_QUERY }));
+      const { result } = renderHook(() => useCollectionVariables({}));
 
       act(() => {
         result.current.prevPage("cursor1");
@@ -326,7 +324,7 @@ describe("useCollection", () => {
     });
 
     it("tracks hasPrevPage from currentPage and hasNextPage from setPageInfo", () => {
-      const { result } = renderHook(() => useCollection({ query: FAKE_QUERY }));
+      const { result } = renderHook(() => useCollectionVariables({}));
 
       // Initially on page 1: no prev, no next
       expect(result.current.hasPrevPage).toBe(false);
@@ -354,13 +352,12 @@ describe("useCollection", () => {
   });
 
   // ---------------------------------------------------------------------------
-  // toQueryArgs
+  // variables
   // ---------------------------------------------------------------------------
-  describe("toQueryArgs", () => {
+  describe("variables", () => {
     it("generates complete variables with filters, sort, and cursor", () => {
       const { result } = renderHook(() =>
-        useCollection({
-          query: FAKE_QUERY,
+        useCollectionVariables({
           params: {
             pageSize: 10,
             initialFilters: [
@@ -379,39 +376,33 @@ describe("useCollection", () => {
         result.current.nextPage("abc123");
       });
 
-      expect(result.current.toQueryArgs()).toEqual({
-        query: FAKE_QUERY,
-        variables: {
+      expect(result.current.variables).toEqual({
+        query: { status: { eq: "ACTIVE" } },
+        order: [{ field: "createdAt", direction: "Desc" }],
+        pagination: {
           first: 10,
-          query: { status: { eq: "ACTIVE" } },
-          order: [{ field: "createdAt", direction: "Desc" }],
           after: "abc123",
         },
       });
     });
 
-    it("omits undefined fields from variables", () => {
-      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);
-      expect("last" in variables).toBe(false);
-      expect("before" in variables).toBe(false);
+    it("omits undefined fields from pagination", () => {
+      const { result } = renderHook(() => useCollectionVariables({}));
+      const { pagination } = result.current.variables;
+      expect(pagination).toEqual({ first: 20 });
+      expect("after" in pagination).toBe(false);
+      expect("last" in pagination).toBe(false);
+      expect("before" in pagination).toBe(false);
     });
 
-    it("includes query in toQueryArgs result", () => {
-      const fakeQuery = { kind: "Document" } as const;
+    it("returns undefined for query and order when empty", () => {
       const { result } = renderHook(() =>
-        useCollection({ query: fakeQuery, params: { pageSize: 10 } }),
+        useCollectionVariables({ params: { pageSize: 10 } }),
       );
 
-      const args = result.current.toQueryArgs();
-      expect(args).toEqual({
-        query: fakeQuery,
-        variables: { first: 10 },
-      });
+      expect(result.current.variables.query).toBeUndefined();
+      expect(result.current.variables.order).toBeUndefined();
+      expect(result.current.variables.pagination).toEqual({ first: 10 });
     });
   });
 
@@ -441,20 +432,18 @@ describe("useCollection", () => {
 
     it("works with tableMetadata", () => {
       const { result } = renderHook(() =>
-        useCollection({
+        useCollectionVariables({
           tableMetadata: testMetadata.task,
-          query: FAKE_QUERY,
           params: { pageSize: 10 },
         }),
       );
-      expect(result.current.toQueryArgs().variables).toEqual({ first: 10 });
+      expect(result.current.variables.pagination).toEqual({ first: 10 });
     });
 
     it("applies typed initialSort", () => {
       const { result } = renderHook(() =>
-        useCollection({
+        useCollectionVariables({
           tableMetadata: testMetadata.task,
-          query: FAKE_QUERY,
           params: {
             initialSort: [{ field: "dueDate", direction: "Desc" }],
           },