@izumisy-tailor/tailor-data-viewer 0.1.33 → 0.1.35

package/README.md

@@ -13,6 +13,7 @@ A React component library for building data exploration interfaces with GraphQL
 - **Sorting & Pagination**: Full cursor-based pagination support
 - **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
 
 ## Installation
 
@@ -55,6 +56,11 @@ const fetcher = createDefaultFetcher({
 export const DataViewer = createDataViewer({
   metadata: tableMetadata,
   fetcher,
+  // Optional: Custom labels for fields and UI text
+  labels: {
+    "Task:status": "ステータス",
+    "$:refresh": "Refresh",
+  },
 });
 ```
 
@@ -101,6 +107,11 @@ const fetcher = createDefaultFetcher({
 export const DataViewer = createDataViewer({
   metadata: tableMetadata,
   fetcher,
+  // Optional: Custom labels for fields and UI text
+  labels: {
+    "orders:status": "Order Status",
+    "*:createdAt": "Created Date",
+  },
 });
 
 export const savedViewStore = createIndexedDBStore();
@@ -147,6 +158,11 @@ const fetcher = createDefaultFetcher({
 export const DataViewer = createDataViewer({
   metadata: tableMetadata,
   fetcher,
+  // Optional: Custom labels and renderers
+  labels: {
+    "User:name": "User Name",
+    "*:createdAt": "Created",
+  },
 });
 ```
 

package/docs/API.md

@@ -25,81 +25,6 @@ const DataViewer = createDataViewer({
 // - DataViewer.fetcher - The fetcher passed to createDataViewer
 ```
 
-## GraphQL Fetcher
-
-### `GraphQLFetcher`
-
-Interface for GraphQL data fetching. Implement this interface to use your own GraphQL client.
-
-```tsx
-interface GraphQLFetcher {
-  execute: <T = unknown>(
-    query: string,
-    variables?: Record<string, unknown>,
-    options?: GraphQLFetcherOptions,
-  ) => Promise<GraphQLFetcherResult<T>>;
-}
-
-interface GraphQLFetcherOptions {
-  signal?: AbortSignal;
-}
-
-interface GraphQLFetcherResult<T> {
-  data: T | null;
-  errors?: GraphQLError[];
-}
-```
-
-### `createDefaultFetcher`
-
-Creates a default GraphQL fetcher using `graphql-request`.
-
-```tsx
-import { createDefaultFetcher } from "@izumisy-tailor/tailor-data-viewer/component";
-
-const fetcher = createDefaultFetcher({
-  endpoint: "https://your-app.tailor.tech/graphql",
-  headers: { "X-Custom-Header": "value" },  // optional
-  credentials: "include",                    // optional, default: "include"
-});
-```
-
-### `createUrqlFetcher`
-
-Creates a GraphQL fetcher from an existing urql Client.
-
-```tsx
-import { createClient } from "@urql/core";
-import { createUrqlFetcher } from "@izumisy-tailor/tailor-data-viewer/component";
-
-const urqlClient = createClient({
-  url: "https://your-app.tailor.tech/graphql",
-  fetchOptions: {
-    headers: { "Authorization": "Bearer token" },
-  },
-});
-
-const fetcher = createUrqlFetcher({ client: urqlClient });
-```
-
-### Custom Fetcher Implementation
-
-You can implement your own fetcher for any GraphQL client:
-
-```tsx
-const customFetcher: GraphQLFetcher = {
-  execute: async (query, variables, options) => {
-    const response = await fetch("/graphql", {
-      method: "POST",
-      headers: { "Content-Type": "application/json" },
-      body: JSON.stringify({ query, variables }),
-      signal: options?.signal,
-    });
-    return response.json();
-  },
-};
-```
-
 ## Components
 
 ### `<DataViewer />`
@@ -234,246 +159,3 @@ interface RelationMetadata {
 }
 ```
 
-## Custom Cell Renderers
-
-### Overview
-
-Custom cell renderers allow you to customize how cells are displayed in the DataTable. You can define renderers by field name (with optional wildcard matching) or by field type.
-
-### Types
-
-```tsx
-interface CellRendererProps {
-  value: unknown;
-  field: FieldMetadata;
-  row: Record<string, unknown>;
-  rowIndex: number;
-  tableName: string;
-  tableMetadata: TableMetadata;
-}
-
-type CellRenderer = (props: CellRendererProps) => ReactNode;
-
-interface CellRenderers {
-  /** Renderers by "tableName:fieldName" pattern */
-  byFieldName?: Record<string, CellRenderer>;
-  /** Renderers by field type (fallback) */
-  byFieldType?: Partial<Record<FieldType, CellRenderer>>;
-}
-
-interface Renderers {
-  cell?: CellRenderers;
-}
-```
-
-### Key Format
-
-The `byFieldName` object uses a `tableName:fieldName` key format:
-
-| Key | Description | Matches |
-|-----|-------------|---------|
-| `orders:status` | Exact match | orders.status |
-| `orders:*Email` | Suffix match (camelCase) | orders.supplierEmail, orders.buyerEmail |
-| `orders:*.email` | Suffix match (dot) | orders.supplier.email |
-| `*:status` | Cross-table exact | *.status |
-| `*:*Email` | Cross-table suffix | *.supplierEmail, *.buyerEmail |
-
-### Resolution Priority
-
-1. `byFieldName["orders:supplier.email"]` — table-specific + exact match (highest)
-2. `byFieldName["orders:*.email"]` — table-specific + suffix match
-3. `byFieldName["*:supplier.email"]` — cross-table + exact match
-4. `byFieldName["*:*.email"]` — cross-table + suffix match
-5. `byFieldType["string"]` — type-based fallback
-6. Default formatting (lowest)
-
-### Usage with createDataViewer (Recommended)
-
-Set renderers at the `createDataViewer` level to apply them across all tables:
-
-```tsx
-import { createDataViewer, createDefaultFetcher, builtInRenderers } from "@izumisy-tailor/tailor-data-viewer/component";
-import { tableMetadata } from "./generated/metadata";
-
-const { EmailLink, StatusBadge, BooleanIcon, RelativeTime, TruncatedId } = builtInRenderers;
-
-const fetcher = createDefaultFetcher({
-  endpoint: "https://your-app.tailor.tech",
-});
-
-export const DataViewer = createDataViewer({
-  metadata: tableMetadata,
-  fetcher,
-  // Renderers are applied across all tables
-  renderers: {
-    cell: {
-      byFieldName: {
-        "*:*Email": EmailLink,
-        "*:createdAt": RelativeTime,
-        "*:id": TruncatedId,
-        "orders:status": StatusBadge({
-          colorMap: { pending: "yellow", approved: "green", rejected: "red" },
-        }),
-      },
-      byFieldType: {
-        boolean: BooleanIcon,
-      },
-    },
-  },
-});
-```
-
-### Usage with DataTable Props
-
-You can also pass renderers directly to `DataTable` to override or add renderers for specific pages:
-
-```tsx
-import { DataTable, builtInRenderers } from "@izumisy-tailor/tailor-data-viewer/component";
-
-const { EmailLink, StatusBadge, BooleanIcon, RelativeTime, TruncatedId } = builtInRenderers;
-
-<DataTable
-  renderers={{
-    cell: {
-      byFieldName: {
-        // Table-specific renderers
-        "orders:status": StatusBadge({
-          colorMap: {
-            "pending": "yellow",
-            "approved": "green",
-            "rejected": "red",
-          },
-        }),
-        "invoices:status": StatusBadge({
-          colorMap: {
-            "draft": "gray",
-            "sent": "blue",
-            "paid": "green",
-          },
-        }),
-
-        // Cross-table suffix match (all *Email fields)
-        "*:*Email": EmailLink,
-
-        // Cross-table exact match
-        "*:createdAt": RelativeTime,
-        "*:id": TruncatedId,
-
-        // Custom renderer with click handler
-        "orders:orderId": ({ value, row }) => (
-          <button
-            onClick={() => navigate(`/orders/${value}`)}
-            className="text-blue-600 hover:underline"
-          >
-            {value}
-          </button>
-        ),
-      },
-      byFieldType: {
-        boolean: BooleanIcon,
-        datetime: RelativeTime,
-      },
-    },
-  }}
-/>
-```
-
-## Built-in Renderers
-
-The library provides several built-in cell renderers for common use cases.
-
-```tsx
-import { builtInRenderers } from "@izumisy-tailor/tailor-data-viewer/component";
-
-const { EmailLink, BooleanIcon, RelativeTime, TruncatedId, ArrayBadges, StatusBadge } = builtInRenderers;
-```
-
-### EmailLink
-
-Renders email values as `mailto:` links. Empty/null values display as "-".
-
-```tsx
-"*:*Email": EmailLink
-// supplierEmail → <a href="mailto:supplier@example.com">supplier@example.com</a>
-```
-
-### BooleanIcon
-
-Renders boolean values as icons: ✓ (green) for true, ✗ (gray) for false.
-
-```tsx
-byFieldType: {
-  boolean: BooleanIcon
-}
-```
-
-### RelativeTime
-
-Renders datetime values as relative time (e.g., "3日前"). Hover shows absolute datetime. Auto-updates every minute.
-
-```tsx
-"*:createdAt": RelativeTime
-// 2024-01-01T10:00:00Z → "3日前" (with tooltip showing "2024/01/01 10:00:00")
-```
-
-### TruncatedId
-
-Renders long IDs (UUIDs) truncated to 8 characters with "...". Hover shows full ID. Click copies to clipboard.
-
-```tsx
-"*:id": TruncatedId
-// "550e8400-e29b-41d4-a716-446655440000" → "550e8400..." (click to copy)
-```
-
-### ArrayBadges
-
-Renders array values as a horizontal list of badges. Shows "+N" when more than 5 items.
-
-```tsx
-byFieldType: {
-  array: ArrayBadges
-}
-// ["tag1", "tag2", "tag3"] → [tag1] [tag2] [tag3]
-```
-
-### StatusBadge
-
-Factory function that creates a colored badge renderer based on value-to-color mapping.
-
-```tsx
-StatusBadge({
-  colorMap: {
-    "pending": "yellow",      // Preset color
-    "approved": "green",
-    "rejected": "red",
-    "pending*": "yellow",     // Prefix match: pending, pending_review
-    "*approved": "green",     // Suffix match: manager_approved
-    "*error*": "red",         // Contains match: validation_error
-  },
-  defaultColor: "gray",       // Default for unmatched values
-})
-```
-
-**Preset Colors:**
-- `gray`: #F3F4F6 bg, #374151 text
-- `red`: #FEE2E2 bg, #991B1B text
-- `yellow`: #FEF3C7 bg, #92400E text
-- `green`: #D1FAE5 bg, #065F46 text
-- `blue`: #DBEAFE bg, #1E40AF text
-
-**Custom Colors:**
-```tsx
-StatusBadge({
-  colorMap: {
-    "custom_status": { bg: "#E0F2FE", text: "#0369A1" },
-  },
-})
-```
-
-**Pattern Priority:**
-1. Exact match (`"approved"`)
-2. Prefix match (`"approved*"`)
-3. Suffix match (`"*approved"`)
-4. Contains match (`"*approved*"`)
-5. `defaultColor`
-

package/docs/README.md

@@ -0,0 +1,23 @@
+# Documentation
+
+Documentation for `@izumisy-tailor/tailor-data-viewer`.
+
+## Getting Started
+
+- [API Reference](API.md) - Core API reference (Factory Function, Components, Hooks, Types)
+
+## Components
+
+- [DataTable](data-table.md) - Main data table component with row actions and click handlers
+
+## Configuration
+
+- [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
+
+## Advanced Usage
+
+- [Compositional API](compositional-api.md) - Building flexible UIs by composing components
+- [Saved View Store](saved-view-store.md) - View persistence and restoration
+- [AppShell Module](app-shell-module.md) - AppShell integration module

package/docs/compositional-api.md

@@ -28,6 +28,11 @@ const fetcher = createDefaultFetcher({
 export const DataViewer = createDataViewer({
   metadata: tableMetadata,
   fetcher,
+  // Optional: Custom labels for fields and UI text
+  labels: {
+    "Task:status": "ステータス",
+    "Task:createdAt": "作成日時",
+  },
 });
 ```
 
@@ -86,6 +91,8 @@ const fetcher = createDefaultFetcher({
 const DataViewer = createDataViewer({
   metadata: tableMetadata,  // Generated from TailorDB schema
   fetcher,
+  labels: { ... },          // Optional: Custom labels
+  renderers: { ... },       // Optional: Custom cell renderers
 });
 
 // Returns:
@@ -93,6 +100,7 @@ const DataViewer = createDataViewer({
 // - DataViewer.ToolbarProvider - Toolbar state provider
 // - DataViewer.metadata - The metadata passed to createDataViewer
 // - DataViewer.fetcher - The fetcher passed to createDataViewer
+// - DataViewer.labels - The labels passed to createDataViewer
 ```
 
 ### DataViewer.TableDataProvider
@@ -254,6 +262,26 @@ const {
 } = useDataViewer();
 ```
 
+### useLabels
+
+Access label resolution for fields and UI text.
+
+```tsx
+const { getLabel, labels } = useLabels();
+
+// Field label (with wildcard fallback)
+const statusLabel = getLabel("orders:status");
+// → labels["orders:status"] → labels["*:status"] → "status"
+
+// Table label
+const tableLabel = getLabel("orders");
+// → labels["orders"] → "orders"
+
+// UI label (with DEFAULT_UI_LABELS fallback)
+const refreshLabel = getLabel("$:refresh");
+// → labels["$:refresh"] → DEFAULT_UI_LABELS["$:refresh"] → "$:refresh"
+```
+
 ### useTableDataContext
 
 Access data fetching state and pagination controls.

package/docs/custom-renderers.md

@@ -0,0 +1,230 @@
+# Custom Cell Renderers
+
+## Overview
+
+Custom cell renderers allow you to customize how cells are displayed in the DataTable. You can define renderers by field name (with optional wildcard matching) or by field type.
+
+## Types
+
+```tsx
+interface CellRendererProps {
+  value: unknown;
+  field: FieldMetadata;
+  row: Record<string, unknown>;
+  rowIndex: number;
+  tableName: string;
+  tableMetadata: TableMetadata;
+}
+
+type CellRenderer = (props: CellRendererProps) => ReactNode;
+
+interface CellRenderers {
+  /** Renderers by "tableName:fieldName" pattern */
+  byFieldName?: Record<string, CellRenderer>;
+  /** Renderers by field type (fallback) */
+  byFieldType?: Partial<Record<FieldType, CellRenderer>>;
+}
+
+interface Renderers {
+  cell?: CellRenderers;
+}
+```
+
+## Key Format
+
+The `byFieldName` object uses a `tableName:fieldName` key format:
+
+| Key | Description | Matches |
+|-----|-------------|---------|
+| `orders:status` | Exact match | orders.status |
+| `orders:*Email` | Suffix match (camelCase) | orders.supplierEmail, orders.buyerEmail |
+| `orders:*.email` | Suffix match (dot) | orders.supplier.email |
+| `*:status` | Cross-table exact | *.status |
+| `*:*Email` | Cross-table suffix | *.supplierEmail, *.buyerEmail |
+
+## Resolution Priority
+
+1. `byFieldName["orders:supplier.email"]` — table-specific + exact match (highest)
+2. `byFieldName["orders:*.email"]` — table-specific + suffix match
+3. `byFieldName["*:supplier.email"]` — cross-table + exact match
+4. `byFieldName["*:*.email"]` — cross-table + suffix match
+5. `byFieldType["string"]` — type-based fallback
+6. Default formatting (lowest)
+
+## Usage with createDataViewer (Recommended)
+
+Set renderers at the `createDataViewer` level to apply them across all tables:
+
+```tsx
+import { createDataViewer, createDefaultFetcher, builtInRenderers } from "@izumisy-tailor/tailor-data-viewer/component";
+import { tableMetadata } from "./generated/metadata";
+
+const { EmailLink, StatusBadge, BooleanIcon, TruncatedId } = builtInRenderers;
+
+const fetcher = createDefaultFetcher({
+  endpoint: "https://your-app.tailor.tech",
+});
+
+export const DataViewer = createDataViewer({
+  metadata: tableMetadata,
+  fetcher,
+  // Renderers are applied across all tables
+  renderers: {
+    cell: {
+      byFieldName: {
+        "*:*Email": EmailLink,
+        "*:id": TruncatedId,
+        "orders:status": StatusBadge({
+          colorMap: { pending: "yellow", approved: "green", rejected: "red" },
+        }),
+      },
+      byFieldType: {
+        boolean: BooleanIcon,
+      },
+    },
+  },
+});
+```
+
+## Usage with DataTable Props
+
+You can also pass renderers directly to `DataTable` to override or add renderers for specific pages:
+
+```tsx
+import { DataTable, builtInRenderers } from "@izumisy-tailor/tailor-data-viewer/component";
+
+const { EmailLink, StatusBadge, BooleanIcon, TruncatedId } = builtInRenderers;
+
+<DataTable
+  renderers={{
+    cell: {
+      byFieldName: {
+        // Table-specific renderers
+        "orders:status": StatusBadge({
+          colorMap: {
+            "pending": "yellow",
+            "approved": "green",
+            "rejected": "red",
+          },
+        }),
+        "invoices:status": StatusBadge({
+          colorMap: {
+            "draft": "gray",
+            "sent": "blue",
+            "paid": "green",
+          },
+        }),
+
+        // Cross-table suffix match (all *Email fields)
+        "*:*Email": EmailLink,
+
+        // Cross-table exact match
+        "*:id": TruncatedId,
+
+        // Custom renderer with click handler
+        "orders:orderId": ({ value, row }) => (
+          <button
+            onClick={() => navigate(`/orders/${value}`)}
+            className="text-blue-600 hover:underline"
+          >
+            {value}
+          </button>
+        ),
+      },
+      byFieldType: {
+        boolean: BooleanIcon,
+      },
+    },
+  }}
+/>
+```
+
+## Built-in Renderers
+
+The library provides several built-in cell renderers for common use cases.
+
+```tsx
+import { builtInRenderers } from "@izumisy-tailor/tailor-data-viewer/component";
+
+const { EmailLink, BooleanIcon, TruncatedId, ArrayBadges, StatusBadge } = builtInRenderers;
+```
+
+### EmailLink
+
+Renders email values as `mailto:` links. Empty/null values display as "-".
+
+```tsx
+"*:*Email": EmailLink
+// supplierEmail → <a href="mailto:supplier@example.com">supplier@example.com</a>
+```
+
+### BooleanIcon
+
+Renders boolean values as icons: ✓ (green) for true, ✗ (gray) for false.
+
+```tsx
+byFieldType: {
+  boolean: BooleanIcon
+}
+```
+
+### TruncatedId
+
+Renders long IDs (UUIDs) truncated to 8 characters with "...". Hover shows full ID. Click copies to clipboard.
+
+```tsx
+"*:id": TruncatedId
+// "550e8400-e29b-41d4-a716-446655440000" → "550e8400..." (click to copy)
+```
+
+### ArrayBadges
+
+Renders array values as a horizontal list of badges. Shows "+N" when more than 5 items.
+
+```tsx
+byFieldType: {
+  array: ArrayBadges
+}
+// ["tag1", "tag2", "tag3"] → [tag1] [tag2] [tag3]
+```
+
+### StatusBadge
+
+Factory function that creates a colored badge renderer based on value-to-color mapping.
+
+```tsx
+StatusBadge({
+  colorMap: {
+    "pending": "yellow",      // Preset color
+    "approved": "green",
+    "rejected": "red",
+    "pending*": "yellow",     // Prefix match: pending, pending_review
+    "*approved": "green",     // Suffix match: manager_approved
+    "*error*": "red",         // Contains match: validation_error
+  },
+  defaultColor: "gray",       // Default for unmatched values
+})
+```
+
+**Preset Colors:**
+- `gray`: #F3F4F6 bg, #374151 text
+- `red`: #FEE2E2 bg, #991B1B text
+- `yellow`: #FEF3C7 bg, #92400E text
+- `green`: #D1FAE5 bg, #065F46 text
+- `blue`: #DBEAFE bg, #1E40AF text
+
+**Custom Colors:**
+```tsx
+StatusBadge({
+  colorMap: {
+    "custom_status": { bg: "#E0F2FE", text: "#0369A1" },
+  },
+})
+```
+
+**Pattern Priority:**
+1. Exact match (`"approved"`)
+2. Prefix match (`"approved*"`)
+3. Suffix match (`"*approved"`)
+4. Contains match (`"*approved*"`)
+5. `defaultColor`