create-grist-widget 0.3.7 → 0.3.9

package/examples/spreadsheet-grid/grist-rdg-columns.ts

@@ -0,0 +1,397 @@
+import React, { memo } from "react"
+import {
+  type CellComponent,
+  type CellProps,
+  createTextColumn,
+  keyColumn,
+  textColumn,
+  type Column,
+} from "react-datasheet-grid"
+
+import {
+  encodeGristValue,
+  normalizeGristChoiceListEntries,
+  resolveGristFormulaKind,
+  type GristReplicaColumn,
+} from "grist-widget-sdk"
+
+import {
+  createGristChoiceColumn,
+  createGristChoiceListColumn,
+  createGristRefListColumn,
+} from "./grist-rdg-choice-column"
+
+/**
+ * Decoded row shape exposed to react-datasheet-grid. `useGrist().records`
+ * always carries a numeric `id` (it's the Grist row id), and the SDK already
+ * decodes cell values via `keepEncoded: false`.
+ */
+export type GristRdgRow = Record<string, unknown> & { id?: number }
+
+/**
+ * Grist column types we let the schema toolbar create / change to.
+ *
+ * Refs / RefLists are intentionally excluded: they require a target table id
+ * and a UX flow we don't want in the minimal demo.
+ */
+export const GRIST_TOOLBAR_COLUMN_TYPES = [
+  "Text",
+  "Numeric",
+  "Int",
+  "Bool",
+  "Date",
+  "DateTime",
+  "Choice",
+  "Any",
+] as const
+
+export type GristToolbarColumnType = (typeof GRIST_TOOLBAR_COLUMN_TYPES)[number]
+
+function looksLikeDateTime(type: string | undefined): boolean {
+  return (
+    type === "DateTime" ||
+    (typeof type === "string" && type.startsWith("DateTime:"))
+  )
+}
+
+function looksLikeComplex(type: string | undefined): boolean {
+  if (!type) return false
+  return type === "Attachments"
+}
+
+function looksLikeRef(type: string | undefined): boolean {
+  return typeof type === "string" && type.startsWith("Ref:")
+}
+
+function looksLikeRefList(type: string | undefined): boolean {
+  return typeof type === "string" && type.startsWith("RefList:")
+}
+
+function isGristHelperColumnId(colId: string): boolean {
+  return colId.startsWith("gristHelper_")
+}
+
+/** True for `computed` and `trigger` formulas — they cannot be written to. */
+export function isFormulaColumn(col: GristReplicaColumn | undefined): boolean {
+  if (!col) return false
+  const kind = resolveGristFormulaKind(col)
+  return kind === "computed" || kind === "trigger"
+}
+
+/** True for non-scalar column types we display as read-only JSON. */
+export function isComplexColumn(col: GristReplicaColumn | undefined): boolean {
+  return looksLikeComplex(col?.type)
+}
+
+function isDetailedRefValue(
+  v: unknown
+): v is { rowId: number; display?: string | null } {
+  if (!v || typeof v !== "object") return false
+  const rowId = (v as { rowId?: unknown }).rowId
+  return typeof rowId === "number"
+}
+
+function chipStyle(ok: boolean): Record<string, string | number> {
+  if (ok) {
+    return {
+      border: "1px solid #86efac",
+      backgroundColor: "#f0fdf4",
+      color: "#166534",
+    }
+  }
+  return {
+    border: "1px solid #dc2626",
+    backgroundColor: "#fef2f2",
+    color: "#991b1b",
+  }
+}
+
+const RefChipCell = memo(function RefChipCell({
+  rowData,
+}: CellProps<unknown, unknown>) {
+  let label = ""
+  let ok = false
+  if (isDetailedRefValue(rowData)) {
+    const display =
+      typeof rowData.display === "string" ? rowData.display.trim() : ""
+    label = display !== "" ? display : String(rowData.rowId)
+    ok = display !== ""
+  } else if (typeof rowData === "number") {
+    label = String(rowData)
+    ok = false
+  } else if (rowData != null) {
+    label = String(rowData)
+    ok = false
+  }
+
+  const children = label
+    ? React.createElement(
+        "span",
+        {
+          style: {
+            borderRadius: 10,
+            padding: "1px 6px",
+            lineHeight: 1.4,
+            ...chipStyle(ok),
+          },
+        },
+        label
+      )
+    : null
+  return React.createElement(
+    "div",
+    {
+      className: "dsg-input",
+      style: { pointerEvents: "none", minHeight: 22, padding: "2px 6px" },
+    },
+    children
+  )
+})
+
+RefChipCell.displayName = "RefChipCell"
+
+function refChipColumn(): Partial<Column<unknown, unknown, unknown>> {
+  return {
+    ...(textColumn as unknown as Partial<Column<unknown, unknown, unknown>>),
+    component: RefChipCell as unknown as CellComponent<unknown, unknown>,
+    disabled: true,
+  }
+}
+
+/**
+ * Build the set of writable column ids (we exclude formula and complex
+ * columns from row writes — Grist would reject formula writes, and complex
+ * columns need their own UX).
+ */
+export function writableColIds(
+  colIds: readonly string[],
+  schemaColumns: Record<string, GristReplicaColumn>
+): Set<string> {
+  const out = new Set<string>()
+  for (const colId of colIds) {
+    if (colId === "id") continue
+    if (colId === "manualSort") continue
+    if (isGristHelperColumnId(colId)) continue
+    const col = schemaColumns[colId]
+    if (isFormulaColumn(col)) continue
+    if (isComplexColumn(col)) continue
+    out.add(colId)
+  }
+  return out
+}
+
+function manualSortKey(row: GristRdgRow): number | null {
+  const v = row.manualSort
+  if (typeof v === "number" && !Number.isNaN(v)) return v
+  if (typeof v === "string" && v.trim() !== "") {
+    const n = Number(v)
+    if (!Number.isNaN(n)) return n
+  }
+  return null
+}
+
+/**
+ * Row order for Grist tables: `manualSort` ascending when present on any row,
+ * otherwise numeric `id` (document order fallback).
+ */
+export function sortRowsByGristOrder(
+  rows: readonly GristRdgRow[]
+): GristRdgRow[] {
+  const hasManual = rows.some((r) => manualSortKey(r) !== null)
+  if (!hasManual) {
+    return [...rows].sort((a, b) => {
+      const ida = typeof a.id === "number" ? a.id : 0
+      const idb = typeof b.id === "number" ? b.id : 0
+      return ida - idb
+    })
+  }
+  return [...rows].sort((a, b) => {
+    const ma = manualSortKey(a)
+    const mb = manualSortKey(b)
+    if (ma !== null && mb !== null && ma !== mb) return ma - mb
+    if (ma !== null && mb === null) return -1
+    if (ma === null && mb !== null) return 1
+    const ida = typeof a.id === "number" ? a.id : 0
+    const idb = typeof b.id === "number" ? b.id : 0
+    return ida - idb
+  })
+}
+
+/**
+ * Encode the writable subset of a row's fields back into Grist wire form.
+ * Used for `table.create` / `table.update` payloads.
+ */
+export function encodeRowFields(
+  row: Record<string, unknown>,
+  schemaColumns: Record<string, GristReplicaColumn>,
+  writable: ReadonlySet<string>
+): Record<string, unknown> {
+  const out: Record<string, unknown> = {}
+  for (const colId of writable) {
+    const value = row[colId]
+    if (value === undefined) continue
+    const type = schemaColumns[colId]?.type
+    const encodedInput =
+      typeof type === "string" &&
+      type.startsWith("RefList:") &&
+      value &&
+      typeof value === "object" &&
+      Array.isArray((value as { rowIds?: unknown }).rowIds)
+        ? (value as { rowIds: number[] }).rowIds
+        : value
+    out[colId] = encodeGristValue(encodedInput, schemaColumns[colId])
+  }
+  return out
+}
+
+/** Read-only "complex" cell — JSON-stringified copy, no edit / paste. */
+function complexDisplayColumn(): Partial<Column<unknown, unknown, string>> {
+  return {
+    ...(textColumn as Partial<Column<unknown, unknown, string>>),
+    copyValue: ({ rowData }) =>
+      rowData == null
+        ? null
+        : typeof rowData === "string"
+          ? rowData
+          : JSON.stringify(rowData),
+    pasteValue: ({ rowData }) => rowData,
+    deleteValue: ({ rowData }) => rowData,
+  }
+}
+
+/**
+ * DateTime variant of `textColumn` — values stay as `Date` objects (the SDK
+ * decodes Grist DateTime cells to JS `Date`), and we display / parse ISO 8601.
+ *
+ * Native HTML `datetime-local` would be nicer but it's a bigger refactor; ISO
+ * text is the lowest-friction path for the minimal widget.
+ */
+function dateTimeTextColumn() {
+  return createTextColumn<Date | null>({
+    placeholder: "YYYY-MM-DDTHH:mm:ssZ",
+    parseUserInput: (raw) => {
+      const s = raw.trim()
+      if (!s) return null
+      const d = new Date(s)
+      return Number.isNaN(d.getTime()) ? null : d
+    },
+    parsePastedValue: (raw) => {
+      const s = raw.trim()
+      if (!s) return null
+      const d = new Date(s)
+      return Number.isNaN(d.getTime()) ? null : d
+    },
+    formatBlurredInput: (value) =>
+      value instanceof Date ? value.toISOString() : "",
+    formatInputOnFocus: (value) =>
+      value instanceof Date ? value.toISOString() : "",
+    formatForCopy: (value) =>
+      value instanceof Date ? value.toISOString() : "",
+  })
+}
+
+/**
+ * Date variant that is resilient to malformed row values.
+ *
+ * RDG's built-in `dateColumn` assumes the cell value is always a `Date` and can
+ * throw when a bad value leaks through (e.g. from malformed source data).
+ * This column accepts Date/string/null and normalizes safely.
+ */
+function safeDateTextColumn() {
+  return createTextColumn<Date | string | null>({
+    placeholder: "YYYY-MM-DD",
+    parseUserInput: (raw) => {
+      const s = raw.trim()
+      if (!s) return null
+      const d = new Date(s)
+      return Number.isNaN(d.getTime()) ? null : d
+    },
+    parsePastedValue: (raw) => {
+      const s = raw.trim()
+      if (!s) return null
+      const d = new Date(s)
+      return Number.isNaN(d.getTime()) ? null : d
+    },
+    formatBlurredInput: (value) => {
+      if (value == null) return ""
+      if (value instanceof Date) return value.toISOString().slice(0, 10)
+      if (typeof value === "string") return value
+      return ""
+    },
+    formatInputOnFocus: (value) => {
+      if (value == null) return ""
+      if (value instanceof Date) return value.toISOString().slice(0, 10)
+      if (typeof value === "string") return value
+      return ""
+    },
+    formatForCopy: (value) => {
+      if (value == null) return ""
+      if (value instanceof Date) return value.toISOString().slice(0, 10)
+      if (typeof value === "string") return value
+      return ""
+    },
+  })
+}
+
+/**
+ * Pick the right RDG column variant for a Grist column.
+ *
+ * The returned column is wrapped in `keyColumn(colId, ...)` so RDG reads /
+ * writes the right key on the row object, and is marked `disabled` for
+ * formula / complex / id columns.
+ */
+export function gristColumnToRdgColumn(
+  colId: string,
+  col: GristReplicaColumn | undefined
+): Partial<Column<GristRdgRow, unknown, unknown>> {
+  const label = col?.label || colId
+  const type = col?.type
+  const readOnly =
+    colId === "id" ||
+    isFormulaColumn(col) ||
+    isComplexColumn(col) ||
+    looksLikeRef(type)
+
+  let base: Partial<Column<unknown, unknown, unknown>>
+  if (isComplexColumn(col)) {
+    base = complexDisplayColumn() as Partial<Column<unknown, unknown, unknown>>
+  } else if (looksLikeRefList(type)) {
+    base = createGristRefListColumn() as Partial<
+      Column<unknown, unknown, unknown>
+    >
+  } else if (looksLikeRef(type)) {
+    base = refChipColumn() as Partial<Column<unknown, unknown, unknown>>
+  } else if (type === "Bool") {
+    base = textColumn as Partial<Column<unknown, unknown, unknown>>
+  } else if (type === "Int") {
+    base = textColumn as Partial<Column<unknown, unknown, unknown>>
+  } else if (type === "Numeric") {
+    base = textColumn as Partial<Column<unknown, unknown, unknown>>
+  } else if (type === "Date") {
+    base = safeDateTextColumn() as Partial<Column<unknown, unknown, unknown>>
+  } else if (looksLikeDateTime(type)) {
+    base = dateTimeTextColumn() as Partial<Column<unknown, unknown, unknown>>
+  } else if (type === "Choice") {
+    const choiceEntries = normalizeGristChoiceListEntries(col?.widgetOptions)
+    base =
+      choiceEntries.length > 0
+        ? (createGristChoiceColumn(choiceEntries) as Partial<
+            Column<unknown, unknown, unknown>
+          >)
+        : (textColumn as Partial<Column<unknown, unknown, unknown>>)
+  } else if (type === "ChoiceList") {
+    const choiceEntries = normalizeGristChoiceListEntries(col?.widgetOptions)
+    base = createGristChoiceListColumn(choiceEntries) as Partial<
+      Column<unknown, unknown, unknown>
+    >
+  } else {
+    base = textColumn as Partial<Column<unknown, unknown, unknown>>
+  }
+
+  return {
+    ...keyColumn(colId, base as Partial<Column<unknown, unknown, unknown>>),
+    id: colId,
+    title: label,
+    disabled: readOnly,
+  } as Partial<Column<GristRdgRow, unknown, unknown>>
+}

