grist-widget-sdk 0.3.26 → 0.4.0

package/dist/{inline-C7DkvuET.d.cts → templates-CGmRIQBV.d.cts}

@@ -1,4 +1,4 @@
-import { e as GristCursorPos, f as GristWidgetInteraction, d as GristWidgetColumnMap, c as GristReplicaColumn, G as GristRowRecord, g as GristReplicaSelection, h as GristWidgetConfiguration, i as GristReadyOptions, j as GristFetchSelectedOptions, k as GristTableOperations } from './types-D3JxUCfL.cjs';
+import { c as GristCursorPos, d as GristWidgetInteraction, b as GristWidgetColumnMap, e as GristReplicaColumn, f as GristRowRecord, g as GristReplicaSelection, h as GristWidgetConfiguration, i as GristReadyOptions, j as GristFetchSelectedOptions, k as GristTableOperations, G as GristReplicaDocument } from './types-DBStn0Dk.cjs';
 
 /**
  * Tiny pub-sub used to broadcast every emulator state change to:
@@ -108,7 +108,7 @@ type EmulatorDocumentState = {
 
 /**
  * Type-only signatures of the Grist plugin interfaces that the emulator
- * exposes to the widget (under both inline and iframe transports).
+ * exposes to the widget.
  *
  * These mirror the upstream `grist-plugin-api` contracts. We re-declare them
  * here instead of `import`ing the upstream types because:
@@ -182,7 +182,7 @@ type CommandApiImpl = {
 
 /**
  * Bundles the six host-side Grist API implementations into one record so
- * transports (iframe, inline) can wire them up uniformly.
+ * inline transport can wire them up.
  */
 
 type EmulatorApiBundle = {
@@ -208,26 +208,6 @@ type EmulatorTransport = {
     /** Replays the post-ready bootstrap (options + cursor + data) as if the widget had just connected. */
     emitInitialState: () => void;
 };
-type TransportContext = {
-    state: EmulatorDocumentState;
-    bus: EventBus;
-    api: EmulatorApiBundle;
-    /** Initial document theme replayed on widget ready (host message channel). */
-    initialTheme?: "light" | "dark";
-    /**
-     * Information piggybacked on `onOptions`. Same as `state.widgetInteraction`
-     * by default but transports may augment it (e.g. `access_level` derived
-     * from `state.configuration.requiredAccess`).
-     */
-    buildInteraction?: () => GristWidgetInteraction;
-    /**
-     * Cursor sentinel sent on initial connection. Defaults to the current
-     * `state.selection.rowId` (which can be `null`, `"new"`, or a numeric id).
-     */
-    initialCursor?: () => number | "new" | null;
-    /** Optional cursor sent alongside `onRecord` payloads. */
-    cursor?: () => GristCursorPos | undefined;
-};
 
 /**
  * Inline transport — synthesises a `window.grist` global wired directly to
@@ -291,22 +271,96 @@ type InlineGristGlobal = {
     };
     on: (eventName: string, listener: (...args: unknown[]) => void) => () => void;
 };
-type InlineTransportOptions = TransportContext & {
+
+/**
+ * Top-level emulator factory. Produces a fully-wired emulator instance:
+ *
+ *   - typed in-memory document state,
+ *   - shared event bus,
+ *   - the six host API impls,
+ *   - the inline transport, which installs `grist` on the page,
+ *   - imperative helpers (`mutate`, `apply`, `selectRow`, `selectTable`)
+ *     that drive the document via the action engine and emit corresponding
+ *     events.
+ *
+ * The instance is multi-instance friendly: nothing is stored on `window`.
+ */
+
+type CreateGristEmulatorOptions = {
+    /** The starting document (must satisfy {@link parseDocument}). */
+    document: GristReplicaDocument;
+    /** Installs `grist` on `target` (default: the global object). */
+    transport?: {
+        kind: "inline";
+        target?: Window & typeof globalThis;
+    };
+    /** Initial widget options exposed via `WidgetAPI`. */
+    widgetOptions?: Record<string, unknown>;
+    /**
+     * Initial widget interaction info (`access_level` and friends) sent
+     * alongside `onOptions`. Without an `access_level`, Grist grants the access
+     * the widget requests in `grist.ready()`.
+     */
+    widgetInteraction?: Record<string, unknown>;
+    /** Initial document theme replayed on widget ready (host `message` channel). */
+    initialTheme?: "light" | "dark";
+};
+type GristEmulator = {
+    /** Underlying mutable document. Treat as read-only outside of `mutate(...)`. */
+    state: EmulatorDocumentState;
+    bus: EventBus;
+    api: EmulatorApiBundle;
+    transport: EmulatorTransport;
+    /** Synthesised `grist` global (only for the inline transport). */
+    grist?: InlineGristGlobal;
+    /** Apply a list of Grist user actions; emits the matching events. */
+    apply: (actions: unknown[][]) => {
+        retValues: unknown[];
+    };
+    /** Convenience helpers for tests and demos. */
+    mutate: {
+        addRow: (tableId: string, fields: Record<string, unknown>) => number;
+        updateRow: (tableId: string, rowId: number, fields: Record<string, unknown>) => void;
+        removeRow: (tableId: string, rowId: number) => void;
+    };
+    selectRow: (rowId: number | "new" | null) => void;
+    selectTable: (tableId: string) => void;
     /**
-     * Where to mount the synthesised `grist` global.
-     * Defaults to the current window. Pass a different target (e.g. an iframe's
-     * `contentWindow`) to install it in another realm.
+     * Set logical→real column mappings, as a user mapping columns in Grist would.
+     * Pass `undefined` to clear — `mappings()` becomes `null` until set again.
      */
-    target?: Window & typeof globalThis;
+    setColumnMappings: (mappings: GristWidgetColumnMap | undefined) => void;
+    setOptions: (options: Record<string, unknown>) => Promise<void>;
+    setInteraction: (interaction: Record<string, unknown>) => void;
+    /** Host theme controls (`grist.on("message")` / `msg.theme`). */
+    theme: {
+        set: (theme: "light" | "dark") => void;
+    };
+    /** Tear down the emulator. Idempotent. */
+    dispose: () => void;
 };
+declare function createGristEmulator(options: CreateGristEmulatorOptions): GristEmulator;
+
 /**
- * Returns an {@link EmulatorTransport} **and** the synthesised `grist`
- * object. `target.grist = global` is set as a side-effect for parity with
- * the production runtime.
+ * Document templates exposed at the top of the emulator API.
+ *
+ * Templates return plain data — they don't allocate state, the caller passes
+ * the returned value into `createGristEmulator(...)` which performs the allocation.
  */
-declare function createInlineTransport(options: InlineTransportOptions): EmulatorTransport & {
-    grist: InlineGristGlobal;
+
+/**
+ * Useful templates for quick demos and tests.
+ */
+declare const presets: {
+    /**
+     * Default starter fixture for demos / sandboxes that need a neutral document
+     * without choosing a domain-specific preset.
+     */
+    defaultTemplate(): GristReplicaDocument;
+    blank(): GristReplicaDocument;
+    todoList(): GristReplicaDocument;
+    contacts(): GristReplicaDocument;
 };
 
-export { createInlineTransport as i };
-export type { EmulatorDocumentState as E, InlineGristGlobal as I, TransportContext as T, EmulatorEvent as a, EmulatorColumn as b, EmulatorApiBundle as c, EmulatorRowId as d, EmulatorTable as e, EmulatorTransport as f, EventBus as g, InlineTransportOptions as h };
+export { createGristEmulator as g, presets as p };
+export type { CreateGristEmulatorOptions as C, EmulatorColumn as E, GristEmulator as G, InlineGristGlobal as I, EmulatorDocumentState as a, EmulatorApiBundle as b, EmulatorEvent as c, EmulatorRowId as d, EmulatorTable as e, EmulatorTransport as f };

package/dist/{inline-DpcT8tV9.d.ts → templates-Cq94qOcf.d.ts}

@@ -1,4 +1,4 @@
-import { e as GristCursorPos, f as GristWidgetInteraction, d as GristWidgetColumnMap, c as GristReplicaColumn, G as GristRowRecord, g as GristReplicaSelection, h as GristWidgetConfiguration, i as GristReadyOptions, j as GristFetchSelectedOptions, k as GristTableOperations } from './types-D3JxUCfL.js';
+import { c as GristCursorPos, d as GristWidgetInteraction, b as GristWidgetColumnMap, e as GristReplicaColumn, f as GristRowRecord, g as GristReplicaSelection, h as GristWidgetConfiguration, i as GristReadyOptions, j as GristFetchSelectedOptions, k as GristTableOperations, G as GristReplicaDocument } from './types-DBStn0Dk.js';
 
 /**
  * Tiny pub-sub used to broadcast every emulator state change to:
@@ -108,7 +108,7 @@ type EmulatorDocumentState = {
 
 /**
  * Type-only signatures of the Grist plugin interfaces that the emulator
- * exposes to the widget (under both inline and iframe transports).
+ * exposes to the widget.
  *
  * These mirror the upstream `grist-plugin-api` contracts. We re-declare them
  * here instead of `import`ing the upstream types because:
@@ -182,7 +182,7 @@ type CommandApiImpl = {
 
 /**
  * Bundles the six host-side Grist API implementations into one record so
- * transports (iframe, inline) can wire them up uniformly.
+ * inline transport can wire them up.
  */
 
 type EmulatorApiBundle = {
@@ -208,26 +208,6 @@ type EmulatorTransport = {
     /** Replays the post-ready bootstrap (options + cursor + data) as if the widget had just connected. */
     emitInitialState: () => void;
 };
-type TransportContext = {
-    state: EmulatorDocumentState;
-    bus: EventBus;
-    api: EmulatorApiBundle;
-    /** Initial document theme replayed on widget ready (host message channel). */
-    initialTheme?: "light" | "dark";
-    /**
-     * Information piggybacked on `onOptions`. Same as `state.widgetInteraction`
-     * by default but transports may augment it (e.g. `access_level` derived
-     * from `state.configuration.requiredAccess`).
-     */
-    buildInteraction?: () => GristWidgetInteraction;
-    /**
-     * Cursor sentinel sent on initial connection. Defaults to the current
-     * `state.selection.rowId` (which can be `null`, `"new"`, or a numeric id).
-     */
-    initialCursor?: () => number | "new" | null;
-    /** Optional cursor sent alongside `onRecord` payloads. */
-    cursor?: () => GristCursorPos | undefined;
-};
 
 /**
  * Inline transport — synthesises a `window.grist` global wired directly to
@@ -291,22 +271,96 @@ type InlineGristGlobal = {
     };
     on: (eventName: string, listener: (...args: unknown[]) => void) => () => void;
 };
-type InlineTransportOptions = TransportContext & {
+
+/**
+ * Top-level emulator factory. Produces a fully-wired emulator instance:
+ *
+ *   - typed in-memory document state,
+ *   - shared event bus,
+ *   - the six host API impls,
+ *   - the inline transport, which installs `grist` on the page,
+ *   - imperative helpers (`mutate`, `apply`, `selectRow`, `selectTable`)
+ *     that drive the document via the action engine and emit corresponding
+ *     events.
+ *
+ * The instance is multi-instance friendly: nothing is stored on `window`.
+ */
+
+type CreateGristEmulatorOptions = {
+    /** The starting document (must satisfy {@link parseDocument}). */
+    document: GristReplicaDocument;
+    /** Installs `grist` on `target` (default: the global object). */
+    transport?: {
+        kind: "inline";
+        target?: Window & typeof globalThis;
+    };
+    /** Initial widget options exposed via `WidgetAPI`. */
+    widgetOptions?: Record<string, unknown>;
+    /**
+     * Initial widget interaction info (`access_level` and friends) sent
+     * alongside `onOptions`. Without an `access_level`, Grist grants the access
+     * the widget requests in `grist.ready()`.
+     */
+    widgetInteraction?: Record<string, unknown>;
+    /** Initial document theme replayed on widget ready (host `message` channel). */
+    initialTheme?: "light" | "dark";
+};
+type GristEmulator = {
+    /** Underlying mutable document. Treat as read-only outside of `mutate(...)`. */
+    state: EmulatorDocumentState;
+    bus: EventBus;
+    api: EmulatorApiBundle;
+    transport: EmulatorTransport;
+    /** Synthesised `grist` global (only for the inline transport). */
+    grist?: InlineGristGlobal;
+    /** Apply a list of Grist user actions; emits the matching events. */
+    apply: (actions: unknown[][]) => {
+        retValues: unknown[];
+    };
+    /** Convenience helpers for tests and demos. */
+    mutate: {
+        addRow: (tableId: string, fields: Record<string, unknown>) => number;
+        updateRow: (tableId: string, rowId: number, fields: Record<string, unknown>) => void;
+        removeRow: (tableId: string, rowId: number) => void;
+    };
+    selectRow: (rowId: number | "new" | null) => void;
+    selectTable: (tableId: string) => void;
     /**
-     * Where to mount the synthesised `grist` global.
-     * Defaults to the current window. Pass a different target (e.g. an iframe's
-     * `contentWindow`) to install it in another realm.
+     * Set logical→real column mappings, as a user mapping columns in Grist would.
+     * Pass `undefined` to clear — `mappings()` becomes `null` until set again.
      */
-    target?: Window & typeof globalThis;
+    setColumnMappings: (mappings: GristWidgetColumnMap | undefined) => void;
+    setOptions: (options: Record<string, unknown>) => Promise<void>;
+    setInteraction: (interaction: Record<string, unknown>) => void;
+    /** Host theme controls (`grist.on("message")` / `msg.theme`). */
+    theme: {
+        set: (theme: "light" | "dark") => void;
+    };
+    /** Tear down the emulator. Idempotent. */
+    dispose: () => void;
 };
+declare function createGristEmulator(options: CreateGristEmulatorOptions): GristEmulator;
+
 /**
- * Returns an {@link EmulatorTransport} **and** the synthesised `grist`
- * object. `target.grist = global` is set as a side-effect for parity with
- * the production runtime.
+ * Document templates exposed at the top of the emulator API.
+ *
+ * Templates return plain data — they don't allocate state, the caller passes
+ * the returned value into `createGristEmulator(...)` which performs the allocation.
  */
-declare function createInlineTransport(options: InlineTransportOptions): EmulatorTransport & {
-    grist: InlineGristGlobal;
+
+/**
+ * Useful templates for quick demos and tests.
+ */
+declare const presets: {
+    /**
+     * Default starter fixture for demos / sandboxes that need a neutral document
+     * without choosing a domain-specific preset.
+     */
+    defaultTemplate(): GristReplicaDocument;
+    blank(): GristReplicaDocument;
+    todoList(): GristReplicaDocument;
+    contacts(): GristReplicaDocument;
 };
 
-export { createInlineTransport as i };
-export type { EmulatorDocumentState as E, InlineGristGlobal as I, TransportContext as T, EmulatorEvent as a, EmulatorColumn as b, EmulatorApiBundle as c, EmulatorRowId as d, EmulatorTable as e, EmulatorTransport as f, EventBus as g, InlineTransportOptions as h };
+export { createGristEmulator as g, presets as p };
+export type { CreateGristEmulatorOptions as C, EmulatorColumn as E, GristEmulator as G, InlineGristGlobal as I, EmulatorDocumentState as a, EmulatorApiBundle as b, EmulatorEvent as c, EmulatorRowId as d, EmulatorTable as e, EmulatorTransport as f };

package/dist/{types-D3JxUCfL.d.cts → types-DBStn0Dk.d.cts}

@@ -86,7 +86,7 @@ type GristColumnToMap = {
     strictType?: boolean;
 };
 /** Argument shape for `grist.ready({ columns })`. */
-type GristColumnsToMap = Array<string | GristColumnToMap>;
+type GristColumnsToMap = ReadonlyArray<string | GristColumnToMap>;
 /**
  * Mapping returned by Grist between logical widget column names and real table column ids.
  * Single mappings are `string`; `allowMultiple` columns are `string[]`.
@@ -103,12 +103,6 @@ type GristReadyOptions = {
     allowSelectBy?: boolean;
     hasCustomOptions?: boolean;
     onEditOptions?: () => void | Promise<void>;
-    /** Passed to availability detection (default 10). */
-    availabilityMaxAttempts?: number;
-    /** Ms between availability polls (default 1000). */
-    availabilityIntervalMs?: number;
-    /** Log when the page is not iframe-embedded (default false). */
-    logWhenNotEmbedded?: boolean;
 };
 /** Optional second argument to `docApi.applyUserActions`. */
 type GristApplyUserActionsOptions = {
@@ -206,23 +200,5 @@ type GristTableOperations = {
     upsert: (records: GristTableUpsertRecord | GristTableUpsertRecord[], options?: GristTableUpsertOptions) => Promise<void>;
     destroy: (recordIds: number | number[]) => Promise<void>;
 };
-/** Subset of `grist.docApi` from https://docs.getgrist.com/grist-plugin-api.js */
-type GristDocApi = {
-    getDocName: () => Promise<string> | string;
-    listTables: () => Promise<string[]> | string[];
-    fetchTable: (tableId: string) => Promise<Record<string, unknown[]>>;
-    applyUserActions: (actions: unknown[][], options?: GristApplyUserActionsOptions) => Promise<unknown>;
-    /** Present when the widget requested sufficient access (e.g. full). */
-    getAccessToken?: (options?: {
-        readOnly?: boolean;
-    }) => Promise<{
-        token: string;
-        baseUrl: string;
-    }>;
-    /** Current section's table data (often smaller than {@link fetchTable} for the whole table). */
-    fetchSelectedTable?: (options?: GristFetchSelectedOptions) => Promise<Record<string, unknown[]>>;
-    /** Single row in the current section by numeric row id. */
-    fetchSelectedRecord?: (rowId: number, options?: GristFetchSelectedOptions) => Promise<Record<string, unknown>>;
-};
 
-export type { GristRowRecord as G, GristReplicaTable as a, GristReplicaDocument as b, GristReplicaColumn as c, GristWidgetColumnMap as d, GristCursorPos as e, GristWidgetInteraction as f, GristReplicaSelection as g, GristWidgetConfiguration as h, GristReadyOptions as i, GristFetchSelectedOptions as j, GristTableOperations as k, GristFormulaKind as l, GristReplicaRow as m, GristRequiredAccess as n, GristDocumentMode as o, GristApplyUserActionsOptions as p, GristColumnToMap as q, GristColumnsToMap as r, GristDocApi as s, GristMinimalRecord as t, GristTableNewRecord as u, GristTableOpOptions as v, GristTableUpdateRecord as w, GristTableUpsertOptions as x, GristTableUpsertRecord as y, GristWidgetLinkingInfo as z };
+export type { GristReplicaDocument as G, GristReplicaTable as a, GristWidgetColumnMap as b, GristCursorPos as c, GristWidgetInteraction as d, GristReplicaColumn as e, GristRowRecord as f, GristReplicaSelection as g, GristWidgetConfiguration as h, GristReadyOptions as i, GristFetchSelectedOptions as j, GristTableOperations as k, GristRequiredAccess as l, GristDocumentMode as m, GristFormulaKind as n, GristApplyUserActionsOptions as o, GristColumnToMap as p, GristColumnsToMap as q, GristReplicaRow as r };

package/dist/{types-D3JxUCfL.d.ts → types-DBStn0Dk.d.ts}

@@ -86,7 +86,7 @@ type GristColumnToMap = {
     strictType?: boolean;
 };
 /** Argument shape for `grist.ready({ columns })`. */
-type GristColumnsToMap = Array<string | GristColumnToMap>;
+type GristColumnsToMap = ReadonlyArray<string | GristColumnToMap>;
 /**
  * Mapping returned by Grist between logical widget column names and real table column ids.
  * Single mappings are `string`; `allowMultiple` columns are `string[]`.
@@ -103,12 +103,6 @@ type GristReadyOptions = {
     allowSelectBy?: boolean;
     hasCustomOptions?: boolean;
     onEditOptions?: () => void | Promise<void>;
-    /** Passed to availability detection (default 10). */
-    availabilityMaxAttempts?: number;
-    /** Ms between availability polls (default 1000). */
-    availabilityIntervalMs?: number;
-    /** Log when the page is not iframe-embedded (default false). */
-    logWhenNotEmbedded?: boolean;
 };
 /** Optional second argument to `docApi.applyUserActions`. */
 type GristApplyUserActionsOptions = {
@@ -206,23 +200,5 @@ type GristTableOperations = {
     upsert: (records: GristTableUpsertRecord | GristTableUpsertRecord[], options?: GristTableUpsertOptions) => Promise<void>;
     destroy: (recordIds: number | number[]) => Promise<void>;
 };
-/** Subset of `grist.docApi` from https://docs.getgrist.com/grist-plugin-api.js */
-type GristDocApi = {
-    getDocName: () => Promise<string> | string;
-    listTables: () => Promise<string[]> | string[];
-    fetchTable: (tableId: string) => Promise<Record<string, unknown[]>>;
-    applyUserActions: (actions: unknown[][], options?: GristApplyUserActionsOptions) => Promise<unknown>;
-    /** Present when the widget requested sufficient access (e.g. full). */
-    getAccessToken?: (options?: {
-        readOnly?: boolean;
-    }) => Promise<{
-        token: string;
-        baseUrl: string;
-    }>;
-    /** Current section's table data (often smaller than {@link fetchTable} for the whole table). */
-    fetchSelectedTable?: (options?: GristFetchSelectedOptions) => Promise<Record<string, unknown[]>>;
-    /** Single row in the current section by numeric row id. */
-    fetchSelectedRecord?: (rowId: number, options?: GristFetchSelectedOptions) => Promise<Record<string, unknown>>;
-};
 
-export type { GristRowRecord as G, GristReplicaTable as a, GristReplicaDocument as b, GristReplicaColumn as c, GristWidgetColumnMap as d, GristCursorPos as e, GristWidgetInteraction as f, GristReplicaSelection as g, GristWidgetConfiguration as h, GristReadyOptions as i, GristFetchSelectedOptions as j, GristTableOperations as k, GristFormulaKind as l, GristReplicaRow as m, GristRequiredAccess as n, GristDocumentMode as o, GristApplyUserActionsOptions as p, GristColumnToMap as q, GristColumnsToMap as r, GristDocApi as s, GristMinimalRecord as t, GristTableNewRecord as u, GristTableOpOptions as v, GristTableUpdateRecord as w, GristTableUpsertOptions as x, GristTableUpsertRecord as y, GristWidgetLinkingInfo as z };
+export type { GristReplicaDocument as G, GristReplicaTable as a, GristWidgetColumnMap as b, GristCursorPos as c, GristWidgetInteraction as d, GristReplicaColumn as e, GristRowRecord as f, GristReplicaSelection as g, GristWidgetConfiguration as h, GristReadyOptions as i, GristFetchSelectedOptions as j, GristTableOperations as k, GristRequiredAccess as l, GristDocumentMode as m, GristFormulaKind as n, GristApplyUserActionsOptions as o, GristColumnToMap as p, GristColumnsToMap as q, GristReplicaRow as r };