create-grist-widget 0.2.13 → 0.2.16

package/package.json

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

package/template/.github/workflows/deploy.yml

@@ -125,10 +125,14 @@ jobs:
         if: steps.plan.outputs.skip == 'true'
         run: echo "== skip — v${{ steps.plan.outputs.version }} already published"
 
-      - name: Finalize (commit + push)
+      - name: Finalize (versions.json + commit + push)
         run: |
+          UPDATE_VERSIONS=""
+          if [ "${{ steps.plan.outputs.context }}" = "release" ]; then
+            UPDATE_VERSIONS="--update-versions"
+          fi
           node scripts/deploy.mjs finalize \
-            --site site --push \
+            --site site --repo "$REPO_NAME" $UPDATE_VERSIONS --push \
             --commit-message "deploy: ${{ steps.plan.outputs.context }} @ ${{ github.sha }}"
 
   cleanup:

package/template/README.md

@@ -6,7 +6,7 @@ Base template to build a Grist widget with `grist-widget-sdk`.
 
 Opened outside a Grist iframe, `main.tsx` picks between two components purely by URL shape (`src/lib/showcase-routing.ts`, no router needed): a bare path with no recognized channel suffix renders `TemplateLanding` (its own hero, onboarding, and released-version index); `/latest/`, `/dev/`, or `/v<version>/` renders `ChannelNotice` instead — a distinct hero explaining which build this is, chips to jump to any other version/channel (`src/lib/showcase-versions.ts`), and a copy-this-URL helper for pasting into Grist's custom widget field.
 
