create-grist-widget 0.2.8 → 0.2.9

package/package.json

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

package/template/README.md

@@ -4,6 +4,8 @@ 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.
+
 `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.
 
 - **ESLint** blocks direct `grist` global usage in `src/` — use the SDK only.

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

@@ -0,0 +1,75 @@
+import { useState } from "react"
+
+import { Button } from "@/components/ui/button"
+import {
+  Card,
+  CardContent,
+  CardDescription,
+  CardHeader,
+  CardTitle,
+} from "@/components/ui/card"
+import { Input } from "@/components/ui/input"
+import { channelLabel, type Channel } from "@/lib/showcase-routing"
+
+// 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.
+export function ChannelNotice({
+  channel,
+  hubPath,
+}: {
+  channel: Channel
+  hubPath: string
+}) {
+  const [copied, setCopied] = useState(false)
+  const url = window.location.href
+
+  function copyUrl() {
+    navigator.clipboard.writeText(url).then(() => {
+      setCopied(true)
+      setTimeout(() => setCopied(false), 1500)
+    })
+  }
+
+  return (
+    <div className="mx-auto flex min-h-full max-w-md flex-col justify-center px-6 py-16">
+      <p className="mb-2 text-center text-sm font-medium text-muted-foreground">
+        grist-widget-template · {channelLabel(channel)}
+      </p>
+      <h1 className="text-center font-heading text-2xl font-semibold tracking-tight">
+        Grist isn't loaded here
+      </h1>
+      <p className="mx-auto mt-3 mb-8 max-w-sm text-center text-sm text-muted-foreground">
+        You're viewing the <span className="font-mono">{channelLabel(channel)}</span>{" "}
+        build directly, outside of Grist.
+      </p>
+
+      <Card className="mb-4">
+        <CardHeader>
+          <CardTitle>Use this as a Grist custom widget</CardTitle>
+          <CardDescription>
+            Paste this URL into Grist's custom widget URL field.
+          </CardDescription>
+        </CardHeader>
+        <CardContent>
+          <div className="flex gap-2">
+            <Input readOnly value={url} onFocus={(e) => e.target.select()} />
+            <Button type="button" onClick={copyUrl}>
+              {copied ? "Copied" : "Copy"}
+            </Button>
+          </div>
+        </CardContent>
+      </Card>
+
+      <a
+        href={hubPath}
+        className="text-center text-sm text-muted-foreground underline underline-offset-4 hover:text-foreground"
+      >
+        ← Back to the template home
+      </a>
+    </div>
+  )
+}

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

@@ -2,16 +2,19 @@ import { useEffect, useState } from "react"
 
 import { Button } from "@/components/ui/button"
 
-// Shown instead of the widget tree when this page is opened directly in a
-// browser tab (not embedded in a Grist iframe) -- i.e. exactly the situation
-// anyone visiting a deployed /latest/, /v<version>/, or /dev/ URL directly is
-// in, whether that's this monorepo's own showcase deploy or a real scaffolded
-// widget someone hasn't customized yet. Same component either way; 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.
+// 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
@@ -104,9 +107,17 @@ git push origin dev`}</code>
       </div>
 
       <section>
