@izumisy-tailor/tailor-data-viewer 0.1.21 → 0.1.22

package/README.md

@@ -88,7 +88,7 @@ function App() {
   return (
     <SavedViewProvider store={store}>
       <DataViewer
-        tableMetadata={tableMetadata}
+        metadata={tableMetadata}
         appUri="https://your-app.tailor.tech/graphql"
       />
     </SavedViewProvider>
@@ -98,6 +98,50 @@ function App() {
 
 For store options, see [Saved View Store](./docs/saved-view-store.md).
 
+### Compositional API
+
+For more control over the UI layout and behavior, use the compositional (compound component) API:
+
+```tsx
+import {
+  DataViewerProvider,
+  TableDataProvider,
+  ToolbarProvider,
+  DataTable,
+  ColumnSelector,
+  SearchFilterForm,
+  CsvButton,
+  RefreshButton,
+} from "@izumisy-tailor/tailor-data-viewer/component";
+
+function CustomDataViewer() {
+  return (
+    <DataViewerProvider
+      tableName="User"
+      metadata={tableMetadata}
+      appUri="https://your-app.tailor.tech"
+    >
+      <TableDataProvider>
+        <ToolbarProvider>
+          <ColumnSelector />
+          <SearchFilterForm />
+          <CsvButton />
+          <RefreshButton />
+        </ToolbarProvider>
+        <DataTable onRecordClick={(id) => console.log(id)} />
+      </TableDataProvider>
+    </DataViewerProvider>
+  );
+}
+```
+
+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`)
+
+For detailed documentation, see [Compositional API](./docs/compositional-api.md).
+
 ### About savedViewStore
 
 `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:

package/dist/generator/index.d.mts

@@ -7,51 +7,74 @@ type FieldType = "string" | "number" | "boolean" | "uuid" | "datetime" | "date"
  * Metadata for a single field
  */
 interface FieldMetadata {
-  name: string;
-  type: FieldType;
-  required: boolean;
-  enumValues?: readonly string[];
-  arrayItemType?: FieldType;
-  description?: string;
+  readonly name: string;
+  readonly type: FieldType;
+  readonly required: boolean;
+  readonly enumValues?: readonly string[];
+  readonly arrayItemType?: FieldType;
+  readonly description?: string;
   /** manyToOne relation info (if this field is a foreign key) */
-  relation?: {
-    /** GraphQL field name for the related object (e.g., "task") */fieldName: string; /** Target table name in camelCase (e.g., "task") */
-    targetTable: string;
+  readonly relation?: {
+    /** GraphQL field name for the related object (e.g., "task") */readonly fieldName: string; /** Target table name in camelCase (e.g., "task") */
+    readonly targetTable: string;
   };
 }
 /**
- * Metadata for a relation
+ * Base properties shared by all relation types
  */
-interface RelationMetadata {
-  /** GraphQL field name (e.g., "task" for manyToOne, "taskAssignments" for oneToMany) */
-  fieldName: string;
+interface RelationMetadataBase {
+  /** GraphQL field name (e.g., "task" for manyToOne/oneToOne, "taskAssignments" for oneToMany) */
+  readonly fieldName: string;
   /** Target table name in camelCase (e.g., "task", "taskAssignment") */
-  targetTable: string;
-  /** Relation type */
-  relationType: "manyToOne" | "oneToMany";
-  /** For manyToOne: the FK field name (e.g., "taskId"). For oneToMany: the FK field on the child table */
-  foreignKeyField: string;
-  /** For manyToOne: the backward field name on the target type (used to generate oneToMany relation) */
-  backwardFieldName?: string;
-  /** True if this is a oneToOne relation (no inverse oneToMany should be generated) */
-  isOneToOne?: boolean;
+  readonly targetTable: string;
+  /** The FK field name (e.g., "taskId") */
+  readonly foreignKeyField: string;
+}
+/**
+ * ManyToOne relation: this table has a FK pointing to another table
+ * Generates an inverse oneToMany relation on the target table
+ */
+interface ManyToOneRelation extends RelationMetadataBase {
+  readonly relationType: "manyToOne";
+  /** The backward field name on the target type (used to generate oneToMany relation) */
+  readonly backwardFieldName?: string;
 }
+/**
+ * OneToOne relation: this table has a FK pointing to another table (1:1)
+ * Does NOT generate an inverse oneToMany relation
+ */
+interface OneToOneRelation extends RelationMetadataBase {
+  readonly relationType: "oneToOne";
+}
+/**
+ * OneToMany relation: another table has a FK pointing to this table
+ * Generated automatically from manyToOne relations
+ */
+interface OneToManyRelation extends RelationMetadataBase {
+  readonly relationType: "oneToMany";
+}
+/**
+ * Metadata for a relation (discriminated union)
+ */
+type RelationMetadata = ManyToOneRelation | OneToOneRelation | OneToManyRelation;
 /**
  * Metadata for a single table
  */
 interface TableMetadata {
-  name: string;
-  pluralForm: string;
-  description?: string;
-  readAllowedRoles: string[];
-  fields: FieldMetadata[];
-  /** Relations (manyToOne and oneToMany) */
-  relations?: RelationMetadata[];
+  readonly name: string;
+  readonly pluralForm: string;
+  readonly description?: string;
+  readonly readAllowedRoles: readonly string[];
+  readonly fields: readonly FieldMetadata[];
+  /** Relations (manyToOne, oneToOne, and oneToMany) */
+  readonly relations?: readonly RelationMetadata[];
 }
 /**
  * Map of all tables
  */
-type TableMetadataMap = Record<string, TableMetadata>;
+type TableMetadataMap = {
+  readonly [key: string]: TableMetadata;
+};
 /**
  * Expanded relation fields configuration
  * Key: relation field name (e.g., "task")
@@ -209,4 +232,4 @@ declare const tableMetadataGenerator: {
   }): GeneratorResult;
 };
 //#endregion
-export { DataViewerMetadataGeneratorOptions, ExpandedRelationFields, FieldMetadata, FieldType, RelationMetadata, TableMetadata, TableMetadataMap, dataViewerMetadataGenerator, tableMetadataGenerator as default, tableMetadataGenerator };
+export { DataViewerMetadataGeneratorOptions, ExpandedRelationFields, FieldMetadata, FieldType, ManyToOneRelation, OneToManyRelation, OneToOneRelation, RelationMetadata, TableMetadata, TableMetadataMap, dataViewerMetadataGenerator, tableMetadataGenerator as default, tableMetadataGenerator };

package/dist/generator/index.mjs

@@ -62,33 +62,41 @@ function dataViewerMetadataGenerator(options = {}) {
 			for (const [fieldName, field] of Object.entries(type.fields)) {
 				const config = field.config;
 				const { type: fieldType, arrayItemType } = mapFieldType(config.type, config.array);
-				const fieldMetadata = {
-					name: fieldName,
-					type: fieldType,
-					required: config.required ?? false,
-					description: config.description
-				};
-				if (config.allowedValues && config.allowedValues.length > 0) fieldMetadata.enumValues = config.allowedValues.map((v) => typeof v === "string" ? v : v.value);
-				if (arrayItemType) fieldMetadata.arrayItemType = arrayItemType;
 				const rawRelation = config.rawRelation;
 				const isManyToOneRelation = rawRelation && (rawRelation.type === "manyToOne" || rawRelation.type === "n-1" || rawRelation.type === "oneToOne" || rawRelation.type === "1-1") && rawRelation.toward;
 				const isOneToOne = rawRelation?.type === "oneToOne" || rawRelation?.type === "1-1";
+				let fieldRelation;
 				if (isManyToOneRelation && rawRelation.toward) {
 					const targetTableName = toCamelCase(rawRelation.toward.type);
 					const relationFieldName = rawRelation.toward.as ?? toCamelCase(rawRelation.toward.type);
-					fieldMetadata.relation = {
+					fieldRelation = {
 						fieldName: relationFieldName,
 						targetTable: targetTableName
 					};
-					relations.push({
+					if (isOneToOne) relations.push({
+						fieldName: relationFieldName,
+						targetTable: targetTableName,
+						relationType: "oneToOne",
+						foreignKeyField: fieldName
+					});
+					else relations.push({
 						fieldName: relationFieldName,
 						targetTable: targetTableName,
 						relationType: "manyToOne",
 						foreignKeyField: fieldName,
-						backwardFieldName: rawRelation.backward,
-						isOneToOne
+						backwardFieldName: rawRelation.backward
 					});
 				}
+				const enumValues = config.allowedValues && config.allowedValues.length > 0 ? config.allowedValues.map((v) => typeof v === "string" ? v : v.value) : void 0;
+				const fieldMetadata = {
+					name: fieldName,
+					type: fieldType,
+					required: config.required ?? false,
+					...config.description && { description: config.description },
+					...enumValues && { enumValues },
+					...arrayItemType && { arrayItemType },
+					...fieldRelation && { relation: fieldRelation }
+				};
 				fields.push(fieldMetadata);
 			}
 			const readAllowedRoles = extractReadAllowedRoles(type.permissions.gql);
@@ -116,7 +124,6 @@ function dataViewerMetadataGenerator(options = {}) {
 			const tableByOriginalName = /* @__PURE__ */ new Map();
 			for (const table of allTables) tableByOriginalName.set(table.originalName, table);
 			for (const table of allTables) for (const relation of table.relations) if (relation.relationType === "manyToOne") {
-				if (relation.isOneToOne) continue;
 				const targetTable = tableByOriginalName.get(relation.targetTable.charAt(0).toUpperCase() + relation.targetTable.slice(1));
 				if (targetTable) {
 					const oneToManyFieldName = relation.backwardFieldName ?? table.pluralForm;

package/docs/compositional-api.md

@@ -0,0 +1,366 @@
+# Compositional Component API
+
+Data Viewer provides a compositional (compound component) API that allows you to build custom data viewing interfaces by composing individual components. This approach gives you full control over the layout and behavior of your data viewer.
+
+## Overview
+
+The compositional API is built around React Context providers that share state between components:
+
+```
+DataViewerProvider          ← Metadata, column state, filters
+  └── TableDataProvider     ← Data fetching, pagination, sorting
+        └── ToolbarProvider ← Toolbar panel state (exclusive open/close)
+              └── Components (ColumnSelector, SearchFilterForm, etc.)
+```
+
+## Quick Start
+
+```tsx
+import {
+  DataViewerProvider,
+  TableDataProvider,
+  ToolbarProvider,
+  DataTable,
+  ColumnSelector,
+  SearchFilterForm,
+  CsvButton,
+  RefreshButton,
+} from "@izumisy-tailor/tailor-data-viewer/component";
+import { tableMetadata } from "./generated/table-metadata";
+
+function MyDataViewer() {
+  return (
+    <DataViewerProvider
+      tableName="User"
+      metadata={tableMetadata}
+      appUri="https://your-app.tailor.tech"
+    >
+      <TableDataProvider>
+        {/* Toolbar */}
+        <ToolbarProvider>
+          <div className="flex gap-2 mb-4">
+            <ColumnSelector />
+            <SearchFilterForm />
+            <CsvButton />
+            <RefreshButton />
+          </div>
+        </ToolbarProvider>
+        
+        {/* Data Table */}
+        <DataTable onRecordClick={(id) => console.log("Clicked:", id)} />
+      </TableDataProvider>
+    </DataViewerProvider>
+  );
+}
+```
+
+## Providers
+
+### DataViewerProvider
+
+The root provider that manages metadata, column state, and filters.
+
+```tsx
+interface DataViewerProviderProps {
+  children: ReactNode;
+  /** Table name to display */
+  tableName: string;
+  /** All table metadata (generated from TailorDB schema) */
+  metadata: TableMetadataMap;
+  /** App URI for GraphQL endpoint */
+  appUri: string;
+  /** Initial data for filters, selected fields, and relations */
+  initialData?: DataViewerInitialData;
+}
+
+interface DataViewerInitialData {
+  filters?: SearchFilters;
+  selectedFields?: string[];
+  selectedRelations?: string[];
+  expandedRelationFields?: ExpandedRelationFields;
+}
+```
+
+**Example:**
+
+```tsx
+<DataViewerProvider
+  tableName="Task"
+  metadata={tableMetadata}
+  appUri="https://your-app.tailor.tech"
+  initialData={{
+    filters: [{ field: "status", fieldType: "enum", value: "active" }],
+    selectedFields: ["id", "title", "status", "createdAt"],
+    selectedRelations: ["assignee"],
+    expandedRelationFields: { assignee: ["name", "email"] },
+  }}
+>
+  {children}
+</DataViewerProvider>
+```
+
+### TableDataProvider
+
+Handles data fetching, pagination, and sorting. Must be a child of `DataViewerProvider`.
+
+```tsx
+<DataViewerProvider {...props}>
+  <TableDataProvider>
+    {/* Components that need data access */}
+  </TableDataProvider>
+</DataViewerProvider>
+```
+
+### ToolbarProvider
+
+Manages exclusive panel state for toolbar components (only one panel can be open at a time). 
+
+```tsx
+<ToolbarProvider>
+  <ColumnSelector />    {/* Opens column selection panel */}
+  <SearchFilterForm />  {/* Opens search filter panel */}
+  <CsvButton />         {/* No panel, just action */}
+  <RefreshButton />     {/* No panel, just action */}
+</ToolbarProvider>
+```
+
+## Components
+
+### DataTable
+
+Displays data in a sortable table with expandable relation cells.
+
+```tsx
+interface DataTableProps {
+  /** Callback when a record row is clicked */
+  onRecordClick?: (recordId: string) => void;
+  /** Callback to open a relation as a new sheet */
+  onOpenAsSheet?: (tableName: string, filterField: string, filterValue: string) => void;
+  /** Callback to open a single record as a new sheet */
+  onOpenSingleRecordAsSheet?: (tableName: string, recordId: string) => void;
+}
+```
+
+**Example:**
+
+```tsx
+<DataTable
+  onRecordClick={(id) => navigate(`/records/${id}`)}
+  onOpenAsSheet={(table, field, value) => openNewTab(table, field, value)}
+/>
+```
+
+### ColumnSelector
+
+Dropdown for selecting visible columns and relation fields.
+
+```tsx
+<ToolbarProvider>
+  <ColumnSelector />
+</ToolbarProvider>
+```
+
+Features:
+- Select/deselect individual fields
+- Select all / Deselect all
+- ManyToOne relation field expansion (inline columns)
+- OneToMany relation selection (expandable rows)
+
+### SearchFilterForm
+
+Form for adding search filters with AND logic.
+
+```tsx
+<ToolbarProvider>
+  <SearchFilterForm />
+</ToolbarProvider>
+```
+
+Features:
+- Supports string, number, boolean, enum, and UUID fields
+- Multiple filters with AND logic
+- Remove individual filters
+
+### CsvButton
+
+Downloads current view data as CSV.
+
+```tsx
+<TableDataProvider>
+  <CsvButton />
+</TableDataProvider>
+```
+
+### RefreshButton
+
+Refetches current data.
+
+```tsx
+<TableDataProvider>
+  <RefreshButton />
+</TableDataProvider>
+```
+
+Can also be used outside TableDataProvider with explicit props:
+
+```tsx
+<RefreshButton loading={isLoading} refetch={handleRefetch} />
+```
+
+## Hooks
+
+### useDataViewer
+
+Access the DataViewer context values.
+
+```tsx
+const {
+  tableMetadata,
+  metadata,
+  appUri,
+  selectedFields,
+  toggleField,
+  selectAllFields,
+  deselectAllFields,
+  selectedRelations,
+  toggleRelation,
+  expandedRelationFields,
+  filters,
+  setFilters,
+  refetch,
+} = useDataViewer();
+```
+
+### useTableDataContext
+
+Access data fetching state and pagination controls.
+
+```tsx
+const {
+  data,
+  loading,
+  error,
+  sortState,
+  setSort,
+  pagination,
+  hasPreviousPage,
+  nextPage,
+  previousPage,
+} = useTableDataContext();
+```
+
+### useToolbar
+
+Access toolbar panel state.
+
+```tsx
+const {
+  activePanel,      // "column" | "search" | null
+  setActivePanel,
+} = useToolbar();
+```
+
+## Advanced Examples
+
+### Custom Toolbar Layout
+
+```tsx
+function CustomToolbar() {
+  return (
+    <ToolbarProvider>
+      <div className="flex justify-between items-center p-4 border-b">
+        <div className="flex gap-2">
+          <ColumnSelector />
+          <SearchFilterForm />
+        </div>
+        <div className="flex gap-2">
+          <CsvButton />
+          <RefreshButton />
+        </div>
+      </div>
+    </ToolbarProvider>
+  );
+}
+```
+
+### Building a Custom Filter Display
+
+```tsx
+function ActiveFilters() {
+  const { filters, setFilters } = useDataViewer();
+
+  const removeFilter = (fieldName: string) => {
+    setFilters(filters.filter(f => f.field !== fieldName));
+  };
+
+  return (
+    <div className="flex gap-2">
+      {filters.map(filter => (
+        <Badge key={filter.field}>
+          {filter.field}: {filter.value}
+          <button onClick={() => removeFilter(filter.field)}>×</button>
+        </Badge>
+      ))}
+    </div>
+  );
+}
+```
+
+### Custom Data Display
+
+```tsx
+function CardView() {
+  const { tableMetadata, selectedFields } = useDataViewer();
+  const { data, loading } = useTableDataContext();
+
+  if (loading) return <Spinner />;
+
+  return (
+    <div className="grid grid-cols-3 gap-4">
+      {data.map(record => (
+        <Card key={record.id as string}>
+          {selectedFields.map(field => (
+            <div key={field}>
+              <strong>{field}:</strong> {String(record[field])}
+            </div>
+          ))}
+        </Card>
+      ))}
+    </div>
+  );
+}
+```
+
+### Combining with External State
+
+```tsx
+function DataViewerWithExternalState() {
+  const [selectedRecordId, setSelectedRecordId] = useState<string | null>(null);
+
+  return (
+    <div className="flex">
+      <div className="w-2/3">
+        <DataViewerProvider
+          tableName="Task"
+          metadata={tableMetadata}
+          appUri={appUri}
+        >
+          <TableDataProvider>
+            <ToolbarProvider>
+              <ColumnSelector />
+              <SearchFilterForm />
+            </ToolbarProvider>
+            <DataTable onRecordClick={setSelectedRecordId} />
+          </TableDataProvider>
+        </DataViewerProvider>
+      </div>
+      
+      <div className="w-1/3">
+        {selectedRecordId && (
+          <RecordDetailPanel recordId={selectedRecordId} />
+        )}
+      </div>
+    </div>
+  );
+}
+```

package/package.json

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

package/src/app-shell/create-data-view-module.tsx

@@ -67,7 +67,7 @@ export function createDataViewModule(config: DataViewModuleConfig) {
     return (
       <SavedViewProvider store={store}>
         <DataViewer
-          tableMetadata={tableMetadata}
+          metadata={tableMetadata}
           appUri={appUri}
           initialViewId={viewId}
         />