create-grist-widget 0.3.7 → 0.3.9

package/examples/attachment-gallery/WidgetApp.tsx

@@ -0,0 +1,202 @@
+import { useEffect, useState } from "react"
+
+import {
+  extractGristAttachmentIdsFromCell,
+  useGrist,
+  useWidgetMetadata,
+  type UseGristOptions,
+} from "grist-widget-sdk"
+
+import { Button } from "@/components/ui/button"
+
+export const GRIST_OPTIONS: UseGristOptions = {
+  requiredAccess: "full",
+  columns: [{ name: "Attachments", type: "Attachments" }],
+}
+
+export const WIDGET_METADATA = {
+  title: "Attachment gallery",
+  description:
+    "Thumbnail grid of every attachment in the selected row. Showcases extractGristAttachmentIdsFromCell + useGrist().fetchAttachmentBlob.",
+} as const
+
+type Thumb = {
+  id: string
+  url: string
+  contentType: string
+}
+
+export function WidgetApp() {
+  useWidgetMetadata(WIDGET_METADATA)
+  const w = useGrist()
+
+  const cellValue = w.mappedRecord?.Attachments ?? null
+  const ids = extractGristAttachmentIdsFromCell(cellValue)
+  const idsKey = ids.join(",")
+
+  if (w.status === "booting") {
+    return <Empty title="Connecting to Grist…" body="" />
+  }
+
+  if (!w.columnMappingStatus.ok) {
+    return (
+      <Empty
+        title="Missing column mapping"
+        body="Open the widget configuration panel and map the Attachments column."
+      />
+    )
+  }
+
+  if (w.mode === "empty") {
+    return (
+      <Empty
+        title="No row selected"
+        body="Select a row in the host Grist section to see its attachments."
+      />
+    )
+  }
+
+  if (ids.length === 0) {
+    return (
+      <Empty
+        title="No attachments in this row"
+        body="The mapped Attachments column is empty for the selected row."
+      />
+    )
+  }
+
+  const rowKey = `${String(w.record?.id ?? "")}:${idsKey}`
+
+  return (
+    <AttachmentGrid
+      key={rowKey}
+      ids={ids}
+      recordId={w.record?.id}
+      fetchAttachmentBlob={w.fetchAttachmentBlob}
+    />
+  )
+}
+
+function AttachmentGrid({
+  ids,
+  recordId,
+  fetchAttachmentBlob,
+}: {
+  ids: string[]
+  recordId: unknown
+  fetchAttachmentBlob: ReturnType<typeof useGrist>["fetchAttachmentBlob"]
+}) {
+  const [thumbs, setThumbs] = useState<Thumb[]>([])
+  const [error, setError] = useState<string | null>(null)
+  const [loading, setLoading] = useState(true)
+
+  // Stable string key so the effect doesn't re-fire when the parent
+  // re-renders with a structurally identical but referentially new array.
+  const idsKey = ids.join(",")
+
+  useEffect(() => {
+    const currentIds = idsKey ? idsKey.split(",") : []
+    let cancelled = false
+    const objectUrls: string[] = []
+    void (async () => {
+      try {
+        const next: Thumb[] = []
+        for (const id of currentIds) {
+          const fetched = await fetchAttachmentBlob(id)
+          if (cancelled) return
+          const url = URL.createObjectURL(fetched.blob)
+          objectUrls.push(url)
+          next.push({
+            id,
+            url,
+            contentType: fetched.contentType,
+          })
+        }
+        if (!cancelled) setThumbs(next)
+      } catch (err) {
+        if (!cancelled)
+          setError(err instanceof Error ? err.message : String(err))
+      } finally {
+        if (!cancelled) setLoading(false)
+      }
+    })()
+    return () => {
+      cancelled = true
+      for (const u of objectUrls) URL.revokeObjectURL(u)
+    }
+  }, [idsKey, fetchAttachmentBlob])
+
+  return (
+    <div className="flex h-svh min-h-0 flex-col gap-3 p-4">
+      <header>
+        <h1 className="text-lg font-medium">Attachments</h1>
+        <p className="text-sm text-muted-foreground">
+          {ids.length} attachment{ids.length === 1 ? "" : "s"} on row{" "}
+          <code className="rounded bg-muted px-1 text-xs">
+            {String(recordId ?? "?")}
+          </code>
+        </p>
+      </header>
+
+      {error ? (
+        <p className="rounded border border-destructive/30 bg-destructive/5 p-3 text-sm text-destructive">
+          {error}
+        </p>
+      ) : null}
+
+      {loading ? (
+        <p className="text-xs text-muted-foreground">Loading thumbnails…</p>
+      ) : null}
+
+      <div className="grid min-h-0 flex-1 grid-cols-2 gap-3 overflow-auto sm:grid-cols-3 lg:grid-cols-4">
+        {thumbs.map((thumb) => (
+          <Thumbnail key={thumb.id} thumb={thumb} />
+        ))}
+      </div>
+    </div>
+  )
+}
+
+function Thumbnail({ thumb }: { thumb: Thumb }) {
+  const isImage = thumb.contentType.startsWith("image/")
+  const label = `attachment-${thumb.id}`
+
+  return (
+    <figure className="group flex flex-col gap-2 rounded-lg border bg-card p-2">
+      <div className="flex aspect-square items-center justify-center overflow-hidden rounded bg-muted">
+        {isImage ? (
+          <img
+            src={thumb.url}
+            alt={label}
+            className="size-full object-cover"
+          />
+        ) : (
+          <span className="text-xs text-muted-foreground">
+            {thumb.contentType || "binary"}
+          </span>
+        )}
+      </div>
+      <figcaption className="flex items-center justify-between gap-2">
+        <span className="truncate text-xs">{label}</span>
+        <Button asChild variant="outline" size="sm">
+          <a href={thumb.url} download={label}>
+            Save
+          </a>
+        </Button>
+      </figcaption>
+    </figure>
+  )
+}
+
+function Empty({ title, body }: { title: string; body: string }) {
+  return (
+    <div className="flex h-svh items-center justify-center p-6">
+      <div className="max-w-sm text-center">
+        <h2 className="font-medium">{title}</h2>
+        {body ? (
+          <p className="mt-2 text-sm text-muted-foreground">{body}</p>
+        ) : null}
+      </div>
+    </div>
+  )
+}

