create-grist-widget 0.3.4 → 0.3.6

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-grist-widget",
-  "version": "0.3.4",
+  "version": "0.3.6",
   "description": "Scaffold a new Grist custom widget from the grist-widget-sdk Vite template",
   "license": "MIT",
   "type": "module",

package/template/AGENTS.md

@@ -0,0 +1,92 @@
+# Agent guide — start here
+
+> Audience: an agent working inside a widget repo scaffolded from
+> `create-grist-widget` (this file travels with the scaffold), or working on
+> this template's own source under
+> `templates/grist-widget-template-vite/` inside the `grist-widget-sdk`
+> monorepo. This repo is a **distribution artifact** — `main` is force-pushed
+> from a fresh scaffold on every release, not developed on directly upstream.
+> If you're in the monorepo working on the SDK itself, read the root
+> `AGENTS.md` instead.
+
+## The widget contract
+
+`src/App.tsx` is the whole widget — one file, three exports:
+
+```tsx
+export const GRIST_OPTIONS: UseGristOptions = { requiredAccess: "read table" }
+export const WIDGET_METADATA = { title: "...", description: "..." } as const
+export function App() {
+  const w = useGrist()
+  // ...
+}
+```
+
+`src/main.tsx` wires it into Grist: `GristWidgetProvider` (reads `GRIST_OPTIONS`) →
+`GristBoundary` → `GristSdkAlerts` → `<App />`. Access level, column mapping, and
+rendering all live in `src/App.tsx` — that's the one file to edit.
+
+## Operating contract
+
+1. **Widgets use the SDK.** No direct `window.grist.*` calls — use `useGrist()` and the
+   other `grist-widget-sdk` hooks.
+2. **`pnpm dev` shows the showcase hub today, not a seeded preview.** Opened outside Grist
+   it renders `TemplateLanding` (onboarding + links to released versions); the widget
+   itself only renders once actually embedded in a Grist document. An offline, seeded
+   `pnpm dev` loop is planned but not shipped in this template yet — don't describe one as
+   if it exists.
+3. **Widget changes get a test.** `src/App.test.tsx` uses `renderWithGrist` + `presets` from
+   `grist-widget-sdk/emulator/testing` — no browser or real Grist doc needed. Run `pnpm test`.
+4. **Always develop on `dev`, release by merging to `main`.** Commit and push to `dev` for
+   every change — it auto-deploys a live preview at `.../dev/` that self-reloads inside an
+   open Grist document a few seconds later. Bump `package.json`'s `version` *before*
+   opening the `dev` → `main` PR: merging without a version bump publishes nothing (the
+   release build silently no-ops whenever that version's directory already exists — the PR
+   merges cleanly and CI reports success either way).
+
+## Commands
+
+| Intent | Command |
+| --- | --- |
+| Install | `pnpm install` |
+| Dev server (showcase hub outside Grist) | `pnpm dev` |
+| Build | `pnpm build` |
+| Test | `pnpm test` |
+| Lint | `pnpm lint` |
+| Format | `pnpm format` |
+| Type-check | `pnpm typecheck` |
+| Preview a production build | `pnpm preview` |
+
+## Path map
+
+| Concept | Path |
+| --- | --- |
+| The widget | `src/App.tsx` |
+| Widget test (the pattern to copy for new tests) | `src/App.test.tsx` |
+| Grist wiring / embed vs. showcase detection | `src/main.tsx` |
+| ui primitives | `src/components/ui/` |
+| Deploy workflow | `.github/workflows/deploy.yml` |
+| Deploy script (version guard, channel logic) | `scripts/deploy.mjs` |
+| Full walkthrough (dev loop, deploying, embedding) | `README.md` |
+| Changelog | `CHANGELOG.md` |
+
+## One-time repo settings
+
+Only needed once, after the first push triggers the deploy workflow's first run (it
+creates a `gh-pages` branch — these settings can't be applied before that exists):
+
+1. Settings → Pages → Source → **Deploy from a branch** → branch `gh-pages`, folder
+   `/ (root)`. Not `main` — pointing Pages at `main` serves this repo's raw, unbuilt source
+   instead of the built site (symptom: a blank page with a `/src/main.tsx` 404).
+2. If that first workflow run fails with a permissions error pushing to `gh-pages`:
+   Settings → Actions → General → Workflow permissions → **Read and write permissions**.
+   Most repos don't need this; it depends on account/org defaults.
+
+Full detail, including the two live URLs (`/latest/` and `/v<version>/`): `README.md`.
+
+## Anti-patterns
+
+- Calling `window.grist.*` inside widget code instead of the SDK's hooks
+- Describing a seeded offline `pnpm dev` preview — that doesn't exist in this template yet
+  (only a seeded offline `pnpm test`, via `renderWithGrist`, does)
+- Merging `dev` into `main` without bumping `package.json`'s `version` first

