create-grist-widget 0.3.7 → 0.3.9

package/examples/writes-demo/WidgetApp.tsx

@@ -0,0 +1,75 @@
+import {
+  useGrist,
+  useWidgetMetadata,
+  type UseGristOptions,
+} from "grist-widget-sdk"
+
+import { Button } from "@/components/ui/button"
+
+export const GRIST_OPTIONS: UseGristOptions = {
+  requiredAccess: "full",
+  columns: [{ name: "Title", type: "Text" }],
+}
+
+export const WIDGET_METADATA = {
+  title: "Table writes",
+  description: "create, update, upsert, destroy via w.table.",
+} as const
+
+export function WidgetApp() {
+  useWidgetMetadata(WIDGET_METADATA)
+  const w = useGrist()
+
+  if (!w.columnMappingStatus.ok) {
+    return <p className="p-4 text-sm">Map the Title column.</p>
+  }
+
+  return (
+    <div className="flex flex-wrap gap-2 p-4">
+      <Button
+        type="button"
+        onClick={() =>
+          void w.table.create({ fields: w.mapBack({ Title: "New" }) })
+        }
+      >
+        create
+      </Button>
+      <Button
+        type="button"
+        disabled={!w.record}
+        onClick={() => {
+          if (!w.record) return
+          void w.table.update({
+            id: w.record.id as number,
+            fields: w.mapBack({ Title: "Updated" }),
+          })
+        }}
+      >
+        update
+      </Button>
+      <Button
+        type="button"
+        onClick={() =>
+          void w.table.upsert({
+            require: w.mapBack({ Title: "Existing" }),
+            fields: w.mapBack({ Title: "Existing" }),
+          })
+        }
+      >
+        upsert
+      </Button>
+      <Button
+        type="button"
+        disabled={!w.records?.length}
+        onClick={() => {
+          const ids = (w.records ?? [])
+            .slice(0, 3)
+            .map((r) => r.id as number)
+          if (ids.length) void w.table.destroy(ids)
+        }}
+      >
+        destroy (first 3)
+      </Button>
+    </div>
+  )
+}

package/manifest.json