package/examples/bulk-mark-done/WidgetApp.tsx

@@ -0,0 +1,43 @@
+import {
+  useGrist,
+  useWidgetMetadata,
+  type UseGristOptions,
+} from "grist-widget-sdk"
+
+import { Button } from "@/components/ui/button"
+
+export const GRIST_OPTIONS: UseGristOptions = {
+  requiredAccess: "full",
+  columns: [{ name: "Done", type: "Bool" }],
+}
+
+export const WIDGET_METADATA = {
+  title: "Bulk mark done",
+  description: "Bulk table.update with an array of row patches.",
+} as const
+
+export function WidgetApp() {
+  useWidgetMetadata(WIDGET_METADATA)
+  const w = useGrist()
+
+  if (!w.columnMappingStatus.ok) {
+    return <p className="p-4 text-sm">Map the Done column.</p>
+  }
+
+  async function markAll() {
+    if (!w.records) return
+    const updates = w.records.map((row) => ({
+      id: row.id as number,
+      fields: w.mapBack({ Done: true }),
+    }))
+    await w.table.update(updates)
+  }
+
+  return (
+    <div className="p-4">
+      <Button type="button" onClick={() => void markAll()}>
+        Mark all rows done
+      </Button>
+    </div>
+  )
+}

package/examples/declared-columns/WidgetApp.tsx

@@ -0,0 +1,42 @@
+import {
+  useGrist,
+  useWidgetMetadata,
+  type UseGristOptions,
+} from "grist-widget-sdk"
+
+export const GRIST_OPTIONS: UseGristOptions = {
+  requiredAccess: "full",
+  columns: [
+    { name: "Title", type: "Text" },
+    { name: "Done", type: "Bool" },
+    { name: "Tags", type: "ChoiceList", allowMultiple: true, optional: true },
+  ],
+}
+
+export const WIDGET_METADATA = {
+  title: "Declared columns",
+  description:
+    "Shows GRIST_OPTIONS column declarations and mappedRecord after the user maps columns.",
+} as const
+
+export function WidgetApp() {
+  useWidgetMetadata(WIDGET_METADATA)
+  const w = useGrist()
+
+  if (!w.columnMappingStatus.ok) {
+    return (
+      <p className="p-4 text-sm">
+        Map columns in the widget panel:{" "}
+        {w.columnMappingStatus.missing.join(", ")}
+      </p>
+    )
+  }
+
+  if (w.mode === "empty") return <p className="p-4 text-sm">Select a row.</p>
+
+  return (
+    <pre className="overflow-auto p-4 text-xs">
+      {JSON.stringify(w.mappedRecord, null, 2)}
+    </pre>
+  )
+}

