create-grist-widget 0.3.24 → 0.3.26

package/examples/spreadsheet-grid/GristDataSheetGrid.tsx

@@ -320,7 +320,7 @@ export function GristDataSheetGrid({
       }
 
       // Sequence: deletes → updates → creates. Errors are tracked by the SDK
-      // and surfaced through `<GristSdkAlerts>`.
+      // and surfaced by the SDK's alerts (mountGristWidget).
       void (async () => {
         try {
           if (deletes.length > 0) await ops.destroy(deletes)

package/examples/spreadsheet-grid/GristSchemaToolbar.tsx

@@ -98,7 +98,7 @@ export function GristSchemaToolbar({
       setNewColId("")
       setNewType("Text")
     } catch {
-      // Surfaced via <GristSdkAlerts>.
+      // Surfaced by the SDK's alerts (mountGristWidget).
     }
   }
 
@@ -109,7 +109,7 @@ export function GristSchemaToolbar({
       await w.applyActions([gristRenameColumnAction(tableId, oldId, newId)])
       await schema.reload()
     } catch {
-      /* surfaced via <GristSdkAlerts> */
+      /* surfaced by the SDK's alerts */
     }
   }
 
@@ -118,7 +118,7 @@ export function GristSchemaToolbar({
       await w.applyActions([gristModifyColumnAction(tableId, colId, { type })])
       await schema.reload()
     } catch {
-      /* surfaced via <GristSdkAlerts> */
+      /* surfaced by the SDK's alerts */
     }
   }
 
@@ -128,7 +128,7 @@ export function GristSchemaToolbar({
       await w.applyActions([gristRemoveColumnAction(tableId, colId)])
       await schema.reload()
     } catch {
-      /* surfaced via <GristSdkAlerts> */
+      /* surfaced by the SDK's alerts */
     }
   }
 

package/package.json

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

package/template/AGENTS.md

@@ -22,16 +22,17 @@ export function App() {
 }
 ```
 
-`src/main.tsx` wires it into Grist: `GristWidgetProvider` (reads `GRIST_OPTIONS`) →
-`GristBoundary` → `GristSdkAlerts` → `<App />`. Access level, column mapping, and
-rendering all live in `src/App.tsx` — that's the one file to edit.
+`src/main.tsx` is one call, `mountGristWidget({ App, options: GRIST_OPTIONS, dev })` from
+`grist-widget-sdk/app`: inside Grist it renders `<App />` in `GristWidgetProvider` and
+`GristBoundary`, with the SDK's alerts and Grist's light/dark theme. Access level, column
+mapping, and rendering all live in `src/App.tsx` — that's the one file to edit.
 
 ## Operating contract
 
 1. **Widgets use the SDK.** No direct `window.grist.*` calls — use `useGrist()` and the
    other `grist-widget-sdk` hooks.
 2. **`pnpm dev` is a bare shell, on purpose — not a seeded preview.** Opened outside Grist
-   it renders `LocalDevNotice`; the widget itself only renders once actually embedded in a
+   it shows the SDK's local-dev page; the widget itself only renders once actually embedded in a
    Grist document. This is deliberate, not a gap: an emulator can't guarantee parity with
    real Grist, so a fake local preview would teach the wrong lesson. Trust `pnpm test`
    (headless, real assertions) for local feedback, and the `dev`-branch loop below for real
@@ -64,7 +65,7 @@ rendering all live in `src/App.tsx` — that's the one file to edit.
 | --- | --- |
 | The widget | `src/App.tsx` |
 | Widget test (the pattern to copy for new tests) | `src/App.test.tsx` |
-| Grist wiring / embed vs. showcase detection | `src/main.tsx` |
+| Grist wiring (mountGristWidget, inside vs. outside Grist) | `src/main.tsx` |
 | ui primitives | `src/components/ui/` |
 | Deploy workflow | `.github/workflows/deploy.yml` |
 | Deploy script (version guard, channel logic) | `scripts/deploy.mjs` |

package/template/README.md

@@ -6,16 +6,16 @@ Base template to build a Grist widget with `grist-widget-sdk`.
 **Install URL**: written here by this widget's first release (its GitHub Pages `/latest/` URL).
 <!-- install-url:end -->
 
-`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.
+`src/main.tsx` is one call to `mountGristWidget()` from `grist-widget-sdk/app` ([reference](https://gristwidgets.com/docs/sdk/api/app)). Inside Grist it renders `App` in `GristWidgetProvider` and `GristBoundary`, under the SDK's alerts, in Grist's light/dark theme. `src/components/theme-provider.tsx` re-exports its `useTheme()`, for shadcn components that need the theme in JavaScript.
 
-Opened outside a Grist iframe, `main.tsx` picks between two components — never a live preview of the widget itself, since nothing here proves anything about real Grist behavior: local `pnpm dev` renders `LocalDevNotice`, a bare shell pointing at the real verification loop below (push to `dev`, open it in a real Grist document); any built/deployed URL (root, `/latest/`, `/dev/`, `/v<version>/` — all carrying the same build, see Deployment below) renders `ReleaseInfo` instead — which build this is, chips to jump to any other version/channel (hover one to see when it shipped; `src/lib/showcase-versions.ts`), and a copy-this-URL helper for pasting into Grist's custom widget field.
+Opened outside a Grist iframe, the page is never a live preview of the widget itself, since nothing there proves anything about real Grist behavior. Local `pnpm dev` shows a local-dev page pointing at the real verification loop below (push to `dev`, open it in a real Grist document). Any built or deployed URL (root, `/latest/`, `/dev/`, `/v<version>/`, all carrying the same build, see Deployment below) shows a release page instead: which build this is, links to every other version and channel (hover one to see when it shipped), and the URL to paste into Grist's custom widget field. Both come from the SDK and follow this widget's shadcn colors; `mountGristWidget()` takes your own components instead (`LocalDevPage`, `ReleasePage`).
 
-When actually embedded, the widget shows connection state only when something is wrong: until Grist is connected, or if the connection is lost or fails, `GristBoundary` replaces the widget with a connecting / unavailable / error screen (the error one with a retry button); once the widget is showing, `GristSdkAlerts` reports what needs attention (column mapping, access level, a failed write…). Nothing is drawn over the widget while all is well.
+When actually embedded, the widget shows connection state only when something is wrong: until Grist is connected, or if the connection is lost or fails, `GristBoundary` replaces the widget with a connecting / unavailable / error screen (the error one with a retry button); once the widget is showing, the SDK's alerts report what needs attention (column mapping, access level, a failed write…) above it. Nothing is drawn over the widget while all is well. Pass your own `Alerts` component to `mountGristWidget()` to render them differently, or `Alerts: null` for none.
 
 `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`. It ships with two mapped columns (`title`, `done`) and an editable form that saves back via `w.table.update(...)`/`w.mapBack(...)` — the smallest real starting point, not a placeholder. See `src/grist-types.example.ts` for typing patterns.
 
 - **ESLint** blocks direct `grist` global usage in `src/` — use the SDK only.
-- Edit `GRIST_OPTIONS.columns` in `App.tsx` to change the required columns (or remove the array entirely to read raw, unmapped records instead); `main.tsx` sets `GristBoundary gate="canRender"` whenever columns are declared. Mapping alerts use `GristSdkAlerts`.
+- Edit `GRIST_OPTIONS.columns` in `App.tsx` to change the required columns (or remove the array entirely to read raw, unmapped records instead); `mountGristWidget()` gates the widget on `canRender` whenever columns are declared, so it renders once they're mapped.
 
 Run `pnpm test` — see `src/App.test.tsx` for the pattern (`renderWithGrist` + `presets` from `grist-widget-sdk/emulator/testing`, no browser or real Grist doc needed). Full guide: [Testing](https://gristwidgets.com/docs/emulator/testing).
 

package/template/package.json

@@ -17,7 +17,7 @@
     "@tailwindcss/vite": "^4.3.3",
     "class-variance-authority": "^0.7.1",
     "clsx": "^2.1.1",
-    "grist-widget-sdk": "^0.3.20",
+    "grist-widget-sdk": "^0.3.26",
     "lucide-react": "^1.61.0",
     "radix-ui": "^1.8.1",
     "react": "^19.3.1",

package/template/scripts/deploy.mjs

@@ -226,11 +226,11 @@ export function injectSelfReload(html, sha) {
 /**
  * Scan siteDir for previously-released v<version>/showcase-meta.json files
  * and assemble the versions.json manifest, newest first. Read by the
- * showcase hub (TemplateLanding) and per-channel notice (ChannelNotice) to
- * show this widget's own release history -- not the grist-widget-sdk
+ * release page grist-widget-sdk/app shows outside Grist (useReleasedVersions)
+ * to list this widget's own release history -- not the grist-widget-sdk
  * monorepo's (found live: every scaffolded widget's version index showed
- * the monorepo's versions instead of its own, since showcase-versions.ts
- * used to hardcode that URL). Entries whose meta has no `repo` field, or a
+ * the monorepo's versions instead of its own, since the template's version
+ * list used to hardcode that URL). Entries whose meta has no `repo` field, or a
  * `repo` that doesn't match this repo, are skipped -- a `gh-pages` branch
  * manually seeded from another repo's export (found live) would otherwise
  * leak that repo's own version history into this one's index.

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/template/tsconfig.app.json

@@ -1,28 +1,13 @@
 {
+  // Compiler settings come from grist-widget-sdk and update with it. This
+  // file keeps what is specific to this widget: its files, paths and types.
+  "extends": "grist-widget-sdk/tsconfig/app.json",
   "compilerOptions": {
+    // Also set in the base. Repeated so that a missing base (a grist-widget-sdk
+    // too old to ship it) fails the typecheck without writing .js files into src/.
+    "noEmit": true,
     "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.app.tsbuildinfo",
-    "target": "ES2022",
-    "useDefineForClassFields": true,
-    "lib": ["ES2022", "DOM", "DOM.Iterable"],
-    "module": "ESNext",
     "types": ["vite/client"],
-    "skipLibCheck": true,
-
-    /* Bundler mode */
-    "moduleResolution": "bundler",
-    "allowImportingTsExtensions": true,
-    "verbatimModuleSyntax": true,
-    "moduleDetection": "force",
-    "noEmit": true,
-    "jsx": "react-jsx",
-
-    /* Linting */
-    "strict": true,
-    "noUnusedLocals": true,
-    "noUnusedParameters": true,
-    "erasableSyntaxOnly": true,
-    "noFallthroughCasesInSwitch": true,
-    "noUncheckedSideEffectImports": true,
     "paths": {
       "@/*": ["./src/*"]
     }

package/template/tsconfig.node.json

@@ -1,26 +1,13 @@
 {
+  // Compiler settings come from grist-widget-sdk and update with it. This
+  // file keeps what is specific to this widget: its files and types.
+  "extends": "grist-widget-sdk/tsconfig/node.json",
   "compilerOptions": {
-    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.node.tsbuildinfo",
-    "target": "ES2023",
-    "lib": ["ES2023"],
-    "module": "ESNext",
-    "types": ["node"],
-    "skipLibCheck": true,
-
-    /* Bundler mode */
-    "moduleResolution": "bundler",
-    "allowImportingTsExtensions": true,
-    "verbatimModuleSyntax": true,
-    "moduleDetection": "force",
+    // Also set in the base. Repeated so that a missing base (a grist-widget-sdk
+    // too old to ship it) fails the typecheck without writing a .js file.
     "noEmit": true,
-
-    /* Linting */
-    "strict": true,
-    "noUnusedLocals": true,
-    "noUnusedParameters": true,
-    "erasableSyntaxOnly": true,
-    "noFallthroughCasesInSwitch": true,
-    "noUncheckedSideEffectImports": true
+    "tsBuildInfoFile": "./node_modules/.tmp/tsconfig.node.tsbuildinfo",
+    "types": ["node"]
   },
   "include": ["vite.config.ts"]
 }

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 }
-}

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

@@ -1,63 +0,0 @@
-import { useEffect, useState } from "react"
-
-import { parseShowcasePath } from "@/lib/showcase-routing"
-
-// Used by ReleaseInfo, which needs the released-version list on every
-// non-embedded, deployed URL. URLs are root-relative to wherever THIS
-// deploy actually lives (derived from
-// window.location.pathname via parseShowcasePath's hubPath), not hardcoded
-// to the grist-widget-sdk monorepo's own showcase: a real scaffolded
-// widget has its own versions.json and its own v<version>/ + dev/ dirs,
-// and previously showed the monorepo's version history and links instead
-// of its own (found live on a real scaffold's landing page).
-function hubPath(): string {
-  const path = parseShowcasePath(window.location.pathname).hubPath
-  return path.endsWith("/") ? path : `${path}/`
-}
-
-export type ReleasedVersion = {
-  version: string
-  publishedAt: string
-}
-
-export function versionsUrl(): string {
-  return `${hubPath()}versions.json`
-}
-
-export function devUrl(): string {
-  return `${hubPath()}dev/`
-}
-
-export function versionUrl(version: string): string {
-  return `${hubPath()}v${version}/`
-}
-
-export function useVersions() {
-  const [versions, setVersions] = useState<ReleasedVersion[] | null>(null)
-  const [error, setError] = useState(false)
-
-  useEffect(() => {
-    let cancelled = false
-    fetch(versionsUrl(), { 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",
-  })
-}