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

package/README.md

@@ -1,21 +1,21 @@
 # Tailor Data Viewer
 
-A React component library for building data exploration interfaces with GraphQL backend support. Provides a tab-based spreadsheet-like UI for viewing and managing table data with relation navigation.
+A low-level React component library for building data table interfaces with Tailor Platform (GraphQL) backends. Provides composable hooks and compound components for query parameter management, table rendering, filtering, sorting, and pagination.
 
 ## Features
 
-- **Tab-based Interface**: Excel-like sheet management with multiple tabs
-- **Table Selection**: Role-based access control for tables
-- **Column Selection**: Dynamic column visibility with manyToOne relation expansion
-- **Relation Navigation**: Expandable inline relations with "Open as Sheet" functionality
-- **Search & Filter**: AND-based filtering on string, number, boolean, and enum fields
-- **View Persistence**: Save and load views with filter and column configurations
-- **Sorting & Pagination**: Full cursor-based pagination support
-- **CSV Export**: Download current view as CSV
-- **Single Record View**: Detailed single record view with all relations
-- **Custom Labels**: Internationalization support for field names and UI text
-- **Custom Renderers**: Built-in and custom cell renderers with pattern matching support
-- **File Type Support**: Automatic query expansion and thumbnail renderers for TailorDB File fields
+- **Separation of Concerns**: Data fetching, query parameter management, and UI are fully decoupled
+- **`useCollectionParams` Hook**: Manages filter, sort, and pagination state; outputs Tailor Platform-compatible GraphQL variables
+- **`CollectionParams.Provider`**: Shares query parameters via React Context across sibling components
+- **`Table.*` Compound Components**: Static, unstyled table primitives (`<table>`, `<thead>`, `<tbody>`, `<tr>`, `<th>`, `<td>`)
+- **`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**: `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
+- **Presentation Agnostic**: Same `useCollectionParams` can drive tables, kanbans, calendars, etc.
 
 ## Installation
 
@@ -39,209 +39,156 @@ This provides AI-optimized documentation for better code generation and assistan
 
 ### Peer Dependencies
 
-This library requires the following peer dependencies:
-
 ```bash
 npm install react react-dom
 ```
 
