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

package/README.md

@@ -11,7 +11,7 @@ A low-level React component library for building data table interfaces with Tail
 - **`DataTable.*` Compound Components**: Data-bound table with sort indicators, cell renderers, and `useDataTable` integration
 - **`useDataTable` Hook**: Integrates data, column visibility, row operations (optimistic updates), and props generators
 - **Column Definition Helpers**: `field()` for data columns with sort/filter, `display()` for render-only columns
-- **Metadata-based Inference**: `inferColumns()` auto-derives sort/filter config from generated table metadata
+- **Metadata-based Inference**: `inferColumnHelper()` auto-derives sort/filter config from generated table metadata
 - **Utility Components**: `ColumnSelector`, `CsvButton`, `SearchFilterForm`, `Pagination` — all props-based, spreadable from hooks
 - **Multi-sort Support**: Multiple simultaneous sort fields
 - **Optimistic Updates**: `updateRow`, `deleteRow`, `insertRow` with rollback
@@ -186,7 +186,7 @@ display("actions", {
 
 ### Table Metadata Generator
 
-This library includes a metadata generator for [Tailor Platform SDK](https://www.npmjs.com/package/@tailor-platform/sdk) that produces type-safe table metadata with `as const` assertions. The generated metadata is used by `inferColumns()` for automatic sort/filter configuration.
+This library includes a metadata generator for [Tailor Platform SDK](https://www.npmjs.com/package/@tailor-platform/sdk) that produces type-safe table metadata with `as const` assertions. The generated metadata is used by `inferColumnHelper()` for automatic sort/filter configuration.
 
 1. Configure the generator in your `tailor.config.ts`:
 
@@ -212,15 +212,15 @@ export default defineConfig({
 tailor-sdk generate
 ```
 
-### `inferColumns(metadata, tableName)`
+### `inferColumnHelper(metadata, tableName)`
 
-`field()` requires manually specifying `sort`/`filter` type configs and enum `options` for every column. `inferColumns()` eliminates this boilerplate by automatically deriving these from the generated table metadata. Based on each field's type (string, number, date, enum, etc.), the appropriate `SortConfig` / `FilterConfig` is set automatically, and enum fields get their options populated from the schema.
+`field()` requires manually specifying `sort`/`filter` type configs and enum `options` for every column. `inferColumnHelper()` eliminates this boilerplate by automatically deriving these from the generated table metadata. Based on each field's type (string, number, date, enum, etc.), the appropriate `SortConfig` / `FilterConfig` is set automatically, and enum fields get their options populated from the schema.
 
 ```tsx
-import { inferColumns, display } from "@izumisy-tailor/tailor-data-viewer/component";
+import { inferColumnHelper, display } from "@izumisy-tailor/tailor-data-viewer/component";
 import { tableMetadata } from "./generated/data-viewer-metadata.generated";
 
-const { column, columns } = inferColumns(tableMetadata, "task");
+const { column, columns } = inferColumnHelper(tableMetadata, "task");
 
 const taskColumns = [
   column("title"),                     // sort/filter auto-configured from metadata
@@ -234,7 +234,7 @@ const taskColumns = [
 ];
 ```
 
-`inferColumns()` can be freely mixed with manual `field()` / `display()` definitions. Use `field()` for fields not in the metadata or those requiring custom configuration, and `inferColumns()` for everything else.
+`inferColumnHelper()` can be freely mixed with manual `field()` / `display()` definitions. Use `field()` for fields not in the metadata or those requiring custom configuration, and `inferColumnHelper()` for everything else.
 
 ### `useDataTable(options)`
 

package/package.json

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

package/src/component/collection-params/collection-params-provider.tsx

@@ -36,7 +36,10 @@ export function CollectionParamsProvider({
 /**
  * Hook to access collection params from the nearest `CollectionParams.Provider`.
  *
- * Returns the same interface as `useCollectionParams()`.
+ * Returns the same interface as `useCollectionParams()`.  Pass a `TFieldName`
+ * type parameter to narrow method arguments like `addFilter` / `setSort`.
+ *
+ * @typeParam TFieldName - Union of allowed field name strings (default: `string`).
  *
  * @throws Error if used outside of `CollectionParams.Provider`.
  *
@@ -46,16 +49,22 @@ export function CollectionParamsProvider({
  *   const { filters, addFilter, removeFilter } = useCollectionParamsContext();
  *   // ...
  * }
+ *
+ * // With typed field names:
+ * type TaskField = FieldName<typeof tableMetadata, "task">;
+ * const { addFilter } = useCollectionParamsContext<TaskField>();
  * ```
  */
-export function useCollectionParamsContext(): UseCollectionParamsReturn {
+export function useCollectionParamsContext<
+  TFieldName extends string = string,
+>(): UseCollectionParamsReturn<TFieldName> {
   const ctx = useContext(CollectionParamsContext);
   if (!ctx) {
     throw new Error(
       "useCollectionParamsContext must be used within <CollectionParams.Provider>",
     );
   }
-  return ctx;
+  return ctx as UseCollectionParamsReturn<TFieldName>;
 }
 
 /**

package/src/component/{use-collection-params.test.ts → collection-params/use-collection-params.test.ts}

@@ -1,6 +1,7 @@
 import { renderHook, act } from "@testing-library/react";
 import { describe, it, expect } from "vitest";
-import { useCollectionParams } from "./collection-params/use-collection-params";
+import type { TableMetadataMap } from "../../generator/metadata-generator";
+import { useCollectionParams } from "./use-collection-params";
 
 describe("useCollectionParams", () => {
   // ---------------------------------------------------------------------------
@@ -337,4 +338,129 @@ describe("useCollectionParams", () => {
       expect("after" in vars).toBe(false);
     });
   });
+
+  // ---------------------------------------------------------------------------
+  // Metadata-typed overload
+  // ---------------------------------------------------------------------------
+  describe("metadata-typed overload", () => {
+    const testMetadata = {
+      task: {
+        name: "task",
+        pluralForm: "tasks",
+        readAllowedRoles: [],
+        fields: [
+          { name: "id", type: "uuid", required: true },
+          { name: "title", type: "string", required: true },
+          {
+            name: "status",
+            type: "enum",
+            required: true,
+            enumValues: ["todo", "in_progress", "done"],
+          },
+          { name: "dueDate", type: "date", required: false },
+          { name: "count", type: "number", required: false },
+        ],
+      },
+    } as const satisfies TableMetadataMap;
+
+    it("works with metadata and tableName", () => {
+      const { result } = renderHook(() =>
+        useCollectionParams({
+          metadata: testMetadata,
+          tableName: "task",
+          pageSize: 10,
+        }),
+      );
+      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({
+          metadata: testMetadata,
+          tableName: "task",
+          initialSort: [{ field: "dueDate", direction: "Desc" }],
+        }),
+      );
+
+      expect(result.current.sortStates).toEqual([
+        { field: "dueDate", direction: "Desc" },
+      ]);
+    });
+  });
 });

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

@@ -1,4 +1,8 @@
-import { useCallback, useMemo, useState } from "react";
+import { useCallback, useMemo, useRef, useState } from "react";
+import type {
+  FieldType,
+  TableMetadataMap,
+} from "../../generator/metadata-generator";
 import type {
   Filter,
   FilterOperator,
@@ -7,6 +11,40 @@ import type {
   UseCollectionParamsOptions,
   UseCollectionParamsReturn,
 } from "../types";
+import { fieldTypeToFilterConfig } from "../types";
+import type { FieldName } from "../types";
+
+// -----------------------------------------------------------------------------
+// Overload signatures
+// -----------------------------------------------------------------------------
+
+/**
+ * Hook for managing collection query parameters (filters, sort, pagination)
+ * with metadata-based field name typing and automatic `fieldType` detection.
+ *
+ * @example
+ * ```tsx
+ * import { tableMetadata } from "./generated/data-viewer-metadata.generated";
+ *
+ * const params = useCollectionParams({
+ *   metadata: tableMetadata,
+ *   tableName: "task",
+ *   pageSize: 20,
+ * });
+ *
+ * params.addFilter("title", "foo");        // ✅ field name auto-completed
+ * params.addFilter("nonExistent", "foo");  // ❌ type error
+ * ```
+ */
+export function useCollectionParams<
+  const TMetadata extends TableMetadataMap,
+  TTableName extends string & keyof TMetadata,
+>(
+  options: UseCollectionParamsOptions<FieldName<TMetadata, TTableName>> & {
+    metadata: TMetadata;
+    tableName: TTableName;
+  },
+): UseCollectionParamsReturn<FieldName<TMetadata, TTableName>>;
 
 /**
  * Hook for managing collection query parameters (filters, sort, pagination).
@@ -16,19 +54,36 @@ import type {
  *
  * @example
  * ```tsx
- * const params = useCollectionParams<Order>({ pageSize: 20 });
+ * const params = useCollectionParams({ pageSize: 20 });
  * const [result] = useQuery({ query: GET_ORDERS, variables: params.variables });
  * ```
  */
 export function useCollectionParams(
-  options: UseCollectionParamsOptions = {},
+  options?: UseCollectionParamsOptions,
+): UseCollectionParamsReturn;
+
+// -----------------------------------------------------------------------------
+// Implementation
+// -----------------------------------------------------------------------------
+export function useCollectionParams(
+  options: UseCollectionParamsOptions & {
+    metadata?: TableMetadataMap;
+    tableName?: string;
+  } = {},
 ): UseCollectionParamsReturn {
   const {
     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
   // ---------------------------------------------------------------------------
@@ -45,9 +100,17 @@ 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: "string", // default, can be overridden by setFilters
+          fieldType: detectedType,
           operator,
           value,
         };

package/src/component/{use-data-table.test.ts → data-table/use-data-table.test.ts}

@@ -1,7 +1,7 @@
 import { renderHook, act } from "@testing-library/react";
 import { describe, it, expect } from "vitest";
-import { useDataTable } from "./data-table/use-data-table";
-import type { Column, CollectionResult } from "./types";
+import { useDataTable } from "./use-data-table";
+import type { Column, CollectionResult } from "../types";
 
 type TestRow = {
   id: string;

package/src/component/field-helpers.test.ts

@@ -1,43 +1,76 @@
-import { describe, it, expect } from "vitest";
-import { field, display, inferColumns } from "./field-helpers";
+import { describe, it, expect, expectTypeOf } from "vitest";
+import { createColumnHelper, inferColumnHelper } from "./field-helpers";
 import type { TableMetadataMap } from "../generator/metadata-generator";
 import { fieldTypeToSortConfig, fieldTypeToFilterConfig } from "./types";
+import type { NodeType } from "./types";
 
-describe("field()", () => {
-  it("creates a field column with minimal options", () => {
-    const col = field<{ name: string }>("name");
-    expect(col.kind).toBe("field");
-    expect(col.dataKey).toBe("name");
-    expect(col.label).toBeUndefined();
-    expect(col.sort).toBeUndefined();
-    expect(col.filter).toBeUndefined();
+describe("NodeType", () => {
+  it("extracts node type from a collection result", () => {
+    type Result = { edges: { node: { id: string; name: string } }[] };
+    type Row = NodeType<Result>;
+    expectTypeOf<Row>().toEqualTypeOf<{ id: string; name: string }>();
+  });
+
+  it("handles nullable collection (e.g. gql-tada ResultOf)", () => {
+    type Result =
+      | { edges: { node: { id: string; amount: number } }[] }
+      | null
+      | undefined;
+    type Row = NodeType<Result>;
+    expectTypeOf<Row>().toEqualTypeOf<{ id: string; amount: number }>();
+  });
+
+  it("works with createColumnHelper", () => {
+    type Result = { edges: { node: { id: string; title: string } }[] } | null;
+    type Row = NodeType<Result>;
+    const { field } = createColumnHelper<Row>();
+    const col = field("title");
+    expect(col.dataKey).toBe("title");
+  });
+});
+
+describe("createColumnHelper()", () => {
+  type TestRow = { name: string; age: number };
+
+  it("returns field and display helpers with TRow bound", () => {
+    const helpers = createColumnHelper<TestRow>();
+    expect(typeof helpers.field).toBe("function");
+    expect(typeof helpers.display).toBe("function");
   });
 
-  it("creates a field column with full options", () => {
-    const col = field<{ name: string }>("name", {
+  it("field helper creates a field column without explicit type param", () => {
+    const { field } = createColumnHelper<TestRow>();
+    const col = field("name", {
       label: "Name",
-      width: 200,
       sort: { type: "string" },
       filter: { type: "string" },
     });
+    expect(col.kind).toBe("field");
+    expect(col.dataKey).toBe("name");
     expect(col.label).toBe("Name");
-    expect(col.width).toBe(200);
     expect(col.sort).toEqual({ type: "string" });
     expect(col.filter).toEqual({ type: "string" });
   });
-});
 
-describe("display()", () => {
-  it("creates a display column", () => {
-    const col = display<{ id: string }>("actions", {
+  it("field helper creates minimal column", () => {
+    const { field } = createColumnHelper<TestRow>();
+    const col = field("age");
+    expect(col.kind).toBe("field");
+    expect(col.dataKey).toBe("age");
+    expect(col.label).toBeUndefined();
+  });
+
+  it("display helper creates a display column without explicit type param", () => {
+    const { display } = createColumnHelper<TestRow>();
+    const col = display("actions", {
       label: "Actions",
-      width: 50,
-      render: () => null,
+      width: 100,
+      render: (row) => `${row.name}: ${row.age}`,
     });
     expect(col.kind).toBe("display");
     expect(col.id).toBe("actions");
     expect(col.label).toBe("Actions");
-    expect(col.width).toBe(50);
+    expect(col.width).toBe(100);
     expect(typeof col.render).toBe("function");
   });
 });
@@ -105,7 +138,7 @@ describe("fieldTypeToFilterConfig", () => {
   });
 });
 
-describe("inferColumns()", () => {
+describe("inferColumnHelper()", () => {
   const testMetadata = {
     task: {
       name: "task",
@@ -134,7 +167,10 @@ describe("inferColumns()", () => {
   } as const satisfies TableMetadataMap;
 
   it("creates a column with auto-detected sort/filter", () => {
-    const { column } = inferColumns(testMetadata, "task");
+    const { column } = inferColumnHelper({
+      metadata: testMetadata,
+      tableName: "task",
+    });
 
     const titleCol = column("title");
     expect(titleCol.kind).toBe("field");
@@ -144,7 +180,10 @@ describe("inferColumns()", () => {
   });
 
   it("auto-detects enum options", () => {
-    const { column } = inferColumns(testMetadata, "task");
+    const { column } = inferColumnHelper({
+      metadata: testMetadata,
+      tableName: "task",
+    });
     const statusCol = column("status");
     expect(statusCol.filter).toEqual({
       type: "enum",
@@ -159,42 +198,60 @@ describe("inferColumns()", () => {
   });
 
   it("auto-detects date type", () => {
-    const { column } = inferColumns(testMetadata, "task");
+    const { column } = inferColumnHelper({
+      metadata: testMetadata,
+      tableName: "task",
+    });
     const dateCol = column("dueDate");
     expect(dateCol.sort).toEqual({ type: "date" });
     expect(dateCol.filter).toEqual({ type: "date" });
   });
 
   it("disables sort with sort: false", () => {
-    const { column } = inferColumns(testMetadata, "task");
+    const { column } = inferColumnHelper({
+      metadata: testMetadata,
+      tableName: "task",
+    });
     const col = column("title", { sort: false });
     expect(col.sort).toBeUndefined();
     expect(col.filter).toEqual({ type: "string" });
   });
 
   it("disables filter with filter: false", () => {
-    const { column } = inferColumns(testMetadata, "task");
+    const { column } = inferColumnHelper({
+      metadata: testMetadata,
+      tableName: "task",
+    });
     const col = column("title", { filter: false });
     expect(col.sort).toEqual({ type: "string" });
     expect(col.filter).toBeUndefined();
   });
 
   it("uuid has no sort, has uuid filter", () => {
-    const { column } = inferColumns(testMetadata, "task");
+    const { column } = inferColumnHelper({
+      metadata: testMetadata,
+      tableName: "task",
+    });
     const col = column("id");
     expect(col.sort).toBeUndefined();
     expect(col.filter).toEqual({ type: "uuid" });
   });
 
   it("array type has no sort/filter", () => {
-    const { column } = inferColumns(testMetadata, "task");
+    const { column } = inferColumnHelper({
+      metadata: testMetadata,
+      tableName: "task",
+    });
     const col = column("tags");
     expect(col.sort).toBeUndefined();
     expect(col.filter).toBeUndefined();
   });
 
   it("columns() creates multiple columns at once", () => {
-    const { columns } = inferColumns(testMetadata, "task");
+    const { columns } = inferColumnHelper({
+      metadata: testMetadata,
+      tableName: "task",
+    });
     const cols = columns(["title", "status", "dueDate"]);
     expect(cols).toHaveLength(3);
     expect(cols[0].dataKey).toBe("title");
@@ -203,7 +260,10 @@ describe("inferColumns()", () => {
   });
 
   it("columns() applies overrides", () => {
-    const { columns } = inferColumns(testMetadata, "task");
+    const { columns } = inferColumnHelper({
+      metadata: testMetadata,
+      tableName: "task",
+    });
     const cols = columns(["title", "status"], {
       overrides: {
         title: { label: "Custom Title", width: 300 },
@@ -214,7 +274,10 @@ describe("inferColumns()", () => {
   });
 
   it("columns() applies global sort/filter options", () => {
-    const { columns } = inferColumns(testMetadata, "task");
+    const { columns } = inferColumnHelper({
+      metadata: testMetadata,
+      tableName: "task",
+    });
     const cols = columns(["title", "status"], { sort: false });
     expect(cols[0].sort).toBeUndefined();
     expect(cols[1].sort).toBeUndefined();
@@ -223,7 +286,10 @@ describe("inferColumns()", () => {
   });
 
   it("throws for non-existent field", () => {
-    const { column } = inferColumns(testMetadata, "task");
+    const { column } = inferColumnHelper({
+      metadata: testMetadata,
+      tableName: "task",
+    });
     // @ts-expect-error - intentionally testing invalid field name
     expect(() => column("nonExistent")).toThrow(
       'Field "nonExistent" not found in table "task" metadata',

package/src/component/field-helpers.ts

@@ -83,7 +83,45 @@ export function display<TRow extends Record<string, unknown>>(
 }
 
 // =============================================================================
-// inferColumns() helper
+// createColumnHelper() factory
+// =============================================================================
+
+/**
+ * Create `field` and `display` helpers with TRow bound once.
+ *
+ * This avoids repeating the row type parameter on every `field()` / `display()` call.
+ *
+ * @example
+ * ```tsx
+ * type Order = { id: string; title: string; amount: number };
+ *
+ * const { field, display } = createColumnHelper<Order>();
+ *
+ * const columns = [
+ *   field("title", { label: "Title", sort: { type: "string" } }),
+ *   field("amount", { label: "Amount", sort: { type: "number" } }),
+ *   display("actions", { render: (row) => <ActionMenu row={row} /> }),
+ * ];
+ * ```
+ */
+export function createColumnHelper<TRow extends Record<string, unknown>>(): {
+  field: (
+    dataKey: keyof TRow & string,
+    options?: FieldColumnOptions<TRow>,
+  ) => FieldColumn<TRow>;
+  display: (
+    id: string,
+    options: DisplayColumnOptions<TRow>,
+  ) => DisplayColumn<TRow>;
+} {
+  return {
+    field: (dataKey, options) => field<TRow>(dataKey, options),
+    display: (id, options) => display<TRow>(id, options),
+  };
+}
+
+// =============================================================================
+// inferColumnHelper() helper
 // =============================================================================
 
 /**
@@ -92,14 +130,16 @@ export function display<TRow extends Record<string, unknown>>(
  * Automatically infers sort/filter configuration from field types,
  * including enum options.
  *
- * @param metadata - The generated `tableMetadata` map (with `as const`).
- * @param tableName - Key of the table in the metadata map.
+ * @param options - Object containing `metadata` (the generated map) and `tableName`.
  *
  * @example
  * ```tsx
  * import { tableMetadata } from "./generated/data-viewer-metadata.generated";
  *
- * const { column, columns } = inferColumns(tableMetadata, "task");
+ * const { column, columns } = inferColumnHelper({
+ *   metadata: tableMetadata,
+ *   tableName: "task",
+ * });
  *
  * const taskColumns = [
  *   column("title"),           // sort/filter auto-detected
@@ -109,13 +149,13 @@ export function display<TRow extends Record<string, unknown>>(
  * ];
  * ```
  */
-export function inferColumns<
+export function inferColumnHelper<
   const TMetadata extends TableMetadataMap,
   TTableName extends string & keyof TMetadata,
->(
-  metadata: TMetadata,
-  tableName: TTableName,
-): {
+>(options: {
+  metadata: TMetadata;
+  tableName: TTableName;
+}): {
   column: (
     dataKey: FieldName<TMetadata, TTableName>,
     options?: MetadataFieldOptions,
@@ -126,12 +166,13 @@ export function inferColumns<
     options?: MetadataFieldsOptions,
   ) => FieldColumn<Record<string, unknown>>[];
 } {
-  const tableMetadata = metadata[tableName];
-  const fields = tableMetadata.fields;
+  const { metadata, tableName } = options;
+  const tableMeta = metadata[tableName];
+  const fields = tableMeta.fields;
 
   const column = (
     dataKey: FieldName<TMetadata, TTableName>,
-    options?: MetadataFieldOptions,
+    columnOptions?: MetadataFieldOptions,
   ): FieldColumn<Record<string, unknown>> => {
     const fieldMeta = fields.find((f) => f.name === dataKey);
     if (!fieldMeta) {
@@ -142,30 +183,30 @@ export function inferColumns<
 
     // Auto-detect sort config
     let sort: SortConfig | undefined;
-    if (options?.sort !== false) {
+    if (columnOptions?.sort !== false) {
       sort = fieldTypeToSortConfig(fieldMeta.type);
     }
-    if (options?.sort === false) {
+    if (columnOptions?.sort === false) {
       sort = undefined;
     }
 
     // Auto-detect filter config
     let filter: FilterConfig | undefined;
-    if (options?.filter !== false) {
+    if (columnOptions?.filter !== false) {
       filter = fieldTypeToFilterConfig(fieldMeta.type, fieldMeta.enumValues);
     }
-    if (options?.filter === false) {
+    if (columnOptions?.filter === false) {
       filter = undefined;
     }
 
     return {
       kind: "field",
       dataKey: fieldMeta.name,
-      label: options?.label ?? fieldMeta.description ?? fieldMeta.name,
-      width: options?.width,
+      label: columnOptions?.label ?? fieldMeta.description ?? fieldMeta.name,
+      width: columnOptions?.width,
       sort,
       filter,
-      renderer: options?.renderer as
+      renderer: columnOptions?.renderer as
         | CellRenderer<Record<string, unknown>>
         | undefined,
     };

package/src/component/index.ts

@@ -9,6 +9,7 @@ export type {
   PageInfo,
   QueryVariables,
   CollectionResult,
+  NodeType,
   CellRendererProps,
   CellRenderer,
   FieldColumnOptions,
@@ -59,7 +60,7 @@ export { useDataTable } from "./data-table/use-data-table";
 export { useDataTableContext } from "./data-table/data-table-context";
 
 // Field helpers
-export { field, display, inferColumns } from "./field-helpers";
+export { createColumnHelper, inferColumnHelper } from "./field-helpers";
 
 // Utility components
 export { Pagination } from "./pagination";

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;
 }