@@ -0,0 +1,304 @@
+[
+  {
+    "id": "attachment-gallery",
+    "title": "Attachment gallery",
+    "description": "Thumbnail grid of every attachment in the selected row. Showcases extractGristAttachmentIdsFromCell + useGrist().fetchAttachmentBlob.",
+    "requiredAccess": "full",
+    "columns": [
+      {
+        "name": "Attachments",
+        "type": "Attachments"
+      }
+    ],
+    "allowSelectBy": false,
+    "hasCustomOptions": false,
+    "hasExampleDocument": false,
+    "usesUi": [
+      "button"
+    ],
+    "sourcePath": "examples/attachment-gallery/WidgetApp.tsx"
+  },
+  {
+    "id": "bulk-mark-done",
+    "title": "Bulk mark done",
+    "description": "Bulk table.update with an array of row patches.",
+    "requiredAccess": "full",
+    "columns": [
+      {
+        "name": "Done",
+        "type": "Bool"
+      }
+    ],
+    "allowSelectBy": false,
+    "hasCustomOptions": false,
+    "hasExampleDocument": false,
+    "usesUi": [
+      "button"
+    ],
+    "sourcePath": "examples/bulk-mark-done/WidgetApp.tsx"
+  },
+  {
+    "id": "declared-columns",
+    "title": "Declared columns",
+    "description": "Shows GRIST_OPTIONS column declarations and mappedRecord after the user maps columns.",
+    "requiredAccess": "full",
+    "columns": [
+      {
+        "name": "Title",
+        "type": "Text"
+      },
+      {
+        "name": "Done",
+        "type": "Bool"
+      },
+      {
+        "name": "Tags",
+        "type": "ChoiceList",
+        "allowMultiple": true,
+        "optional": true
+      }
+    ],
+    "allowSelectBy": false,
+    "hasCustomOptions": false,
+    "hasExampleDocument": false,
+    "usesUi": [],
+    "sourcePath": "examples/declared-columns/WidgetApp.tsx"
+  },
+  {
+    "id": "form-edit",
+    "title": "Row editor",
+    "description": "Edit the selected row in a polished form. Showcases column mappings, write status, and error UI.",
+    "requiredAccess": "full",
+    "columns": [
+      {
+        "name": "Title",
+        "type": "Text"
+      },
+      {
+        "name": "Description",
+        "type": "Text",
+        "optional": true
+      },
+      {
+        "name": "Done",
+        "type": "Bool"
+      },
+      {
+        "name": "Priority",
+        "type": "Text",
+        "optional": true
+      }
+    ],
+    "allowSelectBy": false,
+    "hasCustomOptions": false,
+    "hasExampleDocument": false,
+    "usesUi": [
+      "alert",
+      "button",
+      "input"
+    ],
+    "sourcePath": "examples/form-edit/WidgetApp.tsx"
+  },
+  {
+    "id": "hello-world",
+    "title": "hello-world",
+    "description": null,
+    "requiredAccess": "read table",
+    "columns": [],
+    "allowSelectBy": false,
+    "hasCustomOptions": false,
+    "hasExampleDocument": false,
+    "usesUi": [],
+    "sourcePath": "examples/hello-world/WidgetApp.tsx"
+  },
+  {
+    "id": "mark-done",
+    "title": "Mark done",
+    "description": "Single-row write via table.update.",
+    "requiredAccess": "full",
+    "columns": [
+      {
+        "name": "Done",
+        "type": "Bool"
+      }
+    ],
+    "allowSelectBy": false,
+    "hasCustomOptions": false,
+    "hasExampleDocument": false,
+    "usesUi": [
+      "button"
+    ],
+    "sourcePath": "examples/mark-done/WidgetApp.tsx"
+  },
+  {
+    "id": "reads-demo",
+    "title": "Reads demo",
+    "description": "listTables, fetchTableRows, fetchRow, fetchSelectedRecord.",
+    "requiredAccess": "read table",
+    "columns": [],
+    "allowSelectBy": false,
+    "hasCustomOptions": false,
+    "hasExampleDocument": false,
+    "usesUi": [],
+    "sourcePath": "examples/reads-demo/WidgetApp.tsx"
+  },
+  {
+    "id": "rest-fetch",
+    "title": "REST fetch",
+    "description": "fetchWithAuth against the Grist REST API.",
+    "requiredAccess": "full",
+    "columns": [],
+    "allowSelectBy": false,
+    "hasCustomOptions": false,
+    "hasExampleDocument": false,
+    "usesUi": [
+      "button"
+    ],
+    "sourcePath": "examples/rest-fetch/WidgetApp.tsx"
+  },
+  {
+    "id": "safe-parse",
+    "title": "Safe parse",
+    "description": "safeParseGristTableData with per-cell issues.",
+    "requiredAccess": "read table",
+    "columns": [],
+    "allowSelectBy": false,
+    "hasCustomOptions": false,
+    "hasExampleDocument": false,
+    "usesUi": [],
+    "sourcePath": "examples/safe-parse/WidgetApp.tsx"
+  },
+  {
+    "id": "schema-migration",
+    "title": "Schema migration",
+    "description": "applyActions with gristAddVisibleColumnAction, gristRenameColumnAction, and gristRemoveColumnAction.",
+    "requiredAccess": "full",
+    "columns": [],
+    "allowSelectBy": false,
+    "hasCustomOptions": false,
+    "hasExampleDocument": false,
+    "usesUi": [
+      "button"
+    ],
+    "sourcePath": "examples/schema-migration/WidgetApp.tsx"
+  },
+  {
+    "id": "schema-preview",
+    "title": "Schema preview",
+    "description": "useGristSchema with replicaRowMode schema+samples for LLM context.",
+    "requiredAccess": "read table",
+    "columns": [],
+    "allowSelectBy": false,
+    "hasCustomOptions": false,
+    "hasExampleDocument": false,
+    "usesUi": [],
+    "sourcePath": "examples/schema-preview/WidgetApp.tsx"
+  },
+  {
+    "id": "slice-hooks",
+    "title": "Slice hooks",
+    "description": "useGristStatus, useGristSelection, useGristWrites, useGristTheme in separate child components.",
+    "requiredAccess": "full",
+    "columns": [
+      {
+        "name": "Title",
+        "type": "Text"
+      }
+    ],
+    "allowSelectBy": false,
+    "hasCustomOptions": false,
+    "hasExampleDocument": false,
+    "usesUi": [],
+    "sourcePath": "examples/slice-hooks/WidgetApp.tsx"
+  },
+  {
+    "id": "spreadsheet-grid",
+    "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.",
+    "requiredAccess": "full",
+    "columns": [],
+    "allowSelectBy": true,
+    "hasCustomOptions": false,
+    "hasExampleDocument": false,
+    "usesUi": [
+      "button",
+      "input",
+      "ShadcnDataSheetGrid"
+    ],
+    "sourcePath": "examples/spreadsheet-grid/WidgetApp.tsx"
+  },
+  {
+    "id": "task-board",
+    "title": "Task board",
+    "description": "Mini Kanban board grouped by Status. Drag a card to update Status; click to focus the row in linked sections.",
+    "requiredAccess": "full",
+    "columns": [
+      {
+        "name": "Title",
+        "type": "Text"
+      },
+      {
+        "name": "Status",
+        "type": "Text"
+      },
+      {
+        "name": "Priority",
+        "type": "Text",
+        "optional": true
+      }
+    ],
+    "allowSelectBy": true,
+    "hasCustomOptions": false,
+    "hasExampleDocument": false,
+    "usesUi": [
+      "badge",
+      "card"
+    ],
+    "sourcePath": "examples/task-board/WidgetApp.tsx"
+  },
+  {
+    "id": "theme-demo",
+    "title": "Theme",
+    "description": "Read w.theme from the host document.",
+    "requiredAccess": "read table",
+    "columns": [],
+    "allowSelectBy": false,
+    "hasCustomOptions": false,
+    "hasExampleDocument": false,
+    "usesUi": [],
+    "sourcePath": "examples/theme-demo/WidgetApp.tsx"
+  },
+  {
+    "id": "widget-options",
+    "title": "Widget options",
+    "description": "Persist UI state with setWidgetOption / widgetOptions.",
+    "requiredAccess": "read table",
+    "columns": [],
+    "allowSelectBy": false,
+    "hasCustomOptions": false,
+    "hasExampleDocument": false,
+    "usesUi": [
+      "button"
+    ],
+    "sourcePath": "examples/widget-options/WidgetApp.tsx"
+  },
+  {
+    "id": "writes-demo",
+    "title": "Table writes",
+    "description": "create, update, upsert, destroy via w.table.",
+    "requiredAccess": "full",
+    "columns": [
+      {
+        "name": "Title",
+        "type": "Text"
+      }
+    ],
+    "allowSelectBy": false,
+    "hasCustomOptions": false,
+    "hasExampleDocument": false,
+    "usesUi": [
+      "button"
+    ],
+    "sourcePath": "examples/writes-demo/WidgetApp.tsx"
+  }
+]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-grist-widget",
-  "version": "0.3.7",
+  "version": "0.3.9",
   "description": "Scaffold a new Grist custom widget from the grist-widget-sdk Vite template",
   "license": "MIT",
   "type": "module",
