@izumisy-tailor/tailor-data-viewer 0.2.6 → 0.2.8

package/README.md

@@ -5,8 +5,8 @@ A low-level React component library for building data table interfaces with Tail
 ## Features
 
 - **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
+- **`useCollection` Hook**: Manages filter, sort, and pagination state; outputs Tailor Platform-compatible GraphQL variables
+- **`Collection.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
@@ -15,7 +15,7 @@ A low-level React component library for building data table interfaces with Tail
 - **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.
+- **Presentation Agnostic**: Same `useCollection` can drive tables, kanbans, calendars, etc.
 
 ## Installation
 
@@ -47,9 +47,9 @@ npm install react react-dom
 
 ```tsx
 import {
-  useCollectionParams,
+  useCollection,
   useDataTable,
-  CollectionParams,
+  Collection,
   DataTable,
   Pagination,
   field,
@@ -87,73 +87,76 @@ const columns = [
 
 // 2. Build a page
 function OrdersPage() {
-  const params = useCollectionParams({ pageSize: 20 });
-  const [result] = useQuery({ query: GET_ORDERS, variables: params.variables });
+  const collection = useCollection({ query: GET_ORDERS, params: { pageSize: 20 } });
+  const [result] = useQuery({ ...collection.toQueryArgs() });
 
   const table = useDataTable<Order>({
     columns,
     data: result.data?.orders,
     loading: result.fetching,
-    collectionParams: params,
+    collection,
   });
 
   return (
-    <CollectionParams.Provider value={params}>
+    <Collection.Provider value={collection}>
       <DataTable.Root {...table.rootProps}>
         <DataTable.Headers />
         <DataTable.Body />
       </DataTable.Root>
       <Pagination {...table} />
-    </CollectionParams.Provider>
+    </Collection.Provider>
   );
 }
 ```
 
 ## API Overview
 
-### `useCollectionParams(options?)`
+### `useCollection(options)`
 
-Manages filter, sort, and pagination state. Returns Tailor Platform-compatible `variables` for GraphQL queries.
+Manages filter, sort, and pagination state. Returns `toQueryArgs()` which produces Tailor Platform-compatible arguments for `useQuery()`.
 
 ```tsx
-const params = useCollectionParams({
-  pageSize: 20,
-  initialSort: [{ field: "createdAt", direction: "Desc" }],
+const collection = useCollection({
+  query: GET_ORDERS,
+  params: {
+    pageSize: 20,
+    initialSort: [{ field: "createdAt", direction: "Desc" }],
+  },
 });
 
-// Pass variables to any GraphQL client
-const [result] = useQuery({ query: GET_ORDERS, variables: params.variables });
+// Spread toQueryArgs() into useQuery
+const [result] = useQuery({ ...collection.toQueryArgs() });
 
 // Filter operations
-params.addFilter("status", "ACTIVE", "eq");
-params.setFilters([{ field: "status", fieldType: "enum", operator: "eq", value: "ACTIVE" }]);
-params.removeFilter("status");
-params.clearFilters();
+collection.addFilter("status", "ACTIVE", "eq");
+collection.setFilters([{ field: "status", fieldType: "enum", operator: "eq", value: "ACTIVE" }]);
+collection.removeFilter("status");
+collection.clearFilters();
 
 // Sort operations
-params.setSort("createdAt", "Desc");
-params.setSort("name", "Asc", true); // append for multi-sort
-params.clearSort();
+collection.setSort("createdAt", "Desc");
+collection.setSort("name", "Asc", true); // append for multi-sort
+collection.clearSort();
 
 // Pagination
-params.nextPage(endCursor);
-params.prevPage();
-params.resetPage();
+collection.nextPage(endCursor);
+collection.prevPage();
+collection.resetPage();
 ```
 
-### `CollectionParams.Provider` / `useCollectionParamsContext()`
+### `Collection.Provider` / `useCollectionContext()`
 
-Shares `useCollectionParams` return value via Context. Child components access it with `useCollectionParamsContext()`.
+Shares `useCollection` return value via Context. Child components access it with `useCollectionContext()`.
 
 ```tsx
-<CollectionParams.Provider value={params}>
-  <StatusFilter />   {/* useCollectionParamsContext() inside */}
+<Collection.Provider value={collection}>
+  <StatusFilter />   {/* useCollectionContext() inside */}
   <DataTable.Root {...table.rootProps}>
     <DataTable.Headers />
     <DataTable.Body />
   </DataTable.Root>
   <Pagination {...table} />
-</CollectionParams.Provider>
+</Collection.Provider>
 ```
 
 Provider is optional — for simple cases, pass params directly via props.
@@ -246,7 +249,7 @@ const table = useDataTable<Order>({
   data: result.data?.orders,   // CollectionResult<Order>
   loading: result.fetching,
   error: result.error,
-  collectionParams: params,
+  collection,
 });
 
 // Spread props to components
@@ -320,17 +323,17 @@ Pair with `useDataTable` for automatic header sorting, cell rendering, and row o
 
 ### Utility Components
 
-All utility components are props-based and designed to be used with spread from `useDataTable` / `useCollectionParams`.
+All utility components are props-based and designed to be used with spread from `useDataTable` / `useCollection`.
 
 | 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 |
+| `SearchFilterForm` | `{...table, ...collection}` | Multi-field filter form with operator selection |
 | `Pagination` | `{...table}` | Previous/Next page controls |
 
 ```tsx
-<SearchFilterForm {...table} {...params} />
+<SearchFilterForm {...table} {...collection} />
 <ColumnSelector {...table} />
 <CsvButton {...table} filename="orders-export" />
 <Pagination {...table} />

package/package.json

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

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

@@ -0,0 +1,90 @@
+import { createContext, useContext, type ReactNode } from "react";
+import type { UseCollectionReturn } from "../types";
+
+const CollectionContext = createContext<UseCollectionReturn<
+  string,
+  unknown,
+  unknown
+> | null>(null);
+
+/**
+ * Provider that shares collection query parameters via React Context.
+ *
+ * @example
+ * ```tsx
+ * const collection = useCollection({ params: { pageSize: 20 } });
+ *
+ * <CollectionProvider value={collection}>
+ *   <FilterPanel />
+ *   <DataTable.Root {...table.rootProps}>...</DataTable.Root>
+ *   <Pagination {...table} />
+ * </CollectionProvider>
+ * ```
+ */
+export function CollectionProvider({
+  value,
+  children,
+}: {
+  value: UseCollectionReturn<string, unknown, unknown>;
+  children: ReactNode;
+}) {
+  return (
+    <CollectionContext.Provider value={value}>
+      {children}
+    </CollectionContext.Provider>
+  );
+}
+
+
+
+/**
+ * Hook to access collection state from the nearest `Collection.Provider`.
+ *
+ * Returns the same interface as `useCollection()`.  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 `Collection.Provider`.
+ *
+ * @example
+ * ```tsx
+ * function StatusFilter() {
+ *   const { filters, addFilter, removeFilter } = useCollectionContext();
+ *   // ...
+ * }
+ *
+ * // With typed field names:
+ * type TaskField = FieldName<typeof tableMetadata, "task">;
+ * const { addFilter } = useCollectionContext<TaskField>();
+ * ```
+ */
+export function useCollectionContext<
+  TFieldName extends string = string,
+>(): UseCollectionReturn<TFieldName> {
+  const ctx = useContext(CollectionContext);
+  if (!ctx) {
+    throw new Error(
+      "useCollectionContext must be used within <Collection.Provider>",
+    );
+  }
+  return ctx as UseCollectionReturn<TFieldName>;
+}
+
+
+
+/**
+ * `Collection` namespace object providing the Provider component.
+ *
+ * @example
+ * ```tsx
+ * <Collection.Provider value={collection}>
+ *   ...
+ * </Collection.Provider>
+ * ```
+ */
+export const Collection = {
+  Provider: CollectionProvider,
+} as const;
+
+