create-grist-widget 0.2.10 → 0.2.12

package/package.json

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

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

@@ -1,7 +1,7 @@
 import { useEffect, useState } from "react"
 import { GristHandshakeProvider, useGristHandshakeContext } from "grist-widget-sdk/advanced"
 
-import { deriveDisplayStatus } from "@/lib/grist-handshake-status"
+import { deriveDisplayStatus, type HandshakeDisplayStatus } from "@/lib/grist-handshake-status"
 import { cn } from "@/lib/utils"
 
 // Fixed, approximate countdown shown while retrying -- not a mirror of the
@@ -49,12 +49,8 @@ function StatusDot({ pulsing, className }: { pulsing: boolean; className: string
   )
 }
 
-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")
-
+/** Pure render of a display status -- shared by the real (context-driven) and demo (cycling) chips. */
+function ChipVisual({ display, secondsLeft }: { display: HandshakeDisplayStatus; secondsLeft: number }) {
   switch (display.kind) {
     case "connecting":
       return (
@@ -87,19 +83,89 @@ function ChipContents() {
   }
 }
 
+function RealChipContents() {
+  const { snapshot } = useGristHandshakeContext()
+  const display = deriveDisplayStatus(snapshot.lifecycle)
+  const retryAttempts = display.kind === "retrying" ? display.attempts : 0
+  const secondsLeft = useRetryCountdown(retryAttempts, display.kind === "retrying")
+  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 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.
+ * 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.
  */
-export function GristStatusChip() {
+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
+
   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>
+      <div className="pointer-events-none fixed top-2 right-2 z-50">{pill}</div>
     </GristHandshakeProvider>
   )
 }

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

@@ -1,4 +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"
 
 // The showcase "hub" page: rendered whenever this deploy's URL has no
@@ -11,12 +15,64 @@ import { DEV_URL, formatDate, useVersions, versionUrl } from "@/lib/showcase-ver
 // 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.
+
+// 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.`
+
+function CopyableBlock({ text }: { text: string }) {
+  const [copied, setCopied] = useState(false)
+
+  function copy() {
+    navigator.clipboard.writeText(text).then(() => {
+      setCopied(true)
+      setTimeout(() => setCopied(false), 1500)
+    })
+  }
+
+  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>
+  )
+}
+
+function CreateRepoButton() {
+  return (
+    <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>
+  )
+}
+
 export function TemplateLanding() {
   const { versions, error } = useVersions()
 
   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>
@@ -32,38 +88,85 @@ export function TemplateLanding() {
 
       <div className="mb-10 rounded-lg border p-4">
         <h2 className="mb-3 font-heading text-base font-semibold">
-          Using Claude Code?
+          Get started
         </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>
-          <li>
-            Install the{" "}
-            <a
-              href="https://github.com/apps/claude"
-              className="underline underline-offset-4 hover:text-foreground"
-            >
-              Claude GitHub App
-            </a>{" "}
-            on that repo.
-          </li>
-          <li>
-            Start a Claude Code session connected to it and ask it to
-            scaffold and push.
-          </li>
-        </ol>
-        <pre className="mb-4 overflow-x-auto rounded-lg bg-muted p-4 text-xs">
-          <code>{`npm create grist-widget my-widget
-cd my-widget
+        <Tabs defaultValue="claude-code">
+          <TabsList className="mb-4">
+            <TabsTrigger value="claude-code">Using Claude Code?</TabsTrigger>
+            <TabsTrigger value="manual">Manual setup</TabsTrigger>
+          </TabsList>
+
+          <TabsContent value="claude-code">
+            <ol className="list-inside list-decimal space-y-3 text-sm text-muted-foreground">
+              <li>
+                Create a new, empty GitHub repo for the widget.
+                <CreateRepoButton />
+              </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
+                </a>{" "}
+                on that repo.
+              </li>
+              <li>
+                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>
+          </TabsContent>
 
-git remote add origin https://github.com/<owner>/<repo>.git
+          <TabsContent value="manual">
+            <ol className="list-inside list-decimal space-y-3 text-sm text-muted-foreground">
+              <li>
+                Scaffold it and try it locally:
+                <div className="mt-2 ml-5">
+                  <pre className="overflow-x-auto rounded-lg bg-muted p-4 text-xs">
+                    <code>{`npm create grist-widget my-widget
+cd my-widget
+pnpm install
+pnpm dev`}</code>
+                  </pre>
+                </div>
+              </li>
+              <li>
+                Create a new, empty GitHub repo for the widget.
+                <CreateRepoButton />
+              </li>
+              <li>
+                Push it:
+                <div className="mt-2 ml-5">
+                  <pre className="overflow-x-auto rounded-lg bg-muted p-4 text-xs">
+                    <code>{`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>
+                  </pre>
+                </div>
+              </li>
+              <li>
+                Once that first push's workflow run completes (it creates a{" "}
+                <code className="text-foreground">gh-pages</code> branch),
+                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">
+                  If that first run fails with a permissions error pushing to{" "}
+                  <code className="text-foreground">gh-pages</code>, Settings
+                  → Actions → General → Workflow permissions → "Read and
+                  write permissions" fixes it — most repos don't need this.
+                </p>
+              </li>
+            </ol>
+          </TabsContent>
+        </Tabs>
       </div>
 
       <section>

package/template/src/components/ui/tabs.tsx

@@ -0,0 +1,88 @@
+import * as React from "react"
+import { cva, type VariantProps } from "class-variance-authority"
+import { Tabs as TabsPrimitive } from "radix-ui"
+
+import { cn } from "@/lib/utils"
+
+function Tabs({
+  className,
+  orientation = "horizontal",
+  ...props
+}: React.ComponentProps<typeof TabsPrimitive.Root>) {
+  return (
+    <TabsPrimitive.Root
+      data-slot="tabs"
+      data-orientation={orientation}
+      className={cn(
+        "group/tabs flex gap-2 data-horizontal:flex-col",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+const tabsListVariants = cva(
+  "group/tabs-list inline-flex w-fit items-center justify-center rounded-lg p-[3px] text-muted-foreground group-data-horizontal/tabs:h-8 group-data-vertical/tabs:h-fit group-data-vertical/tabs:flex-col data-[variant=line]:rounded-none",
+  {
+    variants: {
+      variant: {
+        default: "bg-muted",
+        line: "gap-1 bg-transparent",
+      },
+    },
+    defaultVariants: {
+      variant: "default",
+    },
+  }
+)
+
+function TabsList({
+  className,
+  variant = "default",
+  ...props
+}: React.ComponentProps<typeof TabsPrimitive.List> &
+  VariantProps<typeof tabsListVariants>) {
+  return (
+    <TabsPrimitive.List
+      data-slot="tabs-list"
+      data-variant={variant}
+      className={cn(tabsListVariants({ variant }), className)}
+      {...props}
+    />
+  )
+}
+
+function TabsTrigger({
+  className,
+  ...props
+}: React.ComponentProps<typeof TabsPrimitive.Trigger>) {
+  return (
+    <TabsPrimitive.Trigger
+      data-slot="tabs-trigger"
+      className={cn(
+        "relative inline-flex h-[calc(100%-1px)] flex-1 items-center justify-center gap-1.5 rounded-md border border-transparent px-1.5 py-0.5 text-sm font-medium whitespace-nowrap text-foreground/60 transition-all group-data-vertical/tabs:w-full group-data-vertical/tabs:justify-start hover:text-foreground focus-visible:border-ring focus-visible:ring-[3px] focus-visible:ring-ring/50 focus-visible:outline-1 focus-visible:outline-ring disabled:pointer-events-none disabled:opacity-50 has-data-[icon=inline-end]:pr-1 has-data-[icon=inline-start]:pl-1 dark:text-muted-foreground dark:hover:text-foreground group-data-[variant=default]/tabs-list:data-active:shadow-sm group-data-[variant=line]/tabs-list:data-active:shadow-none [&_svg]:pointer-events-none [&_svg]:shrink-0 [&_svg:not([class*='size-'])]:size-4",
+        "group-data-[variant=line]/tabs-list:bg-transparent group-data-[variant=line]/tabs-list:data-active:bg-transparent dark:group-data-[variant=line]/tabs-list:data-active:border-transparent dark:group-data-[variant=line]/tabs-list:data-active:bg-transparent",
+        "data-active:bg-background data-active:text-foreground dark:data-active:border-input dark:data-active:bg-input/30 dark:data-active:text-foreground",
+        "after:absolute after:bg-foreground after:opacity-0 after:transition-opacity group-data-horizontal/tabs:after:inset-x-0 group-data-horizontal/tabs:after:bottom-[-5px] group-data-horizontal/tabs:after:h-0.5 group-data-vertical/tabs:after:inset-y-0 group-data-vertical/tabs:after:-right-1 group-data-vertical/tabs:after:w-0.5 group-data-[variant=line]/tabs-list:data-active:after:opacity-100",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function TabsContent({
+  className,
+  ...props
+}: React.ComponentProps<typeof TabsPrimitive.Content>) {
+  return (
+    <TabsPrimitive.Content
+      data-slot="tabs-content"
+      className={cn("flex-1 text-sm outline-none", className)}
+      {...props}
+    />
+  )
+}
+
+export { Tabs, TabsList, TabsTrigger, TabsContent, tabsListVariants }