grist-widget-sdk 0.5.1 → 0.6.0

package/dist/{define-widget-B1FIvI-h.d.cts → define-widget-CYYdqRmB.d.cts}

@@ -1,4 +1,5 @@
 import { e as GristReplicaColumn, f as GristRowRecord, i as GristReadyOptions, j as GristFetchSelectedOptions, k as GristTableOperations, o as GristApplyUserActionsOptions, c as GristCursorPos, b as GristWidgetColumnMap } from './types-DBStn0Dk.cjs';
+import { GristUserActionTuple } from './actions.cjs';
 
 /**
  * Typed reads, with read-only access: each mapped cell checked against the
@@ -180,30 +181,6 @@ type FetchGristTableRowsOptions = {
 /** Turn `fetchTable` output into row objects (order follows the `id` column). */
 declare function tableDataToRows<T = Record<string, unknown>>(data: GristColumnarTable): GristRowRecord<T>[];
 
-/**
- * Grist `docApi.applyUserActions` payloads are arrays of user-action tuples.
- * @see https://support.getgrist.com/code/interfaces/grist_plugin_api.GristDocAPI/#applyuseractions
- */
-type GristUserActionTuple = unknown[];
-/** `["UpdateRecord", tableId, rowId, { col: value, ... }]` */
-declare function gristUpdateRecordAction(tableId: string, rowId: number, patch: Record<string, unknown>): GristUserActionTuple;
-/** `["AddRecord", tableId, null, { col: value, ... }]` */
-declare function gristAddRecordAction(tableId: string, values: Record<string, unknown>): GristUserActionTuple;
-/** `["RemoveRecord", tableId, rowId]` */
-declare function gristRemoveRecordAction(tableId: string, rowId: number): GristUserActionTuple;
-/** `["AddColumn", tableId, colId, colInfo]` — `colInfo` shape depends on Grist version / column type. */
-declare function gristAddColumnAction(tableId: string, colId: string, colInfo: Record<string, unknown>): GristUserActionTuple;
-/** `["AddVisibleColumn", tableId, colId, colInfo]` — like `AddColumn` but also adds the column to the current view section. */
-declare function gristAddVisibleColumnAction(tableId: string, colId: string, colInfo: Record<string, unknown>): GristUserActionTuple;
-/** `["RenameColumn", tableId, colId, newColId]` */
-declare function gristRenameColumnAction(tableId: string, colId: string, newColId: string): GristUserActionTuple;
-/** `["ModifyColumn", tableId, colId, colInfo]` */
-declare function gristModifyColumnAction(tableId: string, colId: string, colInfo: Record<string, unknown>): GristUserActionTuple;
-/** `["RemoveColumn", tableId, colId]` */
-declare function gristRemoveColumnAction(tableId: string, colId: string): GristUserActionTuple;
-/** `["AddTable", tableId, tableInfo]` */
-declare function gristAddTableAction(tableId: string, tableInfo: Record<string, unknown>): GristUserActionTuple;
-
 /**
  * The alerts `mountGristWidget()` shows above a running widget: what needs the
  * user's attention in Grist (column mapping, access, a failed write, an
@@ -262,10 +239,39 @@ type GristColumnInfo = {
     formula?: string;
     description?: string;
 };
+/** `fetchRows()` options: rows (the default) or Grist's columns. */
+type FetchRowsOptions = FetchGristTableRowsOptions & {
+    /** Grist's column-oriented payload (`{ id: [...], Name: [...] }`) instead of rows. */
+    columnar?: boolean;
+};
+/**
+ * A table's rows, each `{ id, ...cells }` under real column ids. Without a
+ * table id, the widget's own table as its section shows it (filters and
+ * sort applied); with one, any table (full access), in Grist's row order.
+ * `{ columnar: true }` gives Grist's columns instead.
+ */
+type FetchRows = {
+    <T extends Record<string, unknown> = Record<string, unknown>>(tableId?: string | null, options?: FetchRowsOptions & {
+        columnar?: false;
+    }): Promise<GristRowRecord<T>[]>;
+    <T extends Record<string, unknown> = Record<string, unknown>>(options: FetchRowsOptions & {
+        columnar?: false;
+    }): Promise<GristRowRecord<T>[]>;
+    (tableId: string | null | undefined, options: FetchRowsOptions & {
+        columnar: true;
+    }): Promise<GristColumnarTable>;
+    (options: FetchRowsOptions & {
+        columnar: true;
+    }): Promise<GristColumnarTable>;
+};
 type GristApi = {
     reload: () => Promise<void>;
+    fetchRows: FetchRows;
+    /** @deprecated Use `fetchRows({ columnar: true })` (or `fetchRows()` for rows). */
     fetchSelectedTable: (options?: GristFetchSelectedOptions) => Promise<GristColumnarTable>;
+    /** @deprecated Use `fetchRows(tableId, { columnar: true })` (or `fetchRows(tableId)` for rows). */
     fetchTable: (tableId: string) => Promise<GristColumnarTable>;
+    /** @deprecated Use `fetchRows(tableId, options)`. */
     fetchTableRows: <T extends Record<string, unknown> = Record<string, unknown>>(tableId: string, options?: FetchGristTableRowsOptions) => Promise<GristRowRecord<T>[]>;
     listTables: (options?: ListTablesOptions) => Promise<string[]>;
     listColumns: (tableId: string, options?: ListColumnsOptions) => Promise<GristColumnInfo[]>;
@@ -313,8 +319,9 @@ type GristWidgetMode = "empty" | "row" | "new-row";
 type UseGristResult<TRow = Record<string, unknown>, TMapped = Record<string, unknown>> = Omit<GristApi, "fetchTableRows"> & {
     /** `"booting"` until Grist answers, then `"ready"`; `"unavailable"` outside Grist; `"error"` otherwise. */
     status: GristWidgetStatus;
-    /** Inside Grist with its plugin API (null while connecting). */
+    /** @deprecated Use `status`: `status !== "unavailable"` once it isn't `"booting"`. */
     isAvailable: boolean | null;
+    /** @deprecated Use `status === "ready"`. */
     isReady: boolean;
     /** Why the widget can't run (status `"error"` or `"unavailable"`), else null. */
     error: string | null;
@@ -359,7 +366,7 @@ type UseGristResult<TRow = Record<string, unknown>, TMapped = Record<string, unk
     addRecord: (patch: GristRecordPatch<TMapped>) => Promise<number>;
     /** The section's table id. */
     currentTableId: string | null;
-    /** Any table as rows (full access). */
+    /** @deprecated Use `fetchRows(tableId, options)`. */
     fetchTableRows: <T extends Record<string, unknown> = Record<string, unknown>>(tableId: string, options?: Parameters<GristApi["fetchTableRows"]>[1]) => Promise<GristRowRecord<T>[]>;
     /** The last write's state. */
     actionStatus: GristWidgetActionStatus;
@@ -375,7 +382,10 @@ type UseGristResult<TRow = Record<string, unknown>, TMapped = Record<string, unk
 declare function useGrist<TRow = Record<string, unknown>, TMapped = Record<string, unknown>>(options?: UseGristOptions): UseGristResult<TRow, TMapped>;
 /** `useGrist()` inside a provider, or null outside one: for components that also work without Grist. */
 declare function useGristOptional<TRow = Record<string, unknown>, TMapped = Record<string, unknown>>(): UseGristResult<TRow, TMapped> | null;
-/** `useGrist()` inside `<GristWidgetProvider>`; throws outside one. */
+/**
+ * `useGrist()` inside `<GristWidgetProvider>`; throws outside one.
+ * @deprecated Use `widget.useGrist()` (or `useGrist()`): `mountGristWidget()` always renders the provider.
+ */
 declare function useGristContext<TRow = Record<string, unknown>, TMapped = Record<string, unknown>>(): UseGristResult<TRow, TMapped>;
 
 /**
@@ -429,5 +439,5 @@ type GristWidget<D extends GristWidgetDefinition = GristWidgetDefinition> = {
  */
 declare function defineGristWidget<const D extends GristWidgetDefinition>(definition: D): GristWidget<D>;
 
-export { gristAddVisibleColumnAction as A, gristAttachmentCellValue as B, gristAttachmentCellValues as C, gristModifyColumnAction as D, gristRemoveColumnAction as E, gristRemoveRecordAction as F, gristRenameColumnAction as H, gristUpdateRecordAction as I, mergeGristAttachmentCellValue as J, tableDataToRows as K, useGrist as M, useGristContext as N, useGristOptional as O, checkGristCell as s, defineGristWidget as t, encodeGristCell as u, extractGristAttachmentId as v, extractGristAttachmentIdsFromCell as w, gristAddColumnAction as x, gristAddRecordAction as y, gristAddTableAction as z };
-export type { GristWidget as G, ListColumnsOptions as L, StandardSchema as S, UseGristOptions as U, ValidateColumnMappingsResult as V, GristNoiseColumnsOptions as a, GristAttachmentUploadResult as b, GristCellIssue as c, GristColumnInfo as d, GristColumnarTable as e, GristFetchedAttachmentBlob as f, GristMappedRow as g, GristRecordPatch as h, GristSdkAlertKind as i, GristTheme as j, GristUserActionTuple as k, GristWidgetActionStatus as l, GristWidgetDefinition as m, GristWidgetMode as n, GristWidgetRow as o, GristWidgetStatus as p, ListTablesOptions as q, UseGristResult as r };
+export { tableDataToRows as A, useGrist as B, useGristContext as C, useGristOptional as D, checkGristCell as s, defineGristWidget as t, encodeGristCell as u, extractGristAttachmentId as v, extractGristAttachmentIdsFromCell as w, gristAttachmentCellValue as x, gristAttachmentCellValues as y, mergeGristAttachmentCellValue as z };
+export type { FetchRows as F, GristWidget as G, ListColumnsOptions as L, StandardSchema as S, UseGristOptions as U, ValidateColumnMappingsResult as V, GristNoiseColumnsOptions as a, FetchRowsOptions as b, GristAttachmentUploadResult as c, GristCellIssue as d, GristColumnInfo as e, GristColumnarTable as f, GristFetchedAttachmentBlob as g, GristMappedRow as h, GristRecordPatch as i, GristSdkAlertKind as j, GristTheme as k, GristWidgetActionStatus as l, GristWidgetDefinition as m, GristWidgetMode as n, GristWidgetRow as o, GristWidgetStatus as p, ListTablesOptions as q, UseGristResult as r };

package/dist/{define-widget-B9gEtJP0.d.ts → define-widget-D-NmSglS.d.ts}

@@ -1,4 +1,5 @@
 import { e as GristReplicaColumn, f as GristRowRecord, i as GristReadyOptions, j as GristFetchSelectedOptions, k as GristTableOperations, o as GristApplyUserActionsOptions, c as GristCursorPos, b as GristWidgetColumnMap } from './types-DBStn0Dk.js';
+import { GristUserActionTuple } from './actions.js';
 
 /**
  * Typed reads, with read-only access: each mapped cell checked against the
@@ -180,30 +181,6 @@ type FetchGristTableRowsOptions = {
 /** Turn `fetchTable` output into row objects (order follows the `id` column). */
 declare function tableDataToRows<T = Record<string, unknown>>(data: GristColumnarTable): GristRowRecord<T>[];
 
-/**
- * Grist `docApi.applyUserActions` payloads are arrays of user-action tuples.
- * @see https://support.getgrist.com/code/interfaces/grist_plugin_api.GristDocAPI/#applyuseractions
- */
-type GristUserActionTuple = unknown[];
-/** `["UpdateRecord", tableId, rowId, { col: value, ... }]` */
-declare function gristUpdateRecordAction(tableId: string, rowId: number, patch: Record<string, unknown>): GristUserActionTuple;
-/** `["AddRecord", tableId, null, { col: value, ... }]` */
-declare function gristAddRecordAction(tableId: string, values: Record<string, unknown>): GristUserActionTuple;
-/** `["RemoveRecord", tableId, rowId]` */
-declare function gristRemoveRecordAction(tableId: string, rowId: number): GristUserActionTuple;
-/** `["AddColumn", tableId, colId, colInfo]` — `colInfo` shape depends on Grist version / column type. */
-declare function gristAddColumnAction(tableId: string, colId: string, colInfo: Record<string, unknown>): GristUserActionTuple;
-/** `["AddVisibleColumn", tableId, colId, colInfo]` — like `AddColumn` but also adds the column to the current view section. */
-declare function gristAddVisibleColumnAction(tableId: string, colId: string, colInfo: Record<string, unknown>): GristUserActionTuple;
-/** `["RenameColumn", tableId, colId, newColId]` */
-declare function gristRenameColumnAction(tableId: string, colId: string, newColId: string): GristUserActionTuple;
-/** `["ModifyColumn", tableId, colId, colInfo]` */
-declare function gristModifyColumnAction(tableId: string, colId: string, colInfo: Record<string, unknown>): GristUserActionTuple;
-/** `["RemoveColumn", tableId, colId]` */
-declare function gristRemoveColumnAction(tableId: string, colId: string): GristUserActionTuple;
-/** `["AddTable", tableId, tableInfo]` */
-declare function gristAddTableAction(tableId: string, tableInfo: Record<string, unknown>): GristUserActionTuple;
-
 /**
  * The alerts `mountGristWidget()` shows above a running widget: what needs the
  * user's attention in Grist (column mapping, access, a failed write, an
@@ -262,10 +239,39 @@ type GristColumnInfo = {
     formula?: string;
     description?: string;
 };
+/** `fetchRows()` options: rows (the default) or Grist's columns. */
+type FetchRowsOptions = FetchGristTableRowsOptions & {
+    /** Grist's column-oriented payload (`{ id: [...], Name: [...] }`) instead of rows. */
+    columnar?: boolean;
+};
+/**
+ * A table's rows, each `{ id, ...cells }` under real column ids. Without a
+ * table id, the widget's own table as its section shows it (filters and
+ * sort applied); with one, any table (full access), in Grist's row order.
+ * `{ columnar: true }` gives Grist's columns instead.
+ */
+type FetchRows = {
+    <T extends Record<string, unknown> = Record<string, unknown>>(tableId?: string | null, options?: FetchRowsOptions & {
+        columnar?: false;
+    }): Promise<GristRowRecord<T>[]>;
+    <T extends Record<string, unknown> = Record<string, unknown>>(options: FetchRowsOptions & {
+        columnar?: false;
+    }): Promise<GristRowRecord<T>[]>;
+    (tableId: string | null | undefined, options: FetchRowsOptions & {
+        columnar: true;
+    }): Promise<GristColumnarTable>;
+    (options: FetchRowsOptions & {
+        columnar: true;
+    }): Promise<GristColumnarTable>;
+};
 type GristApi = {
     reload: () => Promise<void>;
+    fetchRows: FetchRows;
+    /** @deprecated Use `fetchRows({ columnar: true })` (or `fetchRows()` for rows). */
     fetchSelectedTable: (options?: GristFetchSelectedOptions) => Promise<GristColumnarTable>;
+    /** @deprecated Use `fetchRows(tableId, { columnar: true })` (or `fetchRows(tableId)` for rows). */
     fetchTable: (tableId: string) => Promise<GristColumnarTable>;
+    /** @deprecated Use `fetchRows(tableId, options)`. */
     fetchTableRows: <T extends Record<string, unknown> = Record<string, unknown>>(tableId: string, options?: FetchGristTableRowsOptions) => Promise<GristRowRecord<T>[]>;
     listTables: (options?: ListTablesOptions) => Promise<string[]>;
     listColumns: (tableId: string, options?: ListColumnsOptions) => Promise<GristColumnInfo[]>;
@@ -313,8 +319,9 @@ type GristWidgetMode = "empty" | "row" | "new-row";
 type UseGristResult<TRow = Record<string, unknown>, TMapped = Record<string, unknown>> = Omit<GristApi, "fetchTableRows"> & {
     /** `"booting"` until Grist answers, then `"ready"`; `"unavailable"` outside Grist; `"error"` otherwise. */
     status: GristWidgetStatus;
-    /** Inside Grist with its plugin API (null while connecting). */
+    /** @deprecated Use `status`: `status !== "unavailable"` once it isn't `"booting"`. */
     isAvailable: boolean | null;
+    /** @deprecated Use `status === "ready"`. */
     isReady: boolean;
     /** Why the widget can't run (status `"error"` or `"unavailable"`), else null. */
     error: string | null;
@@ -359,7 +366,7 @@ type UseGristResult<TRow = Record<string, unknown>, TMapped = Record<string, unk
     addRecord: (patch: GristRecordPatch<TMapped>) => Promise<number>;
     /** The section's table id. */
     currentTableId: string | null;
-    /** Any table as rows (full access). */
+    /** @deprecated Use `fetchRows(tableId, options)`. */
     fetchTableRows: <T extends Record<string, unknown> = Record<string, unknown>>(tableId: string, options?: Parameters<GristApi["fetchTableRows"]>[1]) => Promise<GristRowRecord<T>[]>;
     /** The last write's state. */
     actionStatus: GristWidgetActionStatus;
@@ -375,7 +382,10 @@ type UseGristResult<TRow = Record<string, unknown>, TMapped = Record<string, unk
 declare function useGrist<TRow = Record<string, unknown>, TMapped = Record<string, unknown>>(options?: UseGristOptions): UseGristResult<TRow, TMapped>;
 /** `useGrist()` inside a provider, or null outside one: for components that also work without Grist. */
 declare function useGristOptional<TRow = Record<string, unknown>, TMapped = Record<string, unknown>>(): UseGristResult<TRow, TMapped> | null;
-/** `useGrist()` inside `<GristWidgetProvider>`; throws outside one. */
+/**
+ * `useGrist()` inside `<GristWidgetProvider>`; throws outside one.
+ * @deprecated Use `widget.useGrist()` (or `useGrist()`): `mountGristWidget()` always renders the provider.
+ */
 declare function useGristContext<TRow = Record<string, unknown>, TMapped = Record<string, unknown>>(): UseGristResult<TRow, TMapped>;
 
 /**
@@ -429,5 +439,5 @@ type GristWidget<D extends GristWidgetDefinition = GristWidgetDefinition> = {
  */
 declare function defineGristWidget<const D extends GristWidgetDefinition>(definition: D): GristWidget<D>;
 
-export { gristAddVisibleColumnAction as A, gristAttachmentCellValue as B, gristAttachmentCellValues as C, gristModifyColumnAction as D, gristRemoveColumnAction as E, gristRemoveRecordAction as F, gristRenameColumnAction as H, gristUpdateRecordAction as I, mergeGristAttachmentCellValue as J, tableDataToRows as K, useGrist as M, useGristContext as N, useGristOptional as O, checkGristCell as s, defineGristWidget as t, encodeGristCell as u, extractGristAttachmentId as v, extractGristAttachmentIdsFromCell as w, gristAddColumnAction as x, gristAddRecordAction as y, gristAddTableAction as z };
-export type { GristWidget as G, ListColumnsOptions as L, StandardSchema as S, UseGristOptions as U, ValidateColumnMappingsResult as V, GristNoiseColumnsOptions as a, GristAttachmentUploadResult as b, GristCellIssue as c, GristColumnInfo as d, GristColumnarTable as e, GristFetchedAttachmentBlob as f, GristMappedRow as g, GristRecordPatch as h, GristSdkAlertKind as i, GristTheme as j, GristUserActionTuple as k, GristWidgetActionStatus as l, GristWidgetDefinition as m, GristWidgetMode as n, GristWidgetRow as o, GristWidgetStatus as p, ListTablesOptions as q, UseGristResult as r };
+export { tableDataToRows as A, useGrist as B, useGristContext as C, useGristOptional as D, checkGristCell as s, defineGristWidget as t, encodeGristCell as u, extractGristAttachmentId as v, extractGristAttachmentIdsFromCell as w, gristAttachmentCellValue as x, gristAttachmentCellValues as y, mergeGristAttachmentCellValue as z };
+export type { FetchRows as F, GristWidget as G, ListColumnsOptions as L, StandardSchema as S, UseGristOptions as U, ValidateColumnMappingsResult as V, GristNoiseColumnsOptions as a, FetchRowsOptions as b, GristAttachmentUploadResult as c, GristCellIssue as d, GristColumnInfo as e, GristColumnarTable as f, GristFetchedAttachmentBlob as g, GristMappedRow as h, GristRecordPatch as i, GristSdkAlertKind as j, GristTheme as k, GristWidgetActionStatus as l, GristWidgetDefinition as m, GristWidgetMode as n, GristWidgetRow as o, GristWidgetStatus as p, ListTablesOptions as q, UseGristResult as r };

package/dist/emulator/testing.cjs

@@ -47,6 +47,27 @@ var import_client = require("react-dom/client");
 // src/sdk/use-grist.ts
 var import_react = require("react");
 
+// src/sdk/helpers/deprecate.ts
+function isDevelopment() {
+  try {
+    return process.env.NODE_ENV !== "production";
+  } catch {
+    return false;
+  }
+}
+var warned = /* @__PURE__ */ new Set();
+function warnDeprecated(name, instead) {
+  if (warned.has(name) || !isDevelopment()) return;
+  warned.add(name);
+  console.warn(`[grist-widget-sdk] ${name} is deprecated and goes in 1.0: ${instead}. https://gristwidgets.com/docs/sdk/api/deprecated`);
+}
+function deprecatedFunction(name, instead, fn) {
+  return ((...args) => {
+    warnDeprecated(name, instead);
+    return fn(...args);
+  });
+}
+
 // src/sdk/helpers/grist-value-codec.ts
 var MARSHALLED_TAGS = /* @__PURE__ */ new Set(["E", "L", "D", "d", "R", "r", "P"]);
 function isMarshalledTuple(value) {
@@ -617,15 +638,32 @@ function createGristApi(runtime) {
     destroy: (ids) => write(() => resolve().destroy(ids))
   });
   const tables = /* @__PURE__ */ new Map();
+  const selectedColumns = (options) => read(async () => {
+    const impl = docApi().fetchSelectedTable ?? grist.fetchSelectedTable;
+    if (!impl) throw new Error("fetchSelectedTable is not available in this Grist version");
+    return await impl({ keepEncoded: false, ...options });
+  });
+  const tableColumns = (tableId) => read(async () => await docApi().fetchTable(tableId));
+  const fetchRows = (async (a, b) => {
+    const tableId = typeof a === "string" ? a : null;
+    const { columnar, ...rowOptions } = (typeof a === "object" && a !== null ? a : b) ?? {};
+    if (tableId === null) {
+      const data = await selectedColumns(rowOptions.columns ? { keepEncoded: true } : void 0);
+      return columnar ? data : materializeGristRowsFromColumnar(data, { order: "none", ...rowOptions });
+    }
+    if (columnar) return tableColumns(tableId);
+    return read(() => fetchGristTableRows(docApi(), tableId, rowOptions));
+  });
   return {
     reload: () => runtime.reload(),
-    fetchSelectedTable: (options) => read(async () => {
-      const impl = docApi().fetchSelectedTable ?? grist.fetchSelectedTable;
-      if (!impl) throw new Error("fetchSelectedTable is not available in this Grist version");
-      return await impl({ keepEncoded: false, ...options });
-    }),
-    fetchTable: (tableId) => read(async () => await docApi().fetchTable(tableId)),
-    fetchTableRows: (tableId, options) => read(() => fetchGristTableRows(docApi(), tableId, options ?? {})),
+    fetchRows,
+    fetchSelectedTable: deprecatedFunction("useGrist().fetchSelectedTable()", "use fetchRows({ columnar: true }), or fetchRows() for rows", selectedColumns),
+    fetchTable: deprecatedFunction("useGrist().fetchTable()", "use fetchRows(tableId, { columnar: true }), or fetchRows(tableId) for rows", tableColumns),
+    fetchTableRows: deprecatedFunction(
+      "useGrist().fetchTableRows()",
+      "use fetchRows(tableId, options)",
+      (tableId, options) => read(() => fetchGristTableRows(docApi(), tableId, options ?? {}))
+    ),
     listTables: (options) => read(async () => {
       const all = [...await docApi().listTables()];
       return options?.includeSystem ? all : all.filter((t) => !t.startsWith("_grist") && !t.startsWith("GristHidden_"));