@izumisy-tailor/tailor-data-viewer 0.1.51 → 0.1.53

package/README.md

@@ -27,6 +27,16 @@ pnpm add @izumisy-tailor/tailor-data-viewer
 yarn add @izumisy-tailor/tailor-data-viewer
 ```
 
+### For AI Users
+
+If you're using AI coding assistants (Claude Code, Cursor, GitHub Copilot, etc.), we strongly recommend installing the Data Viewer skill:
+
+```bash
+npx skills add git@github.com:tailor-sandbox/tailor-data-viewer.git
+```
+
+This provides AI-optimized documentation for better code generation and assistance.
+
 ### Peer Dependencies
 
 This library requires the following peer dependencies:

package/package.json

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

package/src/component/built-in-renderers.tsx

@@ -1,7 +1,7 @@
 import { useState, useCallback } from "react";
 import { Check, X, Copy, CheckCircle, FileIcon } from "lucide-react";
-import type { CellRenderer } from "./types";
-import { isFileValue, type FileValue } from "./types";
+import type { CellRenderer, RelationFieldMetadata } from "./types";
+import { isFileValue, type FileValue, isRelationFieldMetadata } from "./types";
 import { formatFileSize } from "./lib/format-file-size";
 
 // =============================================================================
@@ -428,6 +428,100 @@ function FileImageThumbnail(
   };
 }
 
+// =============================================================================
+// Relation Column Renderers (for rel() API)
+// =============================================================================
+
+/**
+ * Default renderer for relation total (count) columns.
+ */
+const RelationTotal: CellRenderer = ({ value }) => {
+  if (value == null) {
+    return <span className="text-muted-foreground">-</span>;
+  }
+  const num = Number(value);
+  return <span>{num}</span>;
+};
+
+/**
+ * Default renderer for relation fields with a single field.
+ * For hasMany: displays as comma-separated list.
+ * For hasOne: displays the single value.
+ */
+const RelationSingleField: CellRenderer = ({ value, field }) => {
+  if (value == null) {
+    return <span className="text-muted-foreground">-</span>;
+  }
+
+  // Check if this is a relation field with result type info
+  if (isRelationFieldMetadata(field)) {
+    // For hasMany (array of values)
+    if (Array.isArray(value)) {
+      const items = value as unknown[];
+      if (items.length === 0) {
+        return <span className="text-muted-foreground">-</span>;
+      }
+
+      // Single field: items are objects with one key, extract the value
+      const strings = items.map((item) => {
+        if (typeof item === "object" && item !== null) {
+          const vals = Object.values(item as Record<string, unknown>);
+          return vals.length === 1
+            ? String(vals[0] ?? "")
+            : JSON.stringify(item);
+        }
+        return String(item ?? "");
+      });
+
+      return <span>{strings.join(", ")}</span>;
+    }
+
+    // For hasOne (single object)
+    if (typeof value === "object") {
+      const vals = Object.values(value as Record<string, unknown>);
+      return (
+        <span>
+          {vals.length === 1 ? String(vals[0] ?? "-") : JSON.stringify(value)}
+        </span>
+      );
+    }
+  }
+
+  return <span>{String(value)}</span>;
+};
+
+/**
+ * Default renderer for relation fields with multiple fields.
+ * Displays as JSON for complex objects.
+ */
+const RelationMultipleFields: CellRenderer = ({ value }) => {
+  if (value == null) {
+    return <span className="text-muted-foreground">-</span>;
+  }
+
+  // For arrays (hasMany) or objects (hasOne), display as JSON
+  return <span className="font-mono text-xs">{JSON.stringify(value)}</span>;
+};
+
+/**
+ * Get the appropriate default renderer for a relation column based on its metadata.
+ * This is used internally to select the right renderer.
+ */
+export function getDefaultRelationRenderer(
+  field: RelationFieldMetadata,
+): CellRenderer {
+  if (field.resultType === "total") {
+    return RelationTotal;
+  }
+
+  // For fields, check if single or multiple
+  if (field.selectedFields && field.selectedFields.length === 1) {
+    return RelationSingleField;
+  }
+
+  return RelationMultipleFields;
+}
+
 // =============================================================================
 // Export
 // =============================================================================
@@ -450,6 +544,12 @@ export const builtInRenderers = {
   FileLink,
   /** Factory: Creates a file thumbnail renderer with size and click options */
   FileImageThumbnail,
+  /** Renders relation total (count) as a number */
+  RelationTotal,
+  /** Renders relation fields (single field) as comma-separated list */
+  RelationSingleField,
+  /** Renders relation fields (multiple fields) as JSON */
+  RelationMultipleFields,
 } as const;
 
 export type BuiltInRenderers = typeof builtInRenderers;

package/src/component/column-definition.test.ts

@@ -242,3 +242,154 @@ describe("createColumnDefMap", () => {
     expect(map.get("assignee.name")?.label).toBe("担当者");
   });
 });
+
+describe("relation column support", () => {
+  describe("normalizeColumnDef with RelationColumnFn", () => {
+    it("should normalize a relation total column function", () => {
+      const columnFn = (rel: import("./relation-column").RelationBuilder) =>
+        rel("taskAssignments").total;
+      const result = normalizeColumnDef(columnFn);
+
+      expect(result.field).toBe("taskAssignments.total");
+      expect(result.isRelationField).toBe(true);
+      expect(result.baseField).toBe("taskAssignments");
+      expect(result.relationRef).toBeDefined();
+      expect(result.relationRef?.__type).toBe("relationTotal");
+      expect(result.label).toBe("taskAssignments.total");
+    });
+
+    it("should normalize a relation fields column function", () => {
+      const columnFn = (rel: import("./relation-column").RelationBuilder) =>
+        rel("taskAssignments").fields(["name", "email"]);
+      const result = normalizeColumnDef(columnFn);
+
+      expect(result.field).toBe("taskAssignments.fields:name,email");
+      expect(result.isRelationField).toBe(true);
+      expect(result.baseField).toBe("taskAssignments");
+      expect(result.relationRef).toBeDefined();
+      expect(result.relationRef?.__type).toBe("relationFields");
+      expect(result.label).toBe("taskAssignments");
+    });
+
+    it("should normalize a relation column with filters", () => {
+      const columnFn = (rel: import("./relation-column").RelationBuilder) =>
+        rel("taskAssignments", [
+          { field: "answered", operator: "eq", value: false },
+        ]).total;
+      const result = normalizeColumnDef(columnFn);
+
+      expect(result.field).toBe("taskAssignments.total:answered=false");
+      expect(result.relationRef?.filters).toEqual([
+        { field: "answered", operator: "eq", value: false },
+      ]);
+    });
+  });
+
+  describe("normalizeColumnDef with tuple containing RelationColumnFn", () => {
+    it("should normalize [RelationColumnFn, renderer] tuple", () => {
+      const mockRenderer: CellRenderer = ({ value }) => String(value);
+      const columnFn = (rel: import("./relation-column").RelationBuilder) =>
+        rel("taskAssignments").total;
+      const result = normalizeColumnDef([columnFn, mockRenderer]);
+
+      expect(result.field).toBe("taskAssignments.total");
+      expect(result.renderer).toBe(mockRenderer);
+      expect(result.relationRef?.__type).toBe("relationTotal");
+    });
+
+    it("should normalize [RelationColumnFn, ColumnOptions] tuple", () => {
+      const columnFn = (rel: import("./relation-column").RelationBuilder) =>
+        rel("taskAssignments").total;
+      const result = normalizeColumnDef([
+        columnFn,
+        { label: "担当者数", width: 100 },
+      ]);
+
+      expect(result.field).toBe("taskAssignments.total");
+      expect(result.label).toBe("担当者数");
+      expect(result.width).toBe(100);
+      expect(result.relationRef?.__type).toBe("relationTotal");
+    });
+  });
+
+  describe("normalizeColumnDef with serialized RelationRef", () => {
+    it("should normalize a serialized RelationTotalRef", () => {
+      const serializedRef = {
+        __type: "relationTotal" as const,
+        id: "taskAssignments.total",
+        relationName: "taskAssignments",
+      };
+      const result = normalizeColumnDef(serializedRef);
+
+      expect(result.field).toBe("taskAssignments.total");
+      expect(result.isRelationField).toBe(true);
+      expect(result.relationRef).toEqual(serializedRef);
+    });
+
+    it("should normalize a serialized RelationFieldsRef", () => {
+      const serializedRef = {
+        __type: "relationFields" as const,
+        id: "taskAssignments.fields:name",
+        relationName: "taskAssignments",
+        fields: ["name"],
+      };
+      const result = normalizeColumnDef(serializedRef);
+
+      expect(result.field).toBe("taskAssignments.fields:name");
+      expect(result.isRelationField).toBe(true);
+      expect(result.relationRef).toEqual(serializedRef);
+    });
+
+    it("should normalize [RelationRef, ColumnOptions] tuple", () => {
+      const serializedRef = {
+        __type: "relationTotal" as const,
+        id: "taskAssignments.total",
+        relationName: "taskAssignments",
+      };
+      const result = normalizeColumnDef([
+        serializedRef,
+        { label: "カスタムラベル" },
+      ]);
+
+      expect(result.field).toBe("taskAssignments.total");
+      expect(result.label).toBe("カスタムラベル");
+      expect(result.relationRef).toEqual(serializedRef);
+    });
+  });
+
+  describe("extractFieldsFromColumns with relationRefs", () => {
+    it("should extract relationRefs from normalized columns", () => {
+      const columnFn = (rel: import("./relation-column").RelationBuilder) =>
+        rel("taskAssignments").total;
+      const columns: UntypedColumnDef[] = ["name", "assignee.name", columnFn];
+      const normalized = normalizeColumnDefs(columns);
+      const result = extractFieldsFromColumns(normalized);
+
+      expect(result.selectedFields).toEqual(["name"]);
+      expect(result.selectedRelations).toEqual(["assignee"]);
+      expect(result.expandedRelationFields).toEqual({ assignee: ["name"] });
+      expect(result.relationRefs).toHaveLength(1);
+      expect(result.relationRefs[0].__type).toBe("relationTotal");
+    });
+
+    it("should extract multiple relationRefs", () => {
+      const columns: UntypedColumnDef[] = [
+        (rel: import("./relation-column").RelationBuilder) =>
+          rel("taskAssignments").total,
+        (rel: import("./relation-column").RelationBuilder) =>
+          rel("taskAssignments", [
+            { field: "answered", operator: "eq", value: false },
+          ]).total,
+        (rel: import("./relation-column").RelationBuilder) =>
+          rel("comments").fields(["text"]),
+      ];
+      const normalized = normalizeColumnDefs(columns);
+      const result = extractFieldsFromColumns(normalized);
+
+      expect(result.relationRefs).toHaveLength(3);
+      expect(result.relationRefs[0].relationName).toBe("taskAssignments");
+      expect(result.relationRefs[1].filters).toHaveLength(1);
+      expect(result.relationRefs[2].__type).toBe("relationFields");
+    });
+  });
+});

package/src/component/column-definition.ts

@@ -6,6 +6,14 @@ import type {
   CellRenderer,
   NormalizedColumnDefinition,
 } from "./types";
+import {
+  isRelationRef,
+  isRelationColumnFn,
+  executeRelationColumnFn,
+  getDefaultRelationLabel,
+  type RelationRef,
+  type RelationColumnFn,
+} from "./relation-column";
 
 /**
  * Check if a value is a CellRenderer function
@@ -23,7 +31,14 @@ function isColumnOptions(value: unknown): value is ColumnOptions {
     return false;
   }
   // CellRenderer is a function, ColumnOptions is an object
-  return !isCellRenderer(value);
+  // RelationRef has __type, ColumnOptions does not
+  if (isCellRenderer(value)) {
+    return false;
+  }
+  if (isRelationRef(value)) {
+    return false;
+  }
+  return true;
 }
 
 /**
@@ -63,12 +78,45 @@ function parseFieldPath(fieldPath: string): {
   };
 }
 
+/**
+ * Normalize a RelationRef to NormalizedColumnDefinition
+ */
+function normalizeRelationRef(
+  ref: RelationRef,
+  options?: ColumnOptions,
+): NormalizedColumnDefinition {
+  return {
+    field: ref.id,
+    width: options?.width,
+    minWidth: options?.minWidth,
+    maxWidth: options?.maxWidth,
+    formatter: options?.formatter,
+    renderer: options?.renderer,
+    label: options?.label ?? getDefaultRelationLabel(ref),
+    isRelationField: true,
+    baseField: ref.relationName,
+    nestedField: undefined,
+    relationRef: ref,
+  };
+}
+
 /**
  * Normalize a single ColumnDef to NormalizedColumnDefinition
  */
 export function normalizeColumnDef(
   columnDef: UntypedColumnDef,
 ): NormalizedColumnDefinition {
+  // Handle RelationColumnFn: (rel) => rel("taskAssignments").total
+  if (isRelationColumnFn(columnDef)) {
+    const ref = executeRelationColumnFn(columnDef);
+    return normalizeRelationRef(ref);
+  }
+
+  // Handle serialized RelationRef (from saved views)
+  if (isRelationRef(columnDef)) {
+    return normalizeRelationRef(columnDef);
+  }
+
   // Level 1: Field path only ("email")
   if (typeof columnDef === "string") {
     const { baseField, nestedField, isRelationField } =
@@ -91,6 +139,7 @@ export function normalizeColumnDef(
       width: columnDef.width,
       minWidth: columnDef.minWidth,
       maxWidth: columnDef.maxWidth,
+      formatter: columnDef.formatter,
       renderer: columnDef.renderer,
       label: columnDef.label,
       isRelationField,
@@ -99,9 +148,35 @@ export function normalizeColumnDef(
     };
   }
 
-  // Level 2: Tuple format (["email", renderer] or ["email", { width: 300 }])
+  // Level 2: Tuple format
   if (Array.isArray(columnDef) && columnDef.length === 2) {
-    const [fieldPath, second] = columnDef;
+    const [first, second] = columnDef;
+
+    // Handle tuple with RelationColumnFn: [(rel) => ..., options]
+    if (isRelationColumnFn(first)) {
+      const ref = executeRelationColumnFn(first as RelationColumnFn);
+      if (isCellRenderer(second)) {
+        return normalizeRelationRef(ref, { renderer: second });
+      }
+      if (isColumnOptions(second)) {
+        return normalizeRelationRef(ref, second);
+      }
+      return normalizeRelationRef(ref);
+    }
+
+    // Handle tuple with RelationRef: [RelationRef, options]
+    if (isRelationRef(first)) {
+      if (isCellRenderer(second)) {
+        return normalizeRelationRef(first, { renderer: second });
+      }
+      if (isColumnOptions(second)) {
+        return normalizeRelationRef(first, second);
+      }
+      return normalizeRelationRef(first);
+    }
+
+    // Handle tuple with field path string: ["email", options]
+    const fieldPath = first as string;
     const { baseField, nestedField, isRelationField } =
       parseFieldPath(fieldPath);
 
@@ -123,6 +198,7 @@ export function normalizeColumnDef(
         width: second.width,
         minWidth: second.minWidth,
         maxWidth: second.maxWidth,
+        formatter: second.formatter,
         renderer: second.renderer,
         label: second.label,
         isRelationField,
@@ -158,14 +234,16 @@ export function normalizeColumnDefs(
 export interface ExtractedFields {
   /** List of direct field names (non-relation fields) */
   selectedFields: string[];
-  /** List of relation field names */
+  /** List of relation field names (manyToOne/hasOne) */
   selectedRelations: string[];
-  /** Map of relation field names to their expanded field names */
+  /** Map of relation field names to their expanded field names (manyToOne/hasOne) */
   expandedRelationFields: ExpandedRelationFields;
+  /** List of relation refs from rel() columns (oneToMany/hasMany) */
+  relationRefs: RelationRef[];
 }
 
 /**
- * Extract selectedFields, selectedRelations, and expandedRelationFields
+ * Extract selectedFields, selectedRelations, expandedRelationFields, and relationRefs
  * from normalized column definitions
  */
 export function extractFieldsFromColumns(
@@ -174,10 +252,17 @@ export function extractFieldsFromColumns(
   const selectedFields: string[] = [];
   const selectedRelations: string[] = [];
   const expandedRelationFields: ExpandedRelationFields = {};
+  const relationRefs: RelationRef[] = [];
 
   for (const column of columns) {
+    // Handle rel() columns (relationRef present)
+    if (column.relationRef) {
+      relationRefs.push(column.relationRef);
+      continue;
+    }
+
     if (column.isRelationField) {
-      // Relation field (e.g., "assignee.name")
+      // Relation field (e.g., "assignee.name") - manyToOne/hasOne
       if (!selectedRelations.includes(column.baseField)) {
         selectedRelations.push(column.baseField);
       }
@@ -203,6 +288,7 @@ export function extractFieldsFromColumns(
     selectedFields,
     selectedRelations,
     expandedRelationFields,
+    relationRefs,
   };
 }