grist-widget-sdk 0.3.27 → 0.5.0

package/dist/app.d.cts

@@ -1,104 +1,7 @@
-import * as react from 'react';
-import { ComponentType, ReactNode } from 'react';
-import { UseGristOptions } from './index.cjs';
-import './types-D3JxUCfL.cjs';
-import './use-grist-reads-DpjVuI0H.cjs';
-import 'zod';
-
-/**
- * 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;
+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';
 
 type WidgetTheme = "light" | "dark" | "system";
 type ResolvedWidgetTheme = "light" | "dark";
@@ -143,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,104 +1,7 @@
-import * as react from 'react';
-import { ComponentType, ReactNode } from 'react';
-import { UseGristOptions } from './index.js';
-import './types-D3JxUCfL.js';
-import './use-grist-reads-DUMvJgV7.js';
-import 'zod';
-
-/**
- * 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;
+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';
 
 type WidgetTheme = "light" | "dark" | "system";
 type ResolvedWidgetTheme = "light" | "dark";
@@ -143,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,20 +1,18 @@
 import {
   GristWidgetApp,
   deployChannelLabel,
+  entryProps,
   mountGristWidget,
   parseDeployPath,
   useReleasedVersions,
   useTheme
-} from "./chunk-6Y2IONGJ.js";
-import "./chunk-B4AKVSWV.js";
-import "./chunk-NO6FYX33.js";
-import "./chunk-GTTD5HPO.js";
-import "./chunk-REV5AUXD.js";
-import "./chunk-OPTOYD2Y.js";
-import "./chunk-64SVRWW7.js";
+} from "./chunk-LSALXIGM.js";
+import "./chunk-MAPAWVQC.js";
+import "./chunk-4ZGVKGDF.js";
 export {
   GristWidgetApp,
   deployChannelLabel,
+  entryProps,
   mountGristWidget,
   parseDeployPath,
   useReleasedVersions,

package/dist/chunk-4ZGVKGDF.js

@@ -0,0 +1,204 @@
+// src/sdk/helpers/grist-value-codec.ts
+var MARSHALLED_TAGS = /* @__PURE__ */ new Set(["E", "L", "D", "d", "R", "r", "P"]);
+function isMarshalledTuple(value) {
+  return Array.isArray(value) && typeof value[0] === "string" && value[0].length <= 2 && MARSHALLED_TAGS.has(value[0]);
+}
+function coerceGristDocApiRefRowId(value) {
+  if (typeof value === "number" && Number.isFinite(value)) return value;
+  if (!Array.isArray(value) || value.length < 2) return void 0;
+  const tag = value[0];
+  if (tag === "R" && typeof value[2] === "number" && Number.isFinite(value[2])) return value[2];
+  if (tag === "r" && typeof value[1] === "number" && Number.isFinite(value[1])) return value[1];
+  return void 0;
+}
+function looksLikeAttachmentColumn(column) {
+  return column?.type === "Attachments";
+}
+function looksLikeChoiceListColumn(column) {
+  return column?.type === "ChoiceList";
+}
+function looksLikeRefListColumn(column) {
+  return typeof column?.type === "string" && column.type.startsWith("RefList:");
+}
+function looksLikeRefColumn(column) {
+  return typeof column?.type === "string" && column.type.startsWith("Ref:");
+}
+function looksLikeDateColumn(column) {
+  return column?.type === "Date";
+}
+function looksLikeDateTimeColumn(column) {
+  return typeof column?.type === "string" && column.type.startsWith("DateTime");
+}
+function decodeGristValue(value, column) {
+  if (value === null || value === void 0) return null;
+  if (isMarshalledTuple(value)) {
+    const tag = value[0];
+    switch (tag) {
+      case "E":
+        return {
+          __error: true,
+          type: typeof value[1] === "string" ? value[1] : "Error",
+          message: typeof value[2] === "string" ? value[2] : void 0,
+          traceback: typeof value[3] === "string" ? value[3] : void 0
+        };
+      case "L":
+        return value.slice(1).map((v) => decodeGristValue(v, void 0));
+      case "D":
+        if (typeof value[1] === "number") return new Date(value[1] * 1e3);
+        return null;
+      case "d":
+        if (typeof value[1] === "number") return new Date(value[1] * 1e3);
+        return null;
+      case "R":
+        return {
+          __ref: true,
+          tableId: typeof value[1] === "string" ? value[1] : void 0,
+          rowId: typeof value[2] === "number" ? value[2] : 0
+        };
+      case "r":
+        return { __ref: true, rowId: typeof value[1] === "number" ? value[1] : 0 };
+      case "P":
+        return null;
+      default:
+        return null;
+    }
+  }
+  if (looksLikeDateColumn(column) || looksLikeDateTimeColumn(column)) {
+    if (typeof value === "number" && Number.isFinite(value)) return new Date(value * 1e3);
+  }
+  if (looksLikeRefColumn(column) && typeof value === "number") {
+    return { __ref: true, rowId: value };
+  }
+  if ((looksLikeRefListColumn(column) || looksLikeChoiceListColumn(column) || looksLikeAttachmentColumn(column)) && Array.isArray(value)) {
+    return value.map((v) => decodeGristValue(v, void 0));
+  }
+  if (typeof value === "string" || typeof value === "number" || typeof value === "boolean") return value;
+  if (Array.isArray(value)) return value.map((v) => decodeGristValue(v, void 0));
+  return null;
+}
+function isGristCellError(value) {
+  return Array.isArray(value) && value[0] === "E";
+}
+function encodeGristValue(value, column) {
+  if (value === null || value === void 0) return null;
+  if (looksLikeDateColumn(column) || looksLikeDateTimeColumn(column)) {
+    if (value instanceof Date) return Math.floor(value.getTime() / 1e3);
+    if (typeof value === "string") {
+      const parsed = Date.parse(value);
+      if (!Number.isNaN(parsed)) return Math.floor(parsed / 1e3);
+    }
+    if (typeof value === "number") return Math.floor(value);
+  }
+  if (looksLikeRefColumn(column)) {
+    if (typeof value === "number") return value;
+    if (value && typeof value === "object" && "rowId" in value) {
+      return value.rowId;
+    }
+  }
+  if (looksLikeRefListColumn(column) || looksLikeChoiceListColumn(column) || looksLikeAttachmentColumn(column)) {
+    if (Array.isArray(value)) {
+      const items = value.map((v) => {
+        if (v && typeof v === "object" && "rowId" in v) return v.rowId;
+        return v;
+      });
+      return ["L", ...items];
+    }
+  }
+  return value;
+}
+
+// src/sdk/helpers/grist-user-actions.ts
+function gristUpdateRecordAction(tableId, rowId, patch) {
+  return ["UpdateRecord", tableId, rowId, patch];
+}
+function gristAddRecordAction(tableId, values) {
+  return ["AddRecord", tableId, null, values];
+}
+function gristRemoveRecordAction(tableId, rowId) {
+  return ["RemoveRecord", tableId, rowId];
+}
+function gristBulkUpdateRecordAction(tableId, rowIds, columnarPatch) {
+  return ["BulkUpdateRecord", tableId, rowIds, columnarPatch];
+}
+function gristBulkAddRecordAction(tableId, values, rowIds) {
+  const length = inferBulkLength(values);
+  const ids = rowIds ?? new Array(length).fill(null);
+  return ["BulkAddRecord", tableId, ids, values];
+}
+function gristBulkRemoveRecordAction(tableId, rowIds) {
+  return ["BulkRemoveRecord", tableId, rowIds];
+}
+function gristAddColumnAction(tableId, colId, colInfo) {
+  return ["AddColumn", tableId, colId, colInfo];
+}
+function gristAddVisibleColumnAction(tableId, colId, colInfo) {
+  return ["AddVisibleColumn", tableId, colId, colInfo];
+}
+function gristRenameColumnAction(tableId, colId, newColId) {
+  return ["RenameColumn", tableId, colId, newColId];
+}
+function gristModifyColumnAction(tableId, colId, colInfo) {
+  return ["ModifyColumn", tableId, colId, colInfo];
+}
+function gristRemoveColumnAction(tableId, colId) {
+  return ["RemoveColumn", tableId, colId];
+}
+function gristAddTableAction(tableId, tableInfo) {
+  return ["AddTable", tableId, tableInfo];
+}
+function inferBulkLength(values) {
+  for (const arr of Object.values(values)) if (Array.isArray(arr)) return arr.length;
+  return 0;
+}
+
+// src/sdk/helpers/replica-normalize.ts
+function normalizeReplicaTableInput(table) {
+  return { ...table, rows: table.rows ?? [] };
+}
+function normalizeReplicaDocumentInput(doc) {
+  return {
+    ...doc,
+    tables: Object.fromEntries(
+      Object.entries(doc.tables).map(([tableId, t]) => [tableId, normalizeReplicaTableInput(t)])
+    )
+  };
+}
+function buildReplicaJsonPayload(doc, options) {
+  const limit = options.sampleRowLimit ?? 10;
+  const tables = Object.fromEntries(
+    Object.entries(doc.tables).map(([tid, t]) => {
+      if (options.includeRows === "none") {
+        const { rows: _r, ...rest } = t;
+        return [tid, rest];
+      }
+      if (options.includeRows === "samples") {
+        const r = t.rows ?? [];
+        return [tid, { ...t, rows: r.slice(0, limit) }];
+      }
+      return [tid, { ...t, rows: t.rows }];
+    })
+  );
+  return { ...doc, tables };
+}
+
+export {
+  coerceGristDocApiRefRowId,
+  decodeGristValue,
+  isGristCellError,
+  encodeGristValue,
+  normalizeReplicaDocumentInput,
+  buildReplicaJsonPayload,
+  gristUpdateRecordAction,
+  gristAddRecordAction,
+  gristRemoveRecordAction,
+  gristBulkUpdateRecordAction,
+  gristBulkAddRecordAction,
+  gristBulkRemoveRecordAction,
+  gristAddColumnAction,
+  gristAddVisibleColumnAction,
+  gristRenameColumnAction,
+  gristModifyColumnAction,
+  gristRemoveColumnAction,
+  gristAddTableAction
+};
+//# sourceMappingURL=chunk-4ZGVKGDF.js.map

