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

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,40 +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",
-              fieldType: "enum",
-              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" },
       });
     });
@@ -63,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");
@@ -75,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");
@@ -95,19 +102,17 @@ describe("useCollectionParams", () => {
     });
 
     it("sets filters in bulk", () => {
-      const { result } = renderHook(() => useCollectionParams());
+      const { result } = renderHook(() => useCollection({ query: FAKE_QUERY }));
 
       act(() => {
         result.current.setFilters([
           {
             field: "status",
-            fieldType: "enum",
             operator: "eq",
             value: "ACTIVE",
           },
           {
             field: "amount",
-            fieldType: "number",
             operator: "gte",
             value: 1000,
           },
@@ -115,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");
@@ -137,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");
@@ -148,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(() => {
@@ -174,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");
@@ -183,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");
@@ -204,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");
@@ -220,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");
@@ -230,7 +235,7 @@ describe("useCollectionParams", () => {
       });
 
       expect(result.current.sortStates).toEqual([]);
-      expect(result.current.variables.order).toBeUndefined();
+      expect(result.current.toQueryArgs().variables.order).toBeUndefined();
     });
   });
 
@@ -239,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");
@@ -247,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");
@@ -268,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");
@@ -282,7 +287,7 @@ describe("useCollectionParams", () => {
     });
 
     it("resets page", () => {
-      const { result } = renderHook(() => useCollectionParams());
+      const { result } = renderHook(() => useCollection({ query: FAKE_QUERY }));
 
       act(() => {
         result.current.nextPage("cursor1");
@@ -298,22 +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",
-              fieldType: "enum",
-              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" }],
+          },
         }),
       );
 
@@ -321,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 },
+      });
     });
   });
 
@@ -365,96 +388,25 @@ describe("useCollectionParams", () => {
 
     it("works with metadata and tableName", () => {
       const { result } = renderHook(() =>
-        useCollectionParams({
-          metadata: testMetadata,
-          tableName: "task",
-          pageSize: 10,
-        }),
-      );
-      expect(result.current.variables).toEqual({ first: 10 });
-    });
-
-    it("auto-detects fieldType from metadata for string field", () => {
-      const { result } = renderHook(() =>
-        useCollectionParams({
-          metadata: testMetadata,
-          tableName: "task",
-        }),
-      );
-
-      act(() => {
-        result.current.addFilter("title", "foo");
-      });
-
-      expect(result.current.filters[0].fieldType).toBe("string");
-    });
-
-    it("auto-detects fieldType from metadata for enum field", () => {
-      const { result } = renderHook(() =>
-        useCollectionParams({
-          metadata: testMetadata,
-          tableName: "task",
-        }),
-      );
-
-      act(() => {
-        result.current.addFilter("status", "todo");
-      });
-
-      expect(result.current.filters[0].fieldType).toBe("enum");
-    });
-
-    it("auto-detects fieldType from metadata for date field", () => {
-      const { result } = renderHook(() =>
-        useCollectionParams({
+        useCollection({
           metadata: testMetadata,
           tableName: "task",
+          query: FAKE_QUERY,
+          params: { pageSize: 10 },
         }),
       );
-
-      act(() => {
-        result.current.addFilter("dueDate", "2026-01-01");
-      });
-
-      expect(result.current.filters[0].fieldType).toBe("date");
-    });
-
-    it("auto-detects fieldType from metadata for uuid field", () => {
-      const { result } = renderHook(() =>
-        useCollectionParams({
-          metadata: testMetadata,
-          tableName: "task",
-        }),
-      );
-
-      act(() => {
-        result.current.addFilter("id", "some-uuid");
-      });
-
-      expect(result.current.filters[0].fieldType).toBe("uuid");
-    });
-
-    it("auto-detects fieldType from metadata for number field", () => {
-      const { result } = renderHook(() =>
-        useCollectionParams({
-          metadata: testMetadata,
-          tableName: "task",
-        }),
-      );
-
-      act(() => {
-        result.current.addFilter("count", 42);
-      });
-
-      expect(result.current.filters[0].fieldType).toBe("number");
+      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}

@@ -1,20 +1,27 @@
-import { useCallback, useMemo, useRef, useState } from "react";
-import type {
-  FieldType,
-  TableMetadataMap,
-} from "../../generator/metadata-generator";
+import { useCallback, useMemo, useState } from "react";
+import type { TableMetadataMap } from "../../generator/metadata-generator";
 import type {
   Filter,
   FilterOperator,
+  MetadataFilter,
   QueryVariables,
   SortState,
-  UseCollectionParamsOptions,
-  UseCollectionParamsReturn,
+  UseCollectionOptions,
+  UseCollectionReturn,
   ExtractQueryVariables,
 } from "../types";
-import { fieldTypeToFilterConfig } 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
 // -----------------------------------------------------------------------------
@@ -23,97 +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<FieldName<TMetadata, TTableName>> & {
+  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,
-    metadata,
-    tableName,
-  } = options;
-
-  // Keep a ref to the resolved fields list so callbacks can look up fieldType.
-  const fieldsRef = useRef(
-    metadata && tableName ? metadata[tableName]?.fields : undefined,
-  );
+  } = params;
 
   // ---------------------------------------------------------------------------
   // State
@@ -131,17 +132,8 @@ export function useCollectionParams(
     (field: string, value: unknown, operator: FilterOperator = "eq") => {
       setFiltersState((prev) => {
         const existing = prev.findIndex((f) => f.field === field);
-        // Auto-detect fieldType from metadata when available
-        const fieldMeta = fieldsRef.current?.find((f) => f.name === field);
-        const detectedType: Filter["fieldType"] = fieldMeta
-          ? (fieldTypeToFilterConfig(
-              fieldMeta.type as FieldType,
-              fieldMeta.enumValues as readonly string[] | undefined,
-            )?.type ?? "string")
-          : "string";
         const newFilter: Filter = {
           field,
-          fieldType: detectedType,
           operator,
           value,
         };
@@ -245,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)
@@ -268,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 />