-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 `useGristHandshakeContext()` from `grist-widget-sdk/advanced` in its own `<GristHandshakeProvider>`. Safe to mount alongside `GristWidgetProvider`: both share the page's `ensureGristReady()` singleton (see `apps/docs/api/handshake.md`), so this is purely observational and never duplicates the real handshake.
+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 `apps/docs/api/handshake.md`).
 
 `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.
 
@@ -86,6 +86,19 @@ of changes — it's the permanent working/preview branch for this widget, not
 a one-off feature branch to delete and recreate. Deleting it retires `/dev/`
 automatically.
 
+> ⚠️ **Used GitHub's "Use this template" button instead of `npm create
+> grist-widget`?** That path copies this repo's default branch verbatim —
+> it doesn't run any of the CLI's own setup (renaming `package.json`,
+> titles, etc.), and it won't reset `package.json`'s `version` back to a
+> fresh `0.0.1` for you. Do both by hand before your first real release.
+> Also **never manually seed/copy `gh-pages` content** from another repo
+> (e.g. to get Pages showing something immediately) — each `v<version>/`
+> is only recognized as a genuine prior release if it carries a
+> `showcase-meta.json` naming *this* repo (written by this pipeline's own
+> `place` step); anything else is treated as unpublished and safely
+> rebuilt over, but it's simpler to just let the workflow create
+> `gh-pages` itself (it does, as an orphan branch, on its first real run).
+
 **One-time setup** (the workflow can't do this part for you):
 
 1. **Settings → Pages** → Source: "Deploy from a branch" → branch `gh-pages`

package/template/package.json

@@ -13,7 +13,7 @@
   },
   "dependencies": {
     "@fontsource-variable/geist": "^5.2.8",
-    "grist-widget-sdk": "^0.2.1",
+    "grist-widget-sdk": "^0.2.15",
     "@tailwindcss/vite": "^4.2.1",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",

package/template/scripts/deploy.mjs

@@ -8,6 +8,8 @@
 //   release (push to main / workflow_dispatch)
 //     - immutable  /<repo>/v<version>/   (built once, never overwritten)
 //     - mutable    /<repo>/latest/       (alias to newest release)
+//     - /<repo>/versions.json            (released-version index, newest first
+//                                        -- read by the showcase hub/notice)
 //
 //   dev (push to dev)
 //     - mutable    /<repo>/dev/          (+ version.json + self-reload)
@@ -30,10 +32,19 @@
 //     Removes dev/ from the gh-pages tree (retire the dev URL when the `dev`
 //     branch is deleted). Never touches a release or latest/.
 //
-//   finalize --site <dir> [--push] [--commit-message <msg>]
-//     Commits + pushes the gh-pages tree with a rebase-and-retry loop.
+//   finalize --site <dir> [--update-versions] [--push] [--commit-message <msg>]
+//     Regenerates versions.json (release runs only) and commits + pushes the
+//     gh-pages tree with a rebase-and-retry loop.
 
-import { existsSync, readFileSync, writeFileSync, rmSync, mkdirSync, cpSync } from "node:fs"
+import {
+  existsSync,
+  readFileSync,
+  readdirSync,
+  writeFileSync,
+  rmSync,
+  mkdirSync,
+  cpSync,
+} from "node:fs"
 import { join, dirname } from "node:path"
 import { execFileSync } from "node:child_process"
 
@@ -47,10 +58,33 @@ export function basePathFor(repo, channel, version) {
   return `/${repo}/${leaf}/`
 }
 
+/**
+ * Was `versionDir` actually published by *this* repo's own pipeline? Checks
+ * for a `showcase-meta.json` whose `repo` field matches -- not just that the
+ * directory exists. A `gh-pages` branch manually seeded from another repo's
+ * export (found live: a freshly-created widget repo's `gh-pages` already
+ * contained `v<version>/` directories copied from the template repo it came
+ * from, some with no meta file at all, one with a foreign `showcase-meta.json`
+ * whose `sha` didn't belong to this repo's own history) would otherwise look
+ * indistinguishable from a real prior release and get silently treated as
+ * "already published" forever, permanently squatting on that version path.
+ */
+function isGenuineRelease(versionDir, repo) {
+  const metaPath = join(versionDir, "showcase-meta.json")
+  if (!existsSync(metaPath)) return false
+  try {
+    const meta = JSON.parse(readFileSync(metaPath, "utf8"))
+    return meta.repo === repo
+  } catch {
+    return false
+  }
+}
+
 /**
  * Build the release/dev plan from this repo's own package.json + the current
- * gh-pages tree. Release is skipped when its immutable v<version> dir already
- * exists (unless force), so re-pushing main without a version bump is a no-op.
+ * gh-pages tree. Release is skipped when its immutable v<version> dir was
+ * genuinely published by this repo before (unless force), so re-pushing main
+ * without a version bump is a no-op.
  */
 export function plan(siteDir, repo, event, ref, { force = false } = {}) {
   const isRelease = event === "workflow_dispatch" || ref === "refs/heads/main" || ref === "main"
@@ -61,7 +95,7 @@ export function plan(siteDir, repo, event, ref, { force = false } = {}) {
   const version = pkg.version
   if (!version) throw new Error("package.json has no version")
   const versionDir = join(siteDir, `v${version}`)
-  const exists = existsSync(versionDir)
+  const exists = isGenuineRelease(versionDir, repo)
   return {
     context: "release",
     version,
@@ -107,6 +141,32 @@ export function injectSelfReload(html, sha) {
   return out + snippet
 }
 
+/**
+ * Scan siteDir for previously-released v<version>/showcase-meta.json files
+ * and assemble the versions.json manifest, newest first. Read by the
+ * showcase hub (TemplateLanding) and per-channel notice (ChannelNotice) to
+ * show this widget's own release history -- not the grist-widget-sdk
+ * monorepo's (found live: every scaffolded widget's version index showed
+ * the monorepo's versions instead of its own, since showcase-versions.ts
+ * used to hardcode that URL). Entries whose meta has no `repo` field, or a
+ * `repo` that doesn't match this repo, are skipped -- a `gh-pages` branch
+ * manually seeded from another repo's export (found live) would otherwise
+ * leak that repo's own version history into this one's index.
+ */
+export function buildVersionsManifest(siteDir, repo) {
+  const entries = []
+  for (const name of existsSync(siteDir) ? readdirSync(siteDir) : []) {
+    if (!/^v\d+\.\d+\.\d+/.test(name)) continue
+    const metaPath = join(siteDir, name, "showcase-meta.json")
+    if (!existsSync(metaPath)) continue
+    const meta = JSON.parse(readFileSync(metaPath, "utf8"))
+    if (meta.repo !== repo) continue
+    entries.push({ version: meta.version, publishedAt: meta.publishedAt })
+  }
+  entries.sort((a, b) => new Date(b.publishedAt) - new Date(a.publishedAt))
+  return entries
+}
+
 // ----------------------------------------------------------------------------
 // Filesystem / git effects
 // ----------------------------------------------------------------------------
@@ -118,7 +178,7 @@ function replaceDir(dest, srcDist) {
 }
 
 /** Place a freshly built dist into the gh-pages tree. */
-export function placeTarget({ siteDir, channel, version, distDir, sha, ref }) {
+export function placeTarget({ siteDir, channel, version, distDir, sha, ref, repo }) {
   if (!existsSync(distDir)) throw new Error(`dist not found: ${distDir}`)
   if (channel === "dev") {
     const devDir = join(siteDir, "dev")
@@ -144,6 +204,10 @@ export function placeTarget({ siteDir, channel, version, distDir, sha, ref }) {
   // so nothing 404s.
   const versionDir = join(siteDir, `v${version}`)
   replaceDir(versionDir, distDir)
+  writeFileSync(
+    join(versionDir, "showcase-meta.json"),
+    JSON.stringify({ version, publishedAt: new Date().toISOString(), sha, repo }, null, 2) + "\n",
+  )
   const latestDir = join(siteDir, "latest")
   replaceDir(latestDir, distDir)
   mkdirSync(siteDir, { recursive: true })
@@ -173,8 +237,12 @@ function sleep(ms) {
   while (Date.now() < end) {}
 }
 
-/** Commit + push the gh-pages tree with a rebase-and-retry loop. */
-export function finalize({ siteDir, push, commitMessage, remoteBranch = "gh-pages" }) {
+/** Regenerate versions.json (release runs only), then commit + push with rebase-retry. */
+export function finalize({ siteDir, updateVersions, push, commitMessage, remoteBranch = "gh-pages", repo }) {
+  if (updateVersions) {
+    const versions = buildVersionsManifest(siteDir, repo)
+    writeFileSync(join(siteDir, "versions.json"), JSON.stringify(versions, null, 2) + "\n")
+  }
   git(["add", "-A"], siteDir)
   const status = git(["status", "--porcelain"], siteDir)
   if (!status) {
@@ -241,6 +309,7 @@ function main() {
         distDir: args.dist,
         sha: args.sha,
         ref: args.ref,
+        repo: args.repo,
       })
       console.log("placed:", JSON.stringify(res))
       break
@@ -253,8 +322,10 @@ function main() {
     case "finalize": {
       const res = finalize({
         siteDir: args.site,
+        updateVersions: !!args["update-versions"],
         push: !!args.push,
         commitMessage: args["commit-message"],
+        repo: args.repo,
       })
       console.log("finalize:", JSON.stringify(res))
       break

package/template/src/components/channel-notice.tsx

@@ -10,7 +10,7 @@ import {
 } from "@/components/ui/card"
 import { Input } from "@/components/ui/input"
 import { channelLabel, type Channel } from "@/lib/showcase-routing"
-import { DEV_URL, useVersions, versionUrl } from "@/lib/showcase-versions"
+import { devUrl, useVersions, versionUrl } from "@/lib/showcase-versions"
 import { cn } from "@/lib/utils"
 
 // Shown instead of the widget tree on a specific channel build
@@ -44,7 +44,7 @@ function VersionChips({ current }: { current: Channel }) {
           latest
         </a>
       )}
-      <a href={DEV_URL} className={chipClass(current.kind === "dev")}>
+      <a href={devUrl()} className={chipClass(current.kind === "dev")}>
         dev
       </a>
       {versions?.map((v) => (

package/template/src/components/grist-status-chip.tsx

@@ -1,5 +1,5 @@
 import { useEffect, useState } from "react"
-import { GristHandshakeProvider, useGristHandshakeContext } from "grist-widget-sdk/advanced"
+import { useAmbientGristHandshake, type GristWidgetSnapshot } from "grist-widget-sdk/advanced"
 
 import { deriveDisplayStatus, type HandshakeDisplayStatus } from "@/lib/grist-handshake-status"
 import { cn } from "@/lib/utils"
@@ -83,8 +83,7 @@ function ChipVisual({ display, secondsLeft }: { display: HandshakeDisplayStatus;
   }
 }
 
-function RealChipContents() {
-  const { snapshot } = useGristHandshakeContext()
+function RealChipContents({ snapshot }: { snapshot: GristWidgetSnapshot }) {
   const display = deriveDisplayStatus(snapshot.lifecycle)
   const retryAttempts = display.kind === "retrying" ? display.attempts : 0
   const secondsLeft = useRetryCountdown(retryAttempts, display.kind === "retrying")
@@ -93,25 +92,25 @@ function RealChipContents() {
 
 /**
  * Small pill showing live Grist handshake status while actually embedded in
- * Grist. Mounts its own `<GristHandshakeProvider>` alongside
- * `<GristWidgetProvider>` -- documented (grist-widget-sdk/advanced) as safe
- * to coexist, since both share the page's `ensureGristReady()` singleton.
- * Purely observational: it never drives the real widget's connection, just
- * reflects it.
+ * Grist. Must be mounted *inside* `<GristWidgetProvider>` -- it only observes
+ * that provider's own handshake manager (`useAmbientGristHandshake()`,
+ * `grist-widget-sdk/advanced`) and never mounts its own, so it can't ever run
+ * a second, competing `grist.ready()` call. Renders nothing outside a
+ * provider.
  */
 export function GristStatusChip({ className }: { className?: string }) {
+  const handshake = useAmbientGristHandshake()
+  if (!handshake) return null
   return (
-    <GristHandshakeProvider>
-      <div className="pointer-events-none fixed top-2 right-2 z-50">
-        <div
-          className={cn(
-            "flex items-center gap-1.5 rounded-full border bg-background/90 px-2.5 py-1 text-xs text-muted-foreground shadow-sm backdrop-blur",
-            className,
-          )}
-        >
-          <RealChipContents />
-        </div>
+    <div className="pointer-events-none fixed top-2 right-2 z-50">
+      <div
+        className={cn(
+          "flex items-center gap-1.5 rounded-full border bg-background/90 px-2.5 py-1 text-xs text-muted-foreground shadow-sm backdrop-blur",
+          className,
+        )}
+      >
+        <RealChipContents snapshot={handshake.snapshot} />
       </div>
-    </GristHandshakeProvider>
+    </div>
   )
 }

package/template/src/components/template-landing.tsx

@@ -2,7 +2,7 @@ import { useState } from "react"
 
 import { Button } from "@/components/ui/button"
 import { Tabs, TabsContent, TabsList, TabsTrigger } from "@/components/ui/tabs"
-import { DEV_URL, formatDate, useVersions, versionUrl } from "@/lib/showcase-versions"
+import { devUrl, formatDate, useVersions, versionUrl } from "@/lib/showcase-versions"
 
 // The showcase "hub" page: rendered whenever this deploy's URL has no
 // recognized channel suffix (see src/lib/showcase-routing.ts) -- this repo's
@@ -178,7 +178,7 @@ git push origin dev`}</code>
             Released template versions
           </h2>
           <a
