grist-widget-sdk 0.4.0 → 0.5.0

package/dist/emulator.d.cts

@@ -96,9 +96,9 @@ declare class EmulatorActionError extends Error {
 /**
  * Resolves the `mappings` payload that `CustomSectionAPI.mappings()` returns.
  *
- * The playground emulator does **not** infer logical → real columns from
- * names. Mappings come only from `state.selection.mappings` (playground
- * document inspector or tests). When unset, returns `null`.
+ * The emulator does **not** infer logical → real columns from names, as
+ * real Grist doesn't: mappings come only from `state.selection.mappings`
+ * (a test's `emulator.setColumnMappings(...)`). When unset, returns `null`.
  */
 
 declare function resolveMappings(state: EmulatorDocumentState): GristWidgetColumnMap | null;

package/dist/emulator.d.ts

@@ -96,9 +96,9 @@ declare class EmulatorActionError extends Error {
 /**
  * Resolves the `mappings` payload that `CustomSectionAPI.mappings()` returns.
  *
- * The playground emulator does **not** infer logical → real columns from
- * names. Mappings come only from `state.selection.mappings` (playground
- * document inspector or tests). When unset, returns `null`.
+ * The emulator does **not** infer logical → real columns from names, as
+ * real Grist doesn't: mappings come only from `state.selection.mappings`
+ * (a test's `emulator.setColumnMappings(...)`). When unset, returns `null`.
  */
 
 declare function resolveMappings(state: EmulatorDocumentState): GristWidgetColumnMap | null;

package/dist/emulator.js

@@ -6,7 +6,7 @@ import {
   presets,
   resolveMappings,
   safeParseDocument
-} from "./chunk-B5ZZNLVS.js";
+} from "./chunk-OXA2VITC.js";
 import "./chunk-4ZGVKGDF.js";
 export {
   EmulatorActionError,

package/dist/index.cjs

@@ -24,6 +24,8 @@ __export(src_exports, {
   GristWidgetProvider: () => GristWidgetProvider,
   checkGristCell: () => checkGristCell,
   decodeGristValue: () => decodeGristValue,
+  defineGristWidget: () => defineGristWidget,
+  encodeGristCell: () => encodeGristCell,
   encodeGristValue: () => encodeGristValue,
   extractGristAttachmentId: () => extractGristAttachmentId,
   extractGristAttachmentIdsFromCell: () => extractGristAttachmentIdsFromCell,
@@ -858,16 +860,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(),
@@ -972,58 +982,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";
-  }
-}
-function deriveError(state) {
-  if (state.connection === "not-embedded") return "This page is not embedded in a Grist document.";
-  if (state.connection === "unavailable") return "The Grist plugin API (grist-plugin-api.js) did not load.";
-  if (state.connection === "error") return state.connectionError;
-  if (state.connection === "ready" && accessDenied(state)) {
-    return `Grist granted "${accessLabel(state.grantedAccess)}"; this widget needs "${accessLabel(state.declaredAccess)}". Set the access level in the Custom widget settings.`;
-  }
-  return null;
-}
-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);
-}
-function mapBackPatch(patch, mappings) {
-  const fields = {};
-  const skipped = [];
-  for (const [name, value] of Object.entries(patch)) {
-    if (value === void 0) continue;
-    const real = mappings[name];
-    if (Array.isArray(real)) skipped.push(name);
-    else fields[typeof real === "string" && real ? real : name] = value;
-  }
-  return { fields, skipped };
-}
-
 // src/sdk/runtime/cells.ts
 var ok = (value) => ({ ok: true, value });
 var bad = (message2) => ({ ok: false, message: message2 });
@@ -1087,10 +1045,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) {
@@ -1100,6 +1061,19 @@ function checkGristCell(type, value) {
   }
   return first;
 }
+var LIST_BASES = ["ChoiceList", "RefList", "Attachments"];
+function encodeGristCell(type, value) {
+  if (value === null || value === void 0) return value;
+  const bases = basesOf(type);
+  const accepts = (...names) => names.some((n) => bases.includes(n));
+  if (value instanceof Date) return accepts("Date", "DateTime") ? Math.floor(value.getTime() / 1e3) : value;
+  if (Array.isArray(value)) {
+    if (!accepts(...LIST_BASES) || value[0] === "L") return value;
+    return ["L", ...value.map((item) => rowIdOf(item) ?? item)];
+  }
+  if (accepts("Ref") && typeof value === "object") return rowIdOf(value) ?? value;
+  return value;
+}
 var nameOf = (c) => typeof c === "string" ? c : c.name;
 var typeOf = (c) => typeof c === "string" ? void 0 : c.type;
 var isOptional = (c) => typeof c === "object" && c.optional === true;