-## Usage
-
-There are two ways to use Data Viewer:
-
-1. **AppShell Module** - Recommended for Tailor Platform apps
-2. **Standalone Component** - For custom React apps
-
-### AppShell Module (Recommended)
-
-For Tailor Platform apps using `@tailor-platform/app-shell`:
-
-```typescript
-// src/shared/data-viewer.ts
-import { createDataViewer, createDefaultFetcher } from "@izumisy-tailor/tailor-data-viewer/component";
-import { tableMetadata } from "./generated/table-metadata";
-
-const fetcher = createDefaultFetcher({
-  endpoint: import.meta.env.VITE_APP_URL,
-});
-
-export const DataViewer = createDataViewer({
-  metadata: tableMetadata,
-  fetcher,
-  // Optional: Custom labels for fields and UI text
-  labels: {
-    "Task:status": "ステータス",
-    "$:refresh": "Refresh",
-  },
-});
-```
-
-```typescript
-// src/pages/data-view/index.ts
-import { createDataViewModule } from "@izumisy-tailor/tailor-data-viewer/app-shell";
-import { createIndexedDBStore } from "@izumisy-tailor/tailor-data-viewer/store/indexeddb";
-import { DataViewer } from "../../shared/data-viewer";
-
-export const dataViewModule = createDataViewModule({
-  dataViewer: DataViewer,
-  savedViewStore: createIndexedDBStore(),
-});
-```
-
-```typescript
-// src/app.tsx
-import { AppShell } from "@tailor-platform/app-shell";
-import { dataViewModule } from "./pages/data-view";
-
-export const App = () => (
-  <AppShell
-    modules={[dataViewModule]}
-  />
-);
-```
-
-For detailed options, see [AppShell Module Integration](./docs/app-shell-module.md).
-
-### Standalone Explorer View
-
-For custom React apps without AppShell, use `DataViewer.ExplorerView`. This provides a tab-based UI where users can select tables, create filters, and save views:
+## Quick Start
 
 ```tsx
-// src/lib/data-viewer.ts (create once per app)
-import { createDataViewer, createDefaultFetcher } from "@izumisy-tailor/tailor-data-viewer/component";
-import { createIndexedDBStore } from "@izumisy-tailor/tailor-data-viewer/store/indexeddb";
-import { tableMetadata } from "./generated/table-metadata";
-
-const fetcher = createDefaultFetcher({
-  endpoint: "https://your-app.tailor.tech/graphql",
-});
-
-export const DataViewer = createDataViewer({
-  metadata: tableMetadata,
-  fetcher,
-  // Optional: Custom labels for fields and UI text
-  labels: {
-    "orders:status": "Order Status",
-    "*:createdAt": "Created Date",
-  },
-});
+import {
+  useCollectionParams,
+  useDataTable,
+  CollectionParams,
+  DataTable,
+  Pagination,
+  field,
+  display,
+} from "@izumisy-tailor/tailor-data-viewer/component";
+import "@izumisy-tailor/tailor-data-viewer/styles/theme.css";
 
-export const savedViewStore = createIndexedDBStore();
-```
+// 1. Define columns
+const columns = [
+  field<Order>("name", {
+    label: "Name",
+    sort: { type: "string" },
+    filter: { type: "string" },
+  }),
+  field<Order>("amount", {
+    label: "Amount",
+    sort: { type: "number" },
+    filter: { type: "number" },
+  }),
+  field<Order>("status", {
+    label: "Status",
+    filter: {
+      type: "enum",
+      options: [
+        { value: "DRAFT", label: "Draft" },
+        { value: "APPROVED", label: "Approved" },
+      ],
+    },
+  }),
+  display<Order>("actions", {
+    width: 50,
+    render: (row) => <button onClick={() => handleEdit(row)}>Edit</button>,
+  }),
+];
 
-```tsx
-// src/App.tsx
-import "@izumisy-tailor/tailor-data-viewer/styles/theme.css";
-import { DataViewer, savedViewStore } from "./lib/data-viewer";
+// 2. Build a page
+function OrdersPage() {
+  const params = useCollectionParams({ pageSize: 20 });
+  const [result] = useQuery({ query: GET_ORDERS, variables: params.variables });
 
-function App() {
-  return (
-    <DataViewer.ExplorerView savedViewStore={savedViewStore} />
-  );
-}
+  const table = useDataTable<Order>({
+    columns,
+    data: result.data?.orders,
+    loading: result.fetching,
+    collectionParams: params,
+  });
 
-// With initial view loaded from URL
-function AppWithViewId() {
-  const viewId = useSearchParams().get("viewId") ?? undefined;
   return (
-    <DataViewer.ExplorerView 
-      savedViewStore={savedViewStore} 
-      initialViewId={viewId}
-    />
+    <CollectionParams.Provider value={params}>
+      <DataTable.Root {...table.rootProps}>
+        <DataTable.Headers />
+        <DataTable.Body />
+      </DataTable.Root>
+      <Pagination {...table} />
+    </CollectionParams.Provider>
   );
 }
 ```
 
-For store options, see [Saved View Store](./docs/saved-view-store.md).
+## API Overview
 
-### Compositional API
+### `useCollectionParams(options?)`
 
-For more control over the UI layout and behavior, use the compositional (compound component) API with `createDataViewer`:
+Manages filter, sort, and pagination state. Returns Tailor Platform-compatible `variables` for GraphQL queries.
 
 ```tsx
-// src/shared/data-viewer.ts
-import { createDataViewer, createDefaultFetcher } from "@izumisy-tailor/tailor-data-viewer/component";
-import { tableMetadata } from "./generated/table-metadata";
-
-const fetcher = createDefaultFetcher({
-  endpoint: "https://your-app.tailor.tech",
+const params = useCollectionParams({
+  pageSize: 20,
+  initialSort: [{ field: "createdAt", direction: "Desc" }],
 });
 
-export const DataViewer = createDataViewer({
-  metadata: tableMetadata,
-  fetcher,
-  // Optional: Custom labels and renderers
-  labels: {
-    "User:name": "User Name",
-    "*:createdAt": "Created",
-  },
-});
-```
+// Pass variables to any GraphQL client
+const [result] = useQuery({ query: GET_ORDERS, variables: params.variables });
 