package/dist/chunk-4ZGVKGDF.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../src/sdk/helpers/grist-value-codec.ts","../src/sdk/helpers/grist-user-actions.ts","../src/sdk/helpers/replica-normalize.ts"],"sourcesContent":["/**\n * Encoding helpers for Grist cell values.\n *\n * Grist sends some types as marshalled tuples or numeric epochs. This file\n * exposes pure decode/encode functions so widget code never has to spelunk\n * Grist's wire format.\n *\n * References: Grist `grist/RowRecord` and `grist/DocActions` typings.\n */\n\nimport type { GristReplicaColumn } from \"../types\"\n\n/** `[\"E\", \"ErrorClass\", \"message\", traceback?]` — Grist error sentinel. */\nexport type GristEncodedError = [\"E\", string, string?, string?]\n/** `[\"L\", ...items]` — list (used for ChoiceList, RefList, Attachments). */\nexport type GristEncodedList = [\"L\", ...unknown[]]\n/** `[\"D\", epochSeconds, \"tz/Name\"]` — DateTime with timezone. */\nexport type GristEncodedDateTime = [\"D\", number, string]\n/** `[\"d\", epochSeconds]` — Date (no time). */\nexport type GristEncodedDate = [\"d\", number]\n/** `[\"R\", tableId, rowId]` — explicit reference. */\nexport type GristEncodedRef = [\"R\", string, number]\n/** `[\"r\", rowId]` — bare reference (when table is contextual). */\nexport type GristEncodedBareRef = [\"r\", number]\n/** `[\"P\", encoded]` — pending marker. */\nexport type GristEncodedPending = [\"P\"]\n\nexport type GristDecodedValue =\n  | null\n  | string\n  | number\n  | boolean\n  | Date\n  | GristDecodedValue[]\n  | { __error: true; type: string; message?: string; traceback?: string }\n  | { __ref: true; tableId?: string; rowId: number }\n\nconst MARSHALLED_TAGS = new Set([\"E\", \"L\", \"D\", \"d\", \"R\", \"r\", \"P\"])\n\nfunction isMarshalledTuple(value: unknown): value is unknown[] {\n  return (\n    Array.isArray(value) &&\n    typeof value[0] === \"string\" &&\n    value[0].length <= 2 &&\n    MARSHALLED_TAGS.has(value[0])\n  )\n}\n\n/**\n * Normalises a Grist `fetchTable` cell that points at a row in another table.\n * Most payloads use a bare numeric row id, but `Ref:*` values may appear as\n * `[\"R\", tableId, rowId]` or `[\"r\", rowId]` (same shape as {@link decodeGristValue}).\n */\nexport function coerceGristDocApiRefRowId(value: unknown): number | undefined {\n  if (typeof value === \"number\" && Number.isFinite(value)) return value\n  if (!Array.isArray(value) || value.length < 2) return undefined\n  const tag = value[0]\n  if (tag === \"R\" && typeof value[2] === \"number\" && Number.isFinite(value[2])) return value[2]\n  if (tag === \"r\" && typeof value[1] === \"number\" && Number.isFinite(value[1])) return value[1]\n  return undefined\n}\n\nfunction looksLikeAttachmentColumn(column?: GristReplicaColumn): boolean {\n  return column?.type === \"Attachments\"\n}\n\nfunction looksLikeChoiceListColumn(column?: GristReplicaColumn): boolean {\n  return column?.type === \"ChoiceList\"\n}\n\nfunction looksLikeRefListColumn(column?: GristReplicaColumn): boolean {\n  return typeof column?.type === \"string\" && column.type.startsWith(\"RefList:\")\n}\n\nfunction looksLikeRefColumn(column?: GristReplicaColumn): boolean {\n  return typeof column?.type === \"string\" && column.type.startsWith(\"Ref:\")\n}\n\nfunction looksLikeDateColumn(column?: GristReplicaColumn): boolean {\n  return column?.type === \"Date\"\n}\n\nfunction looksLikeDateTimeColumn(column?: GristReplicaColumn): boolean {\n  return typeof column?.type === \"string\" && column.type.startsWith(\"DateTime\")\n}\n\n/**\n * Decodes a Grist cell value into an idiomatic JS value.\n *\n * Pass the column's metadata (from `useGristSchema` or `_grist_Tables_column`)\n * for type-aware decoding (e.g. `Date` columns return `Date` even when stored as a number).\n */\nexport function decodeGristValue(value: unknown, column?: GristReplicaColumn): GristDecodedValue {\n  if (value === null || value === undefined) return null\n\n  if (isMarshalledTuple(value)) {\n    const tag = value[0] as string\n    switch (tag) {\n      case \"E\":\n        return {\n          __error: true,\n          type: typeof value[1] === \"string\" ? value[1] : \"Error\",\n          message: typeof value[2] === \"string\" ? value[2] : undefined,\n          traceback: typeof value[3] === \"string\" ? value[3] : undefined,\n        }\n      case \"L\":\n        return value.slice(1).map((v) => decodeGristValue(v, undefined)) as GristDecodedValue[]\n      case \"D\":\n        if (typeof value[1] === \"number\") return new Date(value[1] * 1000)\n        return null\n      case \"d\":\n        if (typeof value[1] === \"number\") return new Date(value[1] * 1000)\n        return null\n      case \"R\":\n        return {\n          __ref: true,\n          tableId: typeof value[1] === \"string\" ? value[1] : undefined,\n          rowId: typeof value[2] === \"number\" ? value[2] : 0,\n        }\n      case \"r\":\n        return { __ref: true, rowId: typeof value[1] === \"number\" ? value[1] : 0 }\n      case \"P\":\n        return null\n      default:\n        return null\n    }\n  }\n\n  if (looksLikeDateColumn(column) || looksLikeDateTimeColumn(column)) {\n    if (typeof value === \"number\" && Number.isFinite(value)) return new Date(value * 1000)\n  }\n\n  if (looksLikeRefColumn(column) && typeof value === \"number\") {\n    return { __ref: true, rowId: value }\n  }\n\n  if ((looksLikeRefListColumn(column) || looksLikeChoiceListColumn(column) || looksLikeAttachmentColumn(column)) && Array.isArray(value)) {\n    return value.map((v) => decodeGristValue(v, undefined)) as GristDecodedValue[]\n  }\n\n  if (typeof value === \"string\" || typeof value === \"number\" || typeof value === \"boolean\") return value\n  if (Array.isArray(value)) return value.map((v) => decodeGristValue(v, undefined)) as GristDecodedValue[]\n  return null\n}\n\n/** Convenience: true when the cell is a Grist error sentinel. */\nexport function isGristCellError(value: unknown): value is GristEncodedError {\n  return Array.isArray(value) && value[0] === \"E\"\n}\n\n/**\n * Encodes a JS value into Grist's expected wire form for a given column type.\n *\n * Use before passing values to `applyUserActions` or `TableOperations.update`\n * for `Date`, `DateTime`, `Ref`, `RefList`, and `ChoiceList` columns.\n */\nexport function encodeGristValue(value: unknown, column?: GristReplicaColumn): unknown {\n  if (value === null || value === undefined) return null\n\n  if (looksLikeDateColumn(column) || looksLikeDateTimeColumn(column)) {\n    if (value instanceof Date) return Math.floor(value.getTime() / 1000)\n    if (typeof value === \"string\") {\n      const parsed = Date.parse(value)\n      if (!Number.isNaN(parsed)) return Math.floor(parsed / 1000)\n    }\n    if (typeof value === \"number\") return Math.floor(value)\n  }\n\n  if (looksLikeRefColumn(column)) {\n    if (typeof value === \"number\") return value\n    if (value && typeof value === \"object\" && \"rowId\" in value) {\n      return (value as { rowId: number }).rowId\n    }\n  }\n\n  if (looksLikeRefListColumn(column) || looksLikeChoiceListColumn(column) || looksLikeAttachmentColumn(column)) {\n    if (Array.isArray(value)) {\n      const items = value.map((v) => {\n        if (v && typeof v === \"object\" && \"rowId\" in v) return (v as { rowId: number }).rowId\n        return v\n      })\n      return [\"L\", ...items]\n    }\n  }\n\n  return value\n}\n","/**\n * Grist `docApi.applyUserActions` payloads are arrays of user-action tuples.\n * @see https://support.getgrist.com/code/interfaces/grist_plugin_api.GristDocAPI/#applyuseractions\n */\n\nexport type GristUserActionTuple = unknown[]\n\n/** `[\"UpdateRecord\", tableId, rowId, { col: value, ... }]` */\nexport function gristUpdateRecordAction(\n  tableId: string,\n  rowId: number,\n  patch: Record<string, unknown>\n): GristUserActionTuple {\n  return [\"UpdateRecord\", tableId, rowId, patch]\n}\n\n/** `[\"AddRecord\", tableId, null, { col: value, ... }]` */\nexport function gristAddRecordAction(tableId: string, values: Record<string, unknown>): GristUserActionTuple {\n  return [\"AddRecord\", tableId, null, values]\n}\n\n/** `[\"RemoveRecord\", tableId, rowId]` */\nexport function gristRemoveRecordAction(tableId: string, rowId: number): GristUserActionTuple {\n  return [\"RemoveRecord\", tableId, rowId]\n}\n\n/** `[\"AddColumn\", tableId, colId, colInfo]` — `colInfo` shape depends on Grist version / column type. */\nexport function gristBulkUpdateRecordAction(\n  tableId: string,\n  rowIds: number[],\n  columnarPatch: Record<string, unknown[]>\n): GristUserActionTuple {\n  return [\"BulkUpdateRecord\", tableId, rowIds, columnarPatch]\n}\n\n/**\n * `[\"BulkAddRecord\", tableId, rowIds | nullArray, { col: value[], ... }]`.\n * Pass `null` (or omit) for `rowIds` to let Grist allocate ids; in user-action\n * format Grist expects an array of nulls of the same length as the value arrays.\n */\nexport function gristBulkAddRecordAction(\n  tableId: string,\n  values: Record<string, unknown[]>,\n  rowIds?: Array<number | null>\n): GristUserActionTuple {\n  const length = inferBulkLength(values)\n  const ids = rowIds ?? new Array<number | null>(length).fill(null)\n  return [\"BulkAddRecord\", tableId, ids, values]\n}\n\n/** `[\"BulkRemoveRecord\", tableId, rowIds]` */\nexport function gristBulkRemoveRecordAction(tableId: string, rowIds: number[]): GristUserActionTuple {\n  return [\"BulkRemoveRecord\", tableId, rowIds]\n}\n\n/** `[\"AddColumn\", tableId, colId, colInfo]` — `colInfo` shape depends on Grist version / column type. */\nexport function gristAddColumnAction(tableId: string, colId: string, colInfo: Record<string, unknown>): GristUserActionTuple {\n  return [\"AddColumn\", tableId, colId, colInfo]\n}\n\n/** `[\"AddVisibleColumn\", tableId, colId, colInfo]` — like `AddColumn` but also adds the column to the current view section. */\nexport function gristAddVisibleColumnAction(tableId: string, colId: string, colInfo: Record<string, unknown>): GristUserActionTuple {\n  return [\"AddVisibleColumn\", tableId, colId, colInfo]\n}\n\n/** `[\"RenameColumn\", tableId, colId, newColId]` */\nexport function gristRenameColumnAction(tableId: string, colId: string, newColId: string): GristUserActionTuple {\n  return [\"RenameColumn\", tableId, colId, newColId]\n}\n\n/** `[\"ModifyColumn\", tableId, colId, colInfo]` */\nexport function gristModifyColumnAction(tableId: string, colId: string, colInfo: Record<string, unknown>): GristUserActionTuple {\n  return [\"ModifyColumn\", tableId, colId, colInfo]\n}\n\n/** `[\"RemoveColumn\", tableId, colId]` */\nexport function gristRemoveColumnAction(tableId: string, colId: string): GristUserActionTuple {\n  return [\"RemoveColumn\", tableId, colId]\n}\n\n/** `[\"AddTable\", tableId, tableInfo]` */\nexport function gristAddTableAction(tableId: string, tableInfo: Record<string, unknown>): GristUserActionTuple {\n  return [\"AddTable\", tableId, tableInfo]\n}\n\nfunction inferBulkLength(values: Record<string, unknown[]>): number {\n  for (const arr of Object.values(values)) if (Array.isArray(arr)) return arr.length\n  return 0\n}\n","import type { GristReplicaDocument, GristReplicaRow, GristReplicaTable } from \"../replica-document\"\n\n/**\n * Ensure `rows` is a concrete array for emulator / merge logic.\n * Call at host boundaries (`createDocument`, tests); JSON may still omit `rows` for schema-only.\n */\nexport function normalizeReplicaTableInput<T extends GristReplicaTable>(table: T): T & { rows: GristReplicaRow[] } {\n  return { ...table, rows: table.rows ?? [] }\n}\n\n/** Apply {@link normalizeReplicaTableInput} to every table; shallow-copies the document shell. */\nexport function normalizeReplicaDocumentInput<T extends GristReplicaDocument>(doc: T): T {\n  return {\n    ...doc,\n    tables: Object.fromEntries(\n      Object.entries(doc.tables).map(([tableId, t]) => [tableId, normalizeReplicaTableInput(t)])\n    ),\n  } as T\n}\n\n/** How row arrays appear in serialized replica JSON from {@link buildReplicaJsonPayload}. */\nexport type ReplicaJsonIncludeRows = \"none\" | \"samples\" | \"full\"\n\n/**\n * Clone a replica document for JSON output: strip rows, cap to first N, or pass through.\n * Does not mutate the source document.\n */\nexport function buildReplicaJsonPayload(\n  doc: GristReplicaDocument,\n  options: { includeRows: ReplicaJsonIncludeRows; sampleRowLimit?: number }\n): GristReplicaDocument {\n  const limit = options.sampleRowLimit ?? 10\n  const tables = Object.fromEntries(\n    Object.entries(doc.tables).map(([tid, t]) => {\n      if (options.includeRows === \"none\") {\n        const { rows: _r, ...rest } = t\n        return [tid, rest]\n      }\n      if (options.includeRows === \"samples\") {\n        const r = t.rows ?? []\n        return [tid, { ...t, rows: r.slice(0, limit) }]\n      }\n      return [tid, { ...t, rows: t.rows }]\n    })\n  ) as GristReplicaDocument[\"tables\"]\n  return { ...doc, tables }\n}\n"],"mappings":"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","names":[]}