@@ -1140,6 +1114,62 @@ 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";
+  }
+}
+function deriveError(state) {
+  if (state.connection === "not-embedded") return "This page is not embedded in a Grist document.";
+  if (state.connection === "unavailable") return "The Grist plugin API (grist-plugin-api.js) did not load.";
+  if (state.connection === "error") return state.connectionError;
+  if (state.connection === "ready" && accessDenied(state)) {
+    return `Grist granted "${accessLabel(state.grantedAccess)}"; this widget needs "${accessLabel(state.declaredAccess)}". Set the access level in the Custom widget settings.`;
+  }
+  return null;
+}
+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);
+}
+function mapBackPatch(patch, mappings, columns) {
+  const fields = {};
+  const skipped = [];
+  for (const [name, value] of Object.entries(patch)) {
+    if (value === void 0) continue;
+    const real = mappings[name];
+    if (Array.isArray(real)) {
+      skipped.push(name);
+      continue;
+    }
+    const declared = columns?.find((c) => nameOf(c) === name);
+    fields[typeof real === "string" && real ? real : name] = declared ? encodeGristCell(typeOf(declared), value) : value;
+  }
+  return { fields, skipped };
+}
+
 // src/sdk/helpers/grist-widget-interaction.ts
 function parseGristWidgetLinkingInfo(raw) {
   if (!raw || typeof raw !== "object" || !("asTarget" in raw)) return void 0;
@@ -1489,7 +1519,27 @@ function useMapped(state, options) {
     return { record: selected.value, records: mappedRecords, issues: issues.length ? issues : NO_ISSUES };
   }, [record, records, mappings, columns, schema]);
 }
-function buildResult(state, mapped, connection, mapBack, resolveMappedColumnId) {
+function recordWrites(connection) {
+  const { runtime, api } = connection;
+  const fieldsOf = (patch) => {
+    const { id: _id, ...rest } = patch;
+    return mapBackPatch(rest, runtime.getState().mappings ?? EMPTY_MAPPINGS, runtime.options.columns).fields;
+  };
+  const updateRecord = ((a, b) => {
+    const rowId = typeof a === "number" ? a : runtime.getState().record?.id;
+    const patch = typeof a === "number" ? b ?? {} : a;
+    if (typeof rowId !== "number") {
+      return Promise.reject(new Error("updateRecord(): no row is selected. Pass the row id: updateRecord(rowId, patch)."));
+    }
+    return api.table.update({ id: rowId, fields: fieldsOf(patch) });
+  });
+  const addRecord = async (patch) => {
+    const created = await api.table.create({ fields: fieldsOf(patch) });
+    return (Array.isArray(created) ? created[0] : created).id;
+  };
+  return { updateRecord, addRecord };
+}
+function buildResult(state, mapped, connection, mapBack, resolveMappedColumnId, writes) {
   const { runtime, api } = connection;
   const status = deriveStatus(state);
   const columns = runtime.options.columns;
@@ -1510,6 +1560,8 @@ function buildResult(state, mapped, connection, mapBack, resolveMappedColumnId)
     mode: state.isNewRecord ? "new-row" : state.record ? "row" : "empty",
     resolveMappedColumnId,
     mapBack,
+    updateRecord: writes.updateRecord,
+    addRecord: writes.addRecord,
     currentTableId: state.currentTableId,
     actionStatus: state.actionStatus,
     actionError: state.actionError,
@@ -1532,7 +1584,7 @@ function useGristResult(connection) {
   );
   const mapBack = (0, import_react.useCallback)(
     (patch) => {
-      const { fields, skipped } = mapBackPatch(patch, mappings);
+      const { fields, skipped } = mapBackPatch(patch, mappings, runtime.options.columns);
       const previous = runtime.getState().mapBackSkipped;
       if (previous.join("\0") !== skipped.join("\0")) runtime.update({ mapBackSkipped: skipped });
       return fields;
@@ -1540,9 +1592,10 @@ function useGristResult(connection) {
     [mappings, runtime]
   );
   const mapped = useMapped(state, runtime.options);
+  const writes = (0, import_react.useMemo)(() => recordWrites(connection), [connection]);
   return (0, import_react.useMemo)(
-    () => buildResult(state, mapped, connection, mapBack, resolveMappedColumnId),
-    [state, mapped, connection, mapBack, resolveMappedColumnId]
+    () => buildResult(state, mapped, connection, mapBack, resolveMappedColumnId, writes),
+    [state, mapped, connection, mapBack, resolveMappedColumnId, writes]
   );
 }
 function useGrist(options) {
@@ -1578,6 +1631,17 @@ var DETACHED = (() => {
   return { runtime, api: createGristApi(runtime) };
 })();
 
+// src/sdk/define-widget.ts
+function defineGristWidget(definition) {
+  const { title, description, ...options } = definition;
+  return {
+    definition,
+    options,
+    metadata: { title, description },
+    useGrist: () => useGrist(options)
+  };
+}
+
 // src/sdk/components/grist-widget-provider.tsx
 var import_react2 = require("react");
 var import_jsx_runtime = require("react/jsx-runtime");
@@ -1805,9 +1869,9 @@ function useGristSchema(options) {
   const [document2, setDocument] = (0, import_react4.useState)(null);
   const [loading, setLoading] = (0, import_react4.useState)(false);
   const [error, setError] = (0, import_react4.useState)(null);
-  const includeRowsForBuild = replicaRowMode === "schema-only" ? false : replicaRowMode === "schema+data" ? "full" : "samples";
   const load = (0, import_react4.useCallback)(async () => {
     if (!docApi) return;
+    const includeRowsForBuild = replicaRowMode === "schema-only" ? false : replicaRowMode === "schema+data" ? "full" : "samples";
     setLoading(true);
     setError(null);
     try {
@@ -2001,6 +2065,8 @@ function gristAddTableAction(tableId, tableInfo) {
   GristWidgetProvider,
   checkGristCell,
   decodeGristValue,
+  defineGristWidget,
+  encodeGristCell,
   encodeGristValue,
   extractGristAttachmentId,
   extractGristAttachmentIdsFromCell,