package/examples/task-board/WidgetApp.tsx

@@ -0,0 +1,229 @@
+import { useMemo, useState, type DragEvent } from "react"
+
+import {
+  useGrist,
+  useWidgetMetadata,
+  type UseGristOptions,
+} from "grist-widget-sdk"
+
+import { Badge } from "@/components/ui/badge"
+import { Card, CardContent } from "@/components/ui/card"
+
+export const GRIST_OPTIONS: UseGristOptions = {
+  requiredAccess: "full",
+  allowSelectBy: true,
+  columns: [
+    { name: "Title", type: "Text" },
+    { name: "Status", type: "Text" },
+    { name: "Priority", type: "Text", optional: true },
+  ],
+}
+
+export const WIDGET_METADATA = {
+  title: "Task board",
+  description:
+    "Mini Kanban board grouped by Status. Drag a card to update Status; click to focus the row in linked sections.",
+} as const
+
+const DEFAULT_STATUSES = ["To do", "Doing", "Done"] as const
+
+type Task = {
+  id: number
+  title: string
+  status: string
+  priority: string | null
+}
+
+function pickStatuses(rows: readonly Task[]): readonly string[] {
+  const seen = new Set<string>(DEFAULT_STATUSES)
+  for (const r of rows) {
+    if (r.status && !seen.has(r.status)) seen.add(r.status)
+  }
+  return [...seen]
+}
+
+function asString(value: unknown): string {
+  if (typeof value === "string") return value
+  if (value == null) return ""
+  return String(value)
+}
+
+export function WidgetApp() {
+  useWidgetMetadata(WIDGET_METADATA)
+  const w = useGrist()
+
+  // Resolve the physical column ids once per render. We can't call mapBack on
+  // every row record because mapBack is for a single record write; here we
+  // want to project the rows from raw `records` into a typed shape.
+  const titleColId = w.resolveMappedColumnId("Title")
+  const statusColId = w.resolveMappedColumnId("Status")
+  const priorityColId = w.resolveMappedColumnId("Priority")
+
+  const tasks = useMemo<Task[]>(() => {
+    if (
+      !w.columnMappingStatus.ok ||
+      !titleColId ||
+      !statusColId ||
+      !w.records
+    ) {
+      return []
+    }
+    return w.records.map((row) => {
+      const status = asString(row[statusColId])
+      const priority = priorityColId ? asString(row[priorityColId]) : ""
+      return {
+        id: row.id as number,
+        title: asString(row[titleColId]) || "(untitled)",
+        status: status || "To do",
+        priority: priority || null,
+      }
+    })
+  }, [
+    w.records,
+    w.columnMappingStatus,
+    titleColId,
+    statusColId,
+    priorityColId,
+  ])
+
+  const statuses = useMemo(() => pickStatuses(tasks), [tasks])
+  const [dragId, setDragId] = useState<number | null>(null)
+
+  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 columns: Title (Text), Status (Text), Priority (Text, optional)."
+      />
+    )
+  }
+
+  if (tasks.length === 0) {
+    return (
+      <Empty
+        title="No rows to show"
+        body="Add rows to the selected table — they will appear grouped by Status."
+      />
+    )
+  }
+
+  async function moveToStatus(task: Task, nextStatus: string) {
+    if (task.status === nextStatus) return
+    try {
+      await w.table.update({
+        id: task.id,
+        fields: w.mapBack({ Status: nextStatus }),
+      })
+    } catch {
+      // The card will snap back via the next `records` tick when the
+      // optimistic update is rejected by Grist.
+    }
+  }
+
+  return (
+    <div className="flex h-svh min-h-0 flex-col gap-3 p-4">
+      <header className="flex items-baseline justify-between">
+        <h1 className="text-lg font-medium">Task board</h1>
+        <span className="text-xs text-muted-foreground">
+          {tasks.length} task{tasks.length === 1 ? "" : "s"}
+        </span>
+      </header>
+
+      <div className="grid min-h-0 flex-1 grid-cols-1 gap-3 overflow-auto sm:grid-cols-2 lg:grid-cols-3">
+        {statuses.map((status) => {
+          const inStatus = tasks.filter((c) => c.status === status)
+          return (
+            <section
+              key={status}
+              className="flex min-h-32 flex-col gap-2 rounded-lg border bg-muted/40 p-3"
+              onDragOver={(e) => {
+                e.preventDefault()
+                e.dataTransfer.dropEffect = "move"
+              }}
+              onDrop={(e) => {
+                e.preventDefault()
+                if (dragId == null) return
+                const dragged = tasks.find((c) => c.id === dragId)
+                setDragId(null)
+                if (dragged) void moveToStatus(dragged, status)
+              }}
+            >
+              <header className="flex items-center justify-between">
+                <h2 className="text-sm font-semibold">{status}</h2>
+                <Badge variant="secondary">{inStatus.length}</Badge>
+              </header>
+              <div className="flex flex-col gap-2">
+                {inStatus.map((task) => (
+                  <TaskCard
+                    key={task.id}
+                    task={task}
+                    isSelected={w.record?.id === task.id}
+                    onClick={() => void w.setCursorPosition({ rowId: task.id })}
+                    onDragStart={() => setDragId(task.id)}
+                    onDragEnd={() => setDragId(null)}
+                  />
+                ))}
+                {inStatus.length === 0 ? (
+                  <p className="text-xs text-muted-foreground">No tasks.</p>
+                ) : null}
+              </div>
+            </section>
+          )
+        })}
+      </div>
+    </div>
+  )
+}
+
+function TaskCard({
+  task,
+  isSelected,
+  onClick,
+  onDragStart,
+  onDragEnd,
+}: {
+  task: Task
+  isSelected: boolean
+  onClick: () => void
+  onDragStart: (e: DragEvent<HTMLDivElement>) => void
+  onDragEnd: (e: DragEvent<HTMLDivElement>) => void
+}) {
+  return (
+    <Card
+      draggable
+      onClick={onClick}
+      onDragStart={onDragStart}
+      onDragEnd={onDragEnd}
+      className={
+        "cursor-grab transition-shadow hover:shadow-md " +
+        (isSelected ? "ring-2 ring-primary" : "")
+      }
+    >
+      <CardContent className="flex flex-col gap-1 p-3">
+        <span className="text-sm font-medium">{task.title}</span>
+        {task.priority ? (
+          <Badge variant="outline" className="self-start">
+            {task.priority}
+          </Badge>
+        ) : null}
+      </CardContent>
+    </Card>
+  )
+}
+
+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/theme-demo/WidgetApp.tsx

