@izumisy-tailor/tailor-data-viewer 0.1.41 → 0.1.42

package/README.md

@@ -183,8 +183,8 @@ function CustomDataViewer() {
   return (
     <DataViewer.TableDataProvider
       tableName="User"
+      columns={["id", "name", "email"]}
       initialData={{
-        selectedFields: ["id", "name", "email"],
         sort: { field: "name", direction: "Asc" },
       }}
     >

package/docs/README.md

@@ -12,6 +12,7 @@ Documentation for `@izumisy-tailor/tailor-data-viewer`.
 
 ## Configuration
 
+- [Column Definition API](columns.md) - Flexible column definition with width, renderers, and relation fields
 - [GraphQL Fetcher](fetcher.md) - GraphQL fetcher configuration and custom implementation
 - [Custom Labels](labels.md) - Customizing field names, table names, and UI text (i18n support)
 - [Custom Renderers](custom-renderers.md) - Custom cell renderers and built-in renderers

package/docs/columns.md

@@ -0,0 +1,276 @@
+# Column Definition API
+
+The Column Definition API provides a flexible way to define columns displayed in DataViewer. It supports various levels of definition, from simple field name arrays to detailed configurations including width and renderers.
+
+## Overview
+
+Use the `columns` property to specify which columns to display and their settings.
+
+```tsx
+const { TableDataProvider, ToolbarProvider, DataTable } = createDataViewer({
+  metadata,
+  fetcher,
+});
+
+// Simple usage
+<TableDataProvider tableName="task" columns={["title", "status", "createdAt"]}>
+  ...
+</TableDataProvider>
+
+// Detailed configuration
+<TableDataProvider
+  tableName="task"
+  columns={[
+    "title",
+    ["status", { width: 100 }],
+    ["assignee.name", { label: "Assignee" }],
+    { field: "description", width: 300, renderer: MyCustomRenderer },
+  ]}
+>
+  ...
+</TableDataProvider>
+```
+
+## ColumnDef Type
+
+Column definitions support four levels:
+
+### Level 1: Field Path (String)
+
+The simplest form. Specify the field name as a string.
+
+```typescript
+type ColumnDef = string;
+
+// Example
+const columns = ["id", "title", "status"];
+```
+
+### Level 2a: Tuple (Field Path + Renderer)
+
+Use when specifying a custom renderer.
+
+```typescript
+type ColumnDef = [FieldPath, CellRenderer];
+
+// Example
+const columns = [
+  ["status", StatusBadgeRenderer],
+  ["priority", PriorityRenderer],
+];
+```
+
+### Level 2b: Tuple (Field Path + Options)
+
+Use when specifying options like width or label.
+
+```typescript
+type ColumnDef = [FieldPath, ColumnOptions];
+
+// Example
+const columns = [
+  ["title", { width: 200, label: "Title" }],
+  ["description", { minWidth: 100, maxWidth: 400 }],
+];
+```
+
+### Level 3: Object Form
+
+The complete form that allows explicit specification of all options.
+
+```typescript
+type ColumnDef = ColumnDefinition;
+
+interface ColumnDefinition {
+  /** Field path (can specify relation fields using dot notation) */
+  field: FieldPath;
+  /** Column width (number or string) */
+  width?: number | string;
+  /** Minimum width */
+  minWidth?: number | string;
+  /** Maximum width */
+  maxWidth?: number | string;
+  /** Custom cell renderer */
+  renderer?: CellRenderer;
+  /** Column header label */
+  label?: string;
+}
+
+// Example
+const columns = [
+  { field: "title", width: 200, label: "Title" },
+  { field: "status", renderer: StatusBadgeRenderer, width: 100 },
+];
+```
+
+## Relation Fields
+
+Use dot notation to directly specify fields from relations.
+
+```typescript
+const columns = [
+  "title",
+  "assignee.name",      // name field from assignee relation
+  "assignee.email",     // email field from assignee relation
+  "project.name",       // name field from project relation
+];
+```
+
+This displays the following columns in the table:
+- title
+- assignee.name (label is "assignee.name" or can be overridden with labels)
+- assignee.email
+- project.name
+
+## Options Reference
+
+### width
+
+Specifies the column width. Can be a number (pixels) or string (CSS width value).
+
+```typescript
+{ width: 200 }        // 200px
+{ width: "20%" }      // 20%
+{ width: "auto" }     // auto
+```
+
+### minWidth / maxWidth
+
+Specifies the minimum and maximum width of the column.
+
+```typescript
+{ minWidth: 100, maxWidth: 400 }
+```
+
+### renderer
+
+Specifies a custom cell renderer.
+
+```typescript
+const StatusRenderer: CellRenderer = ({ value, row }) => (
+  <Badge variant={value === "active" ? "success" : "secondary"}>
+    {value}
+  </Badge>
+);
+
+const columns = [
+  ["status", StatusRenderer],
+  // or
+  { field: "status", renderer: StatusRenderer },
+];
+```
+
+### label
+
+Overrides the column header label.
+
+```typescript
+const columns = [
+  ["assignee.name", { label: "Assignee" }],
+  { field: "createdAt", label: "Created At" },
+];
+```
+
+## Type Definitions
+
+```typescript
+/** Field path (can specify relation fields using dot notation) */
+type FieldPath = string;
+
+/** Column options */
+interface ColumnOptions {
+  width?: number | string;
+  minWidth?: number | string;
+  maxWidth?: number | string;
+  renderer?: CellRenderer;
+  label?: string;
+}
+
+/** Column definition (Level 3) */
+interface ColumnDefinition extends ColumnOptions {
+  field: FieldPath;
+}
+
+/** Column definition (all levels) */
+type ColumnDef =
+  | FieldPath                           // Level 1
+  | [FieldPath, CellRenderer]           // Level 2a
+  | [FieldPath, ColumnOptions]          // Level 2b
+  | ColumnDefinition;                   // Level 3
+```
+
+## Normalized Form
+
+Internally, all ColumnDef values are normalized to the following form:
+
+```typescript
+interface NormalizedColumnDefinition {
+  /** Original field path */
+  field: FieldPath;
+  /** Column width */
+  width?: number | string;
+  /** Minimum width */
+  minWidth?: number | string;
+  /** Maximum width */
+  maxWidth?: number | string;
+  /** Custom renderer */
+  renderer?: CellRenderer;
+  /** Column label */
+  label?: string;
+  /** Whether this is a relation field */
+  isRelationField: boolean;
+  /** Base field name (before the dot) */
+  baseField: string;
+  /** Nested field name (after the dot, if any) */
+  nestedField?: string;
+}
+```
+
+## Example: Complete Configuration
+
+```tsx
+import { createDataViewer, builtInRenderers } from "@tailor/data-viewer";
+
+const { TableDataProvider, DataTable, ColumnSelector } = createDataViewer({
+  metadata,
+  fetcher,
+});
+
+function TaskList() {
+  return (
+    <TableDataProvider
+      tableName="task"
+      columns={[
+        // Simple field
+        "title",
+        
+        // Width specification
+        ["status", { width: 120 }],
+        
+        // Custom renderer
+        ["priority", builtInRenderers.statusBadge({
+          mapping: {
+            high: { label: "High", color: "red" },
+            medium: { label: "Medium", color: "yellow" },
+            low: { label: "Low", color: "gray" },
+          },
+        })],
+        
+        // Relation field + label
+        ["assignee.name", { label: "Assignee", width: 150 }],
+        
+        // Complete configuration
+        {
+          field: "description",
+          width: 300,
+          minWidth: 200,
+          maxWidth: 500,
+          label: "Description",
+        },
+      ]}
+    >
+      <DataTable />
+    </TableDataProvider>
+  );
+}
+```

package/docs/compositional-api.md

@@ -53,8 +53,8 @@ function MyDataViewer() {
   return (
     <DataViewer.TableDataProvider
       tableName="User"
+      columns={["id", "name", "email"]}
       initialData={{
-        selectedFields: ["id", "name", "email"],
         sort: { field: "name", direction: "Asc" },
       }}
     >
@@ -112,15 +112,14 @@ interface TableDataProviderProps {
   children: ReactNode;
   /** Table name to display (type-safe when metadata is `as const`) */
   tableName: string;
-  /** Initial data for filters, selected fields, and relations */
+  /** Column definitions for the table (see columns.md for details) */
+  columns?: ColumnDef[];
+  /** Initial data for filters and sort */
   initialData?: DataViewerInitialData;
 }
 
 interface DataViewerInitialData {
   filters?: SearchFilters;
-  selectedFields?: string[];
-  selectedRelations?: string[];
-  expandedRelationFields?: ExpandedRelationFields;
   sort?: { field: string; direction: "Asc" | "Desc" } | { field: string; direction: "Asc" | "Desc" }[];
 }
 ```
@@ -130,11 +129,16 @@ interface DataViewerInitialData {
 ```tsx
 <DataViewer.TableDataProvider
   tableName="Task"
+  columns={[
+    "id",
+    "title",
+    ["status", { width: 120 }],
+    "assignee.name",
+    "assignee.email",
+    "createdAt",
+  ]}
   initialData={{
     filters: [{ field: "status", fieldType: "enum", operator: "eq", value: "active" }],
-    selectedFields: ["id", "title", "status", "createdAt"],
-    selectedRelations: ["assignee"],
-    expandedRelationFields: { assignee: ["name", "email"] },
     sort: { field: "createdAt", direction: "Desc" },
   }}
 >

package/docs/custom-renderers.md

@@ -51,6 +51,83 @@ The `byFieldName` object uses a `tableName:fieldName` key format:
 5. `byFieldType["string"]` — type-based fallback
 6. Default formatting (lowest)
 
+## Renderers vs Column API Renderer Option
+
+There are two ways to define cell renderers: centralized management via `renderers` in `createDataViewer`, or ad-hoc specification using the `renderer` option in the [Column API](./columns.md).
+
+### Ad-hoc Renderer Specification with Column API
+
+The Column API allows you to specify renderers on-the-fly using the `renderer` option in each column definition:
+
+```tsx
+<TableDataProvider
+  tableName="task"
+  columns={[
+    ["status", StatusBadgeRenderer],
+    { field: "priority", renderer: PriorityRenderer },
+  ]}
+>
+  ...
+</TableDataProvider>
+```
+
+### Benefits of Centralized Management with renderers
+
+Using `renderers` in `createDataViewer` for centralized renderer management provides the following benefits:
+
+1. **Eliminate Duplication**: When the same field is rendered across multiple views, you don't need to specify the renderer individually in each view.
+
+2. **Consistency for Relation Fields**: When expanding relation fields like `assignee.email` across multiple views, defining renderers once in `renderers` applies to all views automatically.
+
+3. **Improved Maintainability**: When a renderer change is needed, modifying it in one place reflects the change everywhere.
+
+4. **Efficiency with Wildcards**: Wildcard patterns like `*:*Email` or `*:id` allow you to set common field renderers across all tables at once.
+
+5. **Type-based Fallbacks**: The `byFieldType` option enables automatic rendering based on field types (e.g., all boolean fields rendered as icons).
+
+```tsx
+// Example of centralized management with renderers
+const DataViewer = createDataViewer({
+  metadata,
+  fetcher,
+  renderers: {
+    cell: {
+      byFieldName: {
+        // Define relation field renderers once
+        "*:*.email": EmailLink,
+        "*:id": TruncatedId,
+        
+        // Table-specific renderers
+        "task:status": StatusBadge({
+          colorMap: { todo: "gray", "in-progress": "blue", done: "green" },
+        }),
+      },
+      byFieldType: {
+        boolean: BooleanIcon,
+        array: ArrayBadges,
+      },
+    },
+  },
+});
+
+// No need to specify renderer in columns for each view
+<TableDataProvider tableName="task" columns={["title", "status", "assignee.email"]}>
+  ...
+</TableDataProvider>
+```
+
+### Guidelines for Choosing an Approach
+
+| Case | Recommended Approach |
+|------|----------------------|
+| Same field rendered across multiple views | Centralized management with `renderers` |
+| Different renderer needed only in a specific view | Column API `renderer` option |
+| Expanding relation fields | Centralized management with `renderers` |
+| Common fields across all tables | `renderers` wildcard (`*:fieldName`, `*:*suffix`) |
+| Type-based default rendering | `renderers.cell.byFieldType` |
+
+> **Note**: Renderers specified via the Column API `renderer` option take precedence over centralized `renderers`. Use this when you need a different renderer only in a specific view.
+
 ## Usage with createDataViewer (Recommended)
 
 Set renderers at the `createDataViewer` level to apply them across all tables:

package/docs/labels.md

@@ -30,10 +30,87 @@ For field labels (`getLabel("orders:status")`):
 2. `labels["*:status"]` — wildcard match
 3. `"status"` — fallback to field name
 
+For nested relation fields (`getLabel("task:assignee.name")`):
+1. `labels["task:assignee.name"]` — exact match (highest)
+2. `labels["*:assignee.name"]` — wildcard match for full path
+3. `labels["assignee:name"]` — target table format fallback
+4. `labels["*:name"]` — target field wildcard
+5. `"name"` — fallback to target field name
+
 For UI labels (`getLabel("$:refresh")`):
 1. `labels["$:refresh"]` — custom override (highest)
 2. `DEFAULT_UI_LABELS["$:refresh"]` — built-in default
 
+## Labels vs Column API Label Option
+
+There are two ways to define field labels: centralized management via `labels`, or ad-hoc specification using the `label` option in the [Column API](./columns.md).
+
+### Ad-hoc Label Specification with Column API
+
+The Column API allows you to specify labels on-the-fly using the `label` option in each column definition:
+
+```tsx
+<TableDataProvider
+  tableName="task"
+  columns={[
+    ["assignee.name", { label: "Assignee" }],
+    { field: "createdAt", label: "Created Date" },
+  ]}
+>
+  ...
+</TableDataProvider>
+```
+
+### Benefits of Centralized Management with labels
+
+Using `labels` for centralized label management provides the following benefits:
+
+1. **Eliminate Duplication**: When the same field is used across multiple views, you don't need to specify the label individually in each view.
+
+2. **Consistency for Relation Fields**: When expanding relation fields like `assignee.name` across multiple views, defining them once in `labels` applies to all views automatically.
+
+3. **Improved Maintainability**: When a label change is needed, modifying it in one place reflects the change everywhere.
+
+4. **Efficiency with Wildcards**: Wildcard patterns like `*:createdAt` allow you to set common field labels across all tables at once.
+
+```tsx
+// Example of centralized management with labels
+const DataViewer = createDataViewer({
+  metadata,
+  fetcher,
+  labels: {
+    // Define relation field labels using target table format
+    // These labels apply to all tables referencing the same relation
+    "assignee:name": "Assignee",
+    "assignee:email": "Assignee Email",
+    "project:name": "Project Name",
+    
+    // Or use table-specific format for precise control
+    "task:assignee.name": "Task Assignee",  // Takes priority over "assignee:name"
+    
+    // Common fields across multiple tables
+    "*:createdAt": "Created",
+    "*:updatedAt": "Updated",
+  },
+});
+
+// No need to specify label in columns for each view
+<TableDataProvider tableName="task" columns={["title", "assignee.name", "createdAt"]}>
+  ...
+</TableDataProvider>
+```
+
+### Guidelines for Choosing an Approach
+
+| Case | Recommended Approach |
+|------|----------------------|
+| Same field displayed across multiple views | Centralized management with `labels` |
+| Different label needed only in a specific view | Column API `label` option |
+| Expanding relation fields | Centralized management with `labels` |
+| Common fields across all tables | `labels` wildcard (`*:fieldName`) |
+
+> **Note**: Labels specified via the Column API `label` option take precedence over `labels`. Use this when you need to display a different label only in a specific view.
+
 ## Usage with createDataViewer
 
 ```tsx

package/package.json

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