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

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