@@ -12,7 +12,12 @@
   },
   "files": [
     "bin",
+    "src",
     "template",
+    "vendor",
+    "examples",
+    "ui-source",
+    "manifest.json",
     "LICENSE"
   ],
   "publishConfig": {
@@ -33,7 +38,14 @@
     "cli",
     "create-grist-widget"
   ],
+  "dependencies": {
+    "@clack/prompts": "^1.7.0"
+  },
+  "devDependencies": {
+    "vitest": "^4.1.4"
+  },
   "scripts": {
-    "build": "node scripts/build-template.mjs"
+    "build": "node scripts/build-template.mjs",
+    "test": "vitest run"
   }
 }

package/src/git-gate.mjs

@@ -0,0 +1,30 @@
+// The safety gate `use <example-id>` rests on: overlayExampleSrc overwrites
+// src/App.tsx (and any other example-specific files) in place, so the only
+// thing that makes that recoverable is a clean git tree to diff/revert
+// against. `create`/`init` always leave a repo behind today (see
+// bin/create-grist-widget.mjs's gitInitCommit), but `use` checks for one
+// explicitly rather than assuming it — the plan's own Done-when line calls
+// this out: "it rests on the CLI's git init, which a future --no-git would
+// silently remove." Checking `git rev-parse` (not just "does .git exist")
+// is what keeps this correct independent of that future flag.
+//
+// Exported separately from bin/create-grist-widget.mjs so it has its own
+// unit test (tests/git-gate.test.mjs) — see docs/planning/2026-08-execution-plan.md
+// §105 ("the git gate has its own test").
+
+import { execFileSync } from "node:child_process"
+
+/**
+ * @param {string} cwd
+ * @returns {{ ok: true } | { ok: false, reason: "no-repo" | "dirty" }}
+ */
+export function checkGitGate(cwd) {
+  try {
+    execFileSync("git", ["rev-parse", "--is-inside-work-tree"], { cwd, stdio: "pipe" })
+  } catch {
+    return { ok: false, reason: "no-repo" }
+  }
+  const status = execFileSync("git", ["status", "--porcelain"], { cwd, encoding: "utf8" })
+  if (status.trim()) return { ok: false, reason: "dirty" }
+  return { ok: true }
+}