package/examples/form-edit/WidgetApp.tsx

@@ -0,0 +1,225 @@
+import { useState, type FormEvent, type ReactNode } from "react"
+
+import {
+  useGrist,
+  useWidgetMetadata,
+  type UseGristOptions,
+  type UseGristResult,
+} from "grist-widget-sdk"
+
+import { Alert, AlertDescription, AlertTitle } from "@/components/ui/alert"
+import { Button } from "@/components/ui/button"
+import { Input } from "@/components/ui/input"
+
+export const GRIST_OPTIONS: UseGristOptions = {
+  requiredAccess: "full",
+  columns: [
+    { name: "Title", type: "Text" },
+    { name: "Description", type: "Text", optional: true },
+    { name: "Done", type: "Bool" },
+    { name: "Priority", type: "Text", optional: true },
+  ],
+}
+
+export const WIDGET_METADATA = {
+  title: "Row editor",
+  description:
+    "Edit the selected row in a polished form. Showcases column mappings, write status, and error UI.",
+} as const
+
+type FormEditMappedRecord = {
+  Title?: unknown
+  Description?: unknown
+  Done?: unknown
+  Priority?: unknown
+}
+
+type FormEditGrist = UseGristResult<Record<string, unknown>, FormEditMappedRecord>
+
+type Draft = {
+  title: string
+  description: string
+  done: boolean
+  priority: string
+}
+
+function readDraft(mapped: FormEditMappedRecord | null): Draft {
+  return {
+    title:
+      typeof mapped?.Title === "string"
+        ? mapped.Title
+        : mapped?.Title == null
+          ? ""
+          : String(mapped.Title),
+    description:
+      typeof mapped?.Description === "string"
+        ? mapped.Description
+        : mapped?.Description == null
+          ? ""
+          : String(mapped.Description),
+    done: mapped?.Done === true,
+    priority:
+      typeof mapped?.Priority === "string"
+        ? mapped.Priority
+        : mapped?.Priority == null
+          ? ""
+          : String(mapped.Priority),
+  }
+}
+
+export function WidgetApp() {
+  useWidgetMetadata(WIDGET_METADATA)
+  const w = useGrist<Record<string, unknown>, FormEditMappedRecord>()
+
+  if (w.status === "booting") {
+    return <Empty title="Connecting to Grist…" body="" />
+  }
+
+  if (!w.columnMappingStatus.ok) {
+    return (
+      <Empty
+        title="Missing column mappings"
+        body="Open the widget configuration panel and map the four required columns: Title, Done, Description (optional), Priority (optional)."
+      />
+    )
+  }
+
+  if (w.mode === "empty") {
+    return (
+      <Empty
+        title="No row selected"
+        body="Select a row in the host Grist section to edit it here."
+      />
+    )
+  }
+
+  return <RowEditor key={String(w.record!.id)} w={w} />
+}
+
+function RowEditor({ w }: { w: FormEditGrist }) {
+  const [draft, setDraft] = useState<Draft>(() => readDraft(w.mappedRecord))
+  const [saveError, setSaveError] = useState<string | null>(null)
+
+  async function save(e: FormEvent) {
+    e.preventDefault()
+    if (!w.record) return
+    setSaveError(null)
+    try {
+      await w.table.update({
+        id: w.record.id as number,
+        fields: w.mapBack({
+          Title: draft.title,
+          Description: draft.description || null,
+          Done: draft.done,
+          Priority: draft.priority || null,
+        }),
+      })
+    } catch (err) {
+      setSaveError(err instanceof Error ? err.message : String(err))
+    }
+  }
+
+  return (
+    <form
+      onSubmit={save}
+      className="flex h-svh min-h-0 flex-col gap-4 overflow-auto p-6"
+    >
+      <header>
+        <h1 className="text-lg font-medium">Row #{String(w.record!.id)}</h1>
+        <p className="text-sm text-muted-foreground">
+          Edit fields, then save back to Grist via{" "}
+          <code className="rounded bg-muted px-1 text-xs">table.update</code>.
+        </p>
+      </header>
+
+      <Field label="Title">
+        <Input
+          required
+          value={draft.title}
+          onChange={(e) =>
+            setDraft((d) => ({ ...d, title: e.target.value }))
+          }
+        />
+      </Field>
+
+      <Field label="Description">
+        <Input
+          value={draft.description}
+          onChange={(e) =>
+            setDraft((d) => ({ ...d, description: e.target.value }))
+          }
+        />
+      </Field>
+
+      <Field label="Priority">
+        <Input
+          placeholder="High / Medium / Low"
+          value={draft.priority}
+          onChange={(e) =>
+            setDraft((d) => ({ ...d, priority: e.target.value }))
+          }
+        />
+      </Field>
+
+      <label className="flex items-center gap-2 text-sm">
+        <input
+          type="checkbox"
+          className="size-4 rounded border-input"
+          checked={draft.done}
+          onChange={(e) =>
+            setDraft((d) => ({ ...d, done: e.target.checked }))
+          }
+        />
+        <span>Mark as done</span>
+      </label>
+
+      {saveError ? (
+        <Alert variant="destructive">
+          <AlertTitle>Save failed</AlertTitle>
+          <AlertDescription>{saveError}</AlertDescription>
+        </Alert>
+      ) : null}
+
+      <div className="mt-auto flex items-center gap-2 border-t pt-3">
+        <Button type="submit" disabled={w.actionStatus === "running"}>
+          {w.actionStatus === "running" ? "Saving…" : "Save"}
+        </Button>
+        <Button
+          type="button"
+          variant="outline"
+          onClick={() => setDraft(readDraft(w.mappedRecord))}
+          disabled={w.actionStatus === "running"}
+        >
+          Reset
+        </Button>
+        {w.actionStatus === "error" && w.actionError ? (
+          <span className="text-xs text-destructive">{w.actionError}</span>
+        ) : null}
+      </div>
+    </form>
+  )
+}
+
+function Field({ label, children }: { label: string; children: ReactNode }) {
+  return (
+    <label className="flex flex-col gap-1">
+      <span className="text-xs font-medium uppercase tracking-wide text-muted-foreground">
+        {label}
+      </span>
+      {children}
+    </label>
+  )
+}
+
+function Empty({ title, body }: { title: string; body: string }) {
+  return (
+    <div className="flex h-svh items-center justify-center p-6">
+      <div className="max-w-sm text-center">
+        <h2 className="font-medium">{title}</h2>
+        {body ? (
+          <p className="mt-2 text-sm text-muted-foreground">{body}</p>
+        ) : null}
+      </div>
+    </div>
+  )
+}