-        <h2 className="mb-3 font-heading text-base font-semibold">
-          Released template versions
-        </h2>
+        <div className="mb-3 flex items-center justify-between">
+          <h2 className="font-heading text-base font-semibold">
+            Released template versions
+          </h2>
+          <a
+            href={DEV_URL}
+            className="text-sm text-muted-foreground underline underline-offset-4 hover:text-foreground"
+          >
+            Live dev preview →
+          </a>
+        </div>
         {error ? (
           <p className="text-sm text-muted-foreground">
             Couldn't load the version list.

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

@@ -0,0 +1,103 @@
+import * as React from "react"
+
+import { cn } from "@/lib/utils"
+
+function Card({
+  className,
+  size = "default",
+  ...props
+}: React.ComponentProps<"div"> & { size?: "default" | "sm" }) {
+  return (
+    <div
+      data-slot="card"
+      data-size={size}
+      className={cn(
+        "group/card flex flex-col gap-4 overflow-hidden rounded-xl bg-card py-4 text-sm text-card-foreground ring-1 ring-foreground/10 has-data-[slot=card-footer]:pb-0 has-[>img:first-child]:pt-0 data-[size=sm]:gap-3 data-[size=sm]:py-3 data-[size=sm]:has-data-[slot=card-footer]:pb-0 *:[img:first-child]:rounded-t-xl *:[img:last-child]:rounded-b-xl",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function CardHeader({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="card-header"
+      className={cn(
+        "group/card-header @container/card-header grid auto-rows-min items-start gap-1 rounded-t-xl px-4 group-data-[size=sm]/card:px-3 has-data-[slot=card-action]:grid-cols-[1fr_auto] has-data-[slot=card-description]:grid-rows-[auto_auto] [.border-b]:pb-4 group-data-[size=sm]/card:[.border-b]:pb-3",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function CardTitle({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="card-title"
+      className={cn(
+        "font-heading text-base leading-snug font-medium group-data-[size=sm]/card:text-sm",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function CardDescription({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="card-description"
+      className={cn("text-sm text-muted-foreground", className)}
+      {...props}
+    />
+  )
+}
+
+function CardAction({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="card-action"
+      className={cn(
+        "col-start-2 row-span-2 row-start-1 self-start justify-self-end",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+function CardContent({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="card-content"
+      className={cn("px-4 group-data-[size=sm]/card:px-3", className)}
+      {...props}
+    />
+  )
+}
+
+function CardFooter({ className, ...props }: React.ComponentProps<"div">) {
+  return (
+    <div
+      data-slot="card-footer"
+      className={cn(
+        "flex items-center rounded-b-xl border-t bg-muted/50 p-4 group-data-[size=sm]/card:p-3",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+export {
+  Card,
+  CardHeader,
+  CardFooter,
+  CardTitle,
+  CardAction,
+  CardDescription,
+  CardContent,
+}

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

@@ -0,0 +1,19 @@
+import * as React from "react"
+
+import { cn } from "@/lib/utils"
+
+function Input({ className, type, ...props }: React.ComponentProps<"input">) {
+  return (
+    <input
+      type={type}
+      data-slot="input"
+      className={cn(
+        "h-8 w-full min-w-0 rounded-lg border border-input bg-transparent px-2.5 py-1 text-base transition-colors outline-none file:inline-flex file:h-6 file:border-0 file:bg-transparent file:text-sm file:font-medium file:text-foreground placeholder:text-muted-foreground focus-visible:border-ring focus-visible:ring-3 focus-visible:ring-ring/50 disabled:pointer-events-none disabled:cursor-not-allowed disabled:bg-input/50 disabled:opacity-50 aria-invalid:border-destructive aria-invalid:ring-3 aria-invalid:ring-destructive/20 md:text-sm dark:bg-input/30 dark:disabled:bg-input/80 dark:aria-invalid:border-destructive/50 dark:aria-invalid:ring-destructive/40",
+        className
+      )}
+      {...props}
+    />
+  )
+}
+
+export { Input }

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

@@ -0,0 +1,47 @@
+// Parses the deployed URL shape every channel of this template (or a real
+// scaffolded widget) uses -- /latest/, /dev/, /v<version>/ -- so main.tsx can
+// tell a "hub" page (no recognized channel suffix, e.g. this repo's own
+// /template/) from a "channel" page (a specific release/dev build) using
+// nothing but window.location.pathname. No router needed for two states.
+export type Channel =
+  | { kind: "latest" }
+  | { kind: "dev" }
+  | { kind: "version"; version: string }
+
+export function channelLabel(channel: Channel): string {
+  switch (channel.kind) {
+    case "latest":
+      return "latest"
+    case "dev":
+      return "dev"
+    case "version":
+      return `v${channel.version}`
+  }
+}
+
+/**
+ * `hubPath` is the current path with the trailing channel segment stripped,
+ * e.g. "/grist-widget-sdk/template/latest/" -> "/grist-widget-sdk/template/".
+ * `channel` is null when the path itself already looks like a hub (no
+ * recognized suffix) -- e.g. this repo's own bare /template/, or a local
+ * `pnpm dev` server at "/".
+ */
+export function parseShowcasePath(pathname: string): {
+  channel: Channel | null
+  hubPath: string
+} {
+  const trimmed = pathname.replace(/\/+$/, "")
+  const segments = trimmed.split("/")
+  const last = segments[segments.length - 1] ?? ""
+
+  let channel: Channel | null = null
+  if (last === "latest") channel = { kind: "latest" }
+  else if (last === "dev") channel = { kind: "dev" }
+  else {
+    const match = /^v(\d+\.\d+\.\d+(?:-[\w.]+)?)$/.exec(last)
+    if (match) channel = { kind: "version", version: match[1] }
+  }
+
+  const hubPath = channel ? segments.slice(0, -1).join("/") + "/" : pathname
+  return { channel, hubPath }
+}

package/template/src/main.tsx

@@ -2,25 +2,38 @@ import { StrictMode } from "react"
 import { createRoot } from "react-dom/client"
 import { GristBoundary, GristWidgetProvider } from "grist-widget-sdk"
 
+import { ChannelNotice } from "@/components/channel-notice"
 import { GristSdkAlerts } from "@/components/grist-sdk-alerts"
 import { TemplateLanding } from "@/components/template-landing"
 import { ThemeProvider } from "@/components/theme-provider.tsx"
+import { parseShowcasePath } from "@/lib/showcase-routing"
 import "./index.css"
 import App, { GRIST_OPTIONS } from "./App.tsx"
 
 // A Grist custom widget only ever runs embedded in Grist's own iframe.
 // Opened directly in a browser tab (window.self === window.top), there's no
-// Grist to connect to -- show the template's own landing content instead of
-// mounting the widget tree at all. Same for a real scaffolded widget nobody
-// has customized yet as for this repo's own showcase deploy of the
-// unmodified template; nothing here is monorepo-specific except the fixed
-// URL TemplateLanding fetches its version list from.
+// Grist to connect to. Two different "not embedded" experiences, told apart
+// purely by URL shape (see src/lib/showcase-routing.ts):
+//   - no recognized channel suffix (this repo's own bare /template/, or a
+//     local `pnpm dev` server) -> the rich showcase hub (TemplateLanding):
+//     onboarding + a link to every released version and the dev channel.
+//   - a recognized channel suffix (/latest/, /dev/, /v<version>/) -> a
+//     minimal notice: which build this is, a link back to the hub, and a
+//     copy-this-URL helper for pasting into Grist's custom widget field.
+// The hub always wins over embedding -- /template/ is never meant to
+// function as an actual widget, even if someone pastes it into Grist by
+// mistake.
 const isEmbedded = window.self !== window.top
+const { channel, hubPath } = parseShowcasePath(window.location.pathname)
 
 createRoot(document.getElementById("root")!).render(
   <StrictMode>
     <ThemeProvider>
-      {isEmbedded ? (
+      {!channel ? (
+        <div className="min-h-full w-full bg-background text-foreground">
+          <TemplateLanding />
+        </div>
+      ) : isEmbedded ? (
         <GristWidgetProvider options={GRIST_OPTIONS}>
           <GristBoundary
             gate={GRIST_OPTIONS.columns?.length ? "canRender" : "ready"}
@@ -34,7 +47,7 @@ createRoot(document.getElementById("root")!).render(
         </GristWidgetProvider>
       ) : (
         <div className="min-h-full w-full bg-background text-foreground">
-          <TemplateLanding />
+          <ChannelNotice channel={channel} hubPath={hubPath} />
         </div>
       )}
     </ThemeProvider>