-```tsx
-// src/pages/users/page.tsx
-import { DataViewer } from "../../shared/data-viewer";
-import {
-  DataTable,
-  ColumnSelector,
-  SearchFilterForm,
-  CsvButton,
-  RefreshButton,
-  useDataViewer,
-  useTableDataContext,
-} from "@izumisy-tailor/tailor-data-viewer/component";
+// Filter operations
+params.addFilter("status", "ACTIVE", "eq");
+params.setFilters([{ field: "status", fieldType: "enum", operator: "eq", value: "ACTIVE" }]);
+params.removeFilter("status");
+params.clearFilters();
 
-function CustomDataViewer() {
-  return (
-    <DataViewer.TableDataProvider
-      tableName="User"
-      columns={["id", "name", "email"]}
-      initialData={{
-        sort: { field: "name", direction: "Asc" },
-      }}
-    >
-      <DataViewer.ToolbarProvider>
-        <ColumnSelector />
-        <SearchFilterForm />
-          <CsvButton />
-          <RefreshButton />
-        </DataViewer.ToolbarProvider>
-        <DataTable onRecordClick={(id) => console.log(id)} />
-    </DataViewer.TableDataProvider>
-  );
-}
+// Sort operations
+params.setSort("createdAt", "Desc");
+params.setSort("name", "Asc", true); // append for multi-sort
+params.clearSort();
+
+// Pagination
+params.nextPage(endCursor);
+params.prevPage();
+params.resetPage();
 ```
 
-This approach allows you to:
-- Customize the layout and styling
-- Add your own components alongside Data Viewer components
-- Access internal state via hooks (`useDataViewer`, `useTableDataContext`)
-- Share the same DataViewer instance across multiple pages
+### `CollectionParams.Provider` / `useCollectionParamsContext()`
 
-For detailed documentation, see [Compositional API](./docs/compositional-api.md).
+Shares `useCollectionParams` return value via Context. Child components access it with `useCollectionParamsContext()`.
 
-### About savedViewStore
+```tsx
+<CollectionParams.Provider value={params}>
+  <StatusFilter />   {/* useCollectionParamsContext() inside */}
+  <DataTable.Root {...table.rootProps}>
+    <DataTable.Headers />
+    <DataTable.Body />
+  </DataTable.Root>
+  <Pagination {...table} />
+</CollectionParams.Provider>
+```
 
-`savedViewStore` is a storage implementation for persisting views created in Data Viewer (such as filter settings and column visibility settings). Two built-in stores are provided:
+Provider is optional — for simple cases, pass params directly via props.
 
-- **IndexedDB Store** (`createIndexedDBStore`): Stores data in browser's IndexedDB. Ideal for development, personal use, and offline support
-- **TailorDB Store** (`createTailorDBStore`): Stores data on the server side. Ideal for sharing views across teams
+### Column Definition Helpers
 
-For more details, see [Saved View Store](./docs/saved-view-store.md).
+#### `field(dataKey, options?)`
 
-### Generating Table Metadata
+Defines a data-bound column. Supports sort and filter configuration.
 
