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

package/package.json

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

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

@@ -10,8 +10,7 @@ import type {
   SortState,
   UseCollectionParamsOptions,
   UseCollectionParamsReturn,
-  ExtractOrderField,
-  MatchingTableName,
+  ExtractQueryVariables,
 } from "../types";
 import { fieldTypeToFilterConfig } from "../types";
 import type { FieldName } from "../types";
@@ -24,29 +23,46 @@ 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.
+ *
  * @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,
  * });
  *
- * params.addFilter("title", "foo");        // ✅ field name auto-completed
- * params.addFilter("nonExistent", "foo");  // ❌ type error
+ * // With query — variables typed as VariablesOf<typeof GET_TASKS>
+ * const params = useCollectionParams({
+ *   metadata: tableMetadata,
+ *   tableName: "task",
+ *   query: GET_TASKS,
+ *   pageSize: 20,
+ * });
  * ```
  */
 export function useCollectionParams<
   const TMetadata extends TableMetadataMap,
   TTableName extends string & keyof TMetadata,
+  TQuery = never,
 >(
   options: UseCollectionParamsOptions<FieldName<TMetadata, TTableName>> & {
     metadata: TMetadata;
     tableName: TTableName;
+    query?: TQuery;
   },
-): UseCollectionParamsReturn<FieldName<TMetadata, TTableName>>;
+): UseCollectionParamsReturn<
+  FieldName<TMetadata, TTableName>,
+  [TQuery] extends [never]
+    ? QueryVariables<FieldName<TMetadata, TTableName>>
+    : ExtractQueryVariables<TQuery>
+>;
 
 /**
  * Hook for managing collection query parameters (filters, sort, pagination).
@@ -54,50 +70,28 @@ export function useCollectionParams<
  * Produces `variables` in Tailor Platform format that can be passed directly
  * to a GraphQL query (e.g. urql's `useQuery`).
  *
+ * When `query` is provided, the output `variables` is typed to match
+ * the GraphQL query's expected variables.
+ *
  * @example
  * ```tsx
  * const params = useCollectionParams({ pageSize: 20 });
  * const [result] = useQuery({ query: GET_ORDERS, variables: params.variables });
- * ```
- */
-export function useCollectionParams(
-  options?: UseCollectionParamsOptions,
-): UseCollectionParamsReturn;
-
-/**
- * Hook for managing collection query parameters (filters, sort, pagination)
- * with an explicit `TVariables` type for the output `variables`.
- *
- * The `order[].field` union is extracted from `TVariables` and used as
- * `TFieldName` for `addFilter`, `setSort`, `initialSort`, etc.
- * When `metadata` is provided, `tableName` is constrained to tables
- * whose fields are a superset of the extracted field names.
- *
- * @typeParam TVariables - The exact type for the output `variables` property.
- *                         Typically `VariablesOf<typeof YOUR_QUERY>` from gql-tada.
- *
- * @example
- * ```tsx
- * import type { VariablesOf } from "gql.tada";
  *
- * const params = useCollectionParams<VariablesOf<typeof GET_ORDERS>>({
- *   metadata: tableMetadata,
- *   tableName: "order",   // ← constrained to tables matching order[].field
- *   pageSize: 20,
- * });
- *
- * params.addFilter("status", "ACTIVE");  // ← field name auto-completed
- * const [result] = useQuery({ query: GET_ORDERS, variables: params.variables });
+ * // With query — variables auto-typed
+ * const params = useCollectionParams({ query: GET_ORDERS, pageSize: 20 });
  * ```
  */
-export function useCollectionParams<TVariables>(
-  options?: UseCollectionParamsOptions<ExtractOrderField<TVariables>> & {
-    metadata?: TableMetadataMap;
-    tableName?: TableMetadataMap extends never
-      ? string
-      : MatchingTableName<TableMetadataMap, ExtractOrderField<TVariables>>;
+export function useCollectionParams<TQuery = never>(
+  options?: UseCollectionParamsOptions & {
+    query?: TQuery;
+    metadata?: never;
+    tableName?: never;
   },
-): UseCollectionParamsReturn<ExtractOrderField<TVariables>, TVariables>;
+): UseCollectionParamsReturn<
+  string,
+  [TQuery] extends [never] ? QueryVariables : ExtractQueryVariables<TQuery>
+>;
 
 // -----------------------------------------------------------------------------
 // Implementation

package/src/component/index.ts

@@ -28,6 +28,7 @@ export type {
   DataTableCellProps,
   FieldName,
   ExtractOrderField,
+  ExtractQueryVariables,
   MatchingTableName,
   MetadataFieldOptions,
   MetadataFieldsOptions,

package/src/component/types.ts

@@ -506,6 +506,25 @@ export type ExtractOrderField<T> = T extends {
     : string
   : string;
 
+/**
+ * Extract the variables type from a GraphQL query object.
+ *
+ * Works with `TypedDocumentNode` (used by gql-tada, graphql-codegen, etc.)
+ * which stores the variables type in the `__variablesType` brand property.
+ *
+ * @example
+ * ```ts
+ * const GET_ORDERS = graphql(`query Orders($first: Int, ...) { ... }`);
+ * type Vars = ExtractQueryVariables<typeof GET_ORDERS>;
+ * // → { first?: number | null; order?: OrderInput[] | null; ... }
+ * ```
+ */
+export type ExtractQueryVariables<T> = T extends {
+  __variablesType?: infer V;
+}
+  ? NonNullable<V>
+  : never;
+
 /**
  * Find table names in metadata whose fields are a superset of `TFieldName`.
  *