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

package/package.json

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

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

@@ -1,9 +1,10 @@
 import { createContext, useContext, type ReactNode } from "react";
 import type { UseCollectionParamsReturn } from "../types";
 
-const CollectionParamsContext = createContext<UseCollectionParamsReturn | null>(
-  null,
-);
+const CollectionParamsContext = createContext<UseCollectionParamsReturn<
+  string,
+  unknown
+> | null>(null);
 
 /**
  * Provider that shares collection query parameters via React Context.
@@ -23,7 +24,7 @@ export function CollectionParamsProvider({
   value,
   children,
 }: {
-  value: UseCollectionParamsReturn;
+  value: UseCollectionParamsReturn<string, unknown>;
   children: ReactNode;
 }) {
   return (

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

@@ -10,6 +10,7 @@ import type {
   SortState,
   UseCollectionParamsOptions,
   UseCollectionParamsReturn,
+  ExtractQueryVariables,
 } from "../types";
 import { fieldTypeToFilterConfig } from "../types";
 import type { FieldName } from "../types";
@@ -22,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).
@@ -52,15 +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 });
+ *
+ * // With query — variables auto-typed
+ * const params = useCollectionParams({ query: GET_ORDERS, pageSize: 20 });
  * ```
  */
-export function useCollectionParams(
-  options?: UseCollectionParamsOptions,
-): UseCollectionParamsReturn;
+export function useCollectionParams<TQuery = never>(
+  options?: UseCollectionParamsOptions & {
+    query?: TQuery;
+    metadata?: never;
+    tableName?: never;
+  },
+): UseCollectionParamsReturn<
+  string,
+  [TQuery] extends [never] ? QueryVariables : ExtractQueryVariables<TQuery>
+>;
 
 // -----------------------------------------------------------------------------
 // Implementation

package/src/component/index.ts

@@ -27,6 +27,9 @@ export type {
   DataTableRowProps,
   DataTableCellProps,
   FieldName,
+  ExtractOrderField,
+  ExtractQueryVariables,
+  MatchingTableName,
   MetadataFieldOptions,
   MetadataFieldsOptions,
   ColumnSelectorProps,

package/src/component/types.ts

@@ -290,10 +290,16 @@ export interface UseCollectionParamsOptions<
  * `UseCollectionParamsReturn<string>` (bivariant method check).
  *
  * @typeParam TFieldName - Union of allowed field name strings (default: `string`).
+ * @typeParam TVariables - Type of the `variables` output (default: `QueryVariables<TFieldName>`).
+ *                         Pass `VariablesOf<typeof YOUR_QUERY>` (gql-tada) to get
+ *                         exact type compatibility with your GraphQL client.
  */
-export interface UseCollectionParamsReturn<TFieldName extends string = string> {
+export interface UseCollectionParamsReturn<
+  TFieldName extends string = string,
+  TVariables = QueryVariables<TFieldName>,
+> {
   /** Query variables in Tailor Platform format */
-  variables: QueryVariables<TFieldName>;
+  variables: TVariables;
 
   // Filter operations
   /** Current active filters */
@@ -351,7 +357,7 @@ export interface UseDataTableOptions<TRow extends Record<string, unknown>> {
   /** Error */
   error?: Error | null;
   /** Collection params for sort integration */
-  collectionParams?: UseCollectionParamsReturn;
+  collectionParams?: UseCollectionParamsReturn<string, unknown>;
 }
 
 /**
@@ -480,6 +486,66 @@ export type FieldName<
     : never
   : never;
 
+/**
+ * Extract the `order[].field` union type from a GraphQL variables type.
+ *
+ * For gql-tada's `VariablesOf<typeof QUERY>`, this extracts the allowed
+ * field names from the `order` parameter.
+ *
+ * @example
+ * ```ts
+ * type Fields = ExtractOrderField<VariablesOf<typeof GET_ORDERS>>;
+ * // → "name" | "amount" | "status" | "createdAt"
+ * ```
+ */
+export type ExtractOrderField<T> = T extends {
+  order?: readonly (infer O | null | undefined)[] | null | undefined;
+}
+  ? O extends { field?: infer F | null }
+    ? NonNullable<F> & string
+    : 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`.
+ *
+ * Used to constrain `tableName` so that it matches the `order[].field`
+ * union extracted from `VariablesOf<>`.
+ *
+ * @example
+ * ```ts
+ * type T = MatchingTableName<typeof tableMetadata, "name" | "email">;
+ * // → "buyerContact"  (if buyerContact's fields include name and email)
+ * ```
+ */
+export type MatchingTableName<
+  TMetadata extends TableMetadataMap,
+  TFieldName extends string,
+> = {
+  [K in string & keyof TMetadata]: TFieldName extends FieldName<TMetadata, K>
+    ? K
+    : never;
+}[string & keyof TMetadata];
+
 /**
  * Options for metadata-based single field definition.
  */