create-grist-widget 0.3.25 → 0.3.27

package/template/src/App.test.tsx

@@ -1,13 +1,12 @@
 /**
- * Mirrors `main.tsx`'s real wiring (`GristWidgetProvider` -> `GristBoundary`
- * -> the widget) without importing `main.tsx` itself, so this test exercises
- * the same gate logic the embedded widget actually runs under. See
- * `packages/core/tests/sdk/template-app.test.tsx` in the SDK repo for the
- * same pattern applied to a bare shell.
+ * Renders the widget the way `main.tsx` mounts it inside Grist
+ * (`GristWidgetApp`: provider, boundary gated on the mapped columns, alerts),
+ * against an emulated Grist, so this test exercises what the embedded widget
+ * actually runs under.
  */
 import "@testing-library/jest-dom/vitest"
 import { afterEach, describe, expect, it } from "vitest"
-import { GristBoundary, GristWidgetProvider } from "grist-widget-sdk"
+import { GristWidgetApp } from "grist-widget-sdk/app"
 import {
   act,
   actionsOf,
@@ -28,13 +27,7 @@ import App, { GRIST_OPTIONS } from "./App"
 afterEach(() => cleanup())
 
 function Wrapped() {
-  return (
-    <GristWidgetProvider options={GRIST_OPTIONS}>
-      <GristBoundary gate={GRIST_OPTIONS.columns?.length ? "canRender" : "ready"}>
-        <App />
-      </GristBoundary>
-    </GristWidgetProvider>
-  )
+  return <GristWidgetApp App={App} options={GRIST_OPTIONS} />
 }
 
 describe("App", () => {

package/template/src/components/theme-provider.tsx

@@ -1,229 +1,5 @@
-import * as React from "react"
-
-type Theme = "dark" | "light" | "system"
-type ResolvedTheme = "dark" | "light"
-
-type ThemeProviderProps = {
-  children: React.ReactNode
-  defaultTheme?: Theme
-  storageKey?: string
-  disableTransitionOnChange?: boolean
-}
-
-type ThemeProviderState = {
-  theme: Theme
-  setTheme: (theme: Theme) => void
-}
-
-const COLOR_SCHEME_QUERY = "(prefers-color-scheme: dark)"
-const THEME_VALUES: Theme[] = ["dark", "light", "system"]
-
-const ThemeProviderContext = React.createContext<
-  ThemeProviderState | undefined
->(undefined)
-
-function isTheme(value: string | null): value is Theme {
-  if (value === null) {
-    return false
-  }
-
-  return THEME_VALUES.includes(value as Theme)
-}
-
-function getSystemTheme(): ResolvedTheme {
-  if (window.matchMedia(COLOR_SCHEME_QUERY).matches) {
-    return "dark"
-  }
-
-  return "light"
-}
-
-function disableTransitionsTemporarily() {
-  const style = document.createElement("style")
-  style.appendChild(
-    document.createTextNode(
-      "*,*::before,*::after{-webkit-transition:none!important;transition:none!important}"
-    )
-  )
-  document.head.appendChild(style)
-
-  return () => {
-    window.getComputedStyle(document.body)
-    requestAnimationFrame(() => {
-      requestAnimationFrame(() => {
-        style.remove()
-      })
-    })
-  }
-}
-
-function isEditableTarget(target: EventTarget | null) {
-  if (!(target instanceof HTMLElement)) {
-    return false
-  }
-
-  if (target.isContentEditable) {
-    return true
-  }
-
-  const editableParent = target.closest(
-    "input, textarea, select, [contenteditable='true']"
-  )
-  if (editableParent) {
-    return true
-  }
-
-  return false
-}
-
-export function ThemeProvider({
-  children,
-  defaultTheme = "system",
-  storageKey = "theme",
-  disableTransitionOnChange = true,
-  ...props
-}: ThemeProviderProps) {
-  const [theme, setThemeState] = React.useState<Theme>(() => {
-    const storedTheme = localStorage.getItem(storageKey)
-    if (isTheme(storedTheme)) {
-      return storedTheme
-    }
-
-    return defaultTheme
-  })
-
-  const setTheme = React.useCallback(
-    (nextTheme: Theme) => {
-      localStorage.setItem(storageKey, nextTheme)
-      setThemeState(nextTheme)
-    },
-    [storageKey]
-  )
-
-  const applyTheme = React.useCallback(
-    (nextTheme: Theme) => {
-      const root = document.documentElement
-      const resolvedTheme =
-        nextTheme === "system" ? getSystemTheme() : nextTheme
-      const restoreTransitions = disableTransitionOnChange
-        ? disableTransitionsTemporarily()
-        : null
-
-      root.classList.remove("light", "dark")
-      root.classList.add(resolvedTheme)
-
-      if (restoreTransitions) {
-        restoreTransitions()
-      }
-    },
-    [disableTransitionOnChange]
-  )
-
-  React.useEffect(() => {
-    applyTheme(theme)
-
-    if (theme !== "system") {
-      return undefined
-    }
-
-    const mediaQuery = window.matchMedia(COLOR_SCHEME_QUERY)
-    const handleChange = () => {
-      applyTheme("system")
-    }
-
-    mediaQuery.addEventListener("change", handleChange)
-
-    return () => {
-      mediaQuery.removeEventListener("change", handleChange)
-    }
-  }, [theme, applyTheme])
-
-  React.useEffect(() => {
-    const handleKeyDown = (event: KeyboardEvent) => {
-      if (event.repeat) {
-        return
-      }
-
-      if (event.metaKey || event.ctrlKey || event.altKey) {
-        return
-      }
-
-      if (isEditableTarget(event.target)) {
-        return
-      }
-
-      if (event.key.toLowerCase() !== "d") {
-        return
-      }
-
-      setThemeState((currentTheme) => {
-        const nextTheme =
-          currentTheme === "dark"
-            ? "light"
-            : currentTheme === "light"
-              ? "dark"
-              : getSystemTheme() === "dark"
-                ? "light"
-                : "dark"
-
-        localStorage.setItem(storageKey, nextTheme)
-        return nextTheme
-      })
-    }
-
-    window.addEventListener("keydown", handleKeyDown)
-
-    return () => {
-      window.removeEventListener("keydown", handleKeyDown)
-    }
-  }, [storageKey])
-
-  React.useEffect(() => {
-    const handleStorageChange = (event: StorageEvent) => {
-      if (event.storageArea !== localStorage) {
-        return
-      }
-
-      if (event.key !== storageKey) {
-        return
-      }
-
-      if (isTheme(event.newValue)) {
-        setThemeState(event.newValue)
-        return
-      }
-
-      setThemeState(defaultTheme)
-    }
-
-    window.addEventListener("storage", handleStorageChange)
-
-    return () => {
-      window.removeEventListener("storage", handleStorageChange)
-    }
-  }, [defaultTheme, storageKey])
-
-  const value = React.useMemo(
-    () => ({
-      theme,
-      setTheme,
-    }),
-    [theme, setTheme]
-  )
-
-  return (
-    <ThemeProviderContext.Provider {...props} value={value}>
-      {children}
-    </ThemeProviderContext.Provider>
-  )
-}
-
-export const useTheme = () => {
-  const context = React.useContext(ThemeProviderContext)
-
-  if (context === undefined) {
-    throw new Error("useTheme must be used within a ThemeProvider")
-  }
-
-  return context
-}
+// shadcn components (a toaster, a mode toggle) import the theme from here.
+// grist-widget-sdk/app owns it: inside Grist the widget follows Grist's
+// light/dark theme; on the dev server and the release page, the OS setting,
+// a saved choice and the `d` key.
+export { useTheme } from "grist-widget-sdk/app"

package/template/src/main.tsx

@@ -1,57 +1,11 @@
-import { StrictMode } from "react"
-import { createRoot } from "react-dom/client"
-import { GristBoundary, GristWidgetProvider } from "grist-widget-sdk"
+import { mountGristWidget } from "grist-widget-sdk/app"
 
-import { GristSdkAlerts } from "@/components/grist-sdk-alerts"
-import { LocalDevNotice } from "@/components/local-dev-notice"
-import { ReleaseInfo } from "@/components/release-info"
-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 -- two different non-embedded experiences, told apart
-// by import.meta.env.DEV (a real embed always wins over either, checked
-// first):
-//   - `pnpm dev` (DEV) -> LocalDevNotice: a bare shell pointing at the real
-//     verification loop (push to `dev`, open it in a real Grist doc) --
-//     deliberately not a live/seeded preview. An emulator can't guarantee
-//     parity with real Grist, so pretending otherwise here would teach the
-//     wrong lesson; `pnpm test` (renderWithGrist, headless) is the loop
-//     worth trusting locally. See AGENTS.md.
-//   - any built/deployed URL (root, /latest/, /dev/, /v<version>/, all
-//     carrying the same build per scripts/deploy.mjs) -> ReleaseInfo: which
-//     build this is, chips to jump to any other version/channel, and a
-//     copy-this-URL helper for pasting into Grist's custom widget field.
-const isEmbedded = window.self !== window.top
-const { channel } = parseShowcasePath(window.location.pathname)
-
-createRoot(document.getElementById("root")!).render(
-  <StrictMode>
-    <ThemeProvider>
-      {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>
-      ) : import.meta.env.DEV ? (
-        <div className="min-h-full w-full bg-background text-foreground">
-          <LocalDevNotice />
-        </div>
-      ) : (
-        <div className="min-h-full w-full bg-background text-foreground">
-          <ReleaseInfo channel={channel} />
-        </div>
-      )}
-    </ThemeProvider>
-  </StrictMode>
-)
+// Inside Grist: the widget, behind the SDK's connection screens and alerts,
+// in Grist's light/dark theme. Opened anywhere else (`pnpm dev`, a deployed
+// URL): a page saying where to see it, never a fake preview, since an
+// emulator can't stand in for real Grist (see AGENTS.md). `pnpm test` is the
+// local loop to trust.
+mountGristWidget({ App, options: GRIST_OPTIONS, dev: import.meta.env.DEV })

package/vendor/compose-example.mjs

@@ -98,7 +98,7 @@ export function createComposer({ templateDir, examplesDir, uiDir, manifestPath }
     // only remove files this function itself may have added, so a stale
     // sibling from a *different* previous example doesn't linger.
     for (const entry of readdirSync(srcDir, { withFileTypes: true })) {
-      if (entry.name === "App.tsx" || entry.name === "App.test.tsx") continue
+      if (entry.name === "App.tsx" || entry.name === "App.test.tsx" || entry.name === "App.smoke.test.tsx") continue
       if (["components", "lib", "assets", "index.css", "vite-env.d.ts", "main.tsx"].includes(entry.name)) {
         continue
       }
@@ -175,11 +175,14 @@ export function createComposer({ templateDir, examplesDir, uiDir, manifestPath }
    * `workspace:^` (meaningless outside the pnpm workspace) — a `file:`
    * reference to either `packages/core` (workspace source, already built), a
    * packed tarball, or (for the CLI's `create`) a real published semver range.
+   * `cliDependency` does the same for the template's `create-grist-widget`
+   * devDependency (its deploy bin); without one, the devDependency is dropped,
+   * since a composed example is only typechecked, built and tested here.
    *
    * For composing *many* examples against one shared `pnpm install`, use
    * {@link overlayExampleSrc} directly instead (see its own doc comment).
    */
-  function composeExample({ exampleId, destDir, sdkDependency }) {
+  function composeExample({ exampleId, destDir, sdkDependency, cliDependency }) {
     rmSync(destDir, { recursive: true, force: true })
     cpSync(templateDir, destDir, {
       recursive: true,
@@ -192,6 +195,8 @@ export function createComposer({ templateDir, examplesDir, uiDir, manifestPath }
     const pkg = JSON.parse(readFileSync(pkgPath, "utf8"))
     pkg.name = exampleId
     pkg.dependencies["grist-widget-sdk"] = sdkDependency
+    if (cliDependency) pkg.devDependencies["create-grist-widget"] = cliDependency
+    else delete pkg.devDependencies["create-grist-widget"]
     Object.assign(pkg.dependencies, EXTRA_DEPENDENCIES[exampleId] ?? {})
     writeFileSync(pkgPath, `${JSON.stringify(pkg, null, 2)}\n`)
 

package/template/src/components/grist-sdk-alerts.tsx

@@ -1,80 +0,0 @@
-import { useMemo, type ReactNode } from "react"
-import { AlertTriangle, Link2 } from "lucide-react"
-
-import {
-  useGristSdkAlertDescriptors,
-  useGristOptional,
-  type GetGristSdkAlertDescriptorsOptions,
-  type GristSdkAlertSeverity,
-  type UseGristResult,
-} from "grist-widget-sdk"
-
-import { Alert, AlertDescription, AlertTitle } from "@/components/ui/alert"
-import { cn } from "@/lib/utils"
-
-export type GristSdkAlertsProps = {
-  /** Defaults to the nearest `GristWidgetProvider`. */
-  widget?: UseGristResult
-  children: ReactNode
-  className?: string
-}
-
-const GRIST_ALERT_OPTIONS: GetGristSdkAlertDescriptorsOptions = {
-  sectionNotLinkedHint:
-    "In Grist, select this widget section on the page, then use Link to connect a table, card, or chart view as the selector.",
-}
-
-function alertSeverityClass(severity: GristSdkAlertSeverity): string | undefined {
-  switch (severity) {
-    case "warning":
-      return "border-amber-500/40 bg-amber-500/10 text-amber-950 dark:border-amber-500/30 dark:bg-amber-500/10 dark:text-amber-100"
-    case "info":
-      return "border-muted-foreground/30 bg-muted/50"
-    default:
-      return undefined
-  }
-}
-
-/**
- * Maps {@link getGristSdkAlertDescriptors} from `grist-widget-sdk` to
- * shadcn {@link Alert} (styling follows this app’s `components.json`).
- */
-export function GristSdkAlerts({ widget, children, className }: GristSdkAlertsProps) {
-  const fromContext = useGristOptional()
-  const w = widget ?? fromContext
-
-  if (!w) {
-    throw new Error(
-      "GristSdkAlerts requires a `widget` prop or <GristWidgetProvider>"
-    )
-  }
-
-  const alertOptions = useMemo(() => GRIST_ALERT_OPTIONS, [])
-  const alerts = useGristSdkAlertDescriptors(w, alertOptions)
-
-  if (alerts.length === 0) {
-    return <>{children}</>
-  }
-
-  return (
-    <div className={cn("flex flex-col gap-3", className)}>
-      {alerts.map((a) => (
-        <Alert
-          key={a.id}
-          role={a.ariaRole}
-          variant={a.severity === "error" ? "destructive" : "default"}
-          className={alertSeverityClass(a.severity)}
-        >
-          {a.kind === "section-not-linked" || a.kind === "source-not-wired" ? (
-            <Link2 className="size-4" aria-hidden />
-          ) : (
-            <AlertTriangle className="size-4" aria-hidden />
-          )}
-          <AlertTitle>{a.title}</AlertTitle>
-          <AlertDescription>{a.message}</AlertDescription>
-        </Alert>
-      ))}
-      {children}
-    </div>
-  )
-}

package/template/src/components/local-dev-notice.tsx

@@ -1,55 +0,0 @@
-import {
-  Card,
-  CardDescription,
-  CardHeader,
-  CardTitle,
-} from "@/components/ui/card"
-
-// Shown at the root of a local `pnpm dev` server, never inside Grist.
-// Deliberately a bare shell, not a seeded live preview: an emulator can't
-// guarantee parity with real Grist, so the loop worth trusting here is
-// `pnpm test` (renderWithGrist, headless) plus the real `dev`-branch loop
-// this points at below -- see AGENTS.md's note on why this isn't a fake
-// preview instead.
-export function LocalDevNotice() {
-  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 · local dev
-      </p>
-      <h1 className="text-center font-heading text-2xl font-semibold tracking-tight">
-        Not embedded in Grist
-      </h1>
-      <p className="mx-auto mt-3 mb-8 max-w-sm text-center text-sm text-muted-foreground">
-        This is a local dev server — there's no Grist here to render against.
-      </p>
-
-      <Card className="mb-4">
-        <CardHeader>
-          <CardTitle>Verify against real Grist</CardTitle>
-          <CardDescription>
-            Commit and push to <code className="text-foreground">dev</code>,
-            then open the printed{" "}
-            <code className="text-foreground">/dev/</code> URL in a real
-            Grist document — every later push self-reloads inside it within
-            seconds. See the README's Deployment section for the full loop.
-          </CardDescription>
-        </CardHeader>
-      </Card>
-
-      <Card>
-        <CardHeader>
-          <CardTitle>Not building this widget?</CardTitle>
-          <CardDescription>
-            <code className="text-foreground">npx grist-widget list</code> to
-            see other starting points,{" "}
-            <code className="text-foreground">
-              npx grist-widget use &lt;example&gt;
-            </code>{" "}
-            to swap this one out.
-          </CardDescription>
-        </CardHeader>
-      </Card>
-    </div>
-  )
-}

package/template/src/components/release-info.tsx

@@ -1,111 +0,0 @@
-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"
-import { devUrl, formatDate, useVersions, versionUrl } from "@/lib/showcase-versions"
-import { cn } from "@/lib/utils"
-
-// Shown on every non-embedded, built/deployed URL of this widget -- root,
-// /latest/, /dev/, /v<version>/, all carrying the same build per
-// scripts/deploy.mjs's plan() -- when opened outside Grist. Local `pnpm dev`
-// renders `LocalDevNotice` instead (see src/main.tsx): this component's
-// "paste this URL into Grist" instruction only makes sense for a real,
-// publicly reachable URL, never a bare localhost one.
-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)}
-          title={formatDate(versions[0].publishedAt)}
-          className={chipClass(
-            current.kind === "version" && current.version === versions[0].version,
-          )}
-        >
-          latest
-        </a>
-      )}
-      <a href={devUrl()} className={chipClass(current.kind === "dev")}>
-        dev
-      </a>
-      {versions?.map((v) => (
-        <a
-          key={v.version}
-          href={versionUrl(v.version)}
-          title={formatDate(v.publishedAt)}
-          className={chipClass(
-            current.kind === "version" && current.version === v.version,
-          )}
-        >
-          v{v.version}
-        </a>
-      ))}
-    </div>
-  )
-}
-
-export function ReleaseInfo({ channel }: { channel: Channel }) {
-  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. Hover a chip below to see when it
-        shipped.
-      </p>
-
-      <VersionChips current={channel} />
-
-      <Card>
-        <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>
-    </div>
-  )
-}

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

@@ -1,59 +0,0 @@
-// Parses the deployed URL shape every channel of this template (or a real
-// scaffolded widget) uses -- /latest/, /dev/, /v<version>/ -- so main.tsx and
-// ReleaseInfo can label the current build using nothing but
-// window.location.pathname. No router needed.
-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 a recognized trailing channel segment
- * stripped, e.g. "/grist-widget-sdk/template/latest/" ->
- * "/grist-widget-sdk/template/" -- used to build root-relative URLs
- * (versions.json, /dev/, /v<version>/) regardless of how deep this deploy's
- * own base path is (see showcase-versions.ts).
- *
- * `channel` always resolves to something: `scripts/deploy.mjs` places the
- * same build at the bare deployed root as at `/latest/`, so a path with no
- * recognized suffix (the root itself, or a local `pnpm dev` server) defaults
- * to `{ kind: "latest" }` -- that's genuinely what's there.
- */
-export function parseShowcasePath(pathname: string): {
-  channel: Channel
-  hubPath: string
-} {
-  const trimmed = pathname.replace(/\/+$/, "")
-  const segments = trimmed.split("/")
-  const last = segments[segments.length - 1] ?? ""
-
-  let channel: Channel = { kind: "latest" }
-  let matchedSuffix = false
-  if (last === "latest") {
-    channel = { kind: "latest" }
-    matchedSuffix = true
-  } else if (last === "dev") {
-    channel = { kind: "dev" }
-    matchedSuffix = true
-  } else {
-    const match = /^v(\d+\.\d+\.\d+(?:-[\w.]+)?)$/.exec(last)
-    if (match) {
-      channel = { kind: "version", version: match[1] }
-      matchedSuffix = true
-    }
-  }
-
-  const hubPath = matchedSuffix ? segments.slice(0, -1).join("/") + "/" : pathname
-  return { channel, hubPath }
-}