@izumisy-tailor/tailor-data-viewer 0.2.14 → 0.2.16

package/src/component/types.ts

@@ -1,6 +1,7 @@
 import type { ReactNode } from "react";
 import type {
   FieldType,
+  TableMetadata,
   TableMetadataMap,
 } from "../generator/metadata-generator";
 
@@ -144,24 +145,40 @@ export interface Filter<TFieldName extends string = string> {
  * //   | { field: "status"; operator: "eq" | "ne" | "in" | "notIn"; value: unknown }
  * ```
  */
+/**
+ * Metadata-aware filter type from a single table metadata object.
+ *
+ * Given table metadata, produces a discriminated union over each field
+ * where the `operator` is narrowed to only those valid for that field's type.
+ *
+ * @typeParam TTable - A single table metadata object (as const).
+ */
+export type TableMetadataFilter<TTable extends TableMetadata> =
+  TTable["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;
+
+/**
+ * Metadata-aware filter type.
+ *
+ * @deprecated Use `TableMetadataFilter<TMetadata[TTableName]>` instead.
+ */
 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;
+> = TableMetadataFilter<TMetadata[TTableName]>;
 
 /**
  * Active sort state for a single field.
@@ -177,6 +194,8 @@ export interface SortState {
 export interface PageInfo {
   hasNextPage: boolean;
   endCursor: string | null;
+  hasPreviousPage: boolean;
+  startCursor: string | null;
 }
 
 // =============================================================================
@@ -211,8 +230,14 @@ export interface QueryVariables {
    * performed by `ValidateCollectionQuery` (specifically `CheckOrderField`).
    */
   order?: { field: string; direction: "Asc" | "Desc" }[];
-  first: number;
+  /** Forward pagination: number of items to fetch */
+  first?: number | null;
+  /** Forward pagination: cursor to start after */
   after?: string | null;
+  /** Backward pagination: number of items to fetch from the end */
+  last?: number | null;
+  /** Backward pagination: cursor to fetch before */
+  before?: string | null;
 }
 
 // =============================================================================
@@ -438,14 +463,20 @@ export interface UseCollectionReturn<
   pageSize: number;
   /** Current cursor position */
   cursor: string | null;
-  /** Navigate to next page */
+  /** Current pagination direction */
+  paginationDirection: "forward" | "backward";
+  /** Navigate to next page using endCursor from pageInfo */
   nextPage(endCursor: string): void;
-  /** Navigate to previous page */
-  prevPage(): void;
+  /** Navigate to previous page using startCursor from pageInfo */
+  prevPage(startCursor: string): void;
   /** Reset to first page */
   resetPage(): void;
-  /** Whether there is a previous page */
+  /** Whether there is a previous page (from GraphQL pageInfo) */
   hasPrevPage: boolean;
+  /** Whether there is a next page (from GraphQL pageInfo) */
+  hasNextPage: boolean;
+  /** Set pageInfo from graphql result to track hasPrevPage/hasNextPage */
+  setPageInfo(pageInfo: PageInfo): void;
 }
 
 // =============================================================================
@@ -551,9 +582,11 @@ export interface UseDataTableReturn<TRow extends Record<string, unknown>> {
   /** Navigate to next page */
   nextPage: (endCursor: string) => void;
   /** Navigate to previous page */
-  prevPage: () => void;
+  prevPage: (startCursor: string) => void;
   /** Whether a previous page exists */
   hasPrevPage: boolean;
+  /** Whether a next page exists */
+  hasNextPage: boolean;
 
   // Column management
   /** All column definitions */
@@ -583,16 +616,30 @@ export interface UseDataTableReturn<TRow extends Record<string, unknown>> {
 // =============================================================================
 
 /**
- * Extract field names from table metadata.
+ * Extract field names from a single table metadata object.
+ *
+ * @example
+ * ```ts
+ * type Names = TableFieldName<typeof tableMetadata.task>;
+ * // → "id" | "title" | "status" | "dueDate" | ...
+ * ```
+ */
+export type TableFieldName<TTable extends TableMetadata> =
+  TTable["fields"][number] extends { readonly name: infer N }
+    ? N extends string
+      ? N
+      : never
+    : never;
+
+/**
+ * Extract field names from table metadata map + table name.
+ *
+ * @deprecated Use `TableFieldName<TMetadata[TTableName]>` instead.
  */
 export type FieldName<
   TMetadata extends TableMetadataMap,
   TTableName extends keyof TMetadata,
-> = TMetadata[TTableName]["fields"][number] extends { readonly name: infer N }
-  ? N extends string
-    ? N
-    : never
-  : never;
+> = TableFieldName<TMetadata[TTableName]>;
 
 /**
  * Field types that support ordering.
@@ -609,19 +656,16 @@ type OrderableFieldType =
   | "enum";
 
 /**
- * Extract only orderable field names from table metadata.
+ * Extract only orderable field names from a single table metadata object.
  *
  * Fields whose `type` is not in `OrderableFieldType` (e.g. `uuid`, `array`,
  * `nested`, `file`) are excluded.  This allows `CheckOrderField` to compare
  * only the fields that Tailor Platform actually exposes in the
  * `OrderFieldEnum`, avoiding false positives for fields like `id`.
  */
-export type OrderableFieldName<
-  TMetadata extends TableMetadataMap,
-  TTableName extends keyof TMetadata,
-> =
+export type TableOrderableFieldName<TTable extends TableMetadata> =
   Extract<
-    TMetadata[TTableName]["fields"][number],
+    TTable["fields"][number],
     { readonly type: OrderableFieldType }
   > extends { readonly name: infer N }
     ? N extends string
@@ -629,6 +673,16 @@ export type OrderableFieldName<
       : never
     : never;
 
+/**
+ * Extract only orderable field names from table metadata map + table name.
+ *
+ * @deprecated Use `TableOrderableFieldName<TMetadata[TTableName]>` instead.
+ */
+export type OrderableFieldName<
+  TMetadata extends TableMetadataMap,
+  TTableName extends keyof TMetadata,
+> = TableOrderableFieldName<TMetadata[TTableName]>;
+
 /**
  * Extract the `order[].field` union type from a GraphQL variables type.
  *
@@ -718,9 +772,58 @@ type CheckFirstVariable<TQuery> =
       };
 
 /**
- * Rule 2 — When both metadata and `$order` variable exist, metadata field
- * names must be assignable to the `field` enum inside the `OrderInput` type.
- * Skipped when `TFieldName` is the generic `string` (no metadata).
+ * 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,
@@ -734,9 +837,8 @@ type CheckOrderField<
   : Pass;
 
 /**
- * Rule 3 — When both metadata and `$query` variable exist, metadata field
- * names must be a subset of the `QueryInput` type's keys.
- * Skipped when `TFieldName` is the generic `string` (no metadata).
+ * Rule 8 — When metadata is provided, metadata field names must be a
+ * subset of the `QueryInput` type's keys.
  */
 type CheckQueryInput<
   TQuery,
@@ -757,8 +859,13 @@ type CheckQueryInput<
  * intersecting independent rule types:
  *
  * 1. **`CheckFirstVariable`** — `$first` must exist.
- * 2. **`CheckOrderField`** — OrderInput field compatibility (metadata-aware).
- * 3. **`CheckQueryInput`** — QueryInput key compatibility (metadata-aware).
+ * 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`
@@ -778,9 +885,20 @@ export type ValidateCollectionQuery<
   ExtractQueryVariables<TQuery> extends never
     ? TQuery // No gql-tada type info → skip validation
     : string extends TFieldName
-      ? TQuery & CheckFirstVariable<TQuery> // No metadata → only check $first
+      ? 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>;
 
@@ -791,6 +909,11 @@ export type ValidateCollectionQuery<
  */
 export type HasCollectionQueryError<T> = T extends
   | { __firstVariableError: string }
+  | { __afterVariableError: string }
+  | { __lastVariableError: string }
+  | { __beforeVariableError: string }
+  | { __queryVariableError: string }
+  | { __orderVariableError: string }
   | { __orderFieldError: string }
   | { __queryInputError: string }
   ? true
@@ -982,9 +1105,11 @@ export interface PaginationProps {
   /** Navigate to next page */
   nextPage: (endCursor: string) => void;
   /** Navigate to previous page */
-  prevPage: () => void;
+  prevPage: (startCursor: string) => void;
   /** Whether a previous page exists */
   hasPrevPage: boolean;
+  /** Whether a next page exists */
+  hasNextPage: boolean;
 }
 
 // =============================================================================