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

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@izumisy-tailor/tailor-data-viewer",
   "private": false,
-  "version": "0.2.3",
+  "version": "0.2.5",
   "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,8 @@ import type {
   SortState,
   UseCollectionParamsOptions,
   UseCollectionParamsReturn,
+  ExtractOrderField,
+  MatchingTableName,
 } from "../types";
 import { fieldTypeToFilterConfig } from "../types";
 import type { FieldName } from "../types";
@@ -62,6 +64,41 @@ 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 });
+ * ```
+ */
+export function useCollectionParams<TVariables>(
+  options?: UseCollectionParamsOptions<ExtractOrderField<TVariables>> & {
+    metadata?: TableMetadataMap;
+    tableName?: TableMetadataMap extends never
+      ? string
+      : MatchingTableName<TableMetadataMap, ExtractOrderField<TVariables>>;
+  },
+): UseCollectionParamsReturn<ExtractOrderField<TVariables>, TVariables>;
+
 // -----------------------------------------------------------------------------
 // Implementation
 // -----------------------------------------------------------------------------

package/src/component/index.ts

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

package/src/component/types.ts

@@ -110,10 +110,16 @@ export interface PageInfo {
 
 /**
  * GraphQL query variables in Tailor Platform format.
+ *
+ * @typeParam TFieldName - Union of allowed field name strings (default: `string`).
+ *                         When metadata is provided to `useCollectionParams`, this
+ *                         narrows `order[].field` to match the table's field names,
+ *                         making the output directly compatible with gql-tada's
+ *                         `VariablesOf<>` types.
  */
-export interface QueryVariables {
+export interface QueryVariables<TFieldName extends string = string> {
   query?: Record<string, unknown>;
-  order?: { field: string; direction: "Asc" | "Desc" }[];
+  order?: { field: TFieldName; direction: "Asc" | "Desc" }[];
   first: number;
   after?: string | null;
 }
@@ -284,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;
+  variables: TVariables;
 
   // Filter operations
   /** Current active filters */
@@ -345,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>;
 }
 
 /**
@@ -474,6 +486,47 @@ 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;
+
+/**
+ * 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.
  */