@izumisy-tailor/tailor-data-viewer 0.2.0 → 0.2.2

package/src/component/types.ts

@@ -130,6 +130,25 @@ export interface CollectionResult<T> {
   pageInfo: PageInfo;
 }
 
+/**
+ * Extract the node type from a cursor connection result.
+ *
+ * Handles nullable wrappers commonly produced by GraphQL code generators
+ * (e.g. gql-tada `ResultOf`).
+ *
+ * @example
+ * ```ts
+ * // With gql-tada
+ * type OrdersData = ResultOf<typeof GET_ORDERS>;
+ * type Order = NodeType<OrdersData["orders"]>;
+ *
+ * const { field, display } = createColumnHelper<Order>();
+ * ```
+ */
+export type NodeType<
+  T extends { edges: { node: unknown }[] } | null | undefined,
+> = NonNullable<T>["edges"][number]["node"];
+
 // =============================================================================
 // Cell Renderer
 // =============================================================================
@@ -240,20 +259,33 @@ export type ColumnDefinition<TRow extends Record<string, unknown>> =
 
 /**
  * Options for `useCollectionParams` hook.
+ *
+ * @typeParam TFieldName - Union of allowed field name strings (default: `string`).
  */
-export interface UseCollectionParamsOptions {
+export interface UseCollectionParamsOptions<
+  TFieldName extends string = string,
+> {
   /** Initial filters to apply */
   initialFilters?: Filter[];
   /** Initial sort states */
-  initialSort?: SortState[];
+  initialSort?: { field: TFieldName; direction: "Asc" | "Desc" }[];
   /** Number of items per page (default: 20) */
   pageSize?: number;
 }
 
 /**
  * Return type of `useCollectionParams` hook.
- */
-export interface UseCollectionParamsReturn {
+ *
+ * Methods that accept a field name are typed with `TFieldName` so that
+ * auto-completion works when a concrete union is supplied.
+ *
+ * **Note:** Methods use *method syntax* (not property syntax) intentionally
+ * so that `UseCollectionParamsReturn<"a" | "b">` remains assignable to
+ * `UseCollectionParamsReturn<string>` (bivariant method check).
+ *
+ * @typeParam TFieldName - Union of allowed field name strings (default: `string`).
+ */
+export interface UseCollectionParamsReturn<TFieldName extends string = string> {
   /** Query variables in Tailor Platform format */
   variables: QueryVariables;
 
@@ -261,25 +293,25 @@ export interface UseCollectionParamsReturn {
   /** Current active filters */
   filters: Filter[];
   /** Add or update a filter for a field */
-  addFilter: (field: string, value: unknown, operator?: FilterOperator) => void;
+  addFilter(field: TFieldName, value: unknown, operator?: FilterOperator): void;
   /** Replace all filters at once */
-  setFilters: (filters: Filter[]) => void;
+  setFilters(filters: Filter[]): void;
   /** Remove filter for a specific field */
-  removeFilter: (field: string) => void;
+  removeFilter(field: TFieldName): void;
   /** Clear all filters */
-  clearFilters: () => void;
+  clearFilters(): void;
 
   // Sort operations
   /** Current sort states (supports multi-sort) */
   sortStates: SortState[];
   /** Set sort for a field. If `append` is true, adds to existing sorts. */
-  setSort: (
-    field: string,
+  setSort(
+    field: TFieldName,
     direction?: "Asc" | "Desc",
     append?: boolean,
-  ) => void;
+  ): void;
   /** Clear all sort states */
-  clearSort: () => void;
+  clearSort(): void;
 
   // Pagination operations
   /** Number of items per page */
@@ -287,11 +319,11 @@ export interface UseCollectionParamsReturn {
   /** Current cursor position */
   cursor: string | null;
   /** Navigate to next page */
-  nextPage: (endCursor: string) => void;
+  nextPage(endCursor: string): void;
   /** Navigate to previous page */
-  prevPage: () => void;
+  prevPage(): void;
   /** Reset to first page */
-  resetPage: () => void;
+  resetPage(): void;
   /** Whether there is a previous page */
   hasPrevPage: boolean;
 }