create-grist-widget 0.2.9 → 0.2.10

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "create-grist-widget",
-  "version": "0.2.9",
+  "version": "0.2.10",
   "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,56 +1,16 @@
-import { useEffect, 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/"
-
-type ReleasedVersion = {
-  version: string
-  publishedAt: string
-}
-
-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 }
-}
-
-function formatDate(iso: string) {
-  return new Date(iso).toLocaleDateString(undefined, {
-    year: "numeric",
-    month: "short",
-    day: "numeric",
-  })
-}
-
+// 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.
 export function TemplateLanding() {
   const { versions, error } = useVersions()
 
@@ -61,12 +21,12 @@ export function TemplateLanding() {
           grist-widget-template
         </p>
         <h1 className="font-heading text-3xl font-semibold tracking-tight">
-          Grist isn't loaded here
+          Build a Grist custom widget in minutes
         </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>
 
@@ -147,7 +107,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} />