@@ -0,0 +1,26 @@
+import {
+  useGrist,
+  useWidgetMetadata,
+  type UseGristOptions,
+} from "grist-widget-sdk"
+
+export const GRIST_OPTIONS: UseGristOptions = {
+  requiredAccess: "read table",
+  suppressAlerts: ["section-not-linked"],
+}
+
+export const WIDGET_METADATA = {
+  title: "Theme",
+  description: "Read w.theme from the host document.",
+} as const
+
+export function WidgetApp() {
+  useWidgetMetadata(WIDGET_METADATA)
+  const w = useGrist()
+
+  return (
+    <div className="p-4" data-theme={w.theme ?? "light"}>
+      <p className="text-sm">Host theme: {w.theme ?? "light"}</p>
+    </div>
+  )
+}

package/examples/widget-options/WidgetApp.tsx

@@ -0,0 +1,34 @@
+import {
+  useGrist,
+  useWidgetMetadata,
+  type UseGristOptions,
+} from "grist-widget-sdk"
+
+import { Button } from "@/components/ui/button"
+
+export const GRIST_OPTIONS: UseGristOptions = {
+  requiredAccess: "read table",
+  suppressAlerts: ["section-not-linked"],
+}
+
+export const WIDGET_METADATA = {
+  title: "Widget options",
+  description: "Persist UI state with setWidgetOption / widgetOptions.",
+} as const
+
+export function WidgetApp() {
+  useWidgetMetadata(WIDGET_METADATA)
+  const w = useGrist()
+  const compact = w.widgetOptions?.compact === true
+
+  return (
+    <div className="p-4">
+      <Button
+        type="button"
+        onClick={() => void w.setWidgetOption("compact", !compact)}
+      >
+        {compact ? "Expand" : "Compact"}
+      </Button>
+    </div>
+  )
+}