package/template/CLAUDE.md

@@ -0,0 +1 @@
+@AGENTS.md

package/template/README.md

@@ -8,12 +8,12 @@ Opened outside a Grist iframe, `main.tsx` picks between two components purely by
 
 When actually embedded, `GristStatusChip` (`src/components/grist-status-chip.tsx`) shows a small pill with live handshake status — connecting, retrying with a countdown, connected, or unavailable — using `useAmbientGristHandshake()` from `grist-widget-sdk/advanced`. It must be mounted *inside* `GristWidgetProvider` (see `src/main.tsx`): it only observes that provider's own handshake manager and never mounts a second one, so it's purely observational and can never duplicate or race the real handshake (see the [handshake API reference](https://gristwidgets.com/docs/sdk/api/handshake)).
 
-`src/App.tsx` uses `useGrist<TaskRow, TaskMapped>()` for the selected row (`w.record`, `w.mode`) and remounts the UI with `key={rowKey}` when the row changes — same pattern as `widgets/create-email-draft`. See `src/grist-types.example.ts` for typing patterns.
+`src/App.tsx` uses `useGrist<TaskRow, TaskMapped>()` for the selected row (`w.record`, `w.mode`) and remounts the UI with `key={rowKey}` when the row changes — same pattern as `widgets/create-email-draft`. It ships with two mapped columns (`title`, `done`) and an editable form that saves back via `w.table.update(...)`/`w.mapBack(...)` — the smallest real starting point, not a placeholder. See `src/grist-types.example.ts` for typing patterns.
 
 - **ESLint** blocks direct `grist` global usage in `src/` — use the SDK only.
-- Uncomment `GRIST_OPTIONS.columns` in `App.tsx` to enable column mapping; `main.tsx` sets `GristBoundary gate="canRender"` when columns are declared. Mapping alerts use `GristSdkAlerts`.
+- Edit `GRIST_OPTIONS.columns` in `App.tsx` to change the required columns (or remove the array entirely to read raw, unmapped records instead); `main.tsx` sets `GristBoundary gate="canRender"` whenever columns are declared. Mapping alerts use `GristSdkAlerts`.
 
-To add widget tests later, see [Testing](https://gristwidgets.com/docs/sdk/guide/testing) (`renderWithGrist` from `grist-widget-sdk/emulator/testing`).
+Run `pnpm test` — see `src/App.test.tsx` for the pattern (`renderWithGrist` + `presets` from `grist-widget-sdk/emulator/testing`, no browser or real Grist doc needed). Full guide: [Testing](https://gristwidgets.com/docs/sdk/guide/testing).
 
 **Monorepo dev:** this template resolves `grist-widget-sdk` from `packages/core/dist` (like the other widgets), not from SDK source. After changing the SDK, run `pnpm prebuild` or `pnpm --filter grist-widget-sdk build` before `pnpm dev`.
 

package/template/package.json

@@ -9,7 +9,8 @@
     "lint": "eslint .",
     "format": "prettier --write \"**/*.{ts,tsx}\"",
     "typecheck": "tsc -b",
-    "preview": "vite preview"
+    "preview": "vite preview",
+    "test": "vitest run"
   },
   "dependencies": {
     "@fontsource-variable/geist": "^5.2.8",
@@ -28,6 +29,8 @@
   },
   "devDependencies": {
     "@eslint/js": "^9.39.4",
+    "@testing-library/jest-dom": "^6",
+    "@testing-library/react": "^16.3.2",
     "@types/node": "^24.12.0",
     "@types/react": "^19.2.14",
     "@types/react-dom": "^19.2.3",
@@ -36,12 +39,14 @@
     "eslint-plugin-react-hooks": "^7.0.1",
     "eslint-plugin-react-refresh": "^0.5.2",
     "globals": "^16.5.0",
+    "jsdom": "^29.0.2",
     "prettier": "^3.8.1",
     "prettier-plugin-tailwindcss": "^0.7.2",
     "shadcn": "^4.16.1",
     "typescript": "~5.9.3",
     "typescript-eslint": "^8.57.1",
-    "vite": "^7.3.1"
+    "vite": "^7.3.1",
+    "vitest": "^4.1.4"
   },
   "packageManager": "pnpm@11.1.3"
 }

package/template/src/App.test.tsx

@@ -0,0 +1,81 @@
+/**
+ * Mirrors `main.tsx`'s real wiring (`GristWidgetProvider` -> `GristBoundary`
+ * -> the widget) without importing `main.tsx` itself, so this test exercises
+ * the same gate logic the embedded widget actually runs under. See
+ * `packages/core/tests/sdk/template-app.test.tsx` in the SDK repo for the
+ * same pattern applied to a bare shell.
+ */
+import "@testing-library/jest-dom/vitest"
+import { afterEach, describe, expect, it } from "vitest"
+import { GristBoundary, GristWidgetProvider } from "grist-widget-sdk"
+import {
+  act,
+  actionsOf,
+  cleanup,
+  fireEvent,
+  presets,
+  renderWithGrist,
+  screen,
+  waitFor,
+} from "grist-widget-sdk/emulator/testing"
+
+import App, { GRIST_OPTIONS } from "./App"
+
+// Not using vitest's `globals: true` (see vite.config.ts), so
+// @testing-library/react's automatic afterEach cleanup never registers
+// itself — do it explicitly, or the second test in this file finds two
+// "Title" inputs left over from the first render.
+afterEach(() => cleanup())
+
+function Wrapped() {
+  return (
+    <GristWidgetProvider options={GRIST_OPTIONS}>
+      <GristBoundary gate={GRIST_OPTIONS.columns?.length ? "canRender" : "ready"}>
+        <App />
+      </GristBoundary>
+    </GristWidgetProvider>
+  )
+}
+
+describe("App", () => {
+  it("shows the selected row's mapped title and done state", async () => {
+    const { emulator } = renderWithGrist(<Wrapped />, {
+      emulator: { document: presets.todoList() },
+    })
+    // `columns` in GRIST_OPTIONS names the widget's own logical fields — a
+    // real Grist host maps them to real column ids via the config panel;
+    // the emulator needs the same mapping told to it explicitly (name
+    // matching alone doesn't auto-map, here or in real Grist).
+    emulator.setColumnMappings({ title: "title", done: "done" })
+
+    await waitFor(() => {
+      expect(screen.getByLabelText("Title")).toHaveValue("Buy milk")
+      expect(screen.getByLabelText("Mark as done")).not.toBeChecked()
+    })
+  })
+
+  it("saves an edited title back to Grist", async () => {
+    const { emulator } = renderWithGrist(<Wrapped />, {
+      emulator: { document: presets.todoList() },
+    })
+    emulator.setColumnMappings({ title: "title", done: "done" })
+
+    await waitFor(() => expect(screen.getByLabelText("Title")).toHaveValue("Buy milk"))
+
+    fireEvent.change(screen.getByLabelText("Title"), {
+      target: { value: "Buy oat milk" },
+    })
+    await act(async () => {
+      fireEvent.click(screen.getByText("Save"))
+    })
+
+    await waitFor(() => {
+      expect(actionsOf(emulator)).toContainEqual([
+        "UpdateRecord",
+        "Tasks",
+        1,
+        { title: "Buy oat milk", done: false },
+      ])
+    })
+  })
+})

package/template/src/App.tsx

@@ -1,4 +1,7 @@
+import { useState, type FormEvent } from "react"
+
 import { Button } from "@/components/ui/button"
+import { Input } from "@/components/ui/input"
 import {
   useGrist,
   useWidgetMetadata,
@@ -9,18 +12,21 @@ import {
 import type { TaskMapped, TaskRow } from "./grist-types.example"
 
 export const GRIST_OPTIONS: UseGristOptions = {
-  requiredAccess: "read table",
-  // Uncomment to require column mapping in the widget config panel:
-  // columns: [{ name: "title", type: "Text" }, { name: "done", type: "Bool" }],
+  requiredAccess: "full",
+  columns: [
+    { name: "title", type: "Text" },
+    { name: "done", type: "Bool" },
+  ],
 }
 
 export const WIDGET_METADATA = {
   title: "Grist Widget Template",
-  description:
-    "Starter template for building Grist widgets with React and Vite.",
+  description: "Edit the selected row's title and mark it done.",
 } as const
 
-function GristSelectionDebug({ w }: { w: UseGristResult }) {
+type TemplateGrist = UseGristResult<TaskRow, TaskMapped>
+
+function GristSelectionDebug({ w }: { w: TemplateGrist }) {
   return (
     <details className="rounded-md border border-dashed border-muted-foreground/40 bg-muted/30 p-3 text-xs">
       <summary className="cursor-pointer font-medium text-muted-foreground">
@@ -45,7 +51,88 @@ function GristSelectionDebug({ w }: { w: UseGristResult }) {
   )
 }
 
-function TemplateBody({ w }: { w: UseGristResult }) {
+type Draft = { title: string; done: boolean }
+
+function readDraft(mapped: TaskMapped | null): Draft {
+  return { title: mapped?.title ?? "", done: mapped?.done ?? false }
+}
+
+function RowEditor({ w }: { w: TemplateGrist }) {
+  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,
+        fields: w.mapBack({ title: draft.title, done: draft.done }),
+      })
+    } catch (err) {
+      setSaveError(err instanceof Error ? err.message : String(err))
+    }
+  }
+
+  return (
+    <form onSubmit={save} className="flex flex-col gap-4 p-6 text-sm">
+      <header>
+        <h1 className="font-medium">Row #{String(w.record!.id)}</h1>
+        <p className="text-muted-foreground">
+          Edit the fields, then save back to Grist via{" "}
+          <code className="rounded bg-muted px-1 text-xs">table.update</code>.
+        </p>
+      </header>
+
+      <label className="flex flex-col gap-1">
+        <span className="text-xs font-medium tracking-wide text-muted-foreground uppercase">
+          Title
+        </span>
+        <Input
+          required
+          value={draft.title}
+          onChange={(e) => setDraft((d) => ({ ...d, title: e.target.value }))}
+        />
+      </label>
+
+      <label className="flex items-center gap-2">
+        <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 ? (
+        <p className="text-xs text-destructive">{saveError}</p>
+      ) : null}
+
+      <div className="flex items-center gap-2">
+        <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>
+
+      <GristSelectionDebug w={w} />
+    </form>
+  )
+}
+
+function TemplateBody({ w }: { w: TemplateGrist }) {
   if (w.mode === "empty") {
     return (
       <div className="flex flex-col gap-4 p-6 text-sm">
@@ -64,22 +151,19 @@ function TemplateBody({ w }: { w: UseGristResult }) {
     )
   }
 
-  return (
-    <div className="flex min-h-svh p-6">
-      <div className="flex max-w-md min-w-0 flex-col gap-4 text-sm leading-loose">
-        <div>
-          <h1 className="font-medium">Widget connected to Grist</h1>
-          <p>Record id: {String(w.record?.id ?? "")}</p>
-          <p>You can now render values from the selected record.</p>
-          <Button className="mt-2">Button</Button>
-        </div>
+  if (!w.columnMappingStatus.ok) {
+    return (
+      <div className="flex flex-col gap-4 p-6 text-sm">
+        <p>
+          Open the widget configuration panel and map the two required
+          columns: Title, Done.
+        </p>
         <GristSelectionDebug w={w} />
-        <div className="font-mono text-xs text-muted-foreground">
-          (Press <kbd>d</kbd> to toggle dark mode)
-        </div>
       </div>
-    </div>
-  )
+    )
+  }
+
+  return <RowEditor key={String(w.record!.id)} w={w} />
 }
 
 /**

package/template/vite.config.ts

@@ -2,7 +2,11 @@ import { readFileSync } from "fs"
 import path from "path"
 import tailwindcss from "@tailwindcss/vite"
 import react from "@vitejs/plugin-react"
-import { defineConfig } from "vite"
+// `vitest/config`'s defineConfig is a superset of vite's own -- same build
+// config still works, and it adds the `test` field below. Importing it here
+// (rather than a separate vitest.config.ts) means `pnpm test` reuses this
+// file's `@` alias and plugins instead of duplicating them.
+import { defineConfig } from "vitest/config"
 
 // Read here (Node context) rather than importing package.json into src/ --
 // keeps the whole file out of the bundle, exposing only the one field the
@@ -20,4 +24,7 @@ export default defineConfig({
   define: {
     __CREATE_GRIST_WIDGET_VERSION__: JSON.stringify(pkg.createGristWidgetVersion ?? null),
   },
+  test: {
+    environment: "jsdom",
+  },
 })