package/examples/hello-world/WidgetApp.tsx

@@ -0,0 +1,15 @@
+import { useGrist, type UseGristOptions } from "grist-widget-sdk"
+
+export const GRIST_OPTIONS: UseGristOptions = {
+  requiredAccess: "read table",
+}
+
+export function WidgetApp() {
+  const w = useGrist()
+  const rowKey =
+    w.record && typeof w.record.id === "number" ? String(w.record.id) : w.mode
+
+  if (w.mode === "empty") return <p>Select a row.</p>
+  if (w.mode === "new-row") return <p>New row flow</p>
+  return <p key={rowKey}>Selected row #{String(w.record!.id)}</p>
+}

package/examples/mark-done/WidgetApp.tsx

@@ -0,0 +1,44 @@
+import {
+  useGrist,
+  useWidgetMetadata,
+  type UseGristOptions,
+} from "grist-widget-sdk"
+
+import { Button } from "@/components/ui/button"
+
+export const GRIST_OPTIONS: UseGristOptions = {
+  requiredAccess: "full",
+  columns: [{ name: "Done", type: "Bool" }],
+}
+
+export const WIDGET_METADATA = {
+  title: "Mark done",
+  description: "Single-row write via table.update.",
+} as const
+
+export function WidgetApp() {
+  useWidgetMetadata(WIDGET_METADATA)
+  const w = useGrist()
+
+  if (!w.columnMappingStatus.ok) {
+    return <p className="p-4 text-sm">Map the Done column.</p>
+  }
+  if (w.mode !== "row" || !w.record) {
+    return <p className="p-4 text-sm">Select a row.</p>
+  }
+
+  async function onClick() {
+    await w.table.update({
+      id: w.record!.id as number,
+      fields: w.mapBack({ Done: true }),
+    })
+  }
+
+  return (
+    <div className="p-4">
+      <Button type="button" onClick={() => void onClick()}>
+        Mark done
+      </Button>
+    </div>
+  )
+}

