@izumisy-tailor/tailor-data-viewer 0.2.33 → 0.3.0

package/src/component/types.ts

@@ -53,12 +53,23 @@ export type FilterConfig =
  * are derived from it, eliminating duplication.
  */
 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"],
+  string: [
+    "eq",
+    "ne",
+    "contains",
+    "notContains",
+    "hasPrefix",
+    "hasSuffix",
+    "notHasPrefix",
+    "notHasSuffix",
+    "in",
+    "nin",
+  ],
+  number: ["eq", "ne", "gt", "gte", "lt", "lte", "between", "in", "nin"],
+  date: ["eq", "ne", "gt", "gte", "lt", "lte", "between", "in", "nin"],
+  enum: ["eq", "ne", "in", "nin"],
   boolean: ["eq", "ne"],
-  uuid: ["eq", "ne", "in", "notIn"],
+  uuid: ["eq", "ne", "in", "nin"],
 } as const satisfies Record<FilterConfig["type"], readonly string[]>;
 
 /**
@@ -144,7 +155,7 @@ export interface Filter<TFieldName extends string = string> {
  * 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 }
+ * //   | { field: "status"; operator: "eq" | "ne" | "in" | "nin"; value: unknown }
  * ```
  */
 /**
@@ -208,29 +219,13 @@ export interface PageInfo {
  * GraphQL query variables in Tailor Platform format.
  *
  * Field-level type safety for `query` and `order` is not enforced here.
- * Instead, `ValidateCollectionQuery` performs compile-time checks
- * (e.g. `CheckQueryInput` for filter field names, `CheckOrderField`
- * for orderable fields) when `useCollection` is called with metadata.
+ * When `useCollectionVariables` is called with metadata, `BuildQueryVariables`
+ * produces precise per-field filter types at compile time.
  */
 export interface QueryVariables {
-  /**
-   * Filter object built at runtime by `useCollection`.
-   *
-   * Typed as `Record<string, unknown>` because the concrete shape depends on
-   * which filters the user applies at runtime (e.g. `{ name: { eq: "foo" } }`).
-   *
-   * Compile-time safety for field names is enforced separately by
-   * `ValidateCollectionQuery` (specifically `CheckQueryInput`), which verifies
-   * that metadata field names are a subset of the GraphQL `QueryInput` type's keys.
-   */
+  /** Filter object built at runtime by `useCollectionVariables`. */
   query?: Record<string, unknown>;
-  /**
-   * Sort order built at runtime by `useCollection`.
-   *
-   * `field` is typed as `string` here. Compile-time validation that
-   * field names are assignable to the GraphQL `OrderInput` enum is
-   * performed by `ValidateCollectionQuery` (specifically `CheckOrderField`).
-   */
+  /** Sort order built at runtime by `useCollectionVariables`. */
   order?: { field: string; direction: "Asc" | "Desc" }[];
   /** Forward pagination: number of items to fetch */
   first?: number | null;
@@ -242,6 +237,111 @@ export interface QueryVariables {
   before?: string | null;
 }
 
+// =============================================================================
+// Collection Variables (split into explicit sub-properties)
+// =============================================================================
+
+/**
+ * Pagination variables for cursor-based pagination (Tailor Platform format).
+ */
+export interface PaginationVariables {
+  /** Forward pagination: number of items to fetch */
+  first?: number;
+  /** Forward pagination: cursor to start after */
+  after?: string | null;
+  /** Backward pagination: number of items to fetch from the end */
+  last?: number;
+  /** Backward pagination: cursor to fetch before */
+  before?: string | null;
+}
+
+// ---------------------------------------------------------------------------
+// Metadata-aware filter variable types
+// ---------------------------------------------------------------------------
+
+/**
+ * Maps `FieldType` (from metadata) to the TypeScript value type
+ * used in filter variable construction.
+ */
+type FieldTypeToTSType = {
+  string: string;
+  number: number;
+  boolean: boolean;
+  uuid: string;
+  datetime: string;
+  date: string;
+  time: string;
+  enum: string;
+};
+
+/**
+ * Resolves the value type for a filter operator.
+ * `in`/`nin` operators accept arrays, `between` accepts `{ min, max }`,
+ * all other operators accept a scalar value.
+ */
+type OperatorValueType<TOp extends string, TValue> = TOp extends "in" | "nin"
+  ? TValue[]
+  : TOp extends "between"
+    ? { min: TValue; max: TValue }
+    : TValue;
+
+/**
+ * Builds a filter input type for a specific filter config type and value type.
+ * Each operator key is optional, with the appropriate value type.
+ */
+type FilterInputForFieldType<
+  TFilterConfigType extends FilterConfig["type"],
+  TValue,
+> = {
+  [Op in OperatorForFilterType[TFilterConfigType]]?: OperatorValueType<
+    Op,
+    TValue
+  >;
+};
+
+/**
+ * Builds a Tailor Platform QueryInput-compatible type from table metadata.
+ *
+ * Each filterable field becomes an optional key with its filter input type.
+ * Non-filterable fields (array, nested, file) are excluded.
+ *
+ * The resulting type is structurally assignable to the corresponding
+ * GraphQL QueryInput type generated by gql-tada.
+ */
+export type BuildQueryVariables<TTable extends TableMetadata> = {
+  [F in TTable["fields"][number] as F extends {
+    readonly name: infer N extends string;
+    readonly type: infer T;
+  }
+    ? T extends keyof FieldTypeToFilterConfigType
+      ? FieldTypeToFilterConfigType[T] extends never
+        ? never
+        : N
+      : never
+    : never]?: F extends {
+    readonly type: infer T extends keyof FieldTypeToFilterConfigType &
+      keyof FieldTypeToTSType;
+  }
+    ? FieldTypeToFilterConfigType[T] extends infer FCT extends
+        FilterConfig["type"]
+      ? FilterInputForFieldType<FCT, FieldTypeToTSType[T]>
+      : never
+    : never;
+};
+
+/**
+ * Collection variables split into explicit sub-properties.
+ * Each sub-property maps to a specific part of the GraphQL query variables.
+ */
+export interface CollectionVariables {
+  /** Filter variables (Tailor Platform QueryInput format) */
+  query: Record<string, Record<string, unknown>> | undefined;
+  /** Sort order variables (Tailor Platform OrderInput format) */
+  order: { field: string; direction: "Asc" | "Desc" }[] | undefined;
+  /** Cursor-based pagination variables */
+  pagination: PaginationVariables;
+}
+
 // =============================================================================
 // Collection Result (Tailor Platform standard)
 // =============================================================================
@@ -325,11 +425,11 @@ export type ColumnDefinition<TRow extends Record<string, unknown>> =
   Column<TRow>;
 
 // =============================================================================
-// useCollection Types
+// useCollectionVariables Types
 // =============================================================================
 
 /**
- * Options for `useCollection` hook.
+ * Options for `useCollectionVariables` hook.
  *
  * @typeParam TFieldName - Union of allowed field name strings (default: `string`).
  */
@@ -349,7 +449,7 @@ export interface UseCollectionOptions<
 }
 
 /**
- * Return type of `useCollection` hook.
+ * Return type of `useCollectionVariables` hook.
  *
  * Methods that accept a field name are typed with `TFieldName` so that
  * auto-completion works when a concrete union is supplied.
@@ -361,25 +461,27 @@ export interface UseCollectionOptions<
  * can be safely destructured without triggering `unbound-method` lint rules.
  *
  * @typeParam TFieldName - Union of allowed field name strings (default: `string`).
- * @typeParam TQueryArgs - Type returned by `toQueryArgs()`. Contains both
- *                         `query` and `variables`.
+ * @typeParam TVariables - Type of `variables` property.
  */
 export interface UseCollectionReturn<
   TFieldName extends string = string,
