create-grist-widget 0.3.7 → 0.3.9

package/examples/spreadsheet-grid/GristRdgGrid.tsx

@@ -0,0 +1,189 @@
+import { useCallback, useEffect, useMemo, useRef, useState } from "react"
+import type { Column } from "react-datasheet-grid"
+
+import {
+  ShadcnDataSheetGrid,
+  type DataSheetGridProps,
+} from "@/components/ui/ShadcnDataSheetGrid"
+
+type RowWithOptionalId = { id?: number } & Record<string, unknown>
+
+export type GristGridOperation = {
+  type: "UPDATE" | "DELETE" | "CREATE"
+  fromRowIndex: number
+  toRowIndex: number
+}
+
+export type GristRdgGridColumn<RowT extends RowWithOptionalId> = {
+  id: string
+  column: Partial<Column<RowT, unknown, unknown>>
+  minWidth?: number
+}
+
+export type GristRdgGridProps<RowT extends RowWithOptionalId> = {
+  rows: RowT[]
+  columns: GristRdgGridColumn<RowT>[]
+  onChange: NonNullable<DataSheetGridProps<RowT>["onChange"]>
+  onActiveRowIdChange?: (rowId: number) => void
+  selectedRowId?: number | null
+  invalidCellKeys?: ReadonlySet<string>
+  height?: number
+  rowHeight?: number
+  autoAddRow?: boolean
+  lockRows?: boolean
+  className?: string
+  footer?: React.ReactNode
+}
+
+export function GristRdgGrid<RowT extends RowWithOptionalId>({
+  rows,
+  columns,
+  onChange,
+  onActiveRowIdChange,
+  selectedRowId,
+  invalidCellKeys,
+  height,
+  rowHeight = 32,
+  autoAddRow = false,
+  lockRows = false,
+  className,
+  footer,
+}: GristRdgGridProps<RowT>) {
+  const [columnWidths, setColumnWidths] = useState<Record<string, number>>({})
+  const resizeStateRef = useRef<{
+    colId: string
+    startX: number
+    startWidth: number
+  } | null>(null)
+
+  const startColumnResize = useCallback(
+    (e: React.PointerEvent, colId: string, minWidth: number) => {
+      e.preventDefault()
+      e.stopPropagation()
+      const current = columnWidths[colId]
+      const startWidth = typeof current === "number" ? current : minWidth
+      resizeStateRef.current = {
+        colId,
+        startX: e.clientX,
+        startWidth,
+      }
+    },
+    [columnWidths]
+  )
+
+  useEffect(() => {
+    const onMove = (e: PointerEvent) => {
+      const state = resizeStateRef.current
+      if (!state) return
+      const next = Math.max(70, state.startWidth + (e.clientX - state.startX))
+      setColumnWidths((prev) => ({ ...prev, [state.colId]: next }))
+    }
+    const onUp = () => {
+      resizeStateRef.current = null
+    }
+    window.addEventListener("pointermove", onMove)
+    window.addEventListener("pointerup", onUp)
+    return () => {
+      window.removeEventListener("pointermove", onMove)
+      window.removeEventListener("pointerup", onUp)
+    }
+  }, [])
+
+  const resolvedColumns = useMemo<Partial<Column<RowT, unknown, unknown>>[]>(
+    () =>
+      columns.map(({ id: colId, column, minWidth: explicitMinWidth }) => {
+        const minWidth = explicitMinWidth ?? (colId === "id" ? 70 : 120)
+        const hasCustomWidth = typeof columnWidths[colId] === "number"
+        const basis = hasCustomWidth
+          ? (columnWidths[colId] as number)
+          : minWidth
+        const existingCellClassName = column.cellClassName
+        return {
+          ...column,
+          cellClassName: (opt: {
+            rowData: RowT
+            rowIndex: number
+            columnId?: string
+          }) => {
+            const baseClass =
+              typeof existingCellClassName === "function"
+                ? (
+                    existingCellClassName as (
+                      arg: typeof opt
+                    ) => string | undefined
+                  )(opt)
+                : (existingCellClassName ?? "")
+            const isInvalid =
+              typeof opt.rowData?.id === "number" &&
+              Boolean(invalidCellKeys?.has(`${opt.rowData.id}:${colId}`))
+            if (!isInvalid) return baseClass
+            return baseClass
+              ? `${baseClass} grist-invalid-number-cell`
+              : "grist-invalid-number-cell"
+          },
+          minWidth,
+          basis,
+          grow: hasCustomWidth ? 0 : 1,
+          shrink: hasCustomWidth ? 0 : 1,
+          title: (
+            <div className="relative flex h-full w-full items-center pr-3">
+              <span className="block w-full truncate pr-2">
+                {String(column.title ?? colId)}
+              </span>
+              <button
+                type="button"
+                aria-label={`Resize ${colId}`}
+                className="absolute inset-y-0 right-0 w-2 cursor-col-resize bg-border/40 hover:bg-border"
+                onPointerDown={(e) => startColumnResize(e, colId, minWidth)}
+              />
+            </div>
+          ),
+        } as Partial<Column<RowT, unknown, unknown>>
+      }),
+    [columns, columnWidths, invalidCellKeys, startColumnResize]
+  )
+
+  const handleActiveCellChange = useCallback(
+    (opts: unknown) => {
+      if (!onActiveRowIdChange) return
+      const cell =
+        typeof opts === "object" && opts !== null && "cell" in opts
+          ? (opts as { cell?: { rowId?: unknown; row?: unknown } | null }).cell
+          : (opts as { rowId?: unknown; row?: unknown } | null)
+      if (!cell) return
+      let rowId: number | null = null
+      if (typeof cell.rowId === "number") {
+        rowId = cell.rowId
+      } else if (typeof cell.row === "number") {
+        const row = rows[cell.row]
+        rowId = typeof row?.id === "number" ? row.id : null
+      }
+      if (rowId === null || rowId === selectedRowId) return
+      onActiveRowIdChange(rowId)
+    },
+    [onActiveRowIdChange, rows, selectedRowId]
+  )
+
+  return (
+    <div className="flex h-full min-h-0 flex-col gap-2">
+      <style>{`.grist-invalid-number-cell{background:rgba(239,68,68,0.12)!important;}`}</style>
+      <div className="min-h-0 flex-1 overflow-auto">
+        <ShadcnDataSheetGrid<RowT>
+          value={rows}
+          columns={resolvedColumns}
+          onChange={onChange}
+          onActiveCellChange={handleActiveCellChange as never}
+          rowKey="id"
+          height={height}
+          rowHeight={rowHeight}
+          autoAddRow={autoAddRow}
+          lockRows={lockRows}
+          className={className}
+        />
+      </div>
+      {footer ? (
+        <p className="shrink-0 text-xs text-muted-foreground">{footer}</p>
+      ) : null}
+    </div>
+  )
+}