package/examples/reads-demo/WidgetApp.tsx

@@ -0,0 +1,69 @@
+import { useEffect, useState } from "react"
+
+import {
+  useGrist,
+  useWidgetMetadata,
+  type UseGristOptions,
+} from "grist-widget-sdk"
+
+export const GRIST_OPTIONS: UseGristOptions = {
+  requiredAccess: "read table",
+}
+
+export const WIDGET_METADATA = {
+  title: "Reads demo",
+  description: "listTables, fetchTableRows, fetchRow, fetchSelectedRecord.",
+} as const
+
+export function WidgetApp() {
+  useWidgetMetadata(WIDGET_METADATA)
+  const {
+    isReady,
+    currentTableId,
+    record,
+    listTables,
+    fetchTableRows,
+    fetchRow,
+    fetchSelectedRecord,
+  } = useGrist()
+  const [summary, setSummary] = useState<string>("Loading…")
+
+  useEffect(() => {
+    if (!isReady) return
+    let cancelled = false
+    void (async () => {
+      const tableIds = await listTables()
+      const tableId = currentTableId ?? tableIds[0]
+      if (!tableId) return
+      const rows = await fetchTableRows(tableId)
+      const single =
+        rows[0]?.id != null ? await fetchRow(tableId, rows[0].id as number) : null
+      const here =
+        record?.id != null ? await fetchSelectedRecord(record.id as number) : null
+      if (!cancelled) {
+        setSummary(
+          JSON.stringify(
+            { tableIds, rowCount: rows.length, single, here },
+            null,
+            2,
+          ),
+        )
+      }
+    })()
+    return () => {
+      cancelled = true
+    }
+  }, [
+    isReady,
+    currentTableId,
+    record?.id,
+    listTables,
+    fetchTableRows,
+    fetchRow,
+    fetchSelectedRecord,
+  ])
+
+  return (
+    <pre className="max-h-svh overflow-auto p-4 text-xs">{summary}</pre>
+  )
+}

package/examples/rest-fetch/WidgetApp.tsx

@@ -0,0 +1,49 @@
+import { useState } from "react"
+
+import {
+  useGrist,
+  useWidgetMetadata,
+  type UseGristOptions,
+} from "grist-widget-sdk"
+
+import { Button } from "@/components/ui/button"
+
+export const GRIST_OPTIONS: UseGristOptions = {
+  requiredAccess: "full",
+  suppressAlerts: ["section-not-linked"],
+}
+
+export const WIDGET_METADATA = {
+  title: "REST fetch",
+  description: "fetchWithAuth against the Grist REST API.",
+} as const
+
+export function WidgetApp() {
+  useWidgetMetadata(WIDGET_METADATA)
+  const w = useGrist()
+  const [body, setBody] = useState<string | null>(null)
+  const [error, setError] = useState<string | null>(null)
+
+  async function loadTables() {
+    setError(null)
+    try {
+      const res = await w.fetchWithAuth("/tables")
+      const json = await res.json()
+      setBody(JSON.stringify(json, null, 2))
+    } catch (err) {
+      setError(err instanceof Error ? err.message : String(err))
+    }
+  }
+
+  return (
+    <div className="flex flex-col gap-2 p-4">
+      <Button type="button" onClick={() => void loadTables()}>
+        GET /tables
+      </Button>
+      {error ? <p className="text-xs text-destructive">{error}</p> : null}
+      {body ? (
+        <pre className="max-h-64 overflow-auto text-xs">{body}</pre>
+      ) : null}
+    </div>
+  )
+}