create-grist-widget 0.2.9 → 0.2.11

package/package.json

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

package/template/README.md

@@ -4,7 +4,9 @@ Base template to build a Grist widget with `grist-widget-sdk`.
 
 `src/main.tsx` wraps the app with `GristWidgetProvider`, `GristBoundary`, and `GristSdkAlerts`. The latter maps `getGristSdkAlertDescriptors()` from the SDK to shadcn `Alert` (`src/components/grist-sdk-alerts.tsx` + `src/components/ui/alert.tsx`); keep them in sync with the playground when you change alert styling.
 
-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` (onboarding + released-version index); `/latest/`, `/dev/`, or `/v<version>/` renders the minimal `ChannelNotice` instead — which build this is, a link back to the hub, and a copy-this-URL helper for pasting into Grist's custom widget field.
+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.
 
 `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.
 

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

@@ -10,13 +10,58 @@ 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 { cn } from "@/lib/utils"
 
 // Shown instead of the widget tree on a specific channel build
 // (/latest/, /dev/, /v<version>/) when it's opened directly in a browser tab
 // -- not the rich showcase hub (that's `TemplateLanding`, shown when the URL
-// has no recognized channel suffix). Deliberately minimal: this page's job is
-// just to explain what you're looking at, link back to the hub, and help you
-// paste this exact URL into Grist.
+// has no recognized channel suffix). Deliberately minimal, with its own hero
+// distinct from the hub's: this page's job is just to explain what you're
+// looking at, help you jump to a different build, and help you paste this
+// exact URL into Grist.
+function VersionChips({ current }: { current: Channel }) {
+  const { versions } = useVersions()
+
+  function chipClass(active: boolean) {
+    return cn(
+      "rounded-full border px-3 py-1 text-xs font-medium transition-colors",
+      active
+        ? "border-primary bg-primary text-primary-foreground"
+        : "border-border text-muted-foreground hover:text-foreground",
+    )
+  }
+
+  return (
+    <div className="mb-8 flex flex-wrap justify-center gap-2">
+      {versions !== null && versions.length > 0 && (
+        <a
+          href={versionUrl(versions[0].version)}
+          className={chipClass(
+            current.kind === "version" && current.version === versions[0].version,
+          )}
+        >
+          latest
+        </a>
+      )}
+      <a href={DEV_URL} className={chipClass(current.kind === "dev")}>
+        dev
+      </a>
+      {versions?.map((v) => (
+        <a
+          key={v.version}
+          href={versionUrl(v.version)}
+          className={chipClass(
+            current.kind === "version" && current.version === v.version,
+          )}
+        >
+          v{v.version}
+        </a>
+      ))}
+    </div>
+  )
+}
+
 export function ChannelNotice({
   channel,
   hubPath,
@@ -47,6 +92,8 @@ export function ChannelNotice({
         build directly, outside of Grist.
       </p>
 
+      <VersionChips current={channel} />
+
       <Card className="mb-4">
         <CardHeader>
           <CardTitle>Use this as a Grist custom widget</CardTitle>

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

@@ -0,0 +1,105 @@
+import { useEffect, useState } from "react"
+import { GristHandshakeProvider, useGristHandshakeContext } from "grist-widget-sdk/advanced"
+
+import { deriveDisplayStatus } from "@/lib/grist-handshake-status"
+import { cn } from "@/lib/utils"
+
+// Fixed, approximate countdown shown while retrying -- not a mirror of the
+// SDK's actual internal poll backoff (an implementation detail, not part of
+// the public API surface, which ramps up from ~200ms before settling into a
+// steady cadence). Most production widgets connect in under a second per the
+// SDK's own docs, so a visibly "retrying" chip is already in that settled
+// long tail -- this just picks the same round number as a display countdown.
+const RETRY_COUNTDOWN_SECONDS = 5
+
+function useRetryCountdown(attempts: number, active: boolean) {
+  const [state, setState] = useState({ attempts, secondsLeft: RETRY_COUNTDOWN_SECONDS })
+
+  // Reset the countdown the moment a new retry attempt begins -- an
+  // "adjust state during render" pattern, not a setState-in-effect (which
+  // the linter flags): https://react.dev/learn/you-might-not-need-an-effect
+  if (active && state.attempts !== attempts) {
+    setState({ attempts, secondsLeft: RETRY_COUNTDOWN_SECONDS })
+  }
+
+  useEffect(() => {
+    if (!active) return
+    const id = setInterval(() => {
+      setState((s) => ({ ...s, secondsLeft: s.secondsLeft > 0 ? s.secondsLeft - 1 : 0 }))
+    }, 1000)
+    return () => clearInterval(id)
+  }, [attempts, active])
+
+  return state.secondsLeft
+}
+
+function StatusDot({ pulsing, className }: { pulsing: boolean; className: string }) {
+  return (
+    <span className="relative flex size-2">
+      {pulsing && (
+        <span
+          className={cn(
+            "absolute inline-flex size-full animate-ping rounded-full opacity-75",
+            className,
+          )}
+        />
+      )}
+      <span className={cn("relative inline-flex size-2 rounded-full", className)} />
+    </span>
+  )
+}
+
+function ChipContents() {
+  const { snapshot } = useGristHandshakeContext()
+  const display = deriveDisplayStatus(snapshot.lifecycle)
+  const retryAttempts = display.kind === "retrying" ? display.attempts : 0
+  const secondsLeft = useRetryCountdown(retryAttempts, display.kind === "retrying")
+
+  switch (display.kind) {
+    case "connecting":
+      return (
+        <>
+          <StatusDot pulsing className="bg-amber-500" />
+          Connecting to Grist
+        </>
+      )
+    case "retrying":
+      return (
+        <>
+          <StatusDot pulsing className="bg-amber-500" />
+          Retry Grist connection in {secondsLeft}s
+        </>
+      )
+    case "connected":
+      return (
+        <>
+          <StatusDot pulsing={false} className="bg-emerald-500" />
+          Grist connected
+        </>
+      )
+    case "unavailable":
+      return (
+        <>
+          <StatusDot pulsing={false} className="bg-destructive" />
+          Grist unavailable
+        </>
+      )
+  }
+}
+
+/**
+ * Small pill showing live Grist handshake status. Mounts its own
+ * `<GristHandshakeProvider>` alongside `<GristWidgetProvider>` -- documented
+ * (grist-widget-sdk/advanced) as safe to coexist, since both share the
+ * page's `ensureGristReady()` singleton. This chip is purely observational:
+ * it never drives the real widget's connection, just reflects it.
+ */
+export function GristStatusChip() {
+  return (
+    <GristHandshakeProvider>
+      <div className="pointer-events-none fixed top-2 right-2 z-50 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">
+        <ChipContents />
+      </div>
+    </GristHandshakeProvider>
+  )
+}

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

@@ -1,54 +1,53 @@
-import { useEffect, useState } from "react"
+import { useState } from "react"
 
 import { Button } from "@/components/ui/button"
+import { DEV_URL, 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
 // own bare /template/, or a local `pnpm dev` server. Individual channel
 // builds (/latest/, /dev/, /v<version>/) render `ChannelNotice` instead when
-// not embedded in Grist, with a link back here. Same component for this
-// repo's own showcase as for a real scaffolded widget that happens to have
-// something deployed at its own bare root; the only per-deploy difference is
-// which /v<version>/ dirs actually exist upstream, which is why the version
-// list is fetched from a fixed absolute URL rather than a path relative to
-// wherever this happens to be deployed.
-const VERSIONS_URL =
-  "https://arthurblanchon.github.io/grist-widget-sdk/template/versions.json"
-const DEV_URL = "https://arthurblanchon.github.io/grist-widget-sdk/template/dev/"
+// not embedded in Grist, with a link back here. Its hero introduces the
+// template project itself -- deliberately different from ChannelNotice's
+// hero, which is about the specific build you're looking at. Same component
+// for this repo's own showcase as for a real scaffolded widget that happens
+// to have something deployed at its own bare root; the only per-deploy
+// difference is which /v<version>/ dirs actually exist upstream.
 
-type ReleasedVersion = {
-  version: string
-  publishedAt: string
-}
-
-function useVersions() {
-  const [versions, setVersions] = useState<ReleasedVersion[] | null>(null)
-  const [error, setError] = useState(false)
+// A ready-to-paste instruction for an AI coding agent, not a human. Written
+// to work first-shot: it explains *why* to scaffold into a subdirectory
+// (create-grist-widget's CLI refuses a non-empty target -- and a repo
+// Claude Code is already connected to always has a .git folder) rather than
+// just saying "scaffold and push", which left room for the agent to try
+// (and fail) `npm create grist-widget .` in place.
+const CLAUDE_CODE_PROMPT = `Scaffold a new Grist custom widget here using \`npm create grist-widget\` (https://www.npmjs.com/package/create-grist-widget). This repo is an empty git clone already connected to GitHub, so scaffold into a new subdirectory first -- the CLI refuses a non-empty target directory, and this one already has a .git folder. Then push the scaffold's \`main\` and \`dev\` branches to this repository's own \`origin\` remote, so the bundled GitHub Pages deploy workflow runs. Report back the /latest/ and /v<version>/ GitHub Pages URLs once it's live.`
 
-  useEffect(() => {
-    let cancelled = false
-    fetch(VERSIONS_URL, { cache: "no-store" })
-      .then((res) => (res.ok ? res.json() : Promise.reject(res)))
-      .then((data: ReleasedVersion[]) => {
-        if (!cancelled) setVersions(data)
-      })
-      .catch(() => {
-        if (!cancelled) setError(true)
-      })
-    return () => {
-      cancelled = true
-    }
-  }, [])
+function CopyableBlock({ text }: { text: string }) {
+  const [copied, setCopied] = useState(false)
 
-  return { versions, error }
-}
+  function copy() {
+    navigator.clipboard.writeText(text).then(() => {
+      setCopied(true)
+      setTimeout(() => setCopied(false), 1500)
+    })
+  }
 
-function formatDate(iso: string) {
-  return new Date(iso).toLocaleDateString(undefined, {
-    year: "numeric",
-    month: "short",
-    day: "numeric",
-  })
+  return (
+    <div className="relative">
+      <pre className="overflow-x-auto rounded-lg bg-muted p-4 pr-16 text-xs whitespace-pre-wrap">
+        <code>{text}</code>
+      </pre>
+      <Button
+        type="button"
+        variant="secondary"
+        size="sm"
+        className="absolute top-2 right-2"
+        onClick={copy}
+      >
+        {copied ? "Copied" : "Copy"}
+      </Button>
+    </div>
+  )
 }
 
 export function TemplateLanding() {
@@ -61,12 +60,12 @@ export function TemplateLanding() {
           grist-widget-template
         </p>
         <h1 className="font-heading text-3xl font-semibold tracking-tight">
-          Grist isn't loaded here
+          Build your own Grist custom widget
         </h1>
         <p className="mx-auto mt-3 max-w-md text-sm text-muted-foreground">
-          This page only renders inside a Grist custom widget iframe. Paste
-          its URL into Grist's custom widget field, or read on to scaffold
-          your own copy.
+          A React + TypeScript + Tailwind starting point for{" "}
+          <code className="text-foreground">grist-widget-sdk</code>. Scaffold
+          your own copy, or browse what's already been released below.
         </p>
       </header>
 
@@ -74,12 +73,23 @@ export function TemplateLanding() {
         <h2 className="mb-3 font-heading text-base font-semibold">
           Using Claude Code?
         </h2>
-        <ol className="mb-4 list-inside list-decimal space-y-2 text-sm text-muted-foreground">
-          <li>Create a new, empty GitHub repo for the widget.</li>
+        <ol className="list-inside list-decimal space-y-3 text-sm text-muted-foreground">
+          <li>
+            Create a new, empty GitHub repo for the widget.
+            <div className="mt-2 ml-5">
+              <Button asChild>
+                <a href="https://github.com/new" target="_blank" rel="noreferrer">
+                  Create a new repository
+                </a>
+              </Button>
+            </div>
+          </li>
           <li>
             Install the{" "}
             <a
               href="https://github.com/apps/claude"
+              target="_blank"
+              rel="noreferrer"
               className="underline underline-offset-4 hover:text-foreground"
             >
               Claude GitHub App
@@ -87,11 +97,20 @@ export function TemplateLanding() {
             on that repo.
           </li>
           <li>
-            Start a Claude Code session connected to it and ask it to
-            scaffold and push.
+            Start a Claude Code session connected to it and paste this
+            prompt:
+            <div className="mt-2 ml-5">
+              <CopyableBlock text={CLAUDE_CODE_PROMPT} />
+            </div>
           </li>
         </ol>
-        <pre className="mb-4 overflow-x-auto rounded-lg bg-muted p-4 text-xs">
+      </div>
+
+      <details className="mb-10 rounded-lg border p-4 text-sm text-muted-foreground">
+        <summary className="cursor-pointer font-medium text-foreground">
+          Prefer to run it yourself?
+        </summary>
+        <pre className="mt-3 overflow-x-auto rounded-lg bg-muted p-4 text-xs">
           <code>{`npm create grist-widget my-widget
 cd my-widget
 
@@ -99,12 +118,7 @@ git remote add origin https://github.com/<owner>/<repo>.git
 git push -u origin main
 git push origin dev`}</code>
         </pre>
-        <Button asChild>
-          <a href="https://github.com/new" target="_blank" rel="noreferrer">
-            Create a new repository
-          </a>
-        </Button>
-      </div>
+      </details>
 
       <section>
         <div className="mb-3 flex items-center justify-between">
@@ -147,7 +161,7 @@ git push origin dev`}</code>
                   </span>
                 </div>
                 <a
-                  href={`https://arthurblanchon.github.io/grist-widget-sdk/template/v${v.version}/`}
+                  href={versionUrl(v.version)}
                   className="text-sm underline underline-offset-4 hover:text-foreground"
                 >
                   Preview

package/template/src/lib/grist-handshake-status.ts

@@ -0,0 +1,26 @@
+import type { GristLifecycle } from "grist-widget-sdk/advanced"
+
+// Projects the SDK's full GristLifecycle (advanced API, grist-widget-sdk/advanced)
+// down to the handful of states a small status chip needs to show.
+export type HandshakeDisplayStatus =
+  | { kind: "connecting" }
+  | { kind: "retrying"; attempts: number }
+  | { kind: "connected" }
+  | { kind: "unavailable" }
+
+export function deriveDisplayStatus(lifecycle: GristLifecycle): HandshakeDisplayStatus {
+  switch (lifecycle.phase) {
+    case "idle":
+      return { kind: "connecting" }
+    case "detecting":
+      return lifecycle.attempts > 0
+        ? { kind: "retrying", attempts: lifecycle.attempts }
+        : { kind: "connecting" }
+    case "negotiating":
+      return { kind: "connecting" }
+    case "online":
+      return { kind: "connected" }
+    case "terminated":
+      return { kind: "unavailable" }
+  }
+}

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

@@ -0,0 +1,49 @@
+import { useEffect, useState } from "react"
+
+// 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/"
+
+export type ReleasedVersion = {
+  version: string
+  publishedAt: string
+}
+
+export function versionUrl(version: string): string {
+  return `https://arthurblanchon.github.io/grist-widget-sdk/template/v${version}/`
+}
+
+export function useVersions() {
+  const [versions, setVersions] = useState<ReleasedVersion[] | null>(null)
+  const [error, setError] = useState(false)
+
+  useEffect(() => {
+    let cancelled = false
+    fetch(VERSIONS_URL, { cache: "no-store" })
+      .then((res) => (res.ok ? res.json() : Promise.reject(res)))
+      .then((data: ReleasedVersion[]) => {
+        if (!cancelled) setVersions(data)
+      })
+      .catch(() => {
+        if (!cancelled) setError(true)
+      })
+    return () => {
+      cancelled = true
+    }
+  }, [])
+
+  return { versions, error }
+}
+
+export function formatDate(iso: string) {
+  return new Date(iso).toLocaleDateString(undefined, {
+    year: "numeric",
+    month: "short",
+    day: "numeric",
+  })
+}

package/template/src/main.tsx

@@ -4,6 +4,7 @@ import { GristBoundary, GristWidgetProvider } from "grist-widget-sdk"
 
 import { ChannelNotice } from "@/components/channel-notice"
 import { GristSdkAlerts } from "@/components/grist-sdk-alerts"
+import { GristStatusChip } from "@/components/grist-status-chip"
 import { TemplateLanding } from "@/components/template-landing"
 import { ThemeProvider } from "@/components/theme-provider.tsx"
 import { parseShowcasePath } from "@/lib/showcase-routing"
@@ -34,17 +35,20 @@ createRoot(document.getElementById("root")!).render(
           <TemplateLanding />
         </div>
       ) : isEmbedded ? (
-        <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>
+        <>
+          <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>
+        </>
       ) : (
         <div className="min-h-full w-full bg-background text-foreground">
           <ChannelNotice channel={channel} hubPath={hubPath} />