package/examples/spreadsheet-grid/GristSchemaToolbar.tsx

@@ -0,0 +1,293 @@
+import { useState } from "react"
+import { Plus, RefreshCw, X } from "lucide-react"
+
+import {
+  gristModifyColumnAction,
+  gristRemoveColumnAction,
+  gristRenameColumnAction,
+  useGristContext,
+  useGristSchema,
+  type GristUserActionTuple,
+  type UseGristSchemaResult,
+} from "grist-widget-sdk"
+
+import { Button } from "@/components/ui/button"
+import { Input } from "@/components/ui/input"
+
+import {
+  GRIST_TOOLBAR_COLUMN_TYPES,
+  type GristToolbarColumnType,
+} from "./grist-rdg-columns"
+
+export type GristSchemaToolbarProps = {
+  /**
+   * Optional pre-fetched schema. Shared with `<GristDataSheetGrid>` so we
+   * don't issue duplicate `_grist_Tables_column` reads.
+   */
+  schema?: UseGristSchemaResult
+  /** Per-action toggles. All enabled by default. */
+  enable?: {
+    add?: boolean
+    rename?: boolean
+    retype?: boolean
+    remove?: boolean
+  }
+  className?: string
+}
+
+/**
+ * Renders inline controls for column add / rename / type-change / remove
+ * against the currently-selected Grist table.
+ *
+ * Writes use `useGrist().applyActions(...)` with the SDK's exported action
+ * builders. Schema is reloaded after each mutation so the chip list reflects
+ * the new state immediately.
+ */
+export function GristSchemaToolbar({
+  schema: schemaProp,
+  enable,
+  className,
+}: GristSchemaToolbarProps) {
+  const w = useGristContext()
+  const internalSchema = useGristSchema({
+    tableId: schemaProp ? undefined : (w.currentTableId ?? undefined),
+    requiredAccess: "full",
+  })
+  const schema = schemaProp ?? internalSchema
+
+  const [adding, setAdding] = useState(false)
+  const [newColId, setNewColId] = useState("")
+  const [newType, setNewType] = useState<GristToolbarColumnType>("Text")
+
+  const tableId = w.currentTableId
+  const can = {
+    add: enable?.add ?? true,
+    rename: enable?.rename ?? true,
+    retype: enable?.retype ?? true,
+    remove: enable?.remove ?? true,
+  }
+
+  if (!tableId) return null
+  if (!schema.table) {
+    return (
+      <p className={className ?? "text-xs text-muted-foreground"}>
+        Loading schema…
+      </p>
+    )
+  }
+
+  const cols = Object.entries(schema.table.columns ?? {})
+
+  const handleAdd = async () => {
+    const id = newColId.trim()
+    if (!id) return
+    try {
+      // `AddVisibleColumn` (instead of plain `AddColumn`) also adds the new
+      // column to the *active* section's view fields, so Grist users see it
+      // straight away in the table view they're working with. There's no
+      // dedicated builder for this in the SDK; we hand-write the tuple.
+      const action: GristUserActionTuple = [
+        "AddVisibleColumn",
+        tableId,
+        id,
+        { type: newType, label: id },
+      ]
+      await w.applyActions([action])
+      await schema.reload()
+      setAdding(false)
+      setNewColId("")
+      setNewType("Text")
+    } catch {
+      // Surfaced via <GristSdkAlerts>.
+    }
+  }
+
+  const handleRename = async (oldId: string, rawNewId: string) => {
+    const newId = rawNewId.trim()
+    if (!newId || newId === oldId) return
+    try {
+      await w.applyActions([gristRenameColumnAction(tableId, oldId, newId)])
+      await schema.reload()
+    } catch {
+      /* surfaced via <GristSdkAlerts> */
+    }
+  }
+
+  const handleType = async (colId: string, type: string) => {
+    try {
+      await w.applyActions([gristModifyColumnAction(tableId, colId, { type })])
+      await schema.reload()
+    } catch {
+      /* surfaced via <GristSdkAlerts> */
+    }
+  }
+
+  const handleDelete = async (colId: string) => {
+    if (!window.confirm(`Remove column "${colId}"?`)) return
+    try {
+      await w.applyActions([gristRemoveColumnAction(tableId, colId)])
+      await schema.reload()
+    } catch {
+      /* surfaced via <GristSdkAlerts> */
+    }
+  }
+
+  const isPending = w.actionStatus === "running"
+
+  return (
+    <div className={className ?? "flex flex-wrap items-center gap-1.5"}>
+      <span className="mr-1 text-xs font-medium tracking-wide text-muted-foreground uppercase">
+        Columns
+      </span>
+      <Button
+        type="button"
+        variant="ghost"
+        size="icon-xs"
+        disabled={isPending || schema.loading}
+        onClick={() => void schema.reload()}
+        aria-label="Reload schema"
+        title="Reload schema"
+      >
+        <RefreshCw
+          className={schema.loading ? "size-3 animate-spin" : "size-3"}
+        />
+      </Button>
+
+      {cols.map(([colId, col]) => {
+        const currentType =
+          (typeof col.type === "string" ? col.type : "Text") || "Text"
+        return (
+          <div
+            key={colId}
+            className="inline-flex items-center gap-1 rounded-md border bg-background px-1.5 py-0.5 text-xs"
+          >
+            <Input
+              key={colId}
+              defaultValue={colId}
+              disabled={!can.rename || isPending}
+              className="h-6 w-24 px-1.5 text-xs"
+              onKeyDown={(e) => {
+                if (e.key === "Enter") {
+                  e.currentTarget.blur()
+                } else if (e.key === "Escape") {
+                  e.currentTarget.value = colId
+                  e.currentTarget.blur()
+                }
+              }}
+              onBlur={(e) => {
+                if (!can.rename) return
+                void handleRename(colId, e.currentTarget.value)
+              }}
+              aria-label={`Rename ${colId}`}
+            />
+            <select
+              value={
+                GRIST_TOOLBAR_COLUMN_TYPES.includes(
+                  currentType as GristToolbarColumnType
+                )
+                  ? (currentType as GristToolbarColumnType)
+                  : "Any"
+              }
+              disabled={!can.retype || isPending}
+              onChange={(e) => void handleType(colId, e.target.value)}
+              className="h-6 rounded border border-input bg-background px-1 text-xs"
+              aria-label={`Type of ${colId}`}
+            >
+              {GRIST_TOOLBAR_COLUMN_TYPES.map((t) => (
+                <option key={t} value={t}>
+                  {t}
+                </option>
+              ))}
+              {/* Show the actual type if it's not in the toolbar's curated list (e.g. Ref:Foo). */}
+              {!GRIST_TOOLBAR_COLUMN_TYPES.includes(
+                currentType as GristToolbarColumnType
+              ) ? (
+                <option value={currentType}>{currentType}</option>
+              ) : null}
+            </select>
+            <Button
+              type="button"
+              variant="ghost"
+              size="icon-xs"
+              disabled={!can.remove || isPending}
+              onClick={() => void handleDelete(colId)}
+              aria-label={`Remove ${colId}`}
+            >
+              <X className="size-3" />
+            </Button>
+          </div>
+        )
+      })}
+
+      {can.add ? (
+        adding ? (
+          <div className="inline-flex items-center gap-1 rounded-md border bg-background px-1.5 py-0.5 text-xs">
+            <Input
+              autoFocus
+              placeholder="colId"
+              value={newColId}
+              disabled={isPending}
+              className="h-6 w-24 px-1.5 text-xs"
+              onChange={(e) => setNewColId(e.target.value)}
+              onKeyDown={(e) => {
+                if (e.key === "Enter") {
+                  e.preventDefault()
+                  void handleAdd()
+                } else if (e.key === "Escape") {
+                  setAdding(false)
+                  setNewColId("")
+                }
+              }}
+            />
+            <select
+              value={newType}
+              disabled={isPending}
+              onChange={(e) =>
+                setNewType(e.target.value as GristToolbarColumnType)
+              }
+              className="h-6 rounded border border-input bg-background px-1 text-xs"
+              aria-label="New column type"
+            >
+              {GRIST_TOOLBAR_COLUMN_TYPES.map((t) => (
+                <option key={t} value={t}>
+                  {t}
+                </option>
+              ))}
+            </select>
+            <Button
+              type="button"
+              size="xs"
+              disabled={isPending || !newColId.trim()}
+              onClick={() => void handleAdd()}
+            >
+              Add
+            </Button>
+            <Button
+              type="button"
+              size="xs"
+              variant="ghost"
+              disabled={isPending}
+              onClick={() => {
+                setAdding(false)
+                setNewColId("")
+              }}
+            >
+              Cancel
+            </Button>
+          </div>
+        ) : (
+          <Button
+            type="button"
+            size="xs"
+            variant="outline"
+            onClick={() => setAdding(true)}
+            disabled={isPending}
+          >
+            <Plus className="size-3" />
+            Column
+          </Button>
+        )
+      ) : null}
+    </div>
+  )
+}