-  TQueryArgs = { query: unknown; variables: QueryVariables },
+  TVariables = CollectionVariables,
   TFilter = Filter<TFieldName>,
 > {
   /**
-   * Returns query arguments (`{ query, variables }`) that can be spread
-   * directly into `useQuery()`.
+   * Collection variables split into explicit sub-properties
+   * for direct mapping to GraphQL query variables.
    *
    * @example
    * ```tsx
-   * const collection = useCollection({ query: GET_ORDERS, params: { pageSize: 20 } });
-   * const [result] = useQuery({ ...collection.toQueryArgs() });
+   * const { query, order, pagination } = collection.variables;
+   * const [result] = useQuery({
+   *   query: GET_TASKS,
+   *   variables: { ...pagination, query, order },
+   * });
    * ```
    */
-  toQueryArgs: () => TQueryArgs;
+  variables: TVariables;
 
   // Filter operations
   /** Current active filters */
@@ -647,242 +749,6 @@ export type OrderableFieldName<
   TTableName extends keyof TMetadata,
 > = TableOrderableFieldName<TMetadata[TTableName]>;
 
-/**
- * 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 gql.tada `DocumentDecoration`.
- *
- * gql.tada stores variables via `__apiType?: (variables: V) => R`.
- *
- * @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 {
-  __apiType?: (variables: infer V) => unknown;
-}
-  ? NonNullable<V>
-  : never;
-
-// =============================================================================
-// Collection Query Validation (compile-time safety)
-// =============================================================================
-
-/**
- * Extract the key names of the `query` (filter) input type from GraphQL variables.
- *
- * For gql-tada's `VariablesOf<typeof QUERY>`, this extracts the allowed
- * field names from the `query` (QueryInput) parameter.
- *
- * @example
- * ```ts
- * // query: BuyerContactQueryInput has keys: name, email, phone, ...
- * type Keys = ExtractQueryInputKeys<typeof GET_BUYER_CONTACTS>;
- * // → "name" | "email" | "phone" | ...
- * ```
- */
-export type ExtractQueryInputKeys<T> =
-  ExtractQueryVariables<T> extends {
-    query?: infer Q | null;
-  }
-    ? keyof NonNullable<Q> & string
-    : string;
-
-// ---------------------------------------------------------------------------
-// Individual collection query validation rules
-// ---------------------------------------------------------------------------
-// Each rule resolves to `Pass` when the check passes (or is not applicable),
-// or `{ __xxxError: "…" }` when it fails.  The rules are independent, so
-// adding a new one is just defining a new `Check*` type and appending it to
-// the intersection inside `ValidateCollectionQuery`.
-// ---------------------------------------------------------------------------
-
-/**
- * Identity type for intersection: `T & Pass` ≡ `T`.
- * Used as the "pass" branch of each validation rule.
- */
-// eslint-disable-next-line @typescript-eslint/no-empty-object-type
-type Pass = {};
-
-/**
- * Rule 1 — The query must declare `$first` as a variable.
- */
-type CheckFirstVariable<TQuery> =
-  "first" extends keyof ExtractQueryVariables<TQuery>
-    ? Pass
-    : {
-        __firstVariableError: `Query must declare a $first variable (e.g. $first: Int).`;
-      };
-
-/**
- * Rule 2 — The query must declare `$after` as a variable.
- */
-type CheckAfterVariable<TQuery> =
-  "after" extends keyof ExtractQueryVariables<TQuery>
-    ? Pass
-    : {
-        __afterVariableError: `Query must declare an $after variable (e.g. $after: String).`;
-      };
-
-/**
- * Rule 3 — The query must declare `$last` as a variable.
- */
-type CheckLastVariable<TQuery> =
-  "last" extends keyof ExtractQueryVariables<TQuery>
-    ? Pass
-    : {
-        __lastVariableError: `Query must declare a $last variable (e.g. $last: Int).`;
-      };
-
-/**
- * Rule 4 — The query must declare `$before` as a variable.
- */
-type CheckBeforeVariable<TQuery> =
-  "before" extends keyof ExtractQueryVariables<TQuery>
-    ? Pass
-    : {
-        __beforeVariableError: `Query must declare a $before variable (e.g. $before: String).`;
-      };
-
-/**
- * Rule 5 — The query must declare `$query` as a variable.
- */
-type CheckQueryVariable<TQuery> =
-  "query" extends keyof ExtractQueryVariables<TQuery>
-    ? Pass
-    : {
-        __queryVariableError: `Query must declare a $query variable (e.g. $query: XxxQueryInput!).`;
-      };
-
-/**
- * Rule 6 — The query must declare `$order` as a variable.
- */
-type CheckOrderVariable<TQuery> =
-  "order" extends keyof ExtractQueryVariables<TQuery>
-    ? Pass
-    : {
-        __orderVariableError: `Query must declare an $order variable (e.g. $order: [XxxOrderInput]).`;
-      };
-
-/**
- * Rule 7 — When metadata is provided, metadata field names must be
- * assignable to the `field` enum inside the `OrderInput` type.
- */
-type CheckOrderField<
-  TQuery,
-  TFieldName extends string,
-> = "order" extends keyof ExtractQueryVariables<TQuery>
-  ? [TFieldName] extends [ExtractOrderField<ExtractQueryVariables<TQuery>>]
-    ? Pass
-    : {
-        __orderFieldError: `Some metadata field names are not assignable to OrderInput field enum. Check that the order variable's field type includes all metadata fields.`;
-      }
-  : Pass;
-
-/**
- * Rule 8 — When metadata is provided, metadata field names must be a
- * subset of the `QueryInput` type's keys.
- */
-type CheckQueryInput<
-  TQuery,
-  TFieldName extends string,
-> = "query" extends keyof ExtractQueryVariables<TQuery>
-  ? [Exclude<TFieldName, ExtractQueryInputKeys<TQuery>>] extends [never]
-    ? Pass
-    : {
-        __queryInputError: `Some metadata field names are not present in QueryInput keys. Missing: ${Exclude<TFieldName, ExtractQueryInputKeys<TQuery>> & string}`;
-      }
-  : Pass;
-
-/**
- * Validate that a query document is compatible with `useCollection`.
- *
- * When gql-tada type information is available (i.e. `ExtractQueryVariables`
- * does not resolve to `never`), this type performs compile-time checks by
- * intersecting independent rule types:
- *
- * 1. **`CheckFirstVariable`** — `$first` must exist.
- * 2. **`CheckAfterVariable`** — `$after` must exist.
- * 3. **`CheckLastVariable`** — `$last` must exist.
- * 4. **`CheckBeforeVariable`** — `$before` must exist.
- * 5. **`CheckQueryVariable`** — `$query` must exist.
- * 6. **`CheckOrderVariable`** — `$order` must exist.
- * 7. **`CheckOrderField`** — OrderInput field compatibility (metadata-aware).
- * 8. **`CheckQueryInput`** — QueryInput key compatibility (metadata-aware).
- *
- * Each rule resolves to `{}` on pass or `{ __xxxError: "…" }` on fail.
- * A failing rule adds a phantom error property that makes `TQuery`
- * incompatible with the actual value, producing a compile error.
- *
- * When gql-tada is not used (plain `DocumentNode`), all checks are skipped.
- *
- * @typeParam TQuery - The query document type (e.g. `typeof GET_ORDERS`).
- * @typeParam TFieldName - Union of metadata field names (default: `string`,
- *                         which disables metadata-aware checks).
- */
-export type ValidateCollectionQuery<
-  TQuery,
-  TFieldName extends string = string,
-  TOrderableFieldName extends string = TFieldName,
-> =
-  ExtractQueryVariables<TQuery> extends never
-    ? TQuery // No gql-tada type info → skip validation
-    : string extends TFieldName
-      ? TQuery &
-          CheckFirstVariable<TQuery> &
-          CheckAfterVariable<TQuery> &
-          CheckLastVariable<TQuery> &
-          CheckBeforeVariable<TQuery> &
-          CheckQueryVariable<TQuery> &
-          CheckOrderVariable<TQuery>
-      : TQuery &
-          CheckFirstVariable<TQuery> &
-          CheckAfterVariable<TQuery> &
-          CheckLastVariable<TQuery> &
-          CheckBeforeVariable<TQuery> &
-          CheckQueryVariable<TQuery> &
-          CheckOrderVariable<TQuery> &
-          CheckOrderField<TQuery, TOrderableFieldName> &
-          CheckQueryInput<TQuery, TFieldName>;
-
-/**
- * Helper to check whether a `ValidateCollectionQuery` result contains any
- * validation error.  Use this in type-level assertions instead of checking
- * individual error keys.
- */
-export type HasCollectionQueryError<T> = T extends
-  | { __firstVariableError: string }
-  | { __afterVariableError: string }
-  | { __lastVariableError: string }
-  | { __beforeVariableError: string }
-  | { __queryVariableError: string }
-  | { __orderVariableError: string }
-  | { __orderFieldError: string }
-  | { __queryInputError: string }
-  ? true
-  : false;
-
 /**
  * Find table names in metadata whose fields are a superset of `TFieldName`.
  *
@@ -977,15 +843,18 @@ export const DEFAULT_OPERATOR_LABELS: Record<FilterOperator, string> = {
   eq: "=",
   ne: "≠",
   contains: "contains",
-  startsWith: "starts with",
-  endsWith: "ends with",
+  notContains: "not contains",
+  hasPrefix: "starts with",
+  hasSuffix: "ends with",
+  notHasPrefix: "not starts with",
+  notHasSuffix: "not ends with",
   gt: ">",
   gte: "≥",
   lt: "<",
   lte: "≤",
   between: "between",
   in: "in",
-  notIn: "not in",
+  nin: "not in",
 };
 
 /**

package/src/tests/helpers.tsx

@@ -3,7 +3,7 @@ import { vi } from "vitest";
 import type { Column, UseCollectionReturn } from "../component/types";
 import { DataTableContext } from "../component/data-table/data-table-context";
 import type { DataTableContextValue } from "../component/data-table/data-table-context";
-import { CollectionProvider } from "../component/collection/collection-provider";
+import { CollectionVariablesProvider } from "../component/collection/collection-provider";
 
 // =============================================================================
 // Mock factory: DataTableContext
@@ -43,14 +43,18 @@ export function createMockDataTableContext<T extends Record<string, unknown>>(
 }
 
 // =============================================================================
-// Mock factory: CollectionContext
+// Mock factory: CollectionVariablesContext
 // =============================================================================
 
 export function createMockCollectionContext(
   overrides?: Partial<UseCollectionReturn<string, unknown>>,
 ): UseCollectionReturn<string, unknown> {
   return {
-    toQueryArgs: vi.fn(() => ({ query: null, variables: {} })),
+    variables: {
+      query: undefined,
+      order: undefined,
+      pagination: { first: 20 },
+    },
     filters: [],
     addFilter: vi.fn(),
     setFilters: vi.fn(),
@@ -118,7 +122,7 @@ export function createTestProviders<
     collection?: Partial<UseCollectionReturn<string, unknown>>;
   }) {
     return (
-      <CollectionProvider
+      <CollectionVariablesProvider
         value={createMockCollectionContext({
           ...defaults.collectionDefaults,
           ...collection,
@@ -132,7 +136,7 @@ export function createTestProviders<
         >
           {children}
         </DataTableContext.Provider>
-      </CollectionProvider>
+      </CollectionVariablesProvider>
     );
   };
 }