grist-widget-sdk 0.2.0

package/dist/emulator.d.ts

@@ -0,0 +1,107 @@
+import { k as GristReplicaDocument, n as GristReplicaTable, w as GristWidgetColumnMap } from './types-Fb2wplkv.js';
+export { C as CreateGristEmulatorOptions, G as GristEmulator, c as createGristEmulator } from './create-grist-emulator-C_0I4wax.js';
+export { p as presets } from './templates-BC7FoSdW.js';
+import { z } from 'zod';
+import { a as EmulatorColumn, b as EmulatorDocumentState } from './inline-QitZwXKP.js';
+export { E as EmulatorApiBundle, c as EmulatorEvent, d as EmulatorRowId, e as EmulatorTable, f as EmulatorTransport, I as InlineGristGlobal } from './inline-QitZwXKP.js';
+
+declare function safeParseDocument(input: unknown): z.ZodSafeParseResult<{
+    generatedAt: string;
+    tables: Record<string, {
+        label?: string | undefined;
+        columns?: Record<string, {
+            colRef?: number | undefined;
+            type?: string | undefined;
+            label?: string | undefined;
+            parentPos?: number | undefined;
+            isFormula?: boolean | undefined;
+            formulaKind?: "none" | "computed" | "trigger" | "empty_slot" | undefined;
+            formula?: string | undefined;
+            description?: string | undefined;
+            widgetOptions?: Record<string, unknown> | undefined;
+            displayColRef?: number | undefined;
+            visibleColRef?: number | undefined;
+        }> | undefined;
+        rows?: {
+            [x: string]: unknown;
+            id: number;
+        }[] | undefined;
+        rowCount?: number | undefined;
+        dataOmitted?: boolean | undefined;
+        dataOmittedReason?: string | undefined;
+        error?: string | undefined;
+    }>;
+    source?: string | undefined;
+    docName?: string | undefined;
+    mode?: "schema-only" | "schema+samples" | "schema+data" | undefined;
+    selection?: {
+        tableId?: string | undefined;
+        rowId?: number | "new" | null | undefined;
+        mappings?: unknown;
+        cursor?: unknown;
+    } | undefined;
+    widgetOptions?: Record<string, unknown> | undefined;
+    widgetInteraction?: unknown;
+    configuration?: {
+        requiredAccess?: string | undefined;
+        columns?: unknown;
+        allowSelectBy?: boolean | undefined;
+        hasCustomOptions?: boolean | undefined;
+    } | undefined;
+    accessToken?: {
+        token: string;
+        baseUrl: string;
+        ttlMsecs: number;
+    } | null | undefined;
+}>;
+declare function parseDocument(input: unknown): GristReplicaDocument;
+
+/** Replica table for {@link createDocument}; columns may include `formulaFn` / `inferredFormula` (emulator-only). */
+type CreateDocumentTableInput = Omit<GristReplicaTable, "columns"> & {
+    columns?: Record<string, EmulatorColumn>;
+};
+/** Replica document for {@link createDocument}; widens table columns to {@link EmulatorColumn}. */
+type CreateDocumentInput = Omit<GristReplicaDocument, "tables"> & {
+    tables: Record<string, CreateDocumentTableInput>;
+};
+/**
+ * Ensure `formula` (original) and `inferredFormula` strings exist alongside optional `formulaFn`.
+ */
+declare function enrichEmulatorColumnMetadata(col: EmulatorColumn): EmulatorColumn;
+
+/**
+ * Pure action engine: applies Grist user actions to an
+ * {@link EmulatorDocumentState} and emits the resulting events on the bus.
+ *
+ * This is the single place where state mutates. Every API impl ultimately
+ * routes through `applyUserActions` so behaviour is consistent regardless of
+ * the surface (`grist.docApi.applyUserActions`, `selectedTable.create`,
+ * `setCursorPos`, etc.).
+ *
+ * Supported user actions:
+ *   - AddRecord, BulkAddRecord
+ *   - UpdateRecord, BulkUpdateRecord
+ *   - RemoveRecord, BulkRemoveRecord
+ *   - AddColumn, RemoveColumn, RenameColumn, ModifyColumn
+ *   - AddTable, RemoveTable, RenameTable
+ *
+ * Unknown actions throw a structured error instead of silently succeeding,
+ * which surfaces protocol gaps loudly during widget development.
+ */
+
+declare class EmulatorActionError extends Error {
+    readonly action: unknown;
+    constructor(action: unknown, message: string);
+}
+
+/**
+ * Resolves the `mappings` payload that `CustomSectionAPI.mappings()` returns.
+ *
+ * The playground emulator does **not** infer logical → real columns from
+ * names. Mappings come only from `state.selection.mappings` (playground
+ * document inspector or tests). When unset, returns `null`.
+ */
+
+declare function resolveMappings(state: EmulatorDocumentState): GristWidgetColumnMap | null;
+
+export { type CreateDocumentInput, type CreateDocumentTableInput, EmulatorActionError, EmulatorColumn, EmulatorDocumentState, GristReplicaDocument, enrichEmulatorColumnMetadata, parseDocument, resolveMappings, safeParseDocument };

package/dist/emulator.js

@@ -0,0 +1,26 @@
+import {
+  createGristEmulator,
+  parseDocument,
+  presets,
+  safeParseDocument
+} from "./chunk-QZG7SNUG.js";
+import {
+  EmulatorActionError,
+  enrichEmulatorColumnMetadata
+} from "./chunk-QKXKZ27D.js";
+import "./chunk-GTTD5HPO.js";
+import "./chunk-ELGVOHFD.js";
+import {
+  resolveMappings
+} from "./chunk-PM3B4WYV.js";
+import "./chunk-64SVRWW7.js";
+export {
+  EmulatorActionError,
+  createGristEmulator,
+  enrichEmulatorColumnMetadata,
+  parseDocument,
+  presets,
+  resolveMappings,
+  safeParseDocument
+};
+//# sourceMappingURL=emulator.js.map

package/dist/emulator.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":[],"sourcesContent":[],"mappings":"","names":[]}