grist-widget-sdk 0.3.27 → 0.5.0

package/dist/mount-grist-widget-CkB-3iG_.d.ts

@@ -0,0 +1,137 @@
+import * as react from 'react';
+import { ComponentType, ReactNode } from 'react';
+import { U as UseGristOptions, G as GristWidget } from './define-widget-B9gEtJP0.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;
+    /** The page's title and description (the widget's `WIDGET_METADATA`, or its declaration's). */
+    metadata?: {
+        title?: string;
+        description?: string;
+    };
+    /**
+     * 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;
+};
+/**
+ * A widget's entry module, `src/app/App.tsx`, as `import * as entry` gives
+ * it: the widget as its default export, its declaration as `widget` (or, in
+ * a widget made before `defineGristWidget`, `GRIST_OPTIONS` and
+ * `WIDGET_METADATA`), and optionally its own `Alerts`, `LocalDevPage` and
+ * `ReleasePage`. Everything a widget customises lives there, in its own
+ * file: the template's `src/main.tsx` stays the same in every widget, and
+ * `create-grist-widget upgrade` can rewrite it without losing anything.
+ */
+type GristWidgetEntry = {
+    default: ComponentType;
+    widget?: GristWidget;
+    GRIST_OPTIONS?: UseGristOptions;
+    WIDGET_METADATA?: {
+        title?: string;
+        description?: string;
+    };
+    Alerts?: GristWidgetAppProps["Alerts"];
+    LocalDevPage?: GristWidgetAppProps["LocalDevPage"];
+    ReleasePage?: GristWidgetAppProps["ReleasePage"];
+};
+/** The props {@link GristWidgetApp} takes, from a widget's entry module. */
+declare function entryProps(entry: GristWidgetEntry, dev?: boolean): GristWidgetAppProps;
+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 * as entry from "./app/App"
+ *
+ * mountGristWidget(entry, { dev: import.meta.env.DEV })
+ * ```
+ *
+ * It reads the entry module's exports ({@link GristWidgetEntry}): the widget,
+ * its declaration and any page it replaces. The older form,
+ * `mountGristWidget({ App, options: GRIST_OPTIONS, dev })`, still works.
+ *
+ * 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(entry: GristWidgetEntry, options?: {
+    dev?: boolean;
+    root?: Element | string;
+}): MountedGristWidget;
+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, metadata, dev, Alerts, LocalDevPage, ReleasePage, }: GristWidgetAppProps): react.JSX.Element;
+
+export { GristWidgetApp as G, deployChannelLabel as e, entryProps as f, mountGristWidget as m, parseDeployPath as p };
+export type { DeployChannel as D, MountGristWidgetConfig as M, DeployPath as a, GristWidgetAppProps as b, GristWidgetEntry as c, MountedGristWidget as d };

package/dist/mount-grist-widget-Dtelqao_.d.cts

@@ -0,0 +1,137 @@
+import * as react from 'react';
+import { ComponentType, ReactNode } from 'react';
+import { U as UseGristOptions, G as GristWidget } from './define-widget-B1FIvI-h.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;
+    /** The page's title and description (the widget's `WIDGET_METADATA`, or its declaration's). */
+    metadata?: {
+        title?: string;
+        description?: string;
+    };
+    /**
+     * 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;
+};
+/**
+ * A widget's entry module, `src/app/App.tsx`, as `import * as entry` gives
+ * it: the widget as its default export, its declaration as `widget` (or, in
+ * a widget made before `defineGristWidget`, `GRIST_OPTIONS` and
+ * `WIDGET_METADATA`), and optionally its own `Alerts`, `LocalDevPage` and
+ * `ReleasePage`. Everything a widget customises lives there, in its own
+ * file: the template's `src/main.tsx` stays the same in every widget, and
+ * `create-grist-widget upgrade` can rewrite it without losing anything.
+ */
+type GristWidgetEntry = {
+    default: ComponentType;
+    widget?: GristWidget;
+    GRIST_OPTIONS?: UseGristOptions;
+    WIDGET_METADATA?: {
+        title?: string;
+        description?: string;
+    };
+    Alerts?: GristWidgetAppProps["Alerts"];
+    LocalDevPage?: GristWidgetAppProps["LocalDevPage"];
+    ReleasePage?: GristWidgetAppProps["ReleasePage"];
+};
+/** The props {@link GristWidgetApp} takes, from a widget's entry module. */
+declare function entryProps(entry: GristWidgetEntry, dev?: boolean): GristWidgetAppProps;
+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 * as entry from "./app/App"
+ *
+ * mountGristWidget(entry, { dev: import.meta.env.DEV })
+ * ```
+ *
+ * It reads the entry module's exports ({@link GristWidgetEntry}): the widget,
+ * its declaration and any page it replaces. The older form,
+ * `mountGristWidget({ App, options: GRIST_OPTIONS, dev })`, still works.
+ *
+ * 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(entry: GristWidgetEntry, options?: {
+    dev?: boolean;
+    root?: Element | string;
+}): MountedGristWidget;
+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, metadata, dev, Alerts, LocalDevPage, ReleasePage, }: GristWidgetAppProps): react.JSX.Element;
+
+export { GristWidgetApp as G, deployChannelLabel as e, entryProps as f, mountGristWidget as m, parseDeployPath as p };
+export type { DeployChannel as D, MountGristWidgetConfig as M, DeployPath as a, GristWidgetAppProps as b, GristWidgetEntry as c, MountedGristWidget as d };

package/dist/{inline-DpcT8tV9.d.ts → 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.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.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-C7DkvuET.d.cts → 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.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.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 };