@izumisy-tailor/tailor-data-viewer 0.2.17 → 0.2.19

package/package.json

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

package/src/component/column-selector.test.tsx

@@ -0,0 +1,120 @@
+import { render, screen, fireEvent } from "@testing-library/react";
+import { describe, it, expect, vi } from "vitest";
+import type { Column } from "./types";
+import { createTestProviders } from "../tests/helpers";
+import { ColumnSelector } from "./column-selector";
+
+// =============================================================================
+// Fixtures
+// =============================================================================
+
+type TestRow = { id: string; name: string; status: string };
+
+const testColumns: Column<TestRow>[] = [
+  { kind: "field", dataKey: "name", label: "Name" },
+  { kind: "field", dataKey: "status", label: "Status" },
+  {
+    kind: "display",
+    id: "actions",
+    label: "Actions",
+    render: (row) => <button>Edit {row.name}</button>,
+  },
+];
+
+const testRows: TestRow[] = [
+  { id: "1", name: "Alice", status: "active" },
+  { id: "2", name: "Bob", status: "inactive" },
+];
+
+const TestProviders = createTestProviders({
+  columns: testColumns,
+  rows: testRows,
+});
+
+// =============================================================================
+// Tests
+// =============================================================================
+
+describe("ColumnSelector", () => {
+  it("renders column names with checkboxes", () => {
+    render(
+      <TestProviders>
+        <ColumnSelector />
+      </TestProviders>,
+    );
+
+    expect(screen.getByText("Columns")).toBeInTheDocument();
+    expect(screen.getByText("Name")).toBeInTheDocument();
+    expect(screen.getByText("Status")).toBeInTheDocument();
+    expect(screen.getByText("Actions")).toBeInTheDocument();
+  });
+
+  it("shows checkboxes as checked when columns are visible", () => {
+    render(
+      <TestProviders dataTable={{ isColumnVisible: vi.fn(() => true) }}>
+        <ColumnSelector />
+      </TestProviders>,
+    );
+
+    const checkboxes = screen.getAllByRole("checkbox");
+    for (const cb of checkboxes) {
+      expect(cb).toBeChecked();
+    }
+  });
+
+  it("shows checkboxes as unchecked when columns are hidden", () => {
+    render(
+      <TestProviders dataTable={{ isColumnVisible: vi.fn(() => false) }}>
+        <ColumnSelector />
+      </TestProviders>,
+    );
+
+    const checkboxes = screen.getAllByRole("checkbox");
+    for (const cb of checkboxes) {
+      expect(cb).not.toBeChecked();
+    }
+  });
+
+  it("calls toggleColumn when a checkbox is clicked", () => {
+    const toggleColumn = vi.fn();
+    render(
+      <TestProviders dataTable={{ toggleColumn }}>
+        <ColumnSelector />
+      </TestProviders>,
+    );
+
+    const checkboxes = screen.getAllByRole("checkbox");
+    fireEvent.click(checkboxes[0]);
+    expect(toggleColumn).toHaveBeenCalledWith("name");
+  });
+
+  it("calls showAllColumns when Select all is clicked", () => {
+    const showAllColumns = vi.fn();
+    render(
+      <TestProviders dataTable={{ showAllColumns }}>
+        <ColumnSelector />
+      </TestProviders>,
+    );
+
+    fireEvent.click(screen.getByText("Select all"));
+    expect(showAllColumns).toHaveBeenCalled();
+  });
+
+  it("calls hideAllColumns when Deselect all is clicked", () => {
+    const hideAllColumns = vi.fn();
+    render(
+      <TestProviders dataTable={{ hideAllColumns }}>
+        <ColumnSelector />
+      </TestProviders>,
+    );
+
+    fireEvent.click(screen.getByText("Deselect all"));
+    expect(hideAllColumns).toHaveBeenCalled();
+  });
+
+  it("throws when rendered outside provider", () => {
+    console.error = vi.fn();
+    expect(() => render(<ColumnSelector />)).toThrow();
+    console.error = globalThis.console.error;
+  });
+});

package/src/component/column-selector.tsx

@@ -1,22 +1,26 @@
-import type { ColumnSelectorProps } from "./types";
+import { useDataTableContext } from "./data-table/data-table-context";
 
 /**
  * Column visibility toggle dropdown.
  *
- * Designed to receive props via spread from `useDataTable()`.
+ * Reads column definitions and visibility state from `DataTableContext`.
+ * Must be rendered inside `DataTable.Provider`.
  *
  * @example
  * ```tsx
- * <ColumnSelector {...table} />
+ * <DataTable.Provider value={table}>
+ *   <ColumnSelector />
+ * </DataTable.Provider>
  * ```
  */
