create-grist-widget 0.2.12 → 0.2.14

package/README.md

@@ -46,6 +46,11 @@ simplest way to get from zero to a deployed widget:
    folder `/ (root)`. This can only be set once `gh-pages` exists, which is
    why it's a step *after* the first push, not before.
 
+   > ⚠️ **Not `main`.** Pointing Pages at `main` serves this repo's raw,
+   > unbuilt source instead of the built site — the symptom is a blank page
+   > with a `/src/main.tsx` 404 in the browser console, even though the
+   > workflow itself reports success.
+
    Once that's saved, your widget is live at two URLs:
 
    - `https://<owner>.github.io/<repo>/latest/` — mutable, always points at

package/package.json

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

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

@@ -13,8 +13,11 @@ name: Deploy widget to GitHub Pages
 # One-time setup this workflow can't do for you: enable Pages (Settings ->
 # Pages -> Source: Deploy from a branch -> gh-pages -> / (root); this workflow
 # creates the gh-pages branch itself if missing, but Pages must be pointed at
-# it once) and make sure Actions has write access (Settings -> Actions ->
-# General -> Workflow permissions -> Read and write permissions).
+# it once -- NOT main, which serves this repo's raw unbuilt source instead
+# (symptom: a blank page with a 404 for /src/main.tsx in the browser
+# console, even though this workflow reports success) and make sure Actions
+# has write access (Settings -> Actions -> General -> Workflow permissions ->
+# Read and write permissions).
 
 on:
   push:
@@ -56,10 +59,16 @@ jobs:
         uses: actions/setup-node@v4
         with:
           node-version: 22
-          cache: pnpm
 
+      # Not --frozen-lockfile, and no `cache: pnpm` above: a freshly
+      # scaffolded repo never has a committed pnpm-lock.yaml (the CLI's
+      # auto-commit runs before anyone's first `pnpm install`), and
+      # --frozen-lockfile/cache: pnpm both hard-require one to exist —
+      # found live, the very first real deploy failed with "Dependencies
+      # lock file is not found". A plain install resolves fresh every run
+      # regardless of whether a lockfile was ever committed.
       - name: Install dependencies
-        run: pnpm install --frozen-lockfile
+        run: pnpm install
 
       - name: Clone gh-pages into ./site
         run: |
@@ -116,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 $UPDATE_VERSIONS --push \
             --commit-message "deploy: ${{ steps.plan.outputs.context }} @ ${{ github.sha }}"
 
   cleanup:

package/template/README.md

@@ -92,6 +92,12 @@ automatically.
    → `/ (root)`. The workflow creates the `gh-pages` branch itself the first
    time it runs (if it doesn't exist yet), but Pages needs to be pointed at
    it once.
+   > ⚠️ **Not `main`.** If Pages is left on (or accidentally set to) `main`,
+   > it serves this repo's raw, unbuilt source — including a script tag
+   > pointing at `/src/main.tsx` — instead of the built site. The symptom is
+   > a blank/black page with a 404 for `/src/main.tsx` in the browser
+   > console, even though the workflow itself reports success (it pushed the
+   > right build to `gh-pages`; Pages is just reading from the wrong place).
 2. **Settings → Actions → General → Workflow permissions** → "Read and write
    permissions". New repos sometimes default the workflow's token to
    read-only, which would fail the push to `gh-pages` with a 403.

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"
 
@@ -107,6 +118,28 @@ 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).
+ */
+export function buildVersionsManifest(siteDir) {
+  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"))
+    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
 // ----------------------------------------------------------------------------
@@ -133,12 +166,26 @@ export function placeTarget({ siteDir, channel, version, distDir, sha, ref }) {
     }
     return { placed: "dev" }
   }
-  // release
+  // release: immutable v<version>/, mutable latest/, and the same build
+  // placed directly at the site root too. main.tsx renders the showcase hub
+  // (TemplateLanding) at any URL with no recognized channel suffix — the
+  // bare root included — so without this, a real scaffolded repo's own
+  // https://owner.github.io/repo/ has nothing deployed there at all and
+  // 404s instead of ever reaching that hub. Reusing the release dist here is
+  // exactly like latest/ reusing it: the asset URLs it references (under
+  // v<version>/assets/) already exist from the versionDir placement above,
+  // 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 }, null, 2) + "\n",
+  )
   const latestDir = join(siteDir, "latest")
   replaceDir(latestDir, distDir)
