Tailor Data Viewer

A React component library for building data exploration interfaces with GraphQL backend support. Provides a tab-based spreadsheet-like UI for viewing and managing table data with relation navigation.

Features

• Tab-based Interface: Excel-like sheet management with multiple tabs
• Table Selection: Role-based access control for tables
• Column Selection: Dynamic column visibility with manyToOne relation expansion
• Relation Navigation: Expandable inline relations with "Open as Sheet" functionality
• Search & Filter: AND-based filtering on string, number, boolean, and enum fields
• View Persistence: Save and load views with filter and column configurations
• 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
• 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

npm install @izumisy-tailor/tailor-data-viewer
# or
pnpm add @izumisy-tailor/tailor-data-viewer
# or
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:

npx skills add [email protected]: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:

npm install react react-dom

Usage

There are two ways to use Data Viewer:

1. AppShell Module - Recommended for Tailor Platform apps
2. Standalone Component - For custom React apps

AppShell Module (Recommended)

For Tailor Platform apps using @tailor-platform/app-shell:

// src/shared/data-viewer.ts
import { createDataViewer, createDefaultFetcher } from "@izumisy-tailor/tailor-data-viewer/component";
import { tableMetadata } from "./generated/table-metadata";

const fetcher = createDefaultFetcher({
  endpoint: import.meta.env.VITE_APP_URL,
});

export const DataViewer = createDataViewer({
  metadata: tableMetadata,
  fetcher,
  // Optional: Custom labels for fields and UI text
  labels: {
    "Task:status": "ステータス",
    "$:refresh": "Refresh",
  },
});

// src/pages/data-view/index.ts
import { createDataViewModule } from "@izumisy-tailor/tailor-data-viewer/app-shell";
import { createIndexedDBStore } from "@izumisy-tailor/tailor-data-viewer/store/indexeddb";
import { DataViewer } from "../../shared/data-viewer";

export const dataViewModule = createDataViewModule({
  dataViewer: DataViewer,
  savedViewStore: createIndexedDBStore(),
});

// src/app.tsx
import { AppShell } from "@tailor-platform/app-shell";
import { dataViewModule } from "./pages/data-view";

export const App = () => (
  <AppShell
    modules={[dataViewModule]}
  />
);

For detailed options, see AppShell Module Integration.

Standalone Explorer View

For custom React apps without AppShell, use DataViewer.ExplorerView. This provides a tab-based UI where users can select tables, create filters, and save views:

// src/lib/data-viewer.ts (create once per app)
import { createDataViewer, createDefaultFetcher } from "@izumisy-tailor/tailor-data-viewer/component";
import { createIndexedDBStore } from "@izumisy-tailor/tailor-data-viewer/store/indexeddb";
import { tableMetadata } from "./generated/table-metadata";

const fetcher = createDefaultFetcher({
  endpoint: "https://your-app.tailor.tech/graphql",
});

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();

// src/App.tsx
import "@izumisy-tailor/tailor-data-viewer/styles/theme.css";
import { DataViewer, savedViewStore } from "./lib/data-viewer";

function App() {
  return (
    <DataViewer.ExplorerView savedViewStore={savedViewStore} />
  );
}

// With initial view loaded from URL
function AppWithViewId() {
  const viewId = useSearchParams().get("viewId") ?? undefined;
  return (
    <DataViewer.ExplorerView 
      savedViewStore={savedViewStore} 
      initialViewId={viewId}
    />
  );
}

For store options, see Saved View Store.

Compositional API

For more control over the UI layout and behavior, use the compositional (compound component) API with createDataViewer:

// src/shared/data-viewer.ts
import { createDataViewer, createDefaultFetcher } from "@izumisy-tailor/tailor-data-viewer/component";
import { tableMetadata } from "./generated/table-metadata";

const fetcher = createDefaultFetcher({
  endpoint: "https://your-app.tailor.tech",
});

export const DataViewer = createDataViewer({
  metadata: tableMetadata,
  fetcher,
  // Optional: Custom labels and renderers
  labels: {
    "User:name": "User Name",
    "*:createdAt": "Created",
  },
});

// src/pages/users/page.tsx
import { DataViewer } from "../../shared/data-viewer";
import {
  DataTable,
  ColumnSelector,
  SearchFilterForm,
  CsvButton,
  RefreshButton,
  useDataViewer,
  useTableDataContext,
} from "@izumisy-tailor/tailor-data-viewer/component";

function CustomDataViewer() {
  return (
    <DataViewer.TableDataProvider
      tableName="User"
      columns={["id", "name", "email"]}
      initialData={{
        sort: { field: "name", direction: "Asc" },
      }}
    >
      <DataViewer.ToolbarProvider>
        <ColumnSelector />
        <SearchFilterForm />
          <CsvButton />
          <RefreshButton />
        </DataViewer.ToolbarProvider>
        <DataTable onRecordClick={(id) => console.log(id)} />
    </DataViewer.TableDataProvider>
  );
}

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)
• Share the same DataViewer instance across multiple pages

For detailed documentation, see Compositional API.

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:

• IndexedDB Store (createIndexedDBStore): Stores data in browser's IndexedDB. Ideal for development, personal use, and offline support
• TailorDB Store (createTailorDBStore): Stores data on the server side. Ideal for sharing views across teams

For more details, see Saved View Store.

Generating Table Metadata

This library includes a custom generator for Tailor Platform SDK that automatically generates table metadata from your TailorDB schema.

Setup

1. Install the generator package in your Tailor Platform SDK project:

npm install @izumisy-tailor/tailor-data-viewer

2. Configure the generator in your tailor.config.ts:

import { defineConfig, defineGenerators } from "@tailor-platform/sdk";
import { dataViewerMetadataGenerator } from "@izumisy-tailor/tailor-data-viewer/generator";

export const generators = defineGenerators(
  dataViewerMetadataGenerator({
    distPath: "src/generated/data-viewer-metadata.generated.ts",
  }),
  // ... other generators
);

export default defineConfig({
  name: "my-app",
  // ... your config
});

3. Run the generator:

tailor-sdk generate

This will generate a metadata file at the specified distPath containing type-safe metadata for all your TailorDB types, including fields, relations, and role-based access control settings.

API Reference

See API.md for detailed API documentation including components, hooks, and types.

Styling

The library uses Tailwind CSS classes. Import the base theme or provide your own CSS variables:

/* Option 1: Import included theme */
@import "@izumisy-tailor/tailor-data-viewer/styles/theme.css";

/* Option 2: Use with Tailor app-shell */
@import "@tailor-platform/app-shell/theme.css";

/* Option 3: Define your own CSS variables */
:root {
  --background: 0 0% 100%;
  --foreground: 222.2 84% 4.9%;
  --primary: 222.2 47.4% 11.2%;
  /* ... see theme.css for full list */
}

Development

See the Development Guide for setup and contribution instructions.

License

MIT