-            href={DEV_URL}
+            href={devUrl()}
             className="text-sm text-muted-foreground underline underline-offset-4 hover:text-foreground"
           >
             Live dev preview →

package/template/src/lib/showcase-versions.ts

@@ -1,21 +1,35 @@
 import { useEffect, useState } from "react"
 
+import { parseShowcasePath } from "@/lib/showcase-routing"
+
 // Shared by the showcase hub (TemplateLanding) and the per-channel notice
-// (ChannelNotice) -- both need the same released-version list, fetched from
-// a fixed absolute URL rather than a path relative to wherever this happens
-// to be deployed (see src/components/template-landing.tsx for why).
-export const VERSIONS_URL =
-  "https://arthurblanchon.github.io/grist-widget-sdk/template/versions.json"
-export const DEV_URL = "https://arthurblanchon.github.io/grist-widget-sdk/template/dev/"
-export const HUB_URL = "https://arthurblanchon.github.io/grist-widget-sdk/template/"
+// (ChannelNotice) -- both need the same released-version list. URLs are
+// root-relative to wherever THIS deploy actually lives (derived from
+// window.location.pathname via parseShowcasePath's hubPath), not hardcoded
+// to the grist-widget-sdk monorepo's own showcase: a real scaffolded
+// widget has its own versions.json and its own v<version>/ + dev/ dirs,
+// and previously showed the monorepo's version history and links instead
+// of its own (found live on a real scaffold's landing page).
+function hubPath(): string {
+  const path = parseShowcasePath(window.location.pathname).hubPath
+  return path.endsWith("/") ? path : `${path}/`
+}
 
 export type ReleasedVersion = {
   version: string
   publishedAt: string
 }
 
