grist-widget-sdk 0.4.0 → 0.5.0

package/dist/app.cjs

@@ -22,6 +22,7 @@ var app_exports = {};
 __export(app_exports, {
   GristWidgetApp: () => GristWidgetApp,
   deployChannelLabel: () => deployChannelLabel,
+  entryProps: () => entryProps,
   mountGristWidget: () => mountGristWidget,
   parseDeployPath: () => parseDeployPath,
   useReleasedVersions: () => useReleasedVersions,
@@ -30,7 +31,7 @@ __export(app_exports, {
 module.exports = __toCommonJS(app_exports);
 
 // src/app/mount-grist-widget.tsx
-var import_react7 = require("react");
+var import_react9 = require("react");
 var import_client = require("react-dom/client");
 
 // src/sdk/use-grist.ts
@@ -579,16 +580,24 @@ function createGristApi(runtime) {
       throw err;
     }
   };
-  const write = async (fn) => {
+  let running = 0;
+  let failure = null;
+  const write = (fn) => {
+    if (running++ === 0) failure = null;
     runtime.update({ actionStatus: "running", actionError: null });
-    try {
-      const out = await fn();
-      runtime.update({ actionStatus: "idle" });
-      return out;
-    } catch (err) {
-      runtime.update({ actionStatus: "error", actionError: message(err) });
-      throw err;
-    }
+    const done = (async () => {
+      try {
+        return await fn();
+      } catch (err) {
+        failure = message(err);
+        throw err;
+      } finally {
+        if (--running === 0) runtime.update(failure ? { actionStatus: "error", actionError: failure } : { actionStatus: "idle" });
+      }
+    })();
+    done.catch(() => {
+    });
+    return done;
   };
   const tableOps = (resolve) => ({
     getTableId: () => resolve().getTableId(),
@@ -693,38 +702,6 @@ function validateColumnMappings(spec, mappings) {
   };
 }
 
-// src/sdk/runtime/derive.ts
-var ACCESS_RANK = { none: 0, "read table": 1, full: 2 };
-function parseAccess(raw) {
-  return raw === "none" || raw === "read table" || raw === "full" ? raw : null;
-}
-function accessLabel(level) {
-  return level === "full" ? "Full document access" : level === "read table" ? "Read selected table" : "No document access";
-}
-function accessDenied(state) {
-  return state.grantedAccess !== null && ACCESS_RANK[state.grantedAccess] < ACCESS_RANK[state.declaredAccess];
-}
-function deriveStatus(state) {
-  switch (state.connection) {
-    case "connecting":
-      return "booting";
-    case "not-embedded":
-    case "unavailable":
-      return "unavailable";
-    case "error":
-      return "error";
-    case "ready":
-      return accessDenied(state) ? "error" : "ready";
-  }
-}
-var MAPPINGS_OK = Object.freeze({ ok: true, pending: false, missing: [], emptyMultiples: [] });
-var MAPPINGS_PENDING = Object.freeze({ ok: true, pending: true, missing: [], emptyMultiples: [] });
-function deriveColumnMappingStatus(columns, mappings) {
-  if (!columns?.length) return MAPPINGS_OK;
-  if (mappings === null) return MAPPINGS_PENDING;
-  return validateColumnMappings(columns, mappings);
-}
-
 // src/sdk/runtime/cells.ts
 var ok = (value) => ({ ok: true, value });
 var bad = (message2) => ({ ok: false, message: message2 });
@@ -788,10 +765,13 @@ function checkOne(base, value) {
       return ok(value);
   }
 }
+function basesOf(type) {
+  return (type ?? "Any").split(",").map((t) => t.trim().split(":")[0]).filter(Boolean);
+}
 function checkGristCell(type, value) {
   const error = formulaError(value);
   if (error) return bad(`formula error (${error})`);
-  const bases = (type ?? "Any").split(",").map((t) => t.trim().split(":")[0]).filter(Boolean);
+  const bases = basesOf(type);
   if (bases.length === 0 || bases.includes("Any")) return ok(value === void 0 ? null : value);
   let first = null;
   for (const base of bases) {
@@ -841,6 +821,38 @@ function mapAndCheck(record, columns, mappings, schema) {
   return { value: out, issues };
 }
 
+// src/sdk/runtime/derive.ts
+var ACCESS_RANK = { none: 0, "read table": 1, full: 2 };
+function parseAccess(raw) {
+  return raw === "none" || raw === "read table" || raw === "full" ? raw : null;
+}
+function accessLabel(level) {
+  return level === "full" ? "Full document access" : level === "read table" ? "Read selected table" : "No document access";
+}
+function accessDenied(state) {
+  return state.grantedAccess !== null && ACCESS_RANK[state.grantedAccess] < ACCESS_RANK[state.declaredAccess];
+}
+function deriveStatus(state) {
+  switch (state.connection) {
+    case "connecting":
+      return "booting";
+    case "not-embedded":
+    case "unavailable":
+      return "unavailable";
+    case "error":
+      return "error";
+    case "ready":
+      return accessDenied(state) ? "error" : "ready";
+  }
+}
+var MAPPINGS_OK = Object.freeze({ ok: true, pending: false, missing: [], emptyMultiples: [] });
+var MAPPINGS_PENDING = Object.freeze({ ok: true, pending: true, missing: [], emptyMultiples: [] });
+function deriveColumnMappingStatus(columns, mappings) {
+  if (!columns?.length) return MAPPINGS_OK;
+  if (mappings === null) return MAPPINGS_PENDING;
+  return validateColumnMappings(columns, mappings);
+}
+
 // src/sdk/helpers/grist-widget-interaction.ts
 function parseGristWidgetLinkingInfo(raw) {
   if (!raw || typeof raw !== "object" || !("asTarget" in raw)) return void 0;
@@ -1213,6 +1225,11 @@ function useNearestGristState() {
   return { connection, state, cellIssues: issues };
 }
 
+// src/sdk/define-widget.ts
+function isGristWidget(value) {
+  return typeof value === "object" && value !== null && "definition" in value && "useGrist" in value;
+}
+
 // src/sdk/components/grist-widget-provider.tsx
 var import_react2 = require("react");
 var import_jsx_runtime = require("react/jsx-runtime");
@@ -1371,6 +1388,40 @@ function GristBoundary({ children }) {
   );
 }
 
+// src/sdk/use-widget-metadata.ts
+var import_react4 = require("react");
+function useWidgetMetadata(input) {
+  (0, import_react4.useEffect)(() => {
+    if (!input) return;
+    const { title, description } = input;
+    const canonicalUrl = window.location.href;
+    document.title = title;
+    setMetaTag("name", "title", title);
+    setMetaTag("name", "description", description);
+    setMetaTag("property", "og:title", title);
+    setMetaTag("property", "og:description", description);
+    setMetaTag("property", "og:type", "website");
+    setMetaTag("property", "og:url", canonicalUrl);
+    setMetaTag("name", "twitter:card", "summary");
+    setMetaTag("name", "twitter:title", title);
+    setMetaTag("name", "twitter:description", description);
+  }, [input]);
+}
+function setMetaTag(key, value, content) {
+  let meta = document.head.querySelector(
+    `meta[${key}="${value}"]`
+  );
+  if (!meta) {
+    meta = document.createElement("meta");
+    meta.setAttribute(key, value);
+    document.head.appendChild(meta);
+  }
+  meta.setAttribute("content", content);
+}
+
+// src/app/chrome/local-dev-page.tsx
+var import_react5 = require("react");
+
 // src/app/chrome/tokens.ts
 var token = (name, fallback) => `var(--${name}, ${fallback})`;
 var tokens = {
@@ -1451,7 +1502,20 @@ function widgetTitle() {
 
 // src/app/chrome/local-dev-page.tsx
 var import_jsx_runtime3 = require("react/jsx-runtime");
+function useHasDemo() {
+  const [has, setHas] = (0, import_react5.useState)(null);
+  (0, import_react5.useEffect)(() => {
+    if (typeof fetch !== "function") return;
+    let live = true;
+    fetch("demo/demo.grist", { method: "HEAD" }).then((res) => live && setHas(res.ok)).catch(() => live && setHas(false));
+    return () => {
+      live = false;
+    };
+  }, []);
+  return has;
+}
 function LocalDevPage() {
+  const hasDemo = useHasDemo();
   return /* @__PURE__ */ (0, import_jsx_runtime3.jsxs)("main", { style: pageStyle, children: [
     /* @__PURE__ */ (0, import_jsx_runtime3.jsxs)("p", { style: eyebrowStyle, children: [
       widgetTitle(),
@@ -1459,6 +1523,29 @@ function LocalDevPage() {
     ] }),
     /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("h1", { style: headingStyle, children: "Not embedded in Grist" }),
     /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("p", { style: leadStyle, children: "This is the local dev server: there's no Grist here to render the widget against." }),
+    /* @__PURE__ */ (0, import_jsx_runtime3.jsxs)("section", { style: cardStyle2, children: [
+      /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("h2", { style: cardTitleStyle, children: "Open it in Grist, in this browser" }),
+      hasDemo === false ? /* @__PURE__ */ (0, import_jsx_runtime3.jsxs)("p", { style: cardTextStyle, children: [
+        "Run ",
+        /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("code", { style: codeStyle, children: "pnpm demo --save" }),
+        " once (it needs Docker): it writes",
+        " ",
+        /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("code", { style: codeStyle, children: "public/demo/" }),
+        ", a document for this widget. Then",
+        " ",
+        /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("a", { href: "demo/index.html", children: "demo/index.html" }),
+        " opens it in real Grist, running in the browser, on this dev server's widget: edits reload in place."
+      ] }) : /* @__PURE__ */ (0, import_jsx_runtime3.jsxs)("p", { style: cardTextStyle, children: [
+        /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("a", { href: "demo/index.html", children: "Open demo/index.html" }),
+        ": real Grist running in the browser (no server, nothing saved), with this dev server's widget, so edits reload in place. Its document is",
+        " ",
+        /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("code", { style: codeStyle, children: "public/demo/demo.grist" }),
+        ": after changing the declared columns, run",
+        " ",
+        /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("code", { style: codeStyle, children: "pnpm demo --save" }),
+        " (Docker) to regenerate it."
+      ] })
+    ] }),
     /* @__PURE__ */ (0, import_jsx_runtime3.jsxs)("section", { style: cardStyle2, children: [
       /* @__PURE__ */ (0, import_jsx_runtime3.jsx)("h2", { style: cardTitleStyle, children: "Check it against real Grist" }),
       /* @__PURE__ */ (0, import_jsx_runtime3.jsxs)("p", { style: cardTextStyle, children: [
@@ -1486,7 +1573,7 @@ function LocalDevPage() {
 }
 
 // src/app/chrome/release-page.tsx
-var import_react5 = require("react");
+var import_react7 = require("react");
 
 // src/app/deploy-path.ts
 var VERSION_SEGMENT = /^v(\d+\.\d+\.\d+(?:-[\w.]+)?)$/;
@@ -1511,11 +1598,11 @@ function withTrailingSlash(path) {
 }
 
 // src/app/released-versions.ts
-var import_react4 = require("react");
+var import_react6 = require("react");
 function useReleasedVersions(pathname = typeof window === "undefined" ? "/" : window.location.pathname) {
   const url = `${parseDeployPath(pathname).basePath}versions.json`;
-  const [result, setResult] = (0, import_react4.useState)({ versions: null, error: false });
-  (0, import_react4.useEffect)(() => {
+  const [result, setResult] = (0, import_react6.useState)({ versions: null, error: false });
+  (0, import_react6.useEffect)(() => {
     let cancelled = false;
     fetch(url, { cache: "no-store" }).then((res) => res.ok ? res.json() : Promise.reject(new Error(`HTTP ${res.status}`))).then((data) => {
       if (cancelled) return;
@@ -1590,7 +1677,7 @@ function ChannelLink({
 }
 function InstallUrl() {
   const url = window.location.href;
-  const [copied, setCopied] = (0, import_react5.useState)(false);
+  const [copied, setCopied] = (0, import_react7.useState)(false);
   function copy() {
     void navigator.clipboard?.writeText(url).then(() => {
       setCopied(true);
@@ -1809,14 +1896,14 @@ function LinkIcon() {
 }
 
 // src/app/widget-theme.tsx
-var import_react6 = require("react");
+var import_react8 = require("react");
 var import_jsx_runtime6 = require("react/jsx-runtime");
 var STORAGE_KEY = "theme";
 var DARK_QUERY = "(prefers-color-scheme: dark)";
 var THEMES = ["light", "dark", "system"];
-var ThemeContext = (0, import_react6.createContext)(null);
+var ThemeContext = (0, import_react8.createContext)(null);
 function useTheme() {
-  const value = (0, import_react6.useContext)(ThemeContext);
+  const value = (0, import_react8.useContext)(ThemeContext);
   return value ?? { theme: "system", resolvedTheme: systemTheme(), setTheme: noop };
 }
 function EmbeddedThemeProvider({ children }) {
@@ -1824,22 +1911,22 @@ function EmbeddedThemeProvider({ children }) {
   const system = useSystemTheme(gristTheme === null);
   const resolvedTheme = gristTheme ?? system;
   useApplyTheme(resolvedTheme);
-  const value = (0, import_react6.useMemo)(
+  const value = (0, import_react8.useMemo)(
     () => ({ theme: gristTheme ?? "system", resolvedTheme, setTheme: noop }),
     [gristTheme, resolvedTheme]
   );
   return /* @__PURE__ */ (0, import_jsx_runtime6.jsx)(ThemeContext.Provider, { value, children });
 }
 function StandaloneThemeProvider({ children }) {
-  const [theme, setThemeState] = (0, import_react6.useState)(() => readStoredTheme() ?? "system");
+  const [theme, setThemeState] = (0, import_react8.useState)(() => readStoredTheme() ?? "system");
   const system = useSystemTheme(theme === "system");
   const resolvedTheme = theme === "system" ? system : theme;
   useApplyTheme(resolvedTheme);
-  const setTheme = (0, import_react6.useCallback)((next) => {
+  const setTheme = (0, import_react8.useCallback)((next) => {
     writeStoredTheme(next);
     setThemeState(next);
   }, []);
-  (0, import_react6.useEffect)(() => {
+  (0, import_react8.useEffect)(() => {
     const onKeyDown = (event) => {
       if (event.repeat || event.metaKey || event.ctrlKey || event.altKey) return;
       if (event.key.toLowerCase() !== "d" || isEditableTarget(event.target)) return;
@@ -1853,7 +1940,7 @@ function StandaloneThemeProvider({ children }) {
     window.addEventListener("keydown", onKeyDown);
     return () => window.removeEventListener("keydown", onKeyDown);
   }, []);
-  (0, import_react6.useEffect)(() => {
+  (0, import_react8.useEffect)(() => {
     const onStorage = (event) => {
       if (event.key !== STORAGE_KEY) return;
       setThemeState(isTheme(event.newValue) ? event.newValue : "system");
@@ -1861,15 +1948,15 @@ function StandaloneThemeProvider({ children }) {
     window.addEventListener("storage", onStorage);
     return () => window.removeEventListener("storage", onStorage);
   }, []);
-  const value = (0, import_react6.useMemo)(
+  const value = (0, import_react8.useMemo)(
     () => ({ theme, resolvedTheme, setTheme }),
     [theme, resolvedTheme, setTheme]
   );
   return /* @__PURE__ */ (0, import_jsx_runtime6.jsx)(ThemeContext.Provider, { value, children });
 }
 function useSystemTheme(active) {
-  const [theme, setTheme] = (0, import_react6.useState)(systemTheme);
-  (0, import_react6.useEffect)(() => {
+  const [theme, setTheme] = (0, import_react8.useState)(systemTheme);
+  (0, import_react8.useEffect)(() => {
     if (!active || typeof window.matchMedia !== "function") return;
     const query = window.matchMedia(DARK_QUERY);
     const onChange = () => setTheme(query.matches ? "dark" : "light");
@@ -1880,7 +1967,7 @@ function useSystemTheme(active) {
   return theme;
 }
 function useApplyTheme(theme) {
-  (0, import_react6.useEffect)(() => {
+  (0, import_react8.useEffect)(() => {
     const root = document.documentElement;
     if (root.classList.contains(theme) && !root.classList.contains(other(theme))) return;
     const restoreTransitions = suspendTransitions();
@@ -1933,21 +2020,41 @@ function noop() {
 
 // src/app/mount-grist-widget.tsx
 var import_jsx_runtime7 = require("react/jsx-runtime");
-function mountGristWidget(config) {
-  const { root = "#root", ...props } = config;
+function entryProps(entry, dev = false) {
+  const widget = isGristWidget(entry.widget) ? entry.widget : void 0;
+  const options = widget?.options ?? entry.GRIST_OPTIONS;
+  if (!options) {
+    throw new Error(
+      "mountGristWidget: src/app/App.tsx exports neither `widget` (defineGristWidget) nor `GRIST_OPTIONS`."
+    );
+  }
+  const props = {
+    App: entry.default,
+    options,
+    metadata: widget?.metadata ?? entry.WIDGET_METADATA,
+    dev
+  };
+  if ("Alerts" in entry) props.Alerts = entry.Alerts;
+  if (entry.LocalDevPage) props.LocalDevPage = entry.LocalDevPage;
+  if (entry.ReleasePage) props.ReleasePage = entry.ReleasePage;
+  return props;
+}
+function mountGristWidget(config, entryOptions = {}) {
+  const { root = "#root", ...props } = "App" in config ? config : { ...entryProps(config, entryOptions.dev), root: entryOptions.root };
   const container = typeof root === "string" ? document.querySelector(root) : root;
   if (!container) {
     throw new Error(`mountGristWidget: no element matches "${String(root)}" to render the widget into.`);
   }
   const reactRoot = (0, import_client.createRoot)(container);
   reactRoot.render(
-    /* @__PURE__ */ (0, import_jsx_runtime7.jsx)(import_react7.StrictMode, { children: /* @__PURE__ */ (0, import_jsx_runtime7.jsx)(GristWidgetApp, { ...props }) })
+    /* @__PURE__ */ (0, import_jsx_runtime7.jsx)(import_react9.StrictMode, { children: /* @__PURE__ */ (0, import_jsx_runtime7.jsx)(GristWidgetApp, { ...props }) })
   );
   return { unmount: () => reactRoot.unmount() };
 }
 function GristWidgetApp({
   App,
   options,
+  metadata,
   dev = false,
   Alerts = WidgetAlerts,
   LocalDevPage: LocalDevPage2 = LocalDevPage,
@@ -1955,15 +2062,25 @@ function GristWidgetApp({
 }) {
   const Wrap = Alerts ?? PassThrough;
   if (isEmbedded2()) {
-    return /* @__PURE__ */ (0, import_jsx_runtime7.jsx)(GristWidgetProvider, { options, children: /* @__PURE__ */ (0, import_jsx_runtime7.jsx)(EmbeddedThemeProvider, { children: /* @__PURE__ */ (0, import_jsx_runtime7.jsx)(GristBoundary, { children: /* @__PURE__ */ (0, import_jsx_runtime7.jsx)("div", { style: FILL, children: /* @__PURE__ */ (0, import_jsx_runtime7.jsx)(Wrap, { children: /* @__PURE__ */ (0, import_jsx_runtime7.jsx)(import_react7.Suspense, { fallback: null, children: /* @__PURE__ */ (0, import_jsx_runtime7.jsx)(App, {}) }) }) }) }) }) });
+    return /* @__PURE__ */ (0, import_jsx_runtime7.jsxs)(GristWidgetProvider, { options, children: [
+      /* @__PURE__ */ (0, import_jsx_runtime7.jsx)(PageMetadata, { metadata }),
+      /* @__PURE__ */ (0, import_jsx_runtime7.jsx)(EmbeddedThemeProvider, { children: /* @__PURE__ */ (0, import_jsx_runtime7.jsx)(GristBoundary, { children: /* @__PURE__ */ (0, import_jsx_runtime7.jsx)("div", { style: FILL, children: /* @__PURE__ */ (0, import_jsx_runtime7.jsx)(Wrap, { children: /* @__PURE__ */ (0, import_jsx_runtime7.jsx)(import_react9.Suspense, { fallback: null, children: /* @__PURE__ */ (0, import_jsx_runtime7.jsx)(App, {}) }) }) }) }) })
+    ] });
   }
   const channel = parseDeployPath(window.location.pathname).channel;
-  return /* @__PURE__ */ (0, import_jsx_runtime7.jsx)(StandaloneThemeProvider, { children: /* @__PURE__ */ (0, import_jsx_runtime7.jsx)("div", { style: FILL, children: dev ? /* @__PURE__ */ (0, import_jsx_runtime7.jsx)(LocalDevPage2, {}) : /* @__PURE__ */ (0, import_jsx_runtime7.jsx)(ReleasePage2, { channel }) }) });
+  return /* @__PURE__ */ (0, import_jsx_runtime7.jsxs)(StandaloneThemeProvider, { children: [
+    /* @__PURE__ */ (0, import_jsx_runtime7.jsx)(PageMetadata, { metadata }),
+    /* @__PURE__ */ (0, import_jsx_runtime7.jsx)("div", { style: FILL, children: dev ? /* @__PURE__ */ (0, import_jsx_runtime7.jsx)(LocalDevPage2, {}) : /* @__PURE__ */ (0, import_jsx_runtime7.jsx)(ReleasePage2, { channel }) })
+  ] });
 }
 var FILL = { minHeight: "100%", width: "100%" };
 function isEmbedded2() {
   return typeof window !== "undefined" && window.self !== window.top;
 }
+function PageMetadata({ metadata }) {
+  useWidgetMetadata(metadata?.title ? { title: metadata.title, description: metadata.description ?? "" } : null);
+  return null;
+}
 function PassThrough({ children }) {
   return /* @__PURE__ */ (0, import_jsx_runtime7.jsx)(import_jsx_runtime7.Fragment, { children });
 }
@@ -1971,6 +2088,7 @@ function PassThrough({ children }) {
 0 && (module.exports = {
   GristWidgetApp,
   deployChannelLabel,
+  entryProps,
   mountGristWidget,
   parseDeployPath,
   useReleasedVersions,