@hienlh/ppm 0.13.8 → 0.13.10

package/src/web/components/database/glide-header-menu.tsx

@@ -0,0 +1,111 @@
+import { useState, useEffect, useRef } from "react";
+import { createPortal } from "react-dom";
+import { Filter, Pin, PinOff, ArrowUp, ArrowDown, X } from "lucide-react";
+
+interface HeaderMenuProps {
+  colName: string;
+  bounds: { x: number; y: number; width: number; height: number };
+  isPinned: boolean;
+  filterValue: string;
+  sortState: "asc" | "desc" | null;
+  onFilter: (value: string) => void;
+  onSort: () => void;
+  onClearSort?: () => void;
+  onTogglePin: () => void;
+  onClose: () => void;
+}
+
+/**
+ * Header column dropdown menu — filter input, sort toggle, pin/unpin.
+ * Rendered via React portal into #portal div (required by Glide Data Grid).
+ */
+export function GlideHeaderMenu({
+  colName, bounds, isPinned, filterValue, sortState,
+  onFilter, onSort, onClearSort, onTogglePin, onClose,
+}: HeaderMenuProps) {
+  const [localFilter, setLocalFilter] = useState(filterValue);
+  const ref = useRef<HTMLDivElement>(null);
+  const debounceRef = useRef<ReturnType<typeof setTimeout>>(undefined);
+
+  // Close on outside click
+  useEffect(() => {
+    const handler = (e: MouseEvent) => {
+      if (ref.current && !ref.current.contains(e.target as Node)) onClose();
+    };
+    document.addEventListener("mousedown", handler);
+    return () => document.removeEventListener("mousedown", handler);
+  }, [onClose]);
+
+  // Close on Escape
+  useEffect(() => {
+    const handler = (e: KeyboardEvent) => { if (e.key === "Escape") onClose(); };
+    document.addEventListener("keydown", handler);
+    return () => document.removeEventListener("keydown", handler);
+  }, [onClose]);
+
+  // Debounced filter
+  const handleFilterChange = (val: string) => {
+    setLocalFilter(val);
+    clearTimeout(debounceRef.current);
+    debounceRef.current = setTimeout(() => onFilter(val), 300);
+  };
+
+  // Clamp position to viewport
+  const menuWidth = 220;
+  const left = Math.min(bounds.x, window.innerWidth - menuWidth - 8);
+  const top = bounds.y + bounds.height + 2;
+
+  const portal = document.getElementById("portal");
+  if (!portal) return null;
+
+  return createPortal(
+    <div ref={ref} style={{ position: "fixed", left, top, zIndex: 10000 }}
+      className="w-[220px] bg-popover border border-border rounded-md shadow-lg text-xs overflow-hidden">
+      {/* Column name header */}
+      <div className="px-3 py-1.5 border-b border-border text-muted-foreground font-medium truncate">
+        {colName}
+      </div>
+
+      {/* Filter input */}
+      <div className="px-2 py-1.5 border-b border-border">
+        <div className="flex items-center gap-1">
+          <Filter className="size-3 text-muted-foreground shrink-0" />
+          <input
+            autoFocus type="text" value={localFilter}
+            onChange={(e) => handleFilterChange(e.target.value)}
+            placeholder="Filter (ILIKE)…"
+            className="flex-1 bg-transparent outline-none text-foreground placeholder:text-muted-foreground text-xs"
+          />
+          {localFilter && (
+            <button type="button" onClick={() => handleFilterChange("")}
+              className="text-muted-foreground hover:text-foreground">
+              <X className="size-3" />
+            </button>
+          )}
+        </div>
+      </div>
+
+      {/* Actions */}
+      <div className="py-1">
+        <button type="button" onClick={() => { onSort(); onClose(); }}
+          className="w-full text-left px-3 py-1.5 hover:bg-muted flex items-center gap-2 text-foreground">
+          {sortState === "asc" ? <ArrowDown className="size-3" /> : <ArrowUp className="size-3" />}
+          {sortState === "asc" ? "Sort Descending" : "Sort Ascending"}
+        </button>
+        {sortState && onClearSort && (
+          <button type="button" onClick={() => { onClearSort(); onClose(); }}
+            className="w-full text-left px-3 py-1.5 hover:bg-muted flex items-center gap-2 text-foreground">
+            <X className="size-3" />
+            Clear Sort
+          </button>
+        )}
+        <button type="button" onClick={() => { onTogglePin(); onClose(); }}
+          className="w-full text-left px-3 py-1.5 hover:bg-muted flex items-center gap-2 text-foreground">
+          {isPinned ? <PinOff className="size-3" /> : <Pin className="size-3" />}
+          {isPinned ? "Unpin Column" : "Pin Column"}
+        </button>
+      </div>
+    </div>,
+    portal,
+  );
+}