-This library includes a custom generator for [Tailor Platform SDK](https://www.npmjs.com/package/@tailor-platform/sdk) that automatically generates table metadata from your TailorDB schema.
+```tsx
+field("name", {
+  label: "Name",
+  sort: { type: "string" },
+  filter: { type: "string" },
+  renderer: ({ value }) => <strong>{value}</strong>,
+})
+```
 
-#### Setup
+#### `display(id, options)`
 
-1. Install the generator package in your Tailor Platform SDK project:
+Defines a render-only column (no sort/filter).
 
-```bash
-npm install @izumisy-tailor/tailor-data-viewer
+```tsx
+display("actions", {
+  width: 50,
+  render: (row) => <ActionMenu row={row} />,
+})
 ```
 
-2. Configure the generator in your `tailor.config.ts`:
+### 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 `inferColumnHelper()` for automatic sort/filter configuration.
+
+1. Configure the generator in your `tailor.config.ts`:
 
 ```typescript
 import { defineConfig, defineGenerators } from "@tailor-platform/sdk";
@@ -251,7 +198,6 @@ export const generators = defineGenerators(
   dataViewerMetadataGenerator({
     distPath: "src/generated/data-viewer-metadata.generated.ts",
   }),
-  // ... other generators
 );
 
 export default defineConfig({
@@ -260,30 +206,202 @@ export default defineConfig({
 });
 ```
 
-3. Run the generator:
+2. Run the generator:
 
 ```bash
 tailor-sdk generate
 ```
 
-This will generate a metadata file at the specified `distPath` containing type-safe metadata for all your TailorDB types, including fields, relations, and role-based access control settings.
+### `inferColumnHelper(metadata, tableName)`
+
+`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 { inferColumnHelper, display } from "@izumisy-tailor/tailor-data-viewer/component";
+import { tableMetadata } from "./generated/data-viewer-metadata.generated";
+
+const { column, columns } = inferColumnHelper(tableMetadata, "task");
+
+const taskColumns = [
+  column("title"),                     // sort/filter auto-configured from metadata
+  column("status"),                    // enum options auto-derived
+  column("dueDate"),                   // date type auto-detected
+  column("priority", { sort: false }), // override: disable sort
+  ...columns(["name", "email"]),       // batch definition
+  display("actions", {
+    render: (row) => <ActionMenu row={row} />,
+  }),
+];
+```
+
+`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)`
+
+Integrates data, column visibility, row operations, and props generators.
+
+```tsx
+const table = useDataTable<Order>({
+  columns,
+  data: result.data?.orders,   // CollectionResult<Order>
+  loading: result.fetching,
+  error: result.error,
+  collectionParams: params,
+});
 
-## API Reference
+// Spread props to components
+<DataTable.Root {...table.rootProps}>...</DataTable.Root>
+<ColumnSelector {...table} />
+<CsvButton {...table} />
+<Pagination {...table} />
+
+// Column visibility
+table.toggleColumn("amount");
+table.showAllColumns();
+table.hideAllColumns();
+table.isColumnVisible("amount");
+
+// Optimistic updates
+const { rollback } = table.updateRow(rowId, { status: "APPROVED" });
+const { rollback, deletedRow } = table.deleteRow(rowId);
+const { rollback } = table.insertRow(newRow);
+```
+
+### `Table.*` — Static Table Components
+
+Low-level table primitives without data binding. Use for fully custom layouts or skeleton loading.
+
+```tsx
+<Table.Root>
+  <Table.Headers>
+    <Table.HeaderRow>
+      <Table.HeaderCell>Name</Table.HeaderCell>
+      <Table.HeaderCell>Status</Table.HeaderCell>
+    </Table.HeaderRow>
+  </Table.Headers>
+  <Table.Body>
+    <Table.Row>
+      <Table.Cell>Order A</Table.Cell>
+      <Table.Cell>Approved</Table.Cell>
+    </Table.Row>
+  </Table.Body>
+</Table.Root>
+```
 
-See [API.md](API.md) for detailed API documentation including components, hooks, and types.
+### `DataTable.*` — Data-bound Table Components
+
+Pair with `useDataTable` for automatic header sorting, cell rendering, and row operations.
+
+```tsx
+// Basic usage (spread rootProps)
+<DataTable.Root {...table.rootProps}>
+  <DataTable.Headers />
+  <DataTable.Body />
+</DataTable.Root>
+
+// Custom row rendering
+<DataTable.Root {...table.rootProps}>
+  <DataTable.Headers />
+  <DataTable.Body>
+    {table.rows.map((row, rowIndex) => (
+      <DataTable.Row
+        key={row.id}
+        {...table.getRowProps(row)}
+        onClick={() => navigate(`/orders/${row.id}`)}
+      >
+        {table.visibleColumns.map((col) => (
+          <DataTable.Cell key={col.id} {...table.getCellProps(row, col, rowIndex)} />
+        ))}
+      </DataTable.Row>
+    ))}
+  </DataTable.Body>
+</DataTable.Root>
+```
+
+### Utility Components
+
+All utility components are props-based and designed to be used with spread from `useDataTable` / `useCollectionParams`.
+
+| Component | Spread from | Description |
+|-----------|------------|-------------|
+| `ColumnSelector` | `{...table}` | Column visibility toggle UI |
+| `CsvButton` | `{...table}` | Export visible data as CSV |
+| `SearchFilterForm` | `{...table, ...params}` | Multi-field filter form with operator selection |
+| `Pagination` | `{...table}` | Previous/Next page controls |
+
+```tsx
+<SearchFilterForm {...table} {...params} />
+<ColumnSelector {...table} />
+<CsvButton {...table} filename="orders-export" />
+<Pagination {...table} />
+```
+
+### Optimistic Updates in Cell Renderers
+
+Use `useDataTableContext()` inside `DataTable.Root` to access row operations from custom cell renderers.
+
+```tsx
+const StatusEditor: CellRenderer<Order> = ({ value, row }) => {
+  const { updateRow } = useDataTableContext<Order>();
+  const [updateOrder] = useMutation(UPDATE_ORDER);
+
+  const handleChange = async (newStatus: string) => {
+    const { rollback } = updateRow(row.id, { status: newStatus });
+    try {
+      await updateOrder({ id: row.id, input: { status: newStatus } });
+    } catch (error) {
+      rollback();
+    }
+  };
+
+  return <StatusSelect value={value} onChange={handleChange} />;
+};
+```
+
+### Relation Fields
+
+Use `display()` with GraphQL query expansion to show relation data.
+
+```tsx
+// Include relations in your GraphQL query
+const GET_MEMBERSHIPS = graphql(`
+  query SupplierGroupMemberships {
+    supplierGroupMemberships {
+      edges {
+        node {
+          id
+          supplier { companyName, contactName }
+          addedBy { name }
+          createdAt
+        }
+      }
+    }
+  }
+`);
+
+// Display relation fields with display()
+const columns = [
+  display("supplierCompanyName", {
+    label: "Company",
+    render: (row) => row.supplier?.companyName ?? "-",
+  }),
+  display("addedByName", {
+    label: "Added By",
+    render: (row) => row.addedBy?.name ?? "-",
+  }),
+  field("createdAt", { label: "Created", sort: { type: "date" } }),
+];
+```
 
 ## Styling
 
-The library uses Tailwind CSS classes. Import the base theme or provide your own CSS variables:
+The library uses Tailwind CSS classes. Import the included theme or provide your own CSS variables:
 
 ```css
 /* Option 1: Import included theme */
 @import "@izumisy-tailor/tailor-data-viewer/styles/theme.css";
 
-/* Option 2: Use with Tailor app-shell */
-@import "@tailor-platform/app-shell/theme.css";
-
-/* Option 3: Define your own CSS variables */
+/* Option 2: Define your own CSS variables */
 :root {
   --background: 0 0% 100%;
   --foreground: 222.2 84% 4.9%;
@@ -292,6 +410,14 @@ The library uses Tailwind CSS classes. Import the base theme or provide your own
 }
 ```
 
+## Exports
+
+| Entry Point | Description |
+|-------------|-------------|
+| `@izumisy-tailor/tailor-data-viewer/component` | Hooks, components, helpers, and types |
+| `@izumisy-tailor/tailor-data-viewer/generator` | Metadata generator for Tailor SDK |
+| `@izumisy-tailor/tailor-data-viewer/styles` | CSS theme file |
+
 ## Development
 
 See the [Development Guide](./DEVELOPMENT.md) for setup and contribution instructions.

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "@izumisy-tailor/tailor-data-viewer",
   "private": false,
-  "version": "0.2.0",
+  "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>;
 }
 
 /**