@izumisy-tailor/tailor-data-viewer 0.1.46 → 0.1.48

package/docs/README.md

@@ -21,5 +21,7 @@ Documentation for `@izumisy-tailor/tailor-data-viewer`.
 ## Advanced Usage
 
 - [Compositional API](compositional-api.md) - Building flexible UIs by composing components
+- [Manual Refetch](manual-refetch.md) - Manually refetching table data after external operations
+- [Inline Cell Editing](inline-cell-editing.md) - Implementing editable cells with custom renderers
 - [Saved View Store](saved-view-store.md) - View persistence and restoration
 - [AppShell Module](app-shell-module.md) - AppShell integration module

package/docs/inline-cell-editing.md

@@ -0,0 +1,711 @@
+# Inline Cell Editing
+
+## Overview
+
+Data Viewer supports inline cell editing by combining [Custom Renderers](./custom-renderers.md) and [Manual Refetch](./manual-refetch.md) patterns. This document explains how to implement editable cells that update data and refresh the table automatically.
+
+## How It Works
+
+Inline cell editing is achieved through three key concepts:
+
+1. **Custom Renderer**: Create a renderer that displays an editable input instead of static text
+2. **Row Data Access**: Use the `row` prop to get the record ID for API calls
+3. **Manual Refetch**: Call `refetch()` after successful update to sync the table
+
+```
+┌─────────────────┐     ┌──────────────┐     ┌─────────────┐
+│ Custom Renderer │ ──> │  Update API  │ ──> │   refetch() │
+│   (editable)    │     │    call      │     │   to sync   │
+└─────────────────┘     └──────────────┘     └─────────────┘
+```
+
+## Basic Example: Editable Text Field
+
+A simple inline text editor that updates on blur:
+
+```tsx
+import { useState } from "react";
+import {
+  CellRendererProps,
+  useDataViewer,
+  DataTable,
+} from "@izumisy-tailor/tailor-data-viewer/component";
+import { DataViewer } from "./data-viewer";
+
+// Create a reusable editable text renderer factory
+function EditableText(options: { onSave: (id: string, value: string) => Promise<void> }) {
+  return function EditableTextRenderer({ value, row }: CellRendererProps) {
+    const [editing, setEditing] = useState(false);
+    const [inputValue, setInputValue] = useState(String(value ?? ""));
+    const { refetch } = useDataViewer();
+
+    const handleSave = async () => {
+      setEditing(false);
+      if (inputValue !== String(value)) {
+        await options.onSave(row.id as string, inputValue);
+        await refetch();
+      }
+    };
+
+    if (editing) {
+      return (
+        <input
+          type="text"
+          value={inputValue}
+          onChange={(e) => setInputValue(e.target.value)}
+          onBlur={handleSave}
+          onKeyDown={(e) => e.key === "Enter" && handleSave()}
+          autoFocus
+          className="w-full px-2 py-1 border rounded"
+        />
+      );
+    }
+
+    return (
+      <span
+        onClick={() => setEditing(true)}
+        className="cursor-pointer hover:bg-gray-100 px-2 py-1 rounded"
+      >
+        {(value as string) ?? "-"}
+      </span>
+    );
+  };
+}
+
+// Usage with Column API
+function TaskListPage() {
+  return (
+    <DataViewer.TableDataProvider
+      tableName="task"
+      columns={[
+        [
+          "title",
+          EditableText({
+            onSave: async (id, value) => {
+              await fetch(`/api/tasks/${id}`, {
+                method: "PATCH",
+                body: JSON.stringify({ title: value }),
+              });
+            },
+          }),
+        ],
+        "status",
+        "createdAt",
+      ]}
+    >
+      <DataTable />
+    </DataViewer.TableDataProvider>
+  );
+}
+```
+
+## Complete Example: Editable Status Dropdown
+
+A dropdown selector for status fields:
+
+```tsx
+import { useState } from "react";
+import {
+  CellRendererProps,
+  useDataViewer,
+  DataTable,
+} from "@izumisy-tailor/tailor-data-viewer/component";
+import { DataViewer } from "./data-viewer";
+
+interface EditableStatusOptions {
+  options: { value: string; label: string; color?: string }[];
+  onSave: (id: string, value: string) => Promise<void>;
+}
+
+function EditableStatus({ options, onSave }: EditableStatusOptions) {
+  return function EditableStatusRenderer({ value, row }: CellRendererProps) {
+    const [isOpen, setIsOpen] = useState(false);
+    const [saving, setSaving] = useState(false);
+    const { refetch } = useDataViewer();
+
+    const currentOption = options.find((opt) => opt.value === value);
+
+    const handleSelect = async (newValue: string) => {
+      if (newValue === value) {
+        setIsOpen(false);
+        return;
+      }
+
+      setSaving(true);
+      setIsOpen(false);
+
+      try {
+        await onSave(row.id as string, newValue);
+        await refetch();
+      } catch (error) {
+        console.error("Failed to update status:", error);
+      } finally {
+        setSaving(false);
+      }
+    };
+
+    return (
+      <div className="relative">
+        <button
+          onClick={() => setIsOpen(!isOpen)}
+          disabled={saving}
+          className={`
+            px-3 py-1 rounded-full text-sm font-medium
+            ${saving ? "opacity-50" : "cursor-pointer hover:opacity-80"}
+          `}
+          style={{
+            backgroundColor: currentOption?.color ?? "#E5E7EB",
+          }}
+        >
+          {saving ? "Saving..." : (currentOption?.label ?? String(value))}
+        </button>
+
+        {isOpen && (
+          <div className="absolute z-10 mt-1 bg-white border rounded shadow-lg">
+            {options.map((option) => (
+              <button
+                key={option.value}
+                onClick={() => handleSelect(option.value)}
+                className="block w-full px-4 py-2 text-left hover:bg-gray-100"
+              >
+                <span
+                  className="inline-block w-3 h-3 rounded-full mr-2"
+                  style={{ backgroundColor: option.color }}
+                />
+                {option.label}
+              </button>
+            ))}
+          </div>
+        )}
+      </div>
+    );
+  };
+}
+
+// Usage with Column API
+const statusOptions = [
+  { value: "todo", label: "To Do", color: "#E5E7EB" },
+  { value: "in-progress", label: "In Progress", color: "#DBEAFE" },
+  { value: "done", label: "Done", color: "#D1FAE5" },
+];
+
+function TaskListPage() {
+  return (
+    <DataViewer.TableDataProvider
+      tableName="task"
+      columns={[
+        "title",
+        [
+          "status",
+          EditableStatus({
+            options: statusOptions,
+            onSave: async (id, value) => {
+              await fetch(`/api/tasks/${id}`, {
+                method: "PATCH",
+                body: JSON.stringify({ status: value }),
+              });
+            },
+          }),
+        ],
+        "createdAt",
+      ]}
+    >
+      <DataTable />
+    </DataViewer.TableDataProvider>
+  );
+}
+```
+
+## Example: Editable Checkbox (Boolean)
+
+Toggle boolean values with a single click:
+
+```tsx
+import { useState } from "react";
+import {
+  CellRendererProps,
+  useDataViewer,
+  DataTable,
+} from "@izumisy-tailor/tailor-data-viewer/component";
+import { DataViewer } from "./data-viewer";
+
+function EditableCheckbox(options: { onSave: (id: string, value: boolean) => Promise<void> }) {
+  return function EditableCheckboxRenderer({ value, row }: CellRendererProps) {
+    const [saving, setSaving] = useState(false);
+    const { refetch } = useDataViewer();
+
+    const handleToggle = async () => {
+      setSaving(true);
+      try {
+        await options.onSave(row.id as string, !value);
+        await refetch();
+      } catch (error) {
+        console.error("Failed to toggle:", error);
+      } finally {
+        setSaving(false);
+      }
+    };
+
+    return (
+      <button
+        onClick={handleToggle}
+        disabled={saving}
+        className={`
+          w-5 h-5 rounded border-2 flex items-center justify-center
+          ${saving ? "opacity-50" : "cursor-pointer"}
+          ${value ? "bg-blue-500 border-blue-500" : "border-gray-300"}
+        `}
+      >
+        {value && <span className="text-white text-xs">✓</span>}
+      </button>
+    );
+  };
+}
+
+// Usage with Column API
+function TaskListPage() {
+  return (
+    <DataViewer.TableDataProvider
+      tableName="task"
+      columns={[
+        [
+          "isCompleted",
+          EditableCheckbox({
+            onSave: async (id, value) => {
+              await fetch(`/api/tasks/${id}`, {
+                method: "PATCH",
+                body: JSON.stringify({ isCompleted: value }),
+              });
+            },
+          }),
+        ],
+        "title",
+        "status",
+      ]}
+    >
+      <DataTable />
+    </DataViewer.TableDataProvider>
+  );
+}
+```
+
+## Example: Editable Number Field
+
+Number input with validation:
+
+```tsx
+import { useState } from "react";
+import {
+  CellRendererProps,
+  useDataViewer,
+  DataTable,
+} from "@izumisy-tailor/tailor-data-viewer/component";
+import { DataViewer } from "./data-viewer";
+
+function EditableNumber(options: {
+  onSave: (id: string, value: number) => Promise<void>;
+  min?: number;
+  max?: number;
+}) {
+  return function EditableNumberRenderer({ value, row }: CellRendererProps) {
+    const [editing, setEditing] = useState(false);
+    const [inputValue, setInputValue] = useState(String(value ?? 0));
+    const [error, setError] = useState<string | null>(null);
+    const { refetch } = useDataViewer();
+
+    const handleSave = async () => {
+      const numValue = Number(inputValue);
+
+      if (isNaN(numValue)) {
+        setError("Invalid number");
+        return;
+      }
+      if (options.min !== undefined && numValue < options.min) {
+        setError(`Minimum value is ${options.min}`);
+        return;
+      }
+      if (options.max !== undefined && numValue > options.max) {
+        setError(`Maximum value is ${options.max}`);
+        return;
+      }
+
+      setEditing(false);
+      setError(null);
+
+      if (numValue !== value) {
+        await options.onSave(row.id as string, numValue);
+        await refetch();
+      }
+    };
+
+    if (editing) {
+      return (
+        <div>
+          <input
+            type="number"
+            value={inputValue}
+            onChange={(e) => setInputValue(e.target.value)}
+            onBlur={handleSave}
+            onKeyDown={(e) => e.key === "Enter" && handleSave()}
+            min={options.min}
+            max={options.max}
+            autoFocus
+            className={`
+              w-24 px-2 py-1 border rounded
+              ${error ? "border-red-500" : "border-gray-300"}
+            `}
+          />
+          {error && <div className="text-red-500 text-xs">{error}</div>}
+        </div>
+      );
+    }
+
+    return (
+      <span
+        onClick={() => setEditing(true)}
+        className="cursor-pointer hover:bg-gray-100 px-2 py-1 rounded"
+      >
+        {(value as number) ?? 0}
+      </span>
+    );
+  };
+}
+
+// Usage with Column API
+function ProductListPage() {
+  return (
+    <DataViewer.TableDataProvider
+      tableName="product"
+      columns={[
+        "name",
+        [
+          "quantity",
+          EditableNumber({
+            min: 0,
+            max: 1000,
+            onSave: async (id, value) => {
+              await fetch(`/api/products/${id}`, {
+                method: "PATCH",
+                body: JSON.stringify({ quantity: value }),
+              });
+            },
+          }),
+        ],
+        "price",
+      ]}
+    >
+      <DataTable />
+    </DataViewer.TableDataProvider>
+  );
+}
+```
+
+## Pattern: Accessing Refetch from Renderers
+
+When building reusable editable cell components, you may need to access `refetch` from within the renderer. The `useDataViewer` hook is available inside any component rendered within `TableDataProvider`:
+
+```tsx
+// The renderer is always called inside TableDataProvider context
+function EditableCellRenderer({ value, row }: CellRendererProps) {
+  // ✅ This works because renderers are rendered inside TableDataProvider
+  const { refetch } = useDataViewer();
+
+  // ... editing logic
+}
+```
+
+## Pattern: Optimistic Updates
+
+For better UX, show the updated value immediately while the API call is in progress:
+
+```tsx
+function OptimisticEditableText(options: { onSave: (id: string, value: string) => Promise<void> }) {
+  return function OptimisticEditableTextRenderer({ value, row }: CellRendererProps) {
+    const [editing, setEditing] = useState(false);
+    const [inputValue, setInputValue] = useState(String(value ?? ""));
+    const [displayValue, setDisplayValue] = useState(String(value ?? ""));
+    const [saving, setSaving] = useState(false);
+    const { refetch } = useDataViewer();
+
+    const handleSave = async () => {
+      setEditing(false);
+      if (inputValue !== String(value)) {
+        // Optimistically update display value
+        setDisplayValue(inputValue);
+        setSaving(true);
+
+        try {
+          await options.onSave(row.id as string, inputValue);
+          await refetch();
+        } catch (error) {
+          // Revert on error
+          setDisplayValue(String(value));
+          console.error("Failed to save:", error);
+        } finally {
+          setSaving(false);
+        }
+      }
+    };
+
+    if (editing) {
+      return (
+        <input
+          type="text"
+          value={inputValue}
+          onChange={(e) => setInputValue(e.target.value)}
+          onBlur={handleSave}
+          onKeyDown={(e) => e.key === "Enter" && handleSave()}
+          autoFocus
+          className="w-full px-2 py-1 border rounded"
+        />
+      );
+    }
+
+    return (
+      <span
+        onClick={() => {
+          setInputValue(displayValue);
+          setEditing(true);
+        }}
+        className={`
+          cursor-pointer hover:bg-gray-100 px-2 py-1 rounded
+          ${saving ? "opacity-50" : ""}
+        `}
+      >
+        {displayValue || "-"}
+      </span>
+    );
+  };
+}
+
+// Usage with Column API
+<DataViewer.TableDataProvider
+  tableName="task"
+  columns={[
+    ["title", OptimisticEditableText({ onSave: updateTitle })],
+    "status",
+  ]}
+>
+  <DataTable />
+</DataViewer.TableDataProvider>
+```
+
+## Pattern: Edit Permission Control
+
+Show editable or read-only view based on user permissions:
+
+```tsx
+function EditableTextWithPermission(options: {
+  onSave: (id: string, value: string) => Promise<void>;
+  canEdit: (row: Record<string, unknown>) => boolean;
+}) {
+  return function EditableTextWithPermissionRenderer({ value, row }: CellRendererProps) {
+    const [editing, setEditing] = useState(false);
+    const [inputValue, setInputValue] = useState(String(value ?? ""));
+    const { refetch } = useDataViewer();
+
+    const isEditable = options.canEdit(row);
+
+    const handleSave = async () => {
+      setEditing(false);
+      if (inputValue !== String(value)) {
+        await options.onSave(row.id as string, inputValue);
+        await refetch();
+      }
+    };
+
+    // Read-only view if user cannot edit
+    if (!isEditable) {
+      return <span className="px-2 py-1">{(value as string) ?? "-"}</span>;
+    }
+
+    if (editing) {
+      return (
+        <input
+          type="text"
+          value={inputValue}
+          onChange={(e) => setInputValue(e.target.value)}
+          onBlur={handleSave}
+          onKeyDown={(e) => e.key === "Enter" && handleSave()}
+          autoFocus
+          className="w-full px-2 py-1 border rounded"
+        />
+      );
+    }
+
+    return (
+      <span
+        onClick={() => setEditing(true)}
+        className="cursor-pointer hover:bg-gray-100 px-2 py-1 rounded"
+        title="Click to edit"
+      >
+        {(value as string) ?? "-"}
+        <span className="ml-1 text-gray-400 text-xs">✎</span>
+      </span>
+    );
+  };
+}
+
+// Usage with Column API and permission check
+const currentUserId = "user-123";
+const isAdmin = false;
+
+function TaskListPage() {
+  return (
+    <DataViewer.TableDataProvider
+      tableName="task"
+      columns={[
+        [
+          "title",
+          EditableTextWithPermission({
+            onSave: async (id, value) => {
+              await fetch(`/api/tasks/${id}`, {
+                method: "PATCH",
+                body: JSON.stringify({ title: value }),
+              });
+            },
+            canEdit: (row) => row.assigneeId === currentUserId || isAdmin,
+          }),
+        ],
+        "status",
+        "assignee.name",
+      ]}
+    >
+      <DataTable />
+    </DataViewer.TableDataProvider>
+  );
+}
+```
+
+## Combining Multiple Editable Fields
+
+You can combine multiple editable renderers in a single view:
+
+```tsx
+function TaskListPage() {
+  return (
+    <DataViewer.TableDataProvider
+      tableName="task"
+      columns={[
+        [
+          "isCompleted",
+          EditableCheckbox({
+            onSave: async (id, value) => {
+              await fetch(`/api/tasks/${id}`, {
+                method: "PATCH",
+                body: JSON.stringify({ isCompleted: value }),
+              });
+            },
+          }),
+        ],
+        [
+          "title",
+          EditableText({
+            onSave: async (id, value) => {
+              await fetch(`/api/tasks/${id}`, {
+                method: "PATCH",
+                body: JSON.stringify({ title: value }),
+              });
+            },
+          }),
+        ],
+        [
+          "status",
+          EditableStatus({
+            options: statusOptions,
+            onSave: async (id, value) => {
+              await fetch(`/api/tasks/${id}`, {
+                method: "PATCH",
+                body: JSON.stringify({ status: value }),
+              });
+            },
+          }),
+        ],
+        "createdAt", // Read-only
+      ]}
+    >
+      <DataTable />
+    </DataViewer.TableDataProvider>
+  );
+}
+```
+
+## Tips
+
+### Keyboard Navigation
+
+For better accessibility, consider adding keyboard navigation:
+
+```tsx
+onKeyDown={(e) => {
+  if (e.key === "Enter") handleSave();
+  if (e.key === "Escape") {
+    setInputValue(String(value));
+    setEditing(false);
+  }
+}}
+```
+
+### Debouncing Auto-Save
+
+For auto-save on change (without blur), add debouncing:
+
+```tsx
+import { useDebouncedCallback } from "use-debounce";
+
+const debouncedSave = useDebouncedCallback(async (newValue: string) => {
+  await options.onSave(row.id as string, newValue);
+  await refetch();
+}, 500);
+
+const handleChange = (e: React.ChangeEvent<HTMLInputElement>) => {
+  setInputValue(e.target.value);
+  debouncedSave(e.target.value);
+};
+```
+
+### Extracting onSave Logic
+
+For cleaner code, extract the API call logic into separate functions:
+
+```tsx
+// api/tasks.ts
+export async function updateTask(id: string, data: Partial<Task>) {
+  await fetch(`/api/tasks/${id}`, {
+    method: "PATCH",
+    headers: { "Content-Type": "application/json" },
+    body: JSON.stringify(data),
+  });
+}
+
+// TaskListPage.tsx
+import { updateTask } from "./api/tasks";
+
+<DataViewer.TableDataProvider
+  tableName="task"
+  columns={[
+    [
+      "title",
+      EditableText({
+        onSave: (id, value) => updateTask(id, { title: value }),
+      }),
+    ],
+    [
+      "status",
+      EditableStatus({
+        options: statusOptions,
+        onSave: (id, value) => updateTask(id, { status: value }),
+      }),
+    ],
+  ]}
+>
+  <DataTable />
+</DataViewer.TableDataProvider>
+```
+
+## Related Documentation
+
+- [Custom Renderers](./custom-renderers.md) - Custom cell renderer patterns and built-in renderers
+- [Manual Refetch](./manual-refetch.md) - Manual refetch patterns after data updates
+- [Column Definition API](./columns.md) - Column definition with renderer option
+- [Compositional API](./compositional-api.md) - Building flexible UIs with Providers and Hooks