package/src/web/components/database/glide-save-bar.tsx

@@ -0,0 +1,33 @@
+import { Save, Undo2 } from "lucide-react";
+
+interface SaveBarProps {
+  pendingCount: number;
+  onSave: () => void;
+  onDiscard: () => void;
+}
+
+/**
+ * Floating save bar shown when there are pending cell edits.
+ * Save with click or Mod+Enter. Discard with Escape.
+ */
+export function GlideSaveBar({ pendingCount, onSave, onDiscard }: SaveBarProps) {
+  if (pendingCount === 0) return null;
+
+  return (
+    <div className="flex items-center gap-2 px-3 py-1.5 border-t border-amber-400/50 bg-amber-50 dark:bg-amber-950/30 shrink-0 text-xs">
+      <span className="text-amber-700 dark:text-amber-300 font-medium">
+        {pendingCount} pending edit{pendingCount > 1 ? "s" : ""}
+      </span>
+      <div className="flex-1" />
+      <button type="button" onClick={onDiscard}
+        className="flex items-center gap-1 px-2 py-0.5 rounded text-muted-foreground hover:text-foreground hover:bg-muted transition-colors">
+        <Undo2 className="size-3" /> Discard
+      </button>
+      <button type="button" onClick={onSave}
+        className="flex items-center gap-1 px-2 py-0.5 rounded bg-primary text-primary-foreground hover:bg-primary/90 transition-colors">
+        <Save className="size-3" /> Save
+        <kbd className="ml-1 text-[9px] opacity-70">⌘↵</kbd>
+      </button>
+    </div>
+  );
+}

package/src/web/components/database/sql-query-editor.tsx

@@ -9,6 +9,8 @@ interface SqlQueryEditorProps {
   loading: boolean;
   defaultValue?: string;
   schemaInfo?: SchemaInfo;
+  /** Unique key for caching query text in sessionStorage (e.g. connectionId) */
+  cacheKey?: string;
 }
 
 /** Find the SQL statement surrounding the cursor line (split by ;) */
@@ -41,8 +43,13 @@ export function getStatementAtCursor(text: string, cursorLine: number): string {
 }
 
 /** Shared Monaco-based SQL query editor (editor only, no results) */