package/examples/spreadsheet-grid/WidgetApp.tsx

@@ -0,0 +1,133 @@
+import { useEffect, useRef, useState } from "react"
+
+import {
+  useGristContext,
+  useGristSchema,
+  useWidgetMetadata,
+  type UseGristOptions,
+} from "grist-widget-sdk"
+
+import { Button } from "@/components/ui/button"
+
+import { GristDataSheetGrid } from "./GristDataSheetGrid"
+import { GristSchemaToolbar } from "./GristSchemaToolbar"
+
+function downloadReplicaJson(label: string, doc: unknown) {
+  const safe = label.replace(/[^a-z0-9-]+/gi, "-").toLowerCase()
+  const blob = new Blob([JSON.stringify(doc, null, 2)], {
+    type: "application/json",
+  })
+  const url = URL.createObjectURL(blob)
+  const a = document.createElement("a")
+  a.href = url
+  a.download = `replica-${safe}.json`
+  a.click()
+  URL.revokeObjectURL(url)
+}
+
+export const GRIST_OPTIONS: UseGristOptions = {
+  /** Required so `table.update` / `applyUserActions` succeed. */
+  requiredAccess: "full",
+  /** Needed so `setCursorPos` / linked selection can drive host row focus. */
+  allowSelectBy: true,
+}
+
+export const WIDGET_METADATA = {
+  title: "Spreadsheet grid",
+  description:
+    "Selected Grist section rendered as a fully-synced, editable spreadsheet via react-datasheet-grid, plus a schema toolbar and replica-document export.",
+} as const
+
+export function WidgetApp() {
+  useWidgetMetadata(WIDGET_METADATA)
+
+  // Hoist the schema fetch so the grid + toolbar share it (single
+  // `_grist_Tables_column` round-trip per reload).
+  const w = useGristContext()
+  const schema = useGristSchema({
+    tableId: w.currentTableId ?? undefined,
+    requiredAccess: "full",
+    excludeManualSort: true,
+  })
+
+  const [exporting, setExporting] = useState<string | null>(null)
+  const [showSchemaToolbar, setShowSchemaToolbar] = useState(false)
+  const gridHostRef = useRef<HTMLDivElement | null>(null)
+  const [gridHeight, setGridHeight] = useState<number | undefined>(undefined)
+
+  useEffect(() => {
+    const host = gridHostRef.current
+    if (!host) return
+    const update = () => {
+      const next = Math.floor(host.getBoundingClientRect().height)
+      if (next > 0) setGridHeight(next)
+    }
+    update()
+    const observer = new ResizeObserver(update)
+    observer.observe(host)
+    return () => observer.disconnect()
+  }, [])
+
+  async function exportReplica(
+    key: string,
+    includeRows: false | "samples" | "full"
+  ) {
+    if (!w.isReady) return
+    setExporting(key)
+    try {
+      const doc = await w.buildReplicaDocumentFromDocApi({
+        includeRows,
+        source: "spreadsheet-grid-export",
+      })
+      downloadReplicaJson(key, doc)
+    } finally {
+      setExporting(null)
+    }
+  }
+
+  return (
+    <div className="flex h-svh min-h-0 flex-col gap-3 p-4">
+      <div className="flex flex-wrap items-center gap-2">
+        <Button
+          type="button"
+          variant="outline"
+          size="sm"
+          disabled={!w.isReady || exporting !== null}
+          onClick={() => void exportReplica("schema-only", false)}
+        >
+          {exporting === "schema-only" ? "…" : "Export schema"}
+        </Button>
+        <Button
+          type="button"
+          variant="outline"
+          size="sm"
+          disabled={!w.isReady || exporting !== null}
+          onClick={() => void exportReplica("schema-samples", "samples")}
+        >
+          {exporting === "schema-samples" ? "…" : "Export schema + samples"}
+        </Button>
+        <Button
+          type="button"
+          variant="outline"
+          size="sm"
+          disabled={!w.isReady || exporting !== null}
+          onClick={() => void exportReplica("schema-data", "full")}
+        >
+          {exporting === "schema-data" ? "…" : "Export schema + data"}
+        </Button>
+        <Button
+          type="button"
+          variant="outline"
+          size="sm"
+          onClick={() => setShowSchemaToolbar((v) => !v)}
+        >
+          {showSchemaToolbar ? "Hide schema toolbar" : "Show schema toolbar"}
+        </Button>
+      </div>
+      {showSchemaToolbar ? <GristSchemaToolbar schema={schema} /> : null}
+      <div ref={gridHostRef} className="min-h-0 flex-1 overflow-hidden">
+        <GristDataSheetGrid schema={schema} autoAddRow height={gridHeight} />
+      </div>
+    </div>
+  )
+}