-export function ColumnSelector<TRow extends Record<string, unknown>>({
-  columns,
-  isColumnVisible,
-  toggleColumn,
-  showAllColumns,
-  hideAllColumns,
-}: ColumnSelectorProps<TRow>) {
+export function ColumnSelector() {
+  const {
+    columns,
+    isColumnVisible,
+    toggleColumn,
+    showAllColumns,
+    hideAllColumns,
+  } = useDataTableContext();
   return (
     <div className="relative inline-block">
       <details className="group">
@@ -24,28 +28,22 @@ export function ColumnSelector<TRow extends Record<string, unknown>>({
           Columns
         </summary>
         <div className="absolute right-0 z-50 mt-1 min-w-[180px] rounded-md border bg-popover p-2 text-popover-foreground shadow-md">
-          {(showAllColumns || hideAllColumns) && (
-            <div className="flex gap-2 border-b pb-2 mb-2">
-              {showAllColumns && (
-                <button
-                  type="button"
-                  className="text-xs text-muted-foreground hover:text-foreground"
-                  onClick={showAllColumns}
-                >
-                  Select all
-                </button>
-              )}
-              {hideAllColumns && (
-                <button
-                  type="button"
-                  className="text-xs text-muted-foreground hover:text-foreground"
-                  onClick={hideAllColumns}
-                >
-                  Deselect all
-                </button>
-              )}
-            </div>
-          )}
+          <div className="flex gap-2 border-b pb-2 mb-2">
+            <button
+              type="button"
+              className="text-xs text-muted-foreground hover:text-foreground"
+              onClick={showAllColumns}
+            >
+              Select all
+            </button>
+            <button
+              type="button"
+              className="text-xs text-muted-foreground hover:text-foreground"
+              onClick={hideAllColumns}
+            >
+              Deselect all
+            </button>
+          </div>
           {columns.map((col) => {
             const key = col.kind === "field" ? col.dataKey : col.id;
             const label =

package/src/component/csv-button.test.tsx

@@ -0,0 +1,122 @@
+import { render, screen, fireEvent } from "@testing-library/react";
+import { describe, it, expect, vi, beforeEach, afterEach } from "vitest";
+import type { Column } from "./types";
+import { createTestProviders } from "../tests/helpers";
+import { CsvButton } from "./csv-button";
+
+// =============================================================================
+// Fixtures
+// =============================================================================
+
+type TestRow = { id: string; name: string; status: string };
+
+const testColumns: Column<TestRow>[] = [
+  { kind: "field", dataKey: "name", label: "Name" },
+  { kind: "field", dataKey: "status", label: "Status" },
+];
+
+const testRows: TestRow[] = [
+  { id: "1", name: "Alice", status: "active" },
+  { id: "2", name: "Bob", status: "inactive" },
+];
+
+const TestProviders = createTestProviders({
+  columns: testColumns,
+  rows: testRows,
+});
+
+// =============================================================================
+// Tests
+// =============================================================================
+
+describe("CsvButton", () => {
+  // Save originals before each test to avoid cross-contamination
+  const originalCreateObjectURL = globalThis.URL.createObjectURL;
+  const originalRevokeObjectURL = globalThis.URL.revokeObjectURL;
+  let originalCreateElement: typeof document.createElement;
+
+  beforeEach(() => {
+    originalCreateElement = document.createElement.bind(document);
+  });
+
+  afterEach(() => {
+    globalThis.URL.createObjectURL = originalCreateObjectURL;
+    globalThis.URL.revokeObjectURL = originalRevokeObjectURL;
+    vi.restoreAllMocks();
+  });
+
+  it("renders Export CSV button", () => {
+    render(
+      <TestProviders>
+        <CsvButton />
+      </TestProviders>,
+    );
+
+    expect(screen.getByText("Export CSV")).toBeInTheDocument();
+  });
+
+  it("triggers CSV download on click", () => {
+    const createObjectURL = vi.fn(() => "blob:mock-url");
+    const revokeObjectURL = vi.fn();
+    globalThis.URL.createObjectURL = createObjectURL;
+    globalThis.URL.revokeObjectURL = revokeObjectURL;
+
+    const clickSpy = vi.fn();
+    vi.spyOn(document, "createElement").mockImplementation(
+      (tag: string, options?: ElementCreationOptions) => {
+        if (tag === "a") {
+          return {
+            href: "",
+            download: "",
+            click: clickSpy,
+          } as unknown as HTMLAnchorElement;
+        }
+        return originalCreateElement(tag, options);
+      },
+    );
+
+    render(
+      <TestProviders>
+        <CsvButton filename="test-export" />
+      </TestProviders>,
+    );
+
+    fireEvent.click(screen.getByText("Export CSV"));
+
+    expect(createObjectURL).toHaveBeenCalled();
+    expect(clickSpy).toHaveBeenCalled();
+    expect(revokeObjectURL).toHaveBeenCalledWith("blob:mock-url");
+  });
+
+  it("uses default filename when not specified", () => {
+    globalThis.URL.createObjectURL = vi.fn(() => "blob:url");
+    globalThis.URL.revokeObjectURL = vi.fn();
+
+    const links: { download: string }[] = [];
+    vi.spyOn(document, "createElement").mockImplementation(
+      (tag: string, options?: ElementCreationOptions) => {
+        if (tag === "a") {
+          const link = { href: "", download: "", click: vi.fn() };
+          links.push(link);
+          return link as unknown as HTMLAnchorElement;
+        }
+        return originalCreateElement(tag, options);
+      },
+    );
+
+    render(
+      <TestProviders>
+        <CsvButton />
+      </TestProviders>,
+    );
+
+    fireEvent.click(screen.getByText("Export CSV"));
+    expect(links[0].download).toBe("export.csv");
+  });
+
+  it("throws when rendered outside provider", () => {
+    console.error = vi.fn();
+    expect(() => render(<CsvButton />)).toThrow();
+    console.error = globalThis.console.error;
+  });
+});

package/src/component/csv-button.tsx

@@ -1,20 +1,21 @@
-import type { CsvButtonProps } from "./types";
+import { useDataTableContext } from "./data-table/data-table-context";
 
 /**
  * CSV export button.
  *
  * Exports visible columns and rows to a CSV file download.
+ * Reads `visibleColumns` and `rows` from `DataTableContext`.
+ * Must be rendered inside `DataTable.Provider`.
  *
  * @example
  * ```tsx
- * <CsvButton {...table} filename="orders-export" />
+ * <DataTable.Provider value={table}>
+ *   <CsvButton filename="orders-export" />
+ * </DataTable.Provider>
  * ```
  */
-export function CsvButton<TRow extends Record<string, unknown>>({
-  visibleColumns,
-  rows,
-  filename = "export",
-}: CsvButtonProps<TRow>) {
+export function CsvButton({ filename = "export" }: { filename?: string }) {
+  const { visibleColumns, rows } = useDataTableContext();
   const handleExport = () => {
     // Build header row
     const headers = visibleColumns.map((col) => {

package/src/component/data-table/data-table-context.tsx

@@ -1,25 +1,36 @@
 import { createContext, useContext } from "react";
-import type { Column, RowOperations, SortState } from "../types";
+import type { Column, PageInfo, RowOperations, SortState } from "../types";
 
 /**
- * Context value provided by `DataTable.Root`.
+ * Context value provided by `DataTable.Root` or `DataTable.Provider`.
  *
- * Exposes row operations for optimistic updates and table state
- * so that `DataTable.Headers` / `DataTable.Body` can read them
- * without explicit props.
+ * Exposes row operations for optimistic updates, table state, column
+ * visibility, and page info so that `DataTable.Headers` / `DataTable.Body`
+ * and utility components (`Pagination`, `ColumnSelector`, etc.) can read
+ * them without explicit props.
  */
 export interface DataTableContextValue<TRow extends Record<string, unknown>> {
   updateRow: RowOperations<TRow>["updateRow"];
   deleteRow: RowOperations<TRow>["deleteRow"];
   insertRow: RowOperations<TRow>["insertRow"];
 
-  // Table state propagated from DataTable.Root
+  // Table state propagated from DataTable.Root / DataTable.Provider
   columns: Column<TRow>[];
   rows: TRow[];
   loading: boolean;
   error: Error | null;
   sortStates: SortState[];
   onSort?: (field: string, direction?: "Asc" | "Desc") => void;
+
+  // Column visibility (populated by DataTable.Provider)
+  visibleColumns: Column<TRow>[];
+  isColumnVisible: (fieldOrId: string) => boolean;
+  toggleColumn: (fieldOrId: string) => void;
+  showAllColumns: () => void;
+  hideAllColumns: () => void;
+
+  // Page info from GraphQL response (populated by DataTable.Provider)
+  pageInfo: PageInfo;
 }
 
 // Using `any` for the context default since generic contexts need a base type.

package/src/component/data-table/index.tsx

@@ -5,8 +5,14 @@ import {
   type ReactNode,
 } from "react";
 import { cn } from "../lib/utils";
+import { CollectionProvider } from "../collection/collection-provider";
 import { Table } from "../table";
-import type { Column, DataTableRootProps } from "../types";
+import type {
+  Column,
+  DataTableRootProps,
+  PageInfo,
+  UseDataTableReturn,
+} from "../types";
 import {
   DataTableContext,
   type DataTableContextValue,
@@ -28,6 +34,13 @@ const noopRowOps = {
   insertRow: () => ({ rollback: () => {} }),
 };
 
+const defaultPageInfo: PageInfo = {
+  hasNextPage: false,
+  endCursor: null,
+  hasPreviousPage: false,
+  startCursor: null,
+};
+
 function DataTableRoot<TRow extends Record<string, unknown>>({
   columns = [] as Column<TRow>[],
   rows = [] as TRow[],
@@ -38,6 +51,11 @@ function DataTableRoot<TRow extends Record<string, unknown>>({
   rowOperations,
   children,
 }: DataTableRootProps<TRow>) {
+  // When rendered inside DataTable.Provider, inherit missing fields from context
+  const parentCtx = useContext(
+    DataTableContext,
+  ) as DataTableContextValue<TRow> | null;
+
   const contextValue: DataTableContextValue<TRow> = {
     updateRow: (rowOperations?.updateRow ??
       noopRowOps.updateRow) as DataTableContextValue<TRow>["updateRow"],
@@ -51,6 +69,13 @@ function DataTableRoot<TRow extends Record<string, unknown>>({
     error,
     sortStates,
     onSort,
+    // Inherit column visibility & pageInfo from parent context (DataTable.Provider)
+    visibleColumns: parentCtx?.visibleColumns ?? columns,
+    isColumnVisible: parentCtx?.isColumnVisible ?? (() => true),
+    toggleColumn: parentCtx?.toggleColumn ?? (() => {}),
+    showAllColumns: parentCtx?.showAllColumns ?? (() => {}),
+    hideAllColumns: parentCtx?.hideAllColumns ?? (() => {}),
+    pageInfo: parentCtx?.pageInfo ?? defaultPageInfo,
   };
 
   return (
@@ -60,6 +85,77 @@ function DataTableRoot<TRow extends Record<string, unknown>>({
   );
 }
 
+// =============================================================================
+// DataTable.Provider
+// =============================================================================
+
+/**
+ * Provider that shares `useDataTable()` state via React Context.
+ *
+ * Internally provides both `DataTableContext` and `CollectionContext`
+ * so that utility components (`Pagination`, `ColumnSelector`,
+ * `SearchFilterForm`, `CsvButton`) can consume data without explicit props.
+ *
+ * @example
+ * ```tsx
+ * const collection = useCollection({ query: GET_ORDERS, params: { pageSize: 20 } });
+ * const [result] = useQuery({ ...collection.toQueryArgs() });
+ * const table = useDataTable({ columns, data: result.data?.orders, collection });
+ *
+ * <DataTable.Provider value={table}>
+ *   <SearchFilterForm />
+ *   <ColumnSelector />
+ *   <DataTable.Root>
+ *     <DataTable.Headers />
+ *     <DataTable.Body />
+ *   </DataTable.Root>
+ *   <Pagination />
+ * </DataTable.Provider>
+ * ```
+ */
+function DataTableProviderComponent<TRow extends Record<string, unknown>>({
+  value,
+  children,
+}: {
+  value: UseDataTableReturn<TRow>;
+  children: ReactNode;
+}) {
+  const dataTableValue: DataTableContextValue<TRow> = {
+    columns: value.columns,
+    rows: value.rows,
+    loading: value.loading,
+    error: value.error,
+    sortStates: value.rootProps.sortStates ?? [],
+    onSort: value.rootProps.onSort,
+    updateRow: value.updateRow,
+    deleteRow: value.deleteRow,
+    insertRow: value.insertRow,
+    visibleColumns: value.visibleColumns,
+    isColumnVisible: value.isColumnVisible,
+    toggleColumn: value.toggleColumn,
+    showAllColumns: value.showAllColumns,
+    hideAllColumns: value.hideAllColumns,
+    pageInfo: value.pageInfo,
+  };
+
+  const collectionValue = value.collection ?? null;
+
+  const inner = (
+    <DataTableContext.Provider value={dataTableValue}>
+      {children}
+    </DataTableContext.Provider>
+  );
+
+  // Wrap with CollectionContext when collection is available
+  if (collectionValue) {
+    return (
+      <CollectionProvider value={collectionValue}>{inner}</CollectionProvider>
+    );
+  }
+
+  return inner;
+}
+
 // =============================================================================
 // DataTable.Headers
 // =============================================================================
@@ -298,12 +394,25 @@ function formatValue(value: unknown): ReactNode {
 /**
  * Data-bound table compound component.
  *
- * Use with `useDataTable()` hook which provides `rootProps` to spread.
+ * Use with `useDataTable()` hook which provides `rootProps` to spread,
+ * or wrap with `DataTable.Provider` for context-based usage.
  *
  * @example
  * ```tsx
+ * // Context-based (recommended)
  * const table = useDataTable({ columns, data, loading, collection });
  *
+ * <DataTable.Provider value={table}>
+ *   <SearchFilterForm />
+ *   <ColumnSelector />
+ *   <DataTable.Root>
+ *     <DataTable.Headers />
+ *     <DataTable.Body />
+ *   </DataTable.Root>
+ *   <Pagination />
+ * </DataTable.Provider>
+ *
+ * // Props-based (still supported)
  * <DataTable.Root {...table.rootProps}>
  *   <DataTable.Headers />
  *   <DataTable.Body />
@@ -311,6 +420,7 @@ function formatValue(value: unknown): ReactNode {
  * ```
  */
 export const DataTable = {
+  Provider: DataTableProviderComponent,
   Root: DataTableRoot,
   Headers: DataTableHeaders,
   Body: DataTableBody,

package/src/component/data-table/use-data-table.ts

@@ -272,5 +272,8 @@ export function useDataTable<TRow extends Record<string, unknown>>(
     updateRow,
     deleteRow,
     insertRow,
+
+    // Collection (passthrough for DataTable.Provider)
+    collection,
   };
 }

package/src/component/field-helpers.ts

@@ -130,41 +130,49 @@ export function createColumnHelper<TRow extends Record<string, unknown>>(): {
  * Automatically infers sort/filter configuration from field types,
  * including enum options.
  *
+ * @typeParam TRow - The row type for type-safe renderer access.
  * @param tableMetadata - A single table metadata object from the generated map.
  *
  * @example
  * ```tsx
  * import { tableMetadata } from "./generated/data-viewer-metadata.generated";
  *
- * const { column, columns } = inferColumnHelper(tableMetadata.task);
+ * type Task = { id: string; title: string; status: string; dueDate: string };
+ *
+ * const { column, columns } = inferColumnHelper<Task>(tableMetadata.task);
  *
  * const taskColumns = [
  *   column("title"),           // sort/filter auto-detected
  *   column("status"),          // enum options auto-populated
  *   column("dueDate"),         // date type auto-recognized
- *   display("actions", { render: (row) => <ActionMenu row={row} /> }),
+ *   column("title", {
+ *     renderer: ({ row }) => <span>{row.title}</span>, // row: Task
+ *   }),
  * ];
  * ```
  */
-export function inferColumnHelper<const TTable extends TableMetadata>(
+export function inferColumnHelper<
+  TRow extends Record<string, unknown>,
+  const TTable extends TableMetadata = TableMetadata,
+>(
   tableMetadata: TTable,
 ): {
   column: (
     dataKey: TableFieldName<TTable>,
-    options?: MetadataFieldOptions,
-  ) => FieldColumn<Record<string, unknown>>;
+    options?: MetadataFieldOptions<TRow>,
+  ) => FieldColumn<TRow>;
 
   columns: (
     dataKeys: TableFieldName<TTable>[],
     options?: MetadataFieldsOptions,
-  ) => FieldColumn<Record<string, unknown>>[];
+  ) => FieldColumn<TRow>[];
 } {
   const fields = tableMetadata.fields;
 
   const column = (
     dataKey: TableFieldName<TTable>,
-    columnOptions?: MetadataFieldOptions,
-  ): FieldColumn<Record<string, unknown>> => {
+    columnOptions?: MetadataFieldOptions<TRow>,
+  ): FieldColumn<TRow> => {
     const fieldMeta = fields.find((f) => f.name === dataKey);
     if (!fieldMeta) {
       throw new Error(
@@ -197,20 +205,19 @@ export function inferColumnHelper<const TTable extends TableMetadata>(
       width: columnOptions?.width,
       sort,
       filter,
-      renderer: columnOptions?.renderer as
-        | CellRenderer<Record<string, unknown>>
-        | undefined,
+      renderer: columnOptions?.renderer as CellRenderer<TRow> | undefined,
     };
   };
 
   const columnsHelper = (
     dataKeys: TableFieldName<TTable>[],
     options?: MetadataFieldsOptions,
-  ): FieldColumn<Record<string, unknown>>[] => {
+  ): FieldColumn<TRow>[] => {
     return dataKeys.map((dataKey) => {
       const overrides = options?.overrides?.[dataKey as string];
       return column(dataKey, {
-        ...overrides,
+        label: overrides?.label,
+        width: overrides?.width,
         sort: overrides?.sort ?? options?.sort,
         filter: overrides?.filter ?? options?.filter,
       });

package/src/component/index.ts

@@ -40,11 +40,7 @@ export type {
   MetadataFieldsOptions,
   MetadataFilter,
   TableMetadataFilter,
-  ColumnSelectorProps,
-  CsvButtonProps,
-  SearchFilterFormProps,
   SearchFilterLabels,
-  PaginationProps,
 } from "./types";
 
 export {

package/src/component/pagination.test.tsx

@@ -0,0 +1,129 @@
+import { render, screen, fireEvent } from "@testing-library/react";
+import { describe, it, expect, vi } from "vitest";
+import type { Column } from "./types";
+import { createTestProviders } from "../tests/helpers";
+import { Pagination } from "./pagination";
+
+// =============================================================================
+// Fixtures
+// =============================================================================
+
+type TestRow = { id: string; name: string; status: string };
+
+const testColumns: Column<TestRow>[] = [
+  { kind: "field", dataKey: "name", label: "Name" },
+  { kind: "field", dataKey: "status", label: "Status" },
+];
+
+const testRows: TestRow[] = [
+  { id: "1", name: "Alice", status: "active" },
+  { id: "2", name: "Bob", status: "inactive" },
+];
+
+const TestProviders = createTestProviders({
+  columns: testColumns,
+  rows: testRows,
+  dataTableDefaults: {
+    pageInfo: {
+      hasNextPage: true,
+      endCursor: "cursor-end",
+      hasPreviousPage: true,
+      startCursor: "cursor-start",
+    },
+  },
+  collectionDefaults: {
+    hasPrevPage: true,
+    hasNextPage: true,
+  },
+});
+
+// =============================================================================
+// Tests
+// =============================================================================
+
+describe("Pagination", () => {
+  it("renders Previous and Next buttons", () => {
+    render(
+      <TestProviders>
+        <Pagination />
+      </TestProviders>,
+    );
+
+    expect(screen.getByText("Previous")).toBeInTheDocument();
+    expect(screen.getByText("Next")).toBeInTheDocument();
+  });
+
+  it("disables Previous when hasPrevPage is false", () => {
+    render(
+      <TestProviders collection={{ hasPrevPage: false }}>
+        <Pagination />
+      </TestProviders>,
+    );
+
+    expect(screen.getByText("Previous")).toBeDisabled();
+    expect(screen.getByText("Next")).toBeEnabled();
+  });
+
+  it("disables Next when hasNextPage is false", () => {
+    render(
+      <TestProviders collection={{ hasNextPage: false }}>
+        <Pagination />
+      </TestProviders>,
+    );
+
+    expect(screen.getByText("Previous")).toBeEnabled();
+    expect(screen.getByText("Next")).toBeDisabled();
+  });
+
+  it("calls nextPage with endCursor when Next is clicked", () => {
+    const nextPage = vi.fn();
+    render(
+      <TestProviders collection={{ nextPage }}>
+        <Pagination />
+      </TestProviders>,
+    );
+
+    fireEvent.click(screen.getByText("Next"));
+    expect(nextPage).toHaveBeenCalledWith("cursor-end");
+  });
+
+  it("calls prevPage with startCursor when Previous is clicked", () => {
+    const prevPage = vi.fn();
+    render(
+      <TestProviders collection={{ prevPage }}>
+        <Pagination />
+      </TestProviders>,
+    );
+
+    fireEvent.click(screen.getByText("Previous"));
+    expect(prevPage).toHaveBeenCalledWith("cursor-start");
+  });
+
+  it("does not call nextPage when endCursor is null", () => {
+    const nextPage = vi.fn();
+    render(
+      <TestProviders
+        dataTable={{
+          pageInfo: {
+            hasNextPage: true,
+            endCursor: null,
+            hasPreviousPage: false,
+            startCursor: null,
+          },
+        }}
+        collection={{ nextPage, hasNextPage: true }}
+      >
+        <Pagination />
+      </TestProviders>,
+    );
+
+    fireEvent.click(screen.getByText("Next"));
+    expect(nextPage).not.toHaveBeenCalled();
+  });
+
+  it("throws when rendered outside provider", () => {
+    console.error = vi.fn();
+    expect(() => render(<Pagination />)).toThrow();
+    console.error = globalThis.console.error;
+  });
+});

package/src/component/pagination.tsx

@@ -1,22 +1,24 @@
-import type { PaginationProps } from "./types";
+import { useDataTableContext } from "./data-table/data-table-context";
+import { useCollectionContext } from "./collection/collection-provider";
 
 /**
  * Pagination controls for cursor-based navigation.
  *
- * Designed to receive props via spread from `useDataTable()`.
+ * Reads `pageInfo` from `DataTableContext` and pagination actions
+ * from `CollectionContext`. Must be rendered inside `DataTable.Provider`.
  *
  * @example
  * ```tsx
- * <Pagination {...table} />
+ * <DataTable.Provider value={table}>
+ *   <Pagination />
+ * </DataTable.Provider>
  * ```
  */
-export function Pagination({
-  pageInfo,
-  nextPage,
-  prevPage,
-  hasPrevPage,
-  hasNextPage,
-}: PaginationProps) {
+export function Pagination() {
+  const { pageInfo } = useDataTableContext();
+  const { nextPage, prevPage, hasPrevPage, hasNextPage } =
+    useCollectionContext();
+
   return (
     <div className="flex items-center justify-end gap-2 py-2">
       <button

package/src/component/search-filter-form.test.tsx

@@ -0,0 +1,222 @@
+import { render, screen, fireEvent } from "@testing-library/react";
+import userEvent from "@testing-library/user-event";
+import { describe, it, expect, vi } from "vitest";
+import type { Column, Filter } from "./types";
+import { createTestProviders } from "../tests/helpers";
+import { SearchFilterForm } from "./search-filter-form";
+
+// =============================================================================
+// Fixtures
+// =============================================================================
+
+type TestRow = { id: string; name: string; status: string; priority: number };
+
+const testColumns: Column<TestRow>[] = [
+  {
+    kind: "field",
+    dataKey: "name",
+    label: "Name",
+    sort: { type: "string" },
+    filter: { type: "string" },
+  },
+  {
+    kind: "field",
+    dataKey: "status",
+    label: "Status",
+    filter: {
+      type: "enum",
+      options: [
+        { value: "active", label: "Active" },
+        { value: "inactive", label: "Inactive" },
+      ],
+    },
+  },
+  {
+    kind: "field",
+    dataKey: "priority",
+    label: "Priority",
+    sort: { type: "number" },
+    filter: { type: "number" },
+  },
+  {
+    kind: "display",
+    id: "actions",
+    label: "Actions",
+    render: (row) => <button>Edit {row.name}</button>,
+  },
+];
+
+const testRows: TestRow[] = [
+  { id: "1", name: "Alice", status: "active", priority: 1 },
+  { id: "2", name: "Bob", status: "inactive", priority: 2 },
+];
+
+const TestProviders = createTestProviders({
+  columns: testColumns,
+  rows: testRows,
+});
+
+// =============================================================================
+// Tests
+// =============================================================================
+
+describe("SearchFilterForm", () => {
+  it("renders the search trigger button", () => {
+    render(
+      <TestProviders>
+        <SearchFilterForm />
+      </TestProviders>,
+    );
+
+    expect(screen.getByText("Search")).toBeInTheDocument();
+  });
+
+  it("shows active filter count badge", () => {
+    const filters: Filter[] = [
+      { field: "name", operator: "eq", value: "Alice" },
+    ];
+    render(
+      <TestProviders collection={{ filters }}>
+        <SearchFilterForm />
+      </TestProviders>,
+    );
+
+    expect(screen.getByText("1")).toBeInTheDocument();
+  });
+
+  it("renders custom trigger when provided", () => {
+    render(
+      <TestProviders>
+        <SearchFilterForm trigger={<span>Custom Trigger</span>} />
+      </TestProviders>,
+    );
+
+    expect(screen.getByText("Custom Trigger")).toBeInTheDocument();
+  });
+
+  it("shows filterable field options in the dropdown", () => {
+    render(
+      <TestProviders>
+        <SearchFilterForm />
+      </TestProviders>,
+    );
+
+    expect(screen.getByText("Select field...")).toBeInTheDocument();
+    const options = screen.getAllByRole("option");
+    const optionTexts = options.map((o) => o.textContent);
+    expect(optionTexts).toContain("Name");
+    expect(optionTexts).toContain("Status");
+    expect(optionTexts).toContain("Priority");
+  });
+
+  it("displays active filters with remove buttons", () => {
+    const filters: Filter[] = [
+      { field: "name", operator: "eq", value: "Alice" },
+    ];
+    const removeFilter = vi.fn();
+    render(
+      <TestProviders collection={{ filters, removeFilter }}>
+        <SearchFilterForm />
+      </TestProviders>,
+    );
+
+    expect(screen.getByText("Active filters")).toBeInTheDocument();
+    expect(screen.getByText("Name = Alice")).toBeInTheDocument();
+
+    fireEvent.click(screen.getByText("✕"));
+    expect(removeFilter).toHaveBeenCalledWith("name");
+  });
+
+  it("calls clearFilters when Clear all is clicked", () => {
+    const filters: Filter[] = [
+      { field: "name", operator: "eq", value: "test" },
+    ];
+    const clearFilters = vi.fn();
+    render(
+      <TestProviders collection={{ filters, clearFilters }}>
+        <SearchFilterForm />
+      </TestProviders>,
+    );
+
+    fireEvent.click(screen.getByText("Clear all"));
+    expect(clearFilters).toHaveBeenCalled();
+  });
+
+  it("calls addFilter when a filter is submitted", async () => {
+    const user = userEvent.setup();
+    const addFilter = vi.fn();
+    render(
+      <TestProviders collection={{ addFilter }}>
+        <SearchFilterForm />
+      </TestProviders>,
+    );
+
+    // Select field
+    await user.selectOptions(
+      screen.getByDisplayValue("Select field..."),
+      "name",
+    );
+
+    // Type value
+    await user.type(screen.getByPlaceholderText("Enter value..."), "Alice");
+
+    // Click Add
+    await user.click(screen.getByText("Add"));
+
+    expect(addFilter).toHaveBeenCalledWith("name", "eq", "Alice");
+  });
+
+  it("shows 'No filterable fields' when no columns have filter config", () => {
+    const columnsWithoutFilter: Column<TestRow>[] = [
+      { kind: "field", dataKey: "name", label: "Name" },
+    ];
+    render(
+      <TestProviders dataTable={{ columns: columnsWithoutFilter }}>
+        <SearchFilterForm />
+      </TestProviders>,
+    );
+
+    expect(screen.getByText("No filterable fields")).toBeInTheDocument();
+  });
+
+  it("shows 'All fields have filters applied' when every field is filtered", () => {
+    const filters: Filter[] = [
+      { field: "name", operator: "eq", value: "a" },
+      { field: "status", operator: "eq", value: "active" },
+      { field: "priority", operator: "eq", value: "1" },
+    ];
+    render(
+      <TestProviders collection={{ filters }}>
+        <SearchFilterForm />
+      </TestProviders>,
+    );
+
+    expect(
+      screen.getByText("All fields have filters applied"),
+    ).toBeInTheDocument();
+  });
+
+  it("supports custom labels", () => {
+    render(
+      <TestProviders>
+        <SearchFilterForm
+          labels={{
+            search: "検索",
+            searchFilter: "検索フィルタ",
+            selectField: "フィールド選択...",
+          }}
+        />
+      </TestProviders>,
+    );
+
+    expect(screen.getByText("検索")).toBeInTheDocument();
+    expect(screen.getByText("検索フィルタ")).toBeInTheDocument();
+    expect(screen.getByText("フィールド選択...")).toBeInTheDocument();
+  });
+
+  it("throws when rendered outside provider", () => {
+    console.error = vi.fn();
+    expect(() => render(<SearchFilterForm />)).toThrow();
+    console.error = globalThis.console.error;
+  });
+});

package/src/component/search-filter-form.tsx

@@ -4,38 +4,43 @@ import {
   useEffect,
   useRef,
   type KeyboardEvent,
+  type ReactNode,
 } from "react";
-import type {
-  FilterOperator,
-  SearchFilterFormProps,
-  FilterConfig,
-} from "./types";
+import type { FilterOperator, FilterConfig, SearchFilterLabels } from "./types";
 import { OPERATORS_BY_FILTER_TYPE, DEFAULT_OPERATOR_LABELS } from "./types";
+import { useDataTableContext } from "./data-table/data-table-context";
+import { useCollectionContext } from "./collection/collection-provider";
 
 /**
  * Composite search filter form.
  *
  * Renders a dropdown panel with type-specific filter inputs, operator
- * selectors, and active filter badges.  Designed to receive props via
- * spread from `useDataTable()` / `useCollection()`.
+ * selectors, and active filter badges.  Reads `columns` from
+ * `DataTableContext` and filter state from `CollectionContext`.
+ * Must be rendered inside `DataTable.Provider`.
  *
  * All text is customisable through the optional `labels` prop (defaults
  * to English).
  *
  * @example
  * ```tsx
- * <SearchFilterForm {...table} {...params} />
+ * <DataTable.Provider value={table}>
+ *   <SearchFilterForm />
+ * </DataTable.Provider>
  * ```
  */
-export function SearchFilterForm<TRow extends Record<string, unknown>>({
-  columns,
-  filters,
-  addFilter,
-  removeFilter,
-  clearFilters,
+export function SearchFilterForm({
   labels,
   trigger,
-}: SearchFilterFormProps<TRow>) {
+}: {
+  /** Localizable labels (defaults to English) */
+  labels?: SearchFilterLabels;
+  /** Custom trigger element. When provided, replaces the default trigger button content. */
+  trigger?: ReactNode;
+} = {}) {
+  const { columns } = useDataTableContext();
+  const { filters, addFilter, removeFilter, clearFilters } =
+    useCollectionContext();
   const filterableColumns = columns.filter(
     (col) => col.kind === "field" && col.filter,
   );

package/src/component/types.ts

@@ -609,6 +609,10 @@ export interface UseDataTableReturn<TRow extends Record<string, unknown>> {
   deleteRow: (rowId: string) => { rollback: () => void; deletedRow: TRow };
   /** Optimistically insert a row */
   insertRow: (row: TRow) => { rollback: () => void };
+
+  // Collection (passthrough for DataTable.Provider)
+  /** Collection state passed through from options */
+  collection: UseCollectionReturn<string, unknown> | undefined;
 }
 
 // =============================================================================
@@ -942,14 +946,18 @@ export type MatchingTableName<
 
 /**
  * Options for metadata-based single field definition.
+ *
+ * @typeParam TRow - The row type for type-safe renderer access.
  */
-export interface MetadataFieldOptions {
+export interface MetadataFieldOptions<
+  TRow extends Record<string, unknown> = Record<string, unknown>,
+> {
   /** Label override (defaults to metadata description or field name) */
   label?: string;
   /** Column width */
   width?: number;
-  /** Custom cell renderer */
-  renderer?: CellRenderer<Record<string, unknown>>;
+  /** Custom cell renderer with typed row data */
+  renderer?: CellRenderer<TRow>;
   /** Enable/disable sort (default: auto-detected from type) */
   sort?: boolean;
   /** Enable/disable filter (default: auto-detected from type) */

package/src/tests/helpers.tsx

@@ -0,0 +1,131 @@
+import type { ReactNode } from "react";
+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";
+
+// =============================================================================
+// Mock factory: DataTableContext
+// =============================================================================
+
+export function createMockDataTableContext<T extends Record<string, unknown>>(
+  defaults: { columns: Column<T>[]; rows: T[] },
+  overrides?: Partial<DataTableContextValue<T>>,
+): DataTableContextValue<T> {
+  return {
+    columns: defaults.columns,
+    rows: defaults.rows,
+    loading: false,
+    error: null,
+    sortStates: [],
+    onSort: vi.fn(),
+    updateRow: vi.fn(() => ({ rollback: vi.fn() })),
+    deleteRow: vi.fn(() => ({
+      rollback: vi.fn(),
+      deletedRow: defaults.rows[0],
+    })),
+    insertRow: vi.fn(() => ({ rollback: vi.fn() })),
+    visibleColumns: defaults.columns,
+    isColumnVisible: vi.fn(() => true),
+    toggleColumn: vi.fn(),
+    showAllColumns: vi.fn(),
+    hideAllColumns: vi.fn(),
+    pageInfo: {
+      hasNextPage: false,
+      endCursor: null,
+      hasPreviousPage: false,
+      startCursor: null,
+    },
+    ...overrides,
+  };
+}
+
+// =============================================================================
+// Mock factory: CollectionContext
+// =============================================================================
+
+export function createMockCollectionContext(
+  overrides?: Partial<UseCollectionReturn<string, unknown>>,
+): UseCollectionReturn<string, unknown> {
+  return {
+    toQueryArgs: vi.fn(() => ({ query: null, variables: {} })),
+    filters: [],
+    addFilter: vi.fn(),
+    setFilters: vi.fn(),
+    removeFilter: vi.fn(),
+    clearFilters: vi.fn(),
+    sortStates: [],
+    setSort: vi.fn(),
+    clearSort: vi.fn(),
+    pageSize: 20,
+    cursor: null,
+    paginationDirection: "forward",
+    nextPage: vi.fn(),
+    prevPage: vi.fn(),
+    resetPage: vi.fn(),
+    hasPrevPage: false,
+    hasNextPage: false,
+    setPageInfo: vi.fn(),
+    ...overrides,
+  };
+}
+
+// =============================================================================
+// TestProviders factory
+// =============================================================================
+
+/**
+ * Creates a `TestProviders` wrapper component bound to specific fixture data.
+ *
+ * ```tsx
+ * const TestProviders = createTestProviders({
+ *   columns: testColumns,
+ *   rows: testRows,
+ *   dataTableDefaults: { pageInfo: { hasNextPage: true, ... } },
+ *   collectionDefaults: { hasPrevPage: true },
+ * });
+ *
+ * render(
+ *   <TestProviders dataTable={{ loading: true }}>
+ *     <MyComponent />
+ *   </TestProviders>,
+ * );
+ * ```
+ */
+export function createTestProviders<
+  T extends Record<string, unknown>,
+>(defaults: {
+  columns: Column<T>[];
+  rows: T[];
+  dataTableDefaults?: Partial<DataTableContextValue<T>>;
+  collectionDefaults?: Partial<UseCollectionReturn<string, unknown>>;
+}) {
+  return function TestProviders({
+    children,
+    dataTable,
+    collection,
+  }: {
+    children: ReactNode;
+    dataTable?: Partial<DataTableContextValue<T>>;
+    collection?: Partial<UseCollectionReturn<string, unknown>>;
+  }) {
+    return (
+      <CollectionProvider
+        value={createMockCollectionContext({
+          ...defaults.collectionDefaults,
+          ...collection,
+        })}
+      >
+        <DataTableContext.Provider
+          value={createMockDataTableContext(defaults, {
+            ...defaults.dataTableDefaults,
+            ...dataTable,
+          })}
+        >
+          {children}
+        </DataTableContext.Provider>
+      </CollectionProvider>
+    );
+  };
+}