-  return { placed: `v${version}`, latest: "latest" }
+  mkdirSync(siteDir, { recursive: true })
+  cpSync(distDir, siteDir, { recursive: true })
+  return { placed: `v${version}`, latest: "latest", root: true }
 }
 
 /**
@@ -163,8 +210,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" }) {
+  if (updateVersions) {
+    const versions = buildVersionsManifest(siteDir)
+    writeFileSync(join(siteDir, "versions.json"), JSON.stringify(versions, null, 2) + "\n")
+  }
   git(["add", "-A"], siteDir)
   const status = git(["status", "--porcelain"], siteDir)
   if (!status) {
@@ -243,6 +294,7 @@ function main() {
     case "finalize": {
       const res = finalize({
         siteDir: args.site,
+        updateVersions: !!args["update-versions"],
         push: !!args.push,
         commitMessage: args["commit-message"],
       })

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

@@ -49,7 +49,7 @@ function StatusDot({ pulsing, className }: { pulsing: boolean; className: string
   )
 }
 
-/** Pure render of a display status -- shared by the real (context-driven) and demo (cycling) chips. */
+/** Pure render of a display status. */
 function ChipVisual({ display, secondsLeft }: { display: HandshakeDisplayStatus; secondsLeft: number }) {
   switch (display.kind) {
     case "connecting":
@@ -91,81 +91,27 @@ function RealChipContents() {
   return <ChipVisual display={display} secondsLeft={secondsLeft} />
 }
 
-// A fixed, looping sequence for the showcase hub -- there's no real Grist to
-// connect to on that page (it's shown precisely because a real widget isn't
-// embedded), so this is a cosmetic demo of the same visual states a real
-// widget's chip goes through, not a real handshake attempt.
-const DEMO_SEQUENCE: readonly { display: HandshakeDisplayStatus; ms: number }[] = [
-  { display: { kind: "connecting" }, ms: 1500 },
-  { display: { kind: "retrying", attempts: 1 }, ms: 3000 },
-  { display: { kind: "connected" }, ms: 3500 },
-]
-
-function DemoChipContents() {
-  const [step, setStep] = useState(0)
-  const [countdownState, setCountdownState] = useState({ step, secondsLeft: 3 })
-  const current = DEMO_SEQUENCE[step]
-
-  // Reset the mini countdown the moment the demo cycle enters "retrying" --
-  // an "adjust state during render" pattern, not a setState-in-effect.
-  if (current.display.kind === "retrying" && countdownState.step !== step) {
-    setCountdownState({ step, secondsLeft: 3 })
-  }
-
-  useEffect(() => {
-    const advance = setTimeout(() => {
-      setStep((s) => (s + 1) % DEMO_SEQUENCE.length)
-    }, current.ms)
-    return () => clearTimeout(advance)
-  }, [step, current.ms])
-
-  useEffect(() => {
-    if (current.display.kind !== "retrying") return
-    const id = setInterval(() => {
-      setCountdownState((s) => ({ ...s, secondsLeft: s.secondsLeft > 0 ? s.secondsLeft - 1 : 0 }))
-    }, 1000)
-    return () => clearInterval(id)
-  }, [step, current.display.kind])
-
-  return <ChipVisual display={current.display} secondsLeft={countdownState.secondsLeft} />
-}
-
 /**
- * Small pill showing Grist handshake status. Two modes:
- *
- * - Default: live 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.
- * - `demo`: a cosmetic, looping cycle through the same visual states, used
- *   on the showcase hub page where no real Grist connection is ever
- *   attempted -- a reference to the tech behind the template, not a status
- *   readout.
+ * 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.
  */
-export function GristStatusChip({
-  demo = false,
-  className,
-}: {
-  demo?: boolean
-  className?: string
-}) {
-  const pill = (
-    <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,
-      )}
-    >
-      {demo ? <DemoChipContents /> : <RealChipContents />}
-    </div>
-  )
-
-  if (demo) return pill
-
+export function GristStatusChip({ className }: { className?: string }) {
   return (
     <GristHandshakeProvider>
-      <div className="pointer-events-none fixed top-2 right-2 z-50">{pill}</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 />
+        </div>
+      </div>
     </GristHandshakeProvider>
   )
 }

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

@@ -1,9 +1,8 @@
 import { useState } from "react"
 
-import { GristStatusChip } from "@/components/grist-status-chip"
 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
@@ -70,9 +69,6 @@ export function TemplateLanding() {
   return (
     <div className="mx-auto max-w-2xl px-6 py-16">
       <header className="mb-10 text-center">
-        <div className="mb-4 flex justify-center">
-          <GristStatusChip demo />
-        </div>
         <p className="mb-2 text-sm font-medium text-muted-foreground">
           grist-widget-template
         </p>
@@ -157,6 +153,13 @@ git push origin dev`}</code>
                 enable Pages: Settings → Pages → Source → "Deploy from a
                 branch" → branch <code className="text-foreground">gh-pages</code>{" "}
                 → <code className="text-foreground">/ (root)</code>.
+                <p className="mt-2 text-xs text-muted-foreground">
+                  Not <code className="text-foreground">main</code> — that
+                  serves this repo's raw, unbuilt source instead of the built
+                  site (a blank page with a{" "}
+                  <code className="text-foreground">/src/main.tsx</code> 404
+                  in the console).
+                </p>
                 <p className="mt-2 text-xs text-muted-foreground">
                   If that first run fails with a permissions error pushing to{" "}
                   <code className="text-foreground">gh-pages</code>, Settings
@@ -175,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)