@izumisy-tailor/tailor-data-viewer 0.1.43 → 0.1.45

package/README.md

@@ -14,6 +14,8 @@ A React component library for building data exploration interfaces with GraphQL
 - **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
 
 ## Installation
 

package/dist/generator/index.d.mts

@@ -2,7 +2,7 @@
 /**
  * Field type mapping for Data View
  */
-type FieldType = "string" | "number" | "boolean" | "uuid" | "datetime" | "date" | "time" | "enum" | "array" | "nested";
+type FieldType = "string" | "number" | "boolean" | "uuid" | "datetime" | "date" | "time" | "enum" | "array" | "nested" | "file";
 /**
  * Metadata for a single field
  */

package/dist/generator/index.mjs

@@ -13,7 +13,8 @@ function mapFieldType(tailorType, isArray) {
 		date: "date",
 		time: "time",
 		enum: "enum",
-		nested: "nested"
+		nested: "nested",
+		file: "file"
 	}[tailorType] ?? "string";
 	if (isArray) return {
 		type: "array",

package/docs/API.md

@@ -55,22 +55,16 @@ Context provider for view persistence.
 ### `<DataTable />`
 
 Core data table component with sortable columns and expandable relations.
+Must be used within `DataViewer.Root` context (table metadata and data are obtained from context).
 
 ```tsx
 interface DataTableProps {
-  data: Record<string, unknown>[];
-  fields: FieldMetadata[];
-  selectedFields: string[];
-  sortState: SortState | null;
-  onSort: (field: string) => void;
-  loading?: boolean;
-  tableMetadata?: TableMetadata;
-  tableMetadataMap?: TableMetadataMap;
-  appUri?: string;
-  selectedRelations?: string[];
-  onOpenAsSheet?: (tableName: string, filterField: string, filterValue: string) => void;
-  onOpenSingleRecordAsSheet?: (tableName: string, recordId: string) => void;
-  expandedRelationFields?: ExpandedRelationFields;
+  /** Callback when a row is clicked */
+  onClickRow?: OnClickRow;
+  /** Callback to open a relation as a new view (used for nested relation expansion) */
+  onOpenRelation?: OnOpenRelation;
+  /** Row-level actions to display in the action dropdown menu */
+  rowActions?: RowActions;
 }
 ```
 
@@ -145,7 +139,7 @@ interface FieldMetadata {
   enumValues?: string[];
 }
 
-type FieldType = "string" | "number" | "boolean" | "uuid" | "datetime" | "date" | "time" | "json" | "enum" | "nested" | "array";
+type FieldType = "string" | "number" | "boolean" | "uuid" | "datetime" | "date" | "time" | "json" | "enum" | "nested" | "array" | "file";
 ```
 
 ### RelationMetadata

package/docs/README.md

@@ -16,6 +16,7 @@ Documentation for `@izumisy-tailor/tailor-data-viewer`.
 - [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
+- [File Type Support](file-type.md) - TailorDB File type handling, auto-expansion, and file renderers
 
 ## Advanced Usage
 

package/docs/custom-renderers.md

@@ -51,6 +51,35 @@ The `byFieldName` object uses a `tableName:fieldName` key format:
 5. `byFieldType["string"]` — type-based fallback
 6. Default formatting (lowest)
 
+## Default Renderers
+
+Certain field types have default renderers applied automatically:
+
+| Field Type | Default Renderer | Description |
+|------------|------------------|-------------|
+| `file` | `FileLink` | Displays file as a clickable link with file icon and formatted size |
+
+These defaults are applied when no custom renderer is specified. You can override them by providing your own renderer via `byFieldType` or `byFieldName`:
+
+```tsx
+import { builtInRenderers } from "@izumisy-tailor/tailor-data-viewer";
+
+const { FileImageThumbnail } = builtInRenderers;
+
+// Override the default file renderer with a thumbnail
+const DataViewer = createDataViewer({
+  metadata,
+  fetcher,
+  renderers: {
+    cell: {
+      byFieldType: {
+        file: FileImageThumbnail({ width: 40, height: 40 }),
+      },
+    },
+  },
+});
+```
+
 ## 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).
@@ -305,3 +334,35 @@ StatusBadge({
 3. Suffix match (`"*approved"`)
 4. Contains match (`"*approved*"`)
 5. `defaultColor`
+
+### FileLink
+
+Renders file type values as a download link with file icon and formatted size.
+
+```tsx
+"*:attachment": FileLink
+// { url: "...", size: 1048576 } → 📄 File (1 MB)
+```
+
+### FileImageThumbnail
+
+Factory function that creates a thumbnail renderer for image files. Non-image files display a file icon.
+
+```tsx
+// Default size (40x40)
+"*:avatar": FileImageThumbnail()
+
+// Custom size with click handler
+"*:profileImage": FileImageThumbnail({
+  width: 60,
+  height: 60,
+  onClick: (file, row) => openPreview(file.url),
+})
+```
+
+**Options:**
+- `width?: number` — Thumbnail width in pixels (default: 40)
+- `height?: number` — Thumbnail height in pixels (default: 40)
+- `onClick?: (file: FileValue, row: Record<string, unknown>) => void` — Click handler
+
+> For more details on File type support, see [File Type Support](./file-type.md).

package/docs/fetcher.md

@@ -37,6 +37,20 @@ const fetcher = createDefaultFetcher({
 });
 ```
 
+### Dynamic Headers
+
+The `headers` option can also accept a function that returns headers. This is useful when headers need to be generated dynamically per request (e.g., nonce generation for CSP):
+
+```tsx
+const fetcher = createDefaultFetcher({
+  endpoint: "https://your-app.tailor.tech/graphql",
+  headers: () => ({
+    "X-Custom-Header": "value",
+    "X-Nonce": generateNonce(),  // Called on each request
+  }),
+});
+```
+
 ## `createUrqlFetcher`
 
 Creates a GraphQL fetcher from an existing urql Client.

package/docs/file-type.md

@@ -0,0 +1,249 @@
+# File Type Support
+
+## Overview
+
+TailorDB's `File` type is a special composite type that contains file metadata including URL, size, content type, and more. This library provides built-in support for File type fields, including automatic query expansion and dedicated renderers.
+
+## Default Renderer
+
+**File type fields use `FileLink` as their default renderer.** When you include a `file` type field in your columns without specifying a renderer, `FileLink` is automatically applied. This means file fields will display as clickable links with file size information out of the box.
+
+```tsx
+// FileLink is automatically used - no renderer needed!
+<TableDataProvider
+  tableName="document"
+  columns={["name", "attachment"]}  // attachment renders with FileLink
+>
+```
+
+To override this default, see [Centralized File Renderer Configuration](#centralized-file-renderer-configuration) or use the [Column API](./columns.md) to specify a renderer per column.
+
+## File Type Structure
+
+When a TailorDB field is defined as `file` type, the GraphQL schema returns the following structure:
+
+```graphql
+type File {
+  url: String!           # Pre-signed URL for file access
+  size: Int              # File size in bytes
+  contentType: String    # MIME type (e.g., "image/jpeg", "application/pdf")
+  sha256sum: String      # SHA256 checksum
+  lastUploadedAt: DateTime  # Upload timestamp
+}
+```
+
+## Automatic Query Expansion
+
+When you include a `file` type field in your column selection, the query builder automatically expands it to fetch all subfields:
+
+```tsx
+// Your column definition
+<TableDataProvider
+  tableName="user"
+  columns={["name", "avatar"]}  // avatar is a file type field
+>
+```
+
+```graphql
+# Generated GraphQL query
+query UserList($query: UserQueryInput) {
+  users(query: $query) {
+    edges {
+      node {
+        name
+        avatar {
+          url
+          size
+          contentType
+          sha256sum
+          lastUploadedAt
+        }
+      }
+    }
+  }
+}
+```
+
+This automatic expansion happens when you pass `tableMetadata` to the query builder options. The library uses the metadata to detect `file` type fields and expand them appropriately.
+
+## FileValue Type
+
+The library exports a `FileValue` interface and type guard for working with file values:
+
+```tsx
+import { FileValue, isFileValue } from "@izumisy-tailor/tailor-data-viewer";
+
+interface FileValue {
+  url: string;
+  contentType?: string | null;
+  size?: number | null;
+  sha256sum?: string | null;
+  lastUploadedAt?: string | null;
+}
+
+// Type guard
+if (isFileValue(value)) {
+  console.log(value.url);  // TypeScript knows this is FileValue
+}
+```
+
+## Built-in File Renderers
+
+The library provides two built-in renderers for file fields:
+
+### FileLink
+
+Renders file values as a download link with file icon and formatted size.
+
+```tsx
+import { builtInRenderers } from "@izumisy-tailor/tailor-data-viewer";
+
+const { FileLink } = builtInRenderers;
+
+// Usage
+<TableDataProvider
+  tableName="document"
+  columns={[
+    "name",
+    ["attachment", FileLink],  // Renders as: 📄 File (1.5 MB)
+  ]}
+>
+```
+
+**Features:**
+- Displays file icon and "File" label
+- Shows formatted file size (e.g., "1.5 MB")
+- Opens file URL in new tab on click
+- Shows "-" for null/undefined values
+
+### FileImageThumbnail
+
+Factory function that creates a thumbnail renderer for image files. Non-image files display a file icon.
+
+```tsx
+import { builtInRenderers } from "@izumisy-tailor/tailor-data-viewer";
+
+const { FileImageThumbnail } = builtInRenderers;
+
+// Basic usage with defaults (40x40 px)
+<TableDataProvider
+  tableName="user"
+  columns={[
+    "name",
+    ["avatar", FileImageThumbnail()],
+  ]}
+>
+
+// Custom size
+["avatar", FileImageThumbnail({ width: 60, height: 60 })]
+
+// With click handler for preview modal
+["avatar", FileImageThumbnail({
+  width: 80,
+  height: 80,
+  onClick: (file, row) => {
+    openPreviewModal(file.url);
+  },
+})]
+```
+
+**Options:**
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `width` | `number` | `40` | Thumbnail width in pixels |
+| `height` | `number` | `40` | Thumbnail height in pixels |
+| `onClick` | `(file: FileValue, row: Record<string, unknown>) => void` | - | Click handler with file data and full row |
+
+**Behavior:**
+- **Image files** (`image/*` content types): Displays actual image thumbnail
+- **Non-image files**: Displays file icon placeholder
+- **Null values**: Displays "-"
+
+## Utility Functions
+
+### formatFileSize
+
+The library includes a utility for formatting byte values into human-readable strings:
+
+```tsx
+import { formatFileSize } from "@izumisy-tailor/tailor-data-viewer/component/lib/format-file-size";
+
+formatFileSize(512);         // "512 B"
+formatFileSize(1024);        // "1 KB"
+formatFileSize(1536);        // "1.5 KB"
+formatFileSize(1048576);     // "1 MB"
+formatFileSize(1073741824);  // "1 GB"
+```
+
+## Creating Custom File Renderers
+
+You can create your own file renderers using the `FileValue` type and `isFileValue` guard:
+
+```tsx
+import { isFileValue, type FileValue, type CellRenderer } from "@izumisy-tailor/tailor-data-viewer";
+import { formatFileSize } from "@izumisy-tailor/tailor-data-viewer/component/lib/format-file-size";
+
+const CustomFileRenderer: CellRenderer = ({ value, row }) => {
+  if (!isFileValue(value)) {
+    return <span className="text-muted">No file</span>;
+  }
+
+  const { url, size, contentType } = value;
+  const isImage = contentType?.startsWith("image/");
+  const isPdf = contentType === "application/pdf";
+
+  return (
+    <div className="flex items-center gap-2">
+      {isImage && <img src={url} alt="" className="w-8 h-8 rounded" />}
+      {isPdf && <PdfIcon className="w-8 h-8" />}
+      <div>
+        <a href={url} target="_blank" className="text-blue-600 hover:underline">
+          Download
+        </a>
+        {size && <span className="text-xs text-gray-500 ml-2">{formatFileSize(size)}</span>}
+      </div>
+    </div>
+  );
+};
+```
+
+## Centralized File Renderer Configuration
+
+You can override the default `FileLink` renderer or set field-specific file renderers globally using the `renderers` option in `createDataViewer`:
+
+```tsx
+import { createDataViewer, builtInRenderers } from "@izumisy-tailor/tailor-data-viewer";
+
+const { FileImageThumbnail } = builtInRenderers;
+
+export const DataViewer = createDataViewer({
+  metadata: tableMetadata,
+  fetcher,
+  renderers: {
+    cell: {
+      byFieldType: {
+        // Override default FileLink with thumbnail for all file fields
+        file: FileImageThumbnail({ width: 40, height: 40 }),
+      },
+      byFieldName: {
+        // Override with larger thumbnail for specific avatar fields
+        "*:avatar": FileImageThumbnail({ width: 48, height: 48 }),
+        "*:profileImage": FileImageThumbnail({ width: 48, height: 48 }),
+      },
+    },
+  },
+});
+```
+
+## Differences from Other Field Types
+
+File type fields are handled specially compared to other field types:
+
+| Aspect | Regular Fields | Relation Fields | File Fields |
+|--------|---------------|-----------------|-------------|
+| Query | Single field | Nested object with selected fields | Nested object with fixed subfields |
+| Value | Primitive | Object (varies by selection) | Fixed `FileValue` object |
+| Column Definition | `"fieldName"` | `"relation.fieldName"` | `"fieldName"` (expanded automatically) |
+
+The key difference is that file fields have a **fixed structure** (always the same subfields), while relation fields have **dynamic structure** (depends on which related fields you select).

package/package.json

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

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

@@ -0,0 +1,232 @@
+import { describe, it, expect, vi } from "vitest";
+import { render, screen, fireEvent } from "@testing-library/react";
+import { builtInRenderers } from "./built-in-renderers";
+import type { CellRendererProps } from "./types";
+import type { TableMetadata } from "../generator/metadata-generator";
+
+// Mock table metadata for testing
+const mockTableMetadata: TableMetadata = {
+  name: "testTable",
+  pluralForm: "testTables",
+  readAllowedRoles: [],
+  fields: [],
+  relations: [],
+};
+
+// Helper to create mock CellRendererProps
+const createMockProps = (
+  overrides: Partial<CellRendererProps> = {},
+): CellRendererProps => ({
+  value: null,
+  field: { name: "file", type: "file", required: false },
+  row: {},
+  rowIndex: 0,
+  tableName: "testTable",
+  tableMetadata: mockTableMetadata,
+  ...overrides,
+});
+
+describe("FileLink", () => {
+  const { FileLink } = builtInRenderers;
+
+  it("renders '-' for null value", () => {
+    const props = createMockProps({ value: null });
+    render(<>{FileLink(props)}</>);
+    expect(screen.getByText("-")).toBeInTheDocument();
+  });
+
+  it("renders '-' for non-FileValue object", () => {
+    const props = createMockProps({ value: { invalid: "object" } });
+    render(<>{FileLink(props)}</>);
+    expect(screen.getByText("-")).toBeInTheDocument();
+  });
+
+  it("renders link for valid FileValue", () => {
+    const props = createMockProps({
+      value: {
+        url: "https://example.com/file.pdf",
+        size: 1048576,
+        contentType: "application/pdf",
+      },
+    });
+    render(<>{FileLink(props)}</>);
+
+    const link = screen.getByRole("link");
+    expect(link).toHaveAttribute("href", "https://example.com/file.pdf");
+    expect(link).toHaveAttribute("target", "_blank");
+    expect(screen.getByText("File")).toBeInTheDocument();
+    expect(screen.getByText("(1 MB)")).toBeInTheDocument();
+  });
+
+  it("renders without size when size is null", () => {
+    const props = createMockProps({
+      value: {
+        url: "https://example.com/file.pdf",
+        size: null,
+        contentType: "application/pdf",
+      },
+    });
+    render(<>{FileLink(props)}</>);
+
+    expect(screen.getByText("File")).toBeInTheDocument();
+    expect(screen.queryByText(/\(/)).not.toBeInTheDocument();
+  });
+
+  it("stops propagation on click", () => {
+    const props = createMockProps({
+      value: { url: "https://example.com/file.pdf" },
+    });
+    render(<>{FileLink(props)}</>);
+
+    const link = screen.getByRole("link");
+    const stopPropagation = vi.fn();
+    fireEvent.click(link, { stopPropagation });
+    // Note: stopPropagation is called inside the component
+  });
+});
+
+describe("FileImageThumbnail", () => {
+  const { FileImageThumbnail } = builtInRenderers;
+
+  it("renders '-' for null value", () => {
+    const renderer = FileImageThumbnail();
+    const props = createMockProps({ value: null });
+    render(<>{renderer(props)}</>);
+    expect(screen.getByText("-")).toBeInTheDocument();
+  });
+
+  it("renders '-' for non-FileValue object", () => {
+    const renderer = FileImageThumbnail();
+    const props = createMockProps({ value: { invalid: "object" } });
+    render(<>{renderer(props)}</>);
+    expect(screen.getByText("-")).toBeInTheDocument();
+  });
+
+  it("renders image thumbnail for image content type", () => {
+    const renderer = FileImageThumbnail({ width: 60, height: 60 });
+    const props = createMockProps({
+      value: {
+        url: "https://example.com/image.jpg",
+        contentType: "image/jpeg",
+      },
+    });
+    render(<>{renderer(props)}</>);
+
+    const img = screen.getByRole("img");
+    expect(img).toHaveAttribute("src", "https://example.com/image.jpg");
+    expect(img).toHaveStyle({ width: "60px", height: "60px" });
+  });
+
+  it("renders file icon for non-image content type", () => {
+    const renderer = FileImageThumbnail();
+    const props = createMockProps({
+      value: {
+        url: "https://example.com/document.pdf",
+        contentType: "application/pdf",
+      },
+    });
+    const { container } = render(<>{renderer(props)}</>);
+
+    // Should not render an img element
+    expect(screen.queryByRole("img")).not.toBeInTheDocument();
+    // Should render a div with the file icon container
+    expect(container.querySelector("div")).toBeInTheDocument();
+  });
+
+  it("uses default dimensions when not specified", () => {
+    const renderer = FileImageThumbnail();
+    const props = createMockProps({
+      value: {
+        url: "https://example.com/image.png",
+        contentType: "image/png",
+      },
+    });
+    render(<>{renderer(props)}</>);
+
+    const img = screen.getByRole("img");
+    expect(img).toHaveStyle({ width: "40px", height: "40px" });
+  });
+
+  it("calls onClick handler with file and row data", () => {
+    const onClick = vi.fn();
+    const renderer = FileImageThumbnail({ onClick });
+    const fileValue = {
+      url: "https://example.com/image.jpg",
+      contentType: "image/jpeg",
+      size: 1024,
+    };
+    const row = { id: "123", name: "Test" };
+    const props = createMockProps({ value: fileValue, row });
+    render(<>{renderer(props)}</>);
+
+    const img = screen.getByRole("img");
+    fireEvent.click(img);
+
+    expect(onClick).toHaveBeenCalledWith(fileValue, row);
+  });
+
+  it("has cursor-pointer class when onClick is provided", () => {
+    const onClick = vi.fn();
+    const renderer = FileImageThumbnail({ onClick });
+    const props = createMockProps({
+      value: {
+        url: "https://example.com/image.jpg",
+        contentType: "image/jpeg",
+      },
+    });
+    render(<>{renderer(props)}</>);
+
+    const img = screen.getByRole("img");
+    expect(img.className).toContain("cursor-pointer");
+  });
+
+  it("does not have cursor-pointer class when onClick is not provided", () => {
+    const renderer = FileImageThumbnail();
+    const props = createMockProps({
+      value: {
+        url: "https://example.com/image.jpg",
+        contentType: "image/jpeg",
+      },
+    });
+    render(<>{renderer(props)}</>);
+
+    const img = screen.getByRole("img");
+    expect(img.className).not.toContain("cursor-pointer");
+  });
+
+  describe("image content type detection", () => {
+    const imageTypes = [
+      "image/jpeg",
+      "image/png",
+      "image/gif",
+      "image/webp",
+      "image/svg+xml",
+    ];
+
+    it.each(imageTypes)("renders image for %s", (contentType) => {
+      const renderer = FileImageThumbnail();
+      const props = createMockProps({
+        value: { url: "https://example.com/file", contentType },
+      });
+      render(<>{renderer(props)}</>);
+      expect(screen.getByRole("img")).toBeInTheDocument();
+    });
+
+    const nonImageTypes = [
+      "application/pdf",
+      "text/plain",
+      "application/json",
+      null,
+      undefined,
+    ];
+
+    it.each(nonImageTypes)("renders file icon for %s", (contentType) => {
+      const renderer = FileImageThumbnail();
+      const props = createMockProps({
+        value: { url: "https://example.com/file", contentType },
+      });
+      render(<>{renderer(props)}</>);
+      expect(screen.queryByRole("img")).not.toBeInTheDocument();
+    });
+  });
+});