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

package/package.json

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

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

@@ -44,7 +44,6 @@ describe("useCollectionParams", () => {
           initialFilters: [
             {
               field: "status",
-              fieldType: "enum",
               operator: "eq",
               value: "ACTIVE",
             },
@@ -101,13 +100,11 @@ describe("useCollectionParams", () => {
         result.current.setFilters([
           {
             field: "status",
-            fieldType: "enum",
             operator: "eq",
             value: "ACTIVE",
           },
           {
             field: "amount",
-            fieldType: "number",
             operator: "gte",
             value: 1000,
           },
@@ -308,7 +305,6 @@ describe("useCollectionParams", () => {
           initialFilters: [
             {
               field: "status",
-              fieldType: "enum",
               operator: "eq",
               value: "ACTIVE",
             },
@@ -374,81 +370,6 @@ describe("useCollectionParams", () => {
       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({
-          metadata: testMetadata,
-          tableName: "task",
-        }),
-      );
-
-      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");
-    });
-
     it("applies typed initialSort", () => {
       const { result } = renderHook(() =>
         useCollectionParams({

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

@@ -1,19 +1,15 @@
-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,
-  ExtractOrderField,
-  MatchingTableName,
+  ExtractQueryVariables,
 } from "../types";
-import { fieldTypeToFilterConfig } from "../types";
 import type { FieldName } from "../types";
 
 // -----------------------------------------------------------------------------
@@ -24,29 +20,49 @@ 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>> & {
+  options: UseCollectionParamsOptions<
+    FieldName<TMetadata, TTableName>,
+    MetadataFilter<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
@@ -112,15 +106,8 @@ export function useCollectionParams(
     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,
-  );
-
   // ---------------------------------------------------------------------------
   // State
   // ---------------------------------------------------------------------------
@@ -137,17 +124,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,
         };

package/src/component/index.ts

@@ -5,6 +5,7 @@ export type {
   SelectOption,
   FilterOperator,
   Filter,
+  MetadataFilter,
   SortState,
   PageInfo,
   QueryVariables,
@@ -28,6 +29,7 @@ export type {
   DataTableCellProps,
   FieldName,
   ExtractOrderField,
+  ExtractQueryVariables,
   MatchingTableName,
   MetadataFieldOptions,
   MetadataFieldsOptions,

package/src/component/search-filter-form.tsx

@@ -116,7 +116,9 @@ export function SearchFilterForm<TRow extends Record<string, unknown>>({
   // Reset operator when field changes
   useEffect(() => {
     if (selectedFilterConfig) {
-      const ops = OPERATORS_BY_FILTER_TYPE[selectedFilterConfig.type];
+      const ops = OPERATORS_BY_FILTER_TYPE[
+        selectedFilterConfig.type
+      ] as readonly FilterOperator[];
       if (ops.length > 0 && !ops.includes(selectedOperator)) {
         setSelectedOperator(ops[0]);
       }

package/src/component/types.ts

@@ -39,39 +39,60 @@ export type FilterConfig =
   | { type: "uuid" };
 
 // =============================================================================
-// Filter Operators
+// Filter Operators (Single Source of Truth)
 // =============================================================================
 
-/**
- * Available filter operators (Tailor Platform compliant).
- */
-export type FilterOperator =
-  | "eq"
-  | "ne"
-  | "contains"
-  | "startsWith"
-  | "endsWith"
-  | "gt"
-  | "gte"
-  | "lt"
-  | "lte"
-  | "between"
-  | "in"
-  | "notIn";
-
 /**
  * Operators available per filter type (Tailor Platform schema).
+ *
+ * This `as const satisfies` definition is the **single source of truth**.
+ * Both the `FilterOperator` union and the `OperatorForFilterType` mapping
+ * are derived from it, eliminating duplication.
  */
-export const OPERATORS_BY_FILTER_TYPE: Record<
-  FilterConfig["type"],
-  FilterOperator[]
-> = {
+export const OPERATORS_BY_FILTER_TYPE = {
   string: ["eq", "ne", "contains", "startsWith", "endsWith"],
   number: ["eq", "ne", "gt", "gte", "lt", "lte", "between"],
   date: ["eq", "ne", "gt", "gte", "lt", "lte", "between"],
   enum: ["eq", "ne", "in", "notIn"],
   boolean: ["eq", "ne"],
   uuid: ["eq", "ne", "in", "notIn"],
+} as const satisfies Record<FilterConfig["type"], readonly string[]>;
+
+/**
+ * Maps each filter type to the union of operators it supports.
+ * Derived from `OPERATORS_BY_FILTER_TYPE`.
+ */
+export type OperatorForFilterType = {
+  [T in FilterConfig["type"]]: (typeof OPERATORS_BY_FILTER_TYPE)[T][number];
+};
+
+/**
+ * Union of all available filter operators.
+ * Derived from `OPERATORS_BY_FILTER_TYPE`.
+ */
+export type FilterOperator = OperatorForFilterType[FilterConfig["type"]];
+
+// =============================================================================
+// Filter Type → FieldType Mapping (type-level)
+// =============================================================================
+
+/**
+ * Type-level mapping from `FieldType` (metadata) to `FilterConfig["type"]`.
+ * Mirrors the runtime `fieldTypeToFilterConfig` function.
+ * Types that don't support filtering map to `never`.
+ */
+export type FieldTypeToFilterConfigType = {
+  string: "string";
+  number: "number";
+  boolean: "boolean";
+  uuid: "uuid";
+  datetime: "date";
+  date: "date";
+  time: "date";
+  enum: "enum";
+  array: never;
+  nested: never;
+  file: never;
 };
 
 // =============================================================================
@@ -80,14 +101,53 @@ export const OPERATORS_BY_FILTER_TYPE: Record<
 
 /**
  * Active filter state.
+ *
+ * @typeParam TFieldName - Union of allowed field name strings (default: `string`).
  */
-export interface Filter {
-  field: string;
-  fieldType: FilterConfig["type"];
+export interface Filter<TFieldName extends string = string> {
+  field: TFieldName;
   operator: FilterOperator;
   value: unknown;
 }
 
+/**
+ * Metadata-aware filter type.
+ *
+ * Given table metadata, produces a discriminated union over each field
+ * where the `operator` is narrowed to only those valid for that field's type.
+ * Fields whose `FieldType` doesn't support filtering (array, nested, file) are excluded.
+ *
+ * @typeParam TMetadata - The `tableMetadata` object type (as const).
+ * @typeParam TTableName - The table name key in `TMetadata`.
+ *
+ * @example
+ * ```ts
+ * // If table "task" has fields: name (string), priority (number), status (enum)
+ * type F = MetadataFilter<typeof tableMetadata, "task">;
+ * //   | { field: "name"; operator: "eq" | "ne" | "contains" | ...; value: unknown }
+ * //   | { field: "priority"; operator: "eq" | "ne" | "gt" | ...; value: unknown }
+ * //   | { field: "status"; operator: "eq" | "ne" | "in" | "notIn"; value: unknown }
+ * ```
+ */
+export type MetadataFilter<
+  TMetadata extends TableMetadataMap,
+  TTableName extends string & keyof TMetadata,
+> = TMetadata[TTableName]["fields"][number] extends infer F
+  ? F extends { readonly name: infer N; readonly type: infer T }
+    ? N extends string
+      ? T extends keyof FieldTypeToFilterConfigType
+        ? FieldTypeToFilterConfigType[T] extends never
+          ? never
+          : {
+              field: N;
+              operator: OperatorForFilterType[FieldTypeToFilterConfigType[T]];
+              value: unknown;
+            }
+        : never
+      : never
+    : never
+  : never;
+
 /**
  * Active sort state for a single field.
  */
@@ -270,9 +330,10 @@ export type ColumnDefinition<TRow extends Record<string, unknown>> =
  */
 export interface UseCollectionParamsOptions<
   TFieldName extends string = string,
+  TFilter extends Filter<TFieldName> = Filter<TFieldName>,
 > {
   /** Initial filters to apply */
-  initialFilters?: Filter[];
+  initialFilters?: TFilter[];
   /** Initial sort states */
   initialSort?: { field: TFieldName; direction: "Asc" | "Desc" }[];
   /** Number of items per page (default: 20) */
@@ -506,6 +567,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`.
  *