package/template/scripts/deploy.mjs

@@ -132,11 +132,45 @@ export function plan(siteDir, repo, event, ref, { force = false } = {}) {
   if (!version) throw new Error("package.json has no version")
   const versionDir = join(siteDir, `v${version}`)
   const exists = isGenuineRelease(versionDir, repo)
+  const skip = exists && !force
+  // T-07: "merging without bumping the version publishes nothing" was a
+  // silent no-op, documented in two places (this file's own header comment,
+  // and AGENTS.md's Anti-patterns) instead of made unrepresentable. Turn it
+  // loud for the one case that actually means "I meant to publish and
+  // didn't": a genuine `push` to main (not `workflow_dispatch`, which has
+  // its own explicit --force for intentional rebuilds) landed on a repo
+  // that's already released before, and the version it resolved to was
+  // already published. If HEAD's parent had the *same* version, nothing
+  // about this push looks like an intentional re-run -- fail the workflow
+  // step instead of quietly reporting success. Falls back to today's silent
+  // skip if HEAD~1 doesn't resolve (e.g. a squashed/rebased history, or
+  // this being the repo's very first commit) -- this is a backstop for the
+  // common case, not a guarantee for every git topology.
+  if (event === "push" && !firstRelease && skip) {
+    try {
+      const previousPkgJson = execFileSync("git", ["show", "HEAD~1:package.json"], {
+        encoding: "utf8",
+      })
+      const previousVersion = JSON.parse(previousPkgJson).version
+      if (previousVersion === version) {
+        throw new Error(
+          `deploy: this push to main would publish nothing -- v${version} was already released and ` +
+            `package.json's version is unchanged from the previous commit. Bump "version" in package.json ` +
+            `before merging if you meant to publish new content (see AGENTS.md's Anti-patterns).`
+        )
+      }
+    } catch (err) {
+      // Re-throw our own message; swallow only git/JSON failures (HEAD~1
+      // missing, package.json didn't exist at that commit, etc.) and fall
+      // through to the existing silent-skip behavior for those cases.
+      if (err instanceof Error && err.message.startsWith("deploy: this push")) throw err
+    }
+  }
   return {
     context: "release",
     version,
     base: basePathFor(repo, "release", version),
-    skip: exists && !force,
+    skip,
     reason: exists ? (force ? "force-rebuild" : "already-published") : "new-version",
     // Exposed so the workflow can gate a one-time repo cleanup (prune stray
     // branches, reset dev to main) on exactly this signal -- see

package/ui-source/ShadcnDataSheetGrid.css

@@ -0,0 +1,117 @@
+/**
+ * Theme bridge: react-datasheet-grid uses :root defaults and several hard-coded
+ * colors. This wrapper scopes shadcn design tokens (--background, --border,
+ * oklch, …) so the grid matches the rest of the UI in light/dark mode.
+ */
+.shadcn-dsg {
+  --dsg-border-color: var(--border);
+  --dsg-selection-border-color: var(--ring);
+  --dsg-selection-border-radius: 0;
+  --dsg-selection-border-width: 2px;
+  --dsg-selection-background-color: color-mix(in oklch, var(--primary) 14%, transparent);
+  --dsg-selection-disabled-border-color: color-mix(
+    in oklch,
+    var(--muted-foreground) 50%,
+    transparent
+  );
+  --dsg-selection-disabled-background-color: color-mix(
+    in oklch,
+    var(--muted) 55%,
+    transparent
+  );
+  --dsg-corner-indicator-width: 10px;
+  --dsg-header-text-color: var(--muted-foreground);
+  --dsg-header-active-text-color: var(--foreground);
+  --dsg-cell-background-color: var(--background);
+  --dsg-cell-disabled-background-color: var(--muted);
+  --dsg-transition-duration: 0.1s;
+  --dsg-expand-rows-indicator-width: 10px;
+  --dsg-scroll-shadow-width: 7px;
+  --dsg-scroll-shadow-color: color-mix(in oklch, var(--foreground) 14%, transparent);
+}
+
+.shadcn-dsg .dsg-container {
+  background: var(--background);
+  color: var(--foreground);
+  font-family: inherit;
+  font-size: 0.875rem;
+  line-height: 1.25rem;
+}
+
+.shadcn-dsg .dsg-row-header .dsg-cell {
+  background: var(--muted) !important;
+  color: var(--muted-foreground);
+  font-size: 0.75rem;
+  font-weight: 600;
+  letter-spacing: 0.05em;
+  text-transform: uppercase;
+}
+
+.shadcn-dsg .dsg-cell-header.dsg-cell-gutter {
+  box-shadow:
+    1px 0 var(--dsg-border-color),
+    0 1px var(--dsg-border-color);
+}
+
+.shadcn-dsg .dsg-active-cell-focus {
+  box-shadow: 0 0 0 2px color-mix(in oklch, var(--ring) 55%, transparent);
+}
+
+.shadcn-dsg .dsg-add-row {
+  background: var(--muted);
+  color: var(--foreground);
+  border-color: var(--border);
+}
+
+.shadcn-dsg .dsg-add-row-btn,
+.shadcn-dsg .dsg-add-row-input {
+  background: var(--background);
+  color: var(--foreground);
+  border-color: var(--border);
+  border-radius: var(--radius);
+}
+
+.shadcn-dsg .dsg-add-row-btn:hover,
+.shadcn-dsg .dsg-add-row-input:hover {
+  border-color: var(--input);
+  background: color-mix(in oklch, var(--accent) 35%, var(--background));
+}
+
+.shadcn-dsg .dsg-add-row-btn:focus,
+.shadcn-dsg .dsg-add-row-input:focus {
+  border-color: var(--ring);
+  outline: none;
+  box-shadow: 0 0 0 2px color-mix(in oklch, var(--ring) 35%, transparent);
+}
+
+.shadcn-dsg .dsg-add-row-btn::before,
+.shadcn-dsg .dsg-add-row-btn::after {
+  background: var(--muted-foreground);
+}
+
+.shadcn-dsg .dsg-context-menu {
+  background: var(--popover);
+  color: var(--popover-foreground);
+  border: 1px solid var(--border);
+  border-radius: var(--radius);
+  box-shadow:
+    0 4px 6px -1px color-mix(in oklch, var(--foreground) 8%, transparent),
+    0 2px 4px -2px color-mix(in oklch, var(--foreground) 8%, transparent);
+}
+
+.shadcn-dsg .dsg-context-menu-item:hover {
+  background: var(--accent);
+  color: var(--accent-foreground);
+}
+
+.shadcn-dsg .dsg-expand-rows-rect {
+  background: color-mix(in oklch, var(--primary) 10%, transparent);
+}
+
+.shadcn-dsg .dsg-input {
+  color: var(--foreground);
+}
+
+.shadcn-dsg .dsg-input::placeholder {
+  color: var(--muted-foreground);
+}

package/ui-source/ShadcnDataSheetGrid.tsx

@@ -0,0 +1,46 @@
+import { forwardRef } from "react"
+import {
+  DynamicDataSheetGrid,
+  type DataSheetGridProps,
+  type DataSheetGridRef,
+} from "react-datasheet-grid"
+import "react-datasheet-grid/dist/style.css"
+
+import { cn } from "@/lib/utils"
+
+import "./ShadcnDataSheetGrid.css"
+
+export type ShadcnDataSheetGridProps<T> = DataSheetGridProps<T> & {
+  /** Classes on the outer wrapper (border, radius, layout). */
+  wrapperClassName?: string
+}
+
+/**
+ * Themed datasheet grid aligned with shadcn tokens (light/dark).
+ * Uses `DynamicDataSheetGrid` so `columns` updates apply after mount.
+ */
+type ShadcnDataSheetGridComponent = <T>(
+  props: ShadcnDataSheetGridProps<T> & { ref?: React.Ref<DataSheetGridRef> }
+) => React.ReactElement | null
+
+const ShadcnDataSheetGridInner = <T,>(
+  { wrapperClassName, ...props }: ShadcnDataSheetGridProps<T>,
+  ref: React.ForwardedRef<DataSheetGridRef>
+) => {
+  return (
+    <div
+      className={cn(
+        "shadcn-dsg min-h-0 min-w-0 overflow-hidden rounded-md border border-border bg-background text-foreground shadow-sm",
+        wrapperClassName
+      )}
+    >
+      <DynamicDataSheetGrid ref={ref} {...props} />
+    </div>
+  )
+}
+
+export const ShadcnDataSheetGrid = forwardRef(
+  ShadcnDataSheetGridInner
+) as ShadcnDataSheetGridComponent
+
+export type { DataSheetGridProps, DataSheetGridRef } from "react-datasheet-grid"