grist-widget-sdk 0.4.0 → 0.5.1

package/dist/app.d.cts

@@ -1,103 +1,8 @@
-import * as react from 'react';
-import { ComponentType, ReactNode } from 'react';
-import { UseGristOptions } from './index.cjs';
+export { D as DeployChannel, a as DeployPath, G as GristWidgetApp, b as GristWidgetAppProps, c as GristWidgetEntry, M as MountGristWidgetConfig, d as MountedGristWidget, e as deployChannelLabel, f as entryProps, m as mountGristWidget, p as parseDeployPath } from './mount-grist-widget-Dtelqao_.cjs';
+import 'react';
+import './define-widget-B1FIvI-h.cjs';
 import './types-DBStn0Dk.cjs';
 
-/**
- * Where a deployed build is being served from.
- *
- * A widget's deploy pipeline publishes the same build at its root and at
- * `/latest/`, a preview at `/dev/`, and each release at `/v<version>/`, all
- * under one base path (e.g. `/my-widget/` on GitHub Pages). Opened outside
- * Grist, the page tells them apart from `window.location.pathname` alone.
- */
-type DeployChannel = {
-    kind: "latest";
-} | {
-    kind: "dev";
-} | {
-    kind: "version";
-    version: string;
-};
-type DeployPath = {
-    channel: DeployChannel;
-    /**
-     * The path the channels live under, always ending in `/`: the current
-     * path without its channel segment. `"/my-widget/v1.2.0/"` gives
-     * `"/my-widget/"`.
-     */
-    basePath: string;
-};
-/**
- * Parse a pathname into its deploy channel and base path. A path without a
- * channel segment (the deployed root, or a local dev server) is `latest`:
- * the deploy places the latest release at the root too.
- */
-declare function parseDeployPath(pathname: string): DeployPath;
-/** `"latest"`, `"dev"` or `"v1.2.0"`. */
-declare function deployChannelLabel(channel: DeployChannel): string;
-
-type GristWidgetAppProps = {
-    /** The widget. A `React.lazy()` component works too: its code then loads only inside Grist. */
-    App: ComponentType;
-    /** The widget's `GRIST_OPTIONS`: access level, columns, and so on. */
-    options: UseGristOptions;
-    /**
-     * Whether this is the local dev server. Pass `import.meta.env.DEV`.
-     * Outside Grist it picks the local-dev page over the release page.
-     */
-    dev?: boolean;
-    /**
-     * Wraps the widget inside Grist, under {@link GristBoundary}. The default
-     * lists what needs the user's attention (column mapping, access level,
-     * failed writes) above the widget; `null` renders the widget alone.
-     */
-    Alerts?: ComponentType<{
-        children: ReactNode;
-    }> | null;
-    /** Shown outside Grist on the local dev server. Defaults to a page pointing at `pnpm test` and the `dev` loop. */
-    LocalDevPage?: ComponentType;
-    /**
-     * Shown outside Grist on a deployed URL (`/latest/`, `/dev/`, `/v<version>/`).
-     * Defaults to a page linking every channel and version, with the URL to
-     * paste into Grist.
-     */
-    ReleasePage?: ComponentType<{
-        channel: DeployChannel;
-    }>;
-};
-type MountGristWidgetConfig = GristWidgetAppProps & {
-    /** The element to render into, or its CSS selector. Defaults to `#root`. */
-    root?: Element | string;
-};
-type MountedGristWidget = {
-    unmount: () => void;
-};
-/**
- * Render a widget into the page: everything `src/main.tsx` used to wire by
- * hand.
- *
- * ```tsx
- * import { mountGristWidget } from "grist-widget-sdk/app"
- * import "./index.css"
- * import App, { GRIST_OPTIONS } from "./App"
- *
- * mountGristWidget({ App, options: GRIST_OPTIONS, dev: import.meta.env.DEV })
- * ```
- *
- * Inside Grist, the widget renders in {@link GristWidgetProvider} and
- * {@link GristBoundary}, which gates on its mapped columns when it declares
- * any, and follows Grist's light/dark theme. Outside Grist, where there is
- * nothing to connect to, the page shows `LocalDevPage` on the dev server and
- * `ReleasePage` on a deployed URL.
- */
-declare function mountGristWidget(config: MountGristWidgetConfig): MountedGristWidget;
-/**
- * The tree {@link mountGristWidget} renders, as a component: for a test, or
- * for a page that manages its own React root.
- */
-declare function GristWidgetApp({ App, options, dev, Alerts, LocalDevPage, ReleasePage, }: GristWidgetAppProps): react.JSX.Element;
-
 type WidgetTheme = "light" | "dark" | "system";
 type ResolvedWidgetTheme = "light" | "dark";
 type UseThemeResult = {
@@ -141,5 +46,5 @@ type UseReleasedVersionsResult = {
  */
 declare function useReleasedVersions(pathname?: string): UseReleasedVersionsResult;
 
-export { GristWidgetApp, deployChannelLabel, mountGristWidget, parseDeployPath, useReleasedVersions, useTheme };
-export type { DeployChannel, DeployPath, GristWidgetAppProps, MountGristWidgetConfig, MountedGristWidget, ReleasedVersion, ResolvedWidgetTheme, UseReleasedVersionsResult, UseThemeResult, WidgetTheme };
+export { useReleasedVersions, useTheme };
+export type { ReleasedVersion, ResolvedWidgetTheme, UseReleasedVersionsResult, UseThemeResult, WidgetTheme };

package/dist/app.d.ts

@@ -1,103 +1,8 @@
-import * as react from 'react';
-import { ComponentType, ReactNode } from 'react';
-import { UseGristOptions } from './index.js';
+export { D as DeployChannel, a as DeployPath, G as GristWidgetApp, b as GristWidgetAppProps, c as GristWidgetEntry, M as MountGristWidgetConfig, d as MountedGristWidget, e as deployChannelLabel, f as entryProps, m as mountGristWidget, p as parseDeployPath } from './mount-grist-widget-CkB-3iG_.js';
+import 'react';
+import './define-widget-B9gEtJP0.js';
 import './types-DBStn0Dk.js';
 
-/**
- * Where a deployed build is being served from.
- *
- * A widget's deploy pipeline publishes the same build at its root and at
- * `/latest/`, a preview at `/dev/`, and each release at `/v<version>/`, all
- * under one base path (e.g. `/my-widget/` on GitHub Pages). Opened outside
- * Grist, the page tells them apart from `window.location.pathname` alone.
- */
-type DeployChannel = {
-    kind: "latest";
-} | {
-    kind: "dev";
-} | {
-    kind: "version";
-    version: string;
-};
-type DeployPath = {
-    channel: DeployChannel;
-    /**
-     * The path the channels live under, always ending in `/`: the current
-     * path without its channel segment. `"/my-widget/v1.2.0/"` gives
-     * `"/my-widget/"`.
-     */
-    basePath: string;
-};
-/**
- * Parse a pathname into its deploy channel and base path. A path without a
- * channel segment (the deployed root, or a local dev server) is `latest`:
- * the deploy places the latest release at the root too.
- */
-declare function parseDeployPath(pathname: string): DeployPath;
-/** `"latest"`, `"dev"` or `"v1.2.0"`. */
-declare function deployChannelLabel(channel: DeployChannel): string;
-
-type GristWidgetAppProps = {
-    /** The widget. A `React.lazy()` component works too: its code then loads only inside Grist. */
-    App: ComponentType;
-    /** The widget's `GRIST_OPTIONS`: access level, columns, and so on. */
-    options: UseGristOptions;
-    /**
-     * Whether this is the local dev server. Pass `import.meta.env.DEV`.
-     * Outside Grist it picks the local-dev page over the release page.
-     */
-    dev?: boolean;
-    /**
-     * Wraps the widget inside Grist, under {@link GristBoundary}. The default
-     * lists what needs the user's attention (column mapping, access level,
-     * failed writes) above the widget; `null` renders the widget alone.
-     */
-    Alerts?: ComponentType<{
-        children: ReactNode;
-    }> | null;
-    /** Shown outside Grist on the local dev server. Defaults to a page pointing at `pnpm test` and the `dev` loop. */
-    LocalDevPage?: ComponentType;
-    /**
-     * Shown outside Grist on a deployed URL (`/latest/`, `/dev/`, `/v<version>/`).
-     * Defaults to a page linking every channel and version, with the URL to
-     * paste into Grist.
-     */
-    ReleasePage?: ComponentType<{
-        channel: DeployChannel;
-    }>;
-};
-type MountGristWidgetConfig = GristWidgetAppProps & {
-    /** The element to render into, or its CSS selector. Defaults to `#root`. */
-    root?: Element | string;
-};
-type MountedGristWidget = {
-    unmount: () => void;
-};
-/**
- * Render a widget into the page: everything `src/main.tsx` used to wire by
- * hand.
- *
- * ```tsx
- * import { mountGristWidget } from "grist-widget-sdk/app"
- * import "./index.css"
- * import App, { GRIST_OPTIONS } from "./App"
- *
- * mountGristWidget({ App, options: GRIST_OPTIONS, dev: import.meta.env.DEV })
- * ```
- *
- * Inside Grist, the widget renders in {@link GristWidgetProvider} and
- * {@link GristBoundary}, which gates on its mapped columns when it declares
- * any, and follows Grist's light/dark theme. Outside Grist, where there is
- * nothing to connect to, the page shows `LocalDevPage` on the dev server and
- * `ReleasePage` on a deployed URL.
- */
-declare function mountGristWidget(config: MountGristWidgetConfig): MountedGristWidget;
-/**
- * The tree {@link mountGristWidget} renders, as a component: for a test, or
- * for a page that manages its own React root.
- */
-declare function GristWidgetApp({ App, options, dev, Alerts, LocalDevPage, ReleasePage, }: GristWidgetAppProps): react.JSX.Element;
-
 type WidgetTheme = "light" | "dark" | "system";
 type ResolvedWidgetTheme = "light" | "dark";
 type UseThemeResult = {
@@ -141,5 +46,5 @@ type UseReleasedVersionsResult = {
  */
 declare function useReleasedVersions(pathname?: string): UseReleasedVersionsResult;
 
-export { GristWidgetApp, deployChannelLabel, mountGristWidget, parseDeployPath, useReleasedVersions, useTheme };
-export type { DeployChannel, DeployPath, GristWidgetAppProps, MountGristWidgetConfig, MountedGristWidget, ReleasedVersion, ResolvedWidgetTheme, UseReleasedVersionsResult, UseThemeResult, WidgetTheme };
+export { useReleasedVersions, useTheme };
+export type { ReleasedVersion, ResolvedWidgetTheme, UseReleasedVersionsResult, UseThemeResult, WidgetTheme };

package/dist/app.js

@@ -1,16 +1,18 @@
 import {
   GristWidgetApp,
   deployChannelLabel,
+  entryProps,
   mountGristWidget,
   parseDeployPath,
   useReleasedVersions,
   useTheme
-} from "./chunk-P6VTEKWO.js";
-import "./chunk-O7NY46QY.js";
+} from "./chunk-P5I5MRC6.js";
+import "./chunk-MAPAWVQC.js";
 import "./chunk-4ZGVKGDF.js";
 export {
   GristWidgetApp,
   deployChannelLabel,
+  entryProps,
   mountGristWidget,
   parseDeployPath,
   useReleasedVersions,

package/dist/{chunk-O7NY46QY.js → chunk-MAPAWVQC.js}

@@ -528,10 +528,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) {
@@ -541,6 +544,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;
@@ -819,16 +835,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(),
@@ -973,14 +997,18 @@ function deriveColumnMappingStatus(columns, mappings) {
   if (mappings === null) return MAPPINGS_PENDING;
   return validateColumnMappings(columns, mappings);
 }
-function mapBackPatch(patch, 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);
-    else fields[typeof real === "string" && real ? real : name] = value;
+    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 };
 }
@@ -1340,7 +1368,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;
@@ -1361,6 +1409,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,
@@ -1383,7 +1433,7 @@ function useGristResult(connection) {
   );
   const mapBack = 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;
@@ -1391,9 +1441,10 @@ function useGristResult(connection) {
     [mappings, runtime]
   );
   const mapped = useMapped(state, runtime.options);
+  const writes = useMemo(() => recordWrites(connection), [connection]);
   return 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) {
@@ -1435,6 +1486,20 @@ function useNearestGristState() {
   return { connection, state, cellIssues: issues };
 }
 
+// src/sdk/define-widget.ts
+function defineGristWidget(definition) {
+  const { title, description, ...options } = definition;
+  return {
+    definition,
+    options,
+    metadata: { title, description },
+    useGrist: () => useGrist(options)
+  };
+}
+function isGristWidget(value) {
+  return typeof value === "object" && value !== null && "definition" in value && "useGrist" in value;
+}
+
 // src/sdk/components/grist-widget-provider.tsx
 import { useState } from "react";
 import { jsx } from "react/jsx-runtime";
@@ -1641,9 +1706,9 @@ function useGristSchema(options) {
   const [document2, setDocument] = useState3(null);
   const [loading, setLoading] = useState3(false);
   const [error, setError] = useState3(null);
-  const includeRowsForBuild = replicaRowMode === "schema-only" ? false : replicaRowMode === "schema+data" ? "full" : "samples";
   const load = useCallback3(async () => {
     if (!docApi) return;
+    const includeRowsForBuild = replicaRowMode === "schema-only" ? false : replicaRowMode === "schema+data" ? "full" : "samples";
     setLoading(true);
     setError(null);
     try {
@@ -1813,18 +1878,21 @@ export {
   gristAttachmentCellValue,
   mergeGristAttachmentCellValue,
   isAccessInsufficientError,
+  checkGristCell,
+  encodeGristCell,
   deriveStatus,
   deriveColumnMappingStatus,
-  checkGristCell,
   parseGristWidgetLinkingInfo,
   resetGristForTests,
   useGrist,
   useGristOptional,
   useGristContext,
   useNearestGristState,
+  defineGristWidget,
+  isGristWidget,
   GristWidgetProvider,
   GristBoundary,
   useGristSchema,
   useWidgetMetadata
 };
-//# sourceMappingURL=chunk-O7NY46QY.js.map
+//# sourceMappingURL=chunk-MAPAWVQC.js.map