-export function SqlQueryEditor({ onExecute, loading, defaultValue = "SELECT * FROM ", schemaInfo }: SqlQueryEditorProps) {
-  const [query, setQuery] = useState(defaultValue);
+export function SqlQueryEditor({ onExecute, loading, defaultValue = "SELECT * FROM ", schemaInfo, cacheKey }: SqlQueryEditorProps) {
+  const storageKey = cacheKey ? `ppm:sql-query:${cacheKey}` : null;
+  const [query, setQuery] = useState(() => {
+    if (storageKey) { try { return sessionStorage.getItem(storageKey) ?? defaultValue; } catch { /* */ } }
+    return defaultValue;
+  });
+  const userEditedRef = useRef(false);
   const editorRef = useRef<MonacoType.editor.IStandaloneCodeEditor | null>(null);
   const monacoRef = useRef<typeof MonacoType | null>(null);
   const disposableRef = useRef<MonacoType.IDisposable | null>(null);
@@ -88,7 +95,10 @@ export function SqlQueryEditor({ onExecute, loading, defaultValue = "SELECT * FR
     }
   }, [schemaInfo]);
 
-  useEffect(() => { setQuery(defaultValue); }, [defaultValue]);
+  // Sync from defaultValue only if user hasn't manually edited
+  useEffect(() => {
+    if (!userEditedRef.current) setQuery(defaultValue);
+  }, [defaultValue]);
 
   return (
     <div className="h-full overflow-hidden">
@@ -97,7 +107,7 @@ export function SqlQueryEditor({ onExecute, loading, defaultValue = "SELECT * FR
         language="sql"
         theme={monacoTheme}
         value={query}
-        onChange={(v) => setQuery(v ?? "")}
+        onChange={(v) => { const val = v ?? ""; setQuery(val); userEditedRef.current = true; if (storageKey) try { sessionStorage.setItem(storageKey, val); } catch {} }}
         onMount={handleMount}
         options={{
           minimap: { enabled: false },

package/src/web/components/database/use-database.ts

@@ -2,7 +2,7 @@ import { useState, useCallback } from "react";
 import { api } from "@/lib/api-client";
 
 export interface DbTableInfo { name: string; schema: string; rowCount: number }
-export interface DbColumnInfo { name: string; type: string; nullable: boolean; pk: boolean; defaultValue: string | null }
+export interface DbColumnInfo { name: string; type: string; nullable: boolean; pk: boolean; defaultValue: string | null; fk?: { table: string; column: string } | null }
 export interface DbQueryResult { columns: string[]; rows: Record<string, unknown>[]; rowsAffected: number; changeType: "select" | "modify"; executionTimeMs?: number }
 interface DbTableData { columns: string[]; rows: Record<string, unknown>[]; total: number; page: number; limit: number }
 
@@ -146,6 +146,14 @@ export function useDatabase(connectionId: number) {
     fetchTableData(undefined, undefined, 1, newCol, newDir);
   }, [orderBy, orderDir, fetchTableData]);
 
+  /** Clear sort entirely */
+  const clearSort = useCallback(() => {
+    setOrderBy(null);
+    setOrderDir("ASC");
+    setPageState(1);
+    fetchTableData(undefined, undefined, 1, null, "ASC");
+  }, [fetchTableData]);
+
   /** Bulk delete rows */
   const bulkDelete = useCallback(async (pkColumn: string, pkValues: unknown[]) => {
     if (!selectedTable) return;
@@ -191,7 +199,7 @@ export function useDatabase(connectionId: number) {
   return {
     selectedTable, selectedSchema, selectTable, tableData, schema,
     loading, error, page, setPage: changePage,
-    orderBy, orderDir, toggleSort,
+    orderBy, orderDir, toggleSort, clearSort,
     queryResult, queryError, queryLoading, executeQuery,
     updateCell, deleteRow, bulkDelete, insertRow,
     refreshData: fetchTableData, queryAsTable,

package/src/web/components/database/use-glide-cell-content.ts

@@ -0,0 +1,159 @@
+import { useCallback, useRef } from "react";
+import { GridCellKind, type GridCell, type EditableGridCell, type Item } from "@glideapps/glide-data-grid";
+import type { GridColumnSchema } from "./glide-grid-types";
+import { formatCellValue } from "./glide-grid-types";
+import type { PendingEdit } from "./use-glide-pending-edits";
+
+/** Map DB type string to Glide cell kind */
+function dbTypeToKind(type: string): GridCellKind {
+  const t = type.toLowerCase();
+  if (/^(int|serial|bigint|smallint|float|double|decimal|numeric|real|money)/.test(t)) {
+    return GridCellKind.Number;
+  }
+  if (/^bool/.test(t)) return GridCellKind.Boolean;
+  return GridCellKind.Text;
+}
+
+/** Check if a PK column is auto-increment (serial, identity, nextval default) */
+function isAutoIncrement(col: GridColumnSchema): boolean {
+  const t = col.type.toLowerCase();
+  if (/^(serial|bigserial|smallserial)/.test(t)) return true;
+  if (/^(int|bigint|smallint|integer)/.test(t) && col.defaultValue && /nextval|identity|auto_increment/i.test(col.defaultValue)) return true;
+  // SQLite: INTEGER PRIMARY KEY is auto-increment by default
+  if (t === "integer" && col.pk && !col.defaultValue) return true;
+  return false;
+}
+
+/** Truncate display string for canvas rendering performance */
+function truncateDisplay(val: string, max = 200): string {
+  return val.length > max ? val.slice(0, max) + "…" : val;
+}
+
+/** Amber background for cells with pending unsaved edits */
+const PENDING_THEME = { bgCell: "rgba(251, 191, 36, 0.15)" };
+
+interface UseGlideCellContentResult {
+  getCellContent: (cell: Item) => GridCell;
+  onCellEdited: (cell: Item, newValue: EditableGridCell) => void;
+}
+
+/**
+ * Provides getCellContent and onCellEdited callbacks for Glide Data Grid.
+ * Uses refs for rows/columnOrder to avoid stale closures in canvas render loop.
+ * Integrates with pending edits — shows pending values with amber highlight.
+ */
+export function useGlideCellContent(
+  rows: Record<string, unknown>[],
+  columnOrder: string[],
+  schema: GridColumnSchema[],
+  pkCol: string | null,
+  addPendingEdit: (pkVal: unknown, col: string, newVal: unknown) => void,
+  pendingRef: React.RefObject<Map<string, PendingEdit>>,
+): UseGlideCellContentResult {
+  const rowsRef = useRef(rows);
+  rowsRef.current = rows;
+  const colOrderRef = useRef(columnOrder);
+  colOrderRef.current = columnOrder;
+
+  const schemaMap = useRef(new Map<string, GridColumnSchema>());
+  schemaMap.current = new Map(schema.map((s) => [s.name, s]));
+
+  const getCellContent = useCallback(([colIdx, rowIdx]: Item): GridCell => {
+    const colName = colOrderRef.current[colIdx];
+    const row = rowsRef.current[rowIdx];
+    if (!colName || !row) {
+      return { kind: GridCellKind.Text, data: "", displayData: "", allowOverlay: false };
+    }
+
+    const colSchema = schemaMap.current.get(colName);
+    const kind = colSchema ? dbTypeToKind(colSchema.type) : GridCellKind.Text;
+    const isPk = colSchema?.pk ?? false;
+
+    // Check for pending edit value
+    const pkVal = pkCol ? row[pkCol] : undefined;
+    const isNewRow = typeof pkVal === "string" && pkVal.startsWith("__new_");
+    const pendingKey = `${pkVal}:${colName}`;
+    const pending = pendingRef.current.get(pendingKey);
+    const val = pending !== undefined ? pending.newVal : row[colName];
+    const hasPending = pending !== undefined;
+
+    // New row PK column — auto-increment PKs show "NEW" (readonly), text PKs are editable
+    if (isPk && isNewRow) {
+      const isAuto = colSchema ? isAutoIncrement(colSchema) : false;
+      if (isAuto) {
+        return { kind: GridCellKind.Text, data: "", displayData: "AUTO", allowOverlay: false, readonly: true,
+          themeOverride: { textDark: "#6b7280" } };
+      }
+      // Editable PK (text, uuid, etc.) — show pending value or placeholder
+      const editedVal = pending !== undefined ? String(pending.newVal ?? "") : "";
+      return { kind: GridCellKind.Text, data: editedVal, displayData: editedVal || "Enter ID…",
+        allowOverlay: true, readonly: false,
+        themeOverride: editedVal ? (hasPending ? PENDING_THEME : undefined) : { textDark: "#9ca3af" } };
+    }
+
+    // NULL values — for new rows show default/type hints
+    if (val == null) {
+      let placeholder = isNewRow ? "" : "NULL";
+      if (isNewRow && !hasPending && colSchema) {
+        const t = colSchema.type.toLowerCase();
+        if (colSchema.defaultValue) {
+          placeholder = colSchema.defaultValue;
+        } else if (/^(timestamp|datetime|date)/.test(t)) {
+          placeholder = "NOW()";
+        } else if (/^(uuid)/.test(t)) {
+          placeholder = "gen_random_uuid()";
+        }
+      }
+      return {
+        kind: GridCellKind.Text, data: "", displayData: placeholder,
+        allowOverlay: !isPk, readonly: isPk,
+        themeOverride: hasPending ? PENDING_THEME : (isNewRow || placeholder !== "NULL" ? { textDark: "#9ca3af" } : { textDark: "#6b7280" }),
+      };
+    }
+
+    // Number cells
+    if (kind === GridCellKind.Number && typeof val === "number") {
+      return {
+        kind: GridCellKind.Number, data: val, displayData: String(val),
+        allowOverlay: !isPk, readonly: isPk,
+        themeOverride: hasPending ? PENDING_THEME : undefined,
+      };
+    }
+
+    // Boolean cells
+    if (kind === GridCellKind.Boolean && typeof val === "boolean") {
+      return { kind: GridCellKind.Boolean, data: val, readonly: isPk, allowOverlay: false };
+    }
+
+    // Text cell
+    const strVal = formatCellValue(val);
+    return {
+      kind: GridCellKind.Text, data: strVal, displayData: truncateDisplay(strVal),
+      allowOverlay: !isPk, readonly: isPk,
+      themeOverride: hasPending ? PENDING_THEME : undefined,
+    };
+  }, []); // stable — reads from refs
+
+  const onCellEdited = useCallback(([colIdx, rowIdx]: Item, newValue: EditableGridCell) => {
+    if (!pkCol) return;
+    const colName = colOrderRef.current[colIdx];
+    const row = rowsRef.current[rowIdx];
+    if (!colName || !row) return;
+
+    const pkVal = row[pkCol];
+    let parsed: unknown;
+    if (newValue.kind === GridCellKind.Text) {
+      parsed = newValue.data === "" ? null : newValue.data;
+    } else if (newValue.kind === GridCellKind.Number) {
+      parsed = newValue.data;
+    } else if (newValue.kind === GridCellKind.Boolean) {
+      parsed = newValue.data;
+    } else {
+      return;
+    }
+
+    addPendingEdit(pkVal, colName, parsed);
+  }, [pkCol, addPendingEdit]);
+
+  return { getCellContent, onCellEdited };
+}

package/src/web/components/database/use-glide-columns.ts

@@ -0,0 +1,69 @@
+import { useMemo } from "react";
+import type { GridColumn } from "@glideapps/glide-data-grid";
+import type { GridColumnSchema } from "./glide-grid-types";
+
+interface UseGlideColumnsResult {
+  /** Ordered GridColumn definitions (pinned first) */
+  columns: GridColumn[];
+  /** Number of frozen columns from left */
+  freezeColumns: number;
+  /** Column name order matching GridColumn indices */
+  columnOrder: string[];
+}
+
+/** Estimate column width from header name and sample row values */
+function estimateColWidth(name: string, rows: Record<string, unknown>[], type: string): number {
+  const headerW = name.length * 9 + 40; // header text + sort icon + menu icon padding
+  let maxContentW = 0;
+  const sampleCount = Math.min(rows.length, 20);
+  for (let i = 0; i < sampleCount; i++) {
+    const val = rows[i]?.[name];
+    if (val == null) continue;
+    const len = typeof val === "object" ? 12 : String(val).length;
+    maxContentW = Math.max(maxContentW, len * 8);
+  }
+  const isNumeric = /^(int|serial|bigint|smallint|float|double|decimal|numeric|real|money|bool)/.test(type.toLowerCase());
+  const minW = isNumeric ? 80 : 100;
+  return Math.max(minW, Math.min(Math.max(headerW, maxContentW) + 16, 400));
+}
+
+/**
+ * Build Glide Data Grid column definitions from schema.
+ * Reorders columns: pinned first, then unpinned. Auto-sizes widths.
+ */
+export function useGlideColumns(
+  schema: GridColumnSchema[],
+  columnNames: string[],
+  pinnedCols: Set<string>,
+  colWidths: Map<string, number>,
+  rows: Record<string, unknown>[],
+  orderBy?: string | null,
+  orderDir?: "ASC" | "DESC",
+): UseGlideColumnsResult {
+  return useMemo(() => {
+    const pinned = columnNames.filter((c) => pinnedCols.has(c));
+    const unpinned = columnNames.filter((c) => !pinnedCols.has(c));
+    const ordered = [...pinned, ...unpinned];
+
+    const schemaMap = new Map(schema.map((s) => [s.name, s]));
+
+    const columns: GridColumn[] = ordered.map((name) => {
+      const col = schemaMap.get(name);
+      const isPk = col?.pk ?? false;
+
+      let icon: string | undefined;
+      if (orderBy === name) {
+        icon = orderDir === "ASC" ? "sortAsc" : "sortDesc";
+      } else if (isPk) {
+        icon = "headerRowID";
+      } else if (col?.fk) {
+        icon = "headerFk";
+      }
+
+      const width = colWidths.get(name) ?? estimateColWidth(name, rows, col?.type ?? "text");
+      return { title: name, id: name, width, hasMenu: true, icon };
+    });
+
+    return { columns, freezeColumns: pinned.length, columnOrder: ordered };
+  }, [schema, columnNames, pinnedCols, colWidths, rows, orderBy, orderDir]);
+}

package/src/web/components/database/use-glide-grid-actions.ts

@@ -0,0 +1,164 @@
+import { useState, useCallback, useRef, useEffect } from "react";
+import { useShallow } from "zustand/react/shallow";
+import { useTabStore } from "@/stores/tab-store";
+import type { Item, GridSelection } from "@glideapps/glide-data-grid";
+import type { GridColumnSchema } from "./glide-grid-types";
+import { formatCellValue, detectLang, needsViewer } from "./glide-grid-types";
+import type { PreviewData } from "./glide-data-preview-panel";
+
+interface UseGlideGridActionsParams {
+  displayRows: Record<string, unknown>[];
+  columnOrder: string[];
+  schema: GridColumnSchema[];
+  pkCol: string | null;
+  connectionId?: number;
+  connectionName?: string;
+  selectedTable?: string | null;
+  selectedSchema?: string;
+  addEdit: (pkVal: unknown, col: string, newVal: unknown) => void;
+  /** Current grid selection — needed for document-level paste */
+  gridSelection?: GridSelection;
+  /** Container ref — paste only fires when focus is inside */
+  containerRef?: React.RefObject<HTMLElement | null>;
+}
+
+/**
+ * Extracts preview panel, paste handler, and FK navigation logic
+ * from the main GlideDataGrid component to keep it under 200 lines.
+ */
+export function useGlideGridActions(params: UseGlideGridActionsParams) {
+  const { displayRows, columnOrder, schema, pkCol, connectionId, connectionName, selectedTable, selectedSchema, addEdit, gridSelection, containerRef } = params;
+  const { openTab } = useTabStore(useShallow((s) => ({ openTab: s.openTab })));
+  const [previewData, setPreviewData] = useState<PreviewData | null>(null);
+
+  // Refs to avoid stale closures in canvas callbacks
+  const displayRowsRef = useRef(displayRows);
+  displayRowsRef.current = displayRows;
+  const columnOrderRef = useRef(columnOrder);
+  columnOrderRef.current = columnOrder;
+
+  // Preview panel — inline Monaco viewer for cell/row content
+  const openRowPreview = useCallback((rowIdx: number) => {
+    const row = displayRows[rowIdx]; if (!row) return;
+    const pk = pkCol ? String(row[pkCol] ?? "") : "";
+    const table = selectedTable ?? "";
+    const content = JSON.stringify(row, null, 2);
+    setPreviewData({ title: pk ? `Row #${pk}${table ? ` — ${table}` : ""}` : `Row — ${table}`,
+      content, language: "json", viewerKey: `${connectionId}:${table}:row:${pk}` });
+  }, [displayRows, pkCol, selectedTable, connectionId]);
+
+  const openCellPreview = useCallback((rowIdx: number, colIdx: number) => {
+    const row = displayRows[rowIdx]; if (!row) return;
+    const colName = columnOrder[colIdx]; if (!colName) return;
+    const val = formatCellValue(row[colName]);
+    const pk = pkCol ? String(row[pkCol] ?? rowIdx) : String(rowIdx);
+    const table = selectedTable ?? "";
+    setPreviewData({ title: `${colName} #${pk}${table ? ` — ${table}` : ""}`,
+      content: val, language: detectLang(val), viewerKey: `${connectionId}:${table}:${colName}:${pk}` });
+  }, [displayRows, columnOrder, pkCol, selectedTable, connectionId]);
+
+  const openPreviewInTab = useCallback(() => {
+    if (!previewData) return;
+    openTab({ type: "editor", title: previewData.title, projectId: null, closable: true,
+      metadata: { inlineContent: previewData.content, inlineLanguage: previewData.language, viewerKey: previewData.viewerKey } });
+  }, [openTab, previewData]);
+
+  // Custom paste handler — routes pasted TSV cells through addEdit
+  const handlePaste = useCallback((target: Item, values: readonly (readonly string[])[]) => {
+    if (!pkCol) return false;
+    const [startCol, startRow] = target;
+    for (let r = 0; r < values.length; r++) {
+      const row = displayRowsRef.current[startRow + r];
+      if (!row) continue;
+      const pk = row[pkCol];
+      for (let c = 0; c < values[r]!.length; c++) {
+        const colName = columnOrderRef.current[startCol + c];
+        if (!colName) continue;
+        const colDef = schema.find((s) => s.name === colName);
+        if (colDef?.pk) continue;
+        const raw = values[r]![c]!;
+        addEdit(pk, colName, raw === "" ? null : raw);
+      }
+    }
+    return false; // we handled it
+  }, [pkCol, schema, addEdit]);
+
+  // Document-level paste listener — works even when Glide canvas doesn't have focus
+  const schemaRef = useRef(schema);
+  schemaRef.current = schema;
+  const gridSelRef = useRef(gridSelection);
+  gridSelRef.current = gridSelection;
+  const addEditRef = useRef(addEdit);
+  addEditRef.current = addEdit;
+  const pkColRef = useRef(pkCol);
+  pkColRef.current = pkCol;
+
+  useEffect(() => {
+    if (!containerRef) return;
+    const handler = (e: ClipboardEvent) => {
+      const container = containerRef.current;
+      if (!container || !container.contains(document.activeElement)) return;
+      // Skip if an input/textarea is focused (e.g. search bar)
+      const tag = (document.activeElement as HTMLElement)?.tagName;
+      if (tag === "INPUT" || tag === "TEXTAREA") return;
+      const pk = pkColRef.current;
+      if (!pk) return;
+      const sel = gridSelRef.current?.current;
+      if (!sel) return; // need a selected cell as paste anchor
+      const text = e.clipboardData?.getData("text/plain");
+      if (!text) return;
+      const tsvRows = text.split(/\r?\n/).filter((r) => r.length > 0).map((r) => r.split("\t"));
+      if (tsvRows.length === 0) return;
+      const [startCol, startRow] = sel.cell;
+      for (let r = 0; r < tsvRows.length; r++) {
+        const row = displayRowsRef.current[startRow + r];
+        if (!row) continue;
+        const rowPk = row[pk];
+        for (let c = 0; c < tsvRows[r]!.length; c++) {
+          const colName = columnOrderRef.current[startCol + c];
+          if (!colName) continue;
+          const colDef = schemaRef.current.find((s) => s.name === colName);
+          if (colDef?.pk) continue;
+          const raw = tsvRows[r]![c]!;
+          addEditRef.current(rowPk, colName, raw === "" ? null : raw);
+        }
+      }
+      e.preventDefault();
+    };
+    document.addEventListener("paste", handler);
+    return () => document.removeEventListener("paste", handler);
+  }, [containerRef]);
+
+  // FK detection helpers for context menu
+  const getContextFk = useCallback((colName: string | null) => {
+    if (!colName) return null;
+    return schema.find((s) => s.name === colName)?.fk ?? null;
+  }, [schema]);
+
+  const isCellViewable = useCallback((row: Record<string, unknown> | null, colName: string | null) => {
+    return row && colName ? needsViewer(row[colName]) : false;
+  }, []);
+
+  // FK navigation: open referenced table in new tab filtered by FK value
+  const openFkTable = useCallback((fk: { table: string; column: string }, cellValue: unknown) => {
+    if (cellValue == null || !connectionId) return;
+    openTab({
+      type: "database",
+      title: `${connectionName ?? "DB"} · ${fk.table}`,
+      projectId: null,
+      closable: true,
+      metadata: {
+        connectionId, connectionName,
+        tableName: fk.table,
+        schemaName: selectedSchema ?? "public",
+        initialSql: `SELECT * FROM "${fk.table}" WHERE "${fk.column}" = '${String(cellValue).replace(/'/g, "''")}'`,
+      },
+    });
+  }, [connectionId, connectionName, selectedSchema, openTab]);
+
+  return {
+    previewData, setPreviewData,
+    openRowPreview, openCellPreview, openPreviewInTab,
+    handlePaste, getContextFk, isCellViewable, openFkTable,
+  };
+}