create-grist-widget 0.2.11 → 0.2.13

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.11",
+  "version": "0.2.13",
   "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: |

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

@@ -133,12 +133,22 @@ 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)
   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 }
 }
 
 /**

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. */
+function ChipVisual({ display, secondsLeft }: { display: HandshakeDisplayStatus; secondsLeft: number }) {
   switch (display.kind) {
     case "connecting":
       return (
@@ -87,18 +83,34 @@ 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} />
+}
+
 /**
- * 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 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() {
+export function GristStatusChip({ className }: { className?: string }) {
   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 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,6 +1,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"
 
 // The showcase "hub" page: rendered whenever this deploy's URL has no
@@ -50,6 +51,18 @@ function CopyableBlock({ text }: { text: string }) {
   )
 }
 
+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()
 
@@ -60,7 +73,7 @@ export function TemplateLanding() {
           grist-widget-template
         </p>
         <h1 className="font-heading text-3xl font-semibold tracking-tight">
-          Build your own Grist custom widget
+          Build a Grist custom widget in minutes
         </h1>
         <p className="mx-auto mt-3 max-w-md text-sm text-muted-foreground">
           A React + TypeScript + Tailwind starting point for{" "}
@@ -71,54 +84,93 @@ 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="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
-            </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>
-      </div>
+        <Tabs defaultValue="claude-code">
+          <TabsList className="mb-4">
+            <TabsTrigger value="claude-code">Using Claude Code?</TabsTrigger>
+            <TabsTrigger value="manual">Manual setup</TabsTrigger>
+          </TabsList>
 
-      <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
+          <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>
-      </details>
+                  </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">
+                  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
+                  → Actions → General → Workflow permissions → "Read and
+                  write permissions" fixes it — most repos don't need this.
+                </p>
+              </li>
+            </ol>
+          </TabsContent>
+        </Tabs>
+      </div>
 
       <section>
         <div className="mb-3 flex items-center justify-between">

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 }