+export function versionsUrl(): string {
+  return `${hubPath()}versions.json`
+}
+
+export function devUrl(): string {
+  return `${hubPath()}dev/`
+}
+
 export function versionUrl(version: string): string {
-  return `https://arthurblanchon.github.io/grist-widget-sdk/template/v${version}/`
+  return `${hubPath()}v${version}/`
 }
 
 export function useVersions() {
@@ -24,7 +38,7 @@ export function useVersions() {
 
   useEffect(() => {
     let cancelled = false
-    fetch(VERSIONS_URL, { cache: "no-store" })
+    fetch(versionsUrl(), { cache: "no-store" })
       .then((res) => (res.ok ? res.json() : Promise.reject(res)))
       .then((data: ReleasedVersion[]) => {
         if (!cancelled) setVersions(data)

package/template/src/main.tsx

@@ -35,20 +35,18 @@ createRoot(document.getElementById("root")!).render(
           <TemplateLanding />
         </div>
       ) : isEmbedded ? (
-        <>
+        <GristWidgetProvider options={GRIST_OPTIONS}>
           <GristStatusChip />
-          <GristWidgetProvider options={GRIST_OPTIONS}>
-            <GristBoundary
-              gate={GRIST_OPTIONS.columns?.length ? "canRender" : "ready"}
-            >
-              <div className="min-h-full w-full bg-background text-foreground">
-                <GristSdkAlerts>
-                  <App />
-                </GristSdkAlerts>
-              </div>
-            </GristBoundary>
-          </GristWidgetProvider>
-        </>
+          <GristBoundary
+            gate={GRIST_OPTIONS.columns?.length ? "canRender" : "ready"}
+          >
+            <div className="min-h-full w-full bg-background text-foreground">
+              <GristSdkAlerts>
+                <App />
+              </GristSdkAlerts>
+            </div>
+          </GristBoundary>
+        </GristWidgetProvider>
       ) : (
         <div className="min-h-full w-full bg-background text-foreground">
           <ChannelNotice channel={channel} hubPath={hubPath} />