grist-widget-sdk 0.3.27 → 0.4.0

package/dist/use-grist-C5DMZ3wU.d.ts

@@ -0,0 +1,358 @@
+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';
+
+type ValidateColumnMappingsResult = {
+    ok: boolean;
+    /**
+     * `true` while the host has not yet reported column mappings (e.g. between
+     * `grist.ready()` resolving and the first `onRecord` / `onRecords` callback,
+     * or before `sectionApi.mappings()` returns). Callers should not gate UI or
+     * emit mapping alerts while pending.
+     */
+    pending?: boolean;
+    /** Logical names of required columns the user has not yet mapped. */
+    missing: string[];
+    /** Logical names of `allowMultiple` columns mapped to an empty list. */
+    emptyMultiples: string[];
+};
+
+type GristNoiseColumnsOptions = {
+    excludeId?: boolean;
+    excludeGristHelpers?: boolean;
+    excludeLoggingColumns?: boolean;
+    /**
+     * When `true`, treat Grist's `manualSort` column as noise (omit from filtered replicas).
+     * Default `false` — `manualSort` is kept unless you opt in.
+     */
+    excludeManualSort?: boolean;
+};
+
+type GristFetchedAttachmentBlob = {
+    blob: Blob;
+    contentType: string;
+};
+/**
+ * All attachment ids found in a Grist attachment cell value (ordered, deduped).
+ * Attachment columns are usually an **array** of file refs; a single id or one JSON object is also supported.
+ */
+declare function extractGristAttachmentIdsFromCell(value: unknown): string[];
+/** First attachment id in the cell, if any (see {@link extractGristAttachmentIdsFromCell}). */
+declare function extractGristAttachmentId(value: unknown): string | undefined;
+
+type GristEncodedAttachmentList = ["L", ...(number | string)[]];
+type GristAttachmentUploadResult = {
+    /** All attachment ids returned by `POST /attachments`. */
+    ids: string[];
+    /** First id in `ids` (convenience for single-file uploads). */
+    firstId: string;
+};
+/** Wire value for an Attachments cell (Grist list encoding). */
+declare function gristAttachmentCellValues(attachmentIds: (string | number)[]): GristEncodedAttachmentList;
+/** Wire value for a single-file Attachments cell. */
+declare function gristAttachmentCellValue(attachmentId: string | number): GristEncodedAttachmentList;
+/**
+ * Merge new attachment ids into an existing Attachments cell value (deduped, order preserved).
+ */
+declare function mergeGristAttachmentCellValue(existingCell: unknown, newIds: (string | number)[]): GristEncodedAttachmentList;
+
+/** Column-oriented table payload (`fetchTable`, `fetchSelectedTable`): `{ id: [...], Name: [...] }`. */
+type GristColumnarTable = Record<string, unknown[]>;
+type GristTableRowsOrder = "none" | "id" | "grist";
+type FetchGristTableRowsOptions = {
+    /** Column metadata, to decode each cell (except `id`) with `decodeGristValue`. */
+    columns?: Record<string, GristReplicaColumn>;
+    /**
+     * Row order:
+     * - `grist` (default): `manualSort` ascending when present, then `id`.
+     * - `id`: numeric `id` ascending.
+     * - `none`: as `fetchTable` returned them.
+     */
+    order?: GristTableRowsOrder;
+};
+/** 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;
+
+/**
+ * Typed reads, with read-only access: each mapped cell checked against the
+ * type its column declares in `GRIST_OPTIONS.columns`.
+ *
+ * Grist's mapping panel only offers the columns of the declared type, so for
+ * a mapped column the declaration is the contract; and the plugin API's
+ * decoded values already say what they are (a `Date`, a `Reference` with a
+ * `rowId`, a list of ids, a `RaisedException` for a formula error, the raw
+ * text of an invalid cell). Checked in Grist 1.7.22, every type, both
+ * `cellFormat`s. So a cell is turned into the JS value its type promises, or
+ * into `null` with an issue: no schema to fetch, no full access, no
+ * dependency.
+ */
+
+/** A mapped cell that didn't match its declared type, or a rule of the widget's schema. */
+type GristCellIssue = {
+    rowId: number;
+    /** The declared column name, or "" for a schema rule on the whole record. */
+    column: string;
+    message: string;
+    /** The value Grist sent. */
+    value: unknown;
+};
+type Check = {
+    ok: true;
+    value: unknown;
+} | {
+    ok: false;
+    message: string;
+};
+/**
+ * `value` as its declared `type` promises ("Numeric", "Ref:Tasks",
+ * "Text,Ref"…): a match of any listed type, or a failure that says why.
+ * Without a type (or "Any"), the value as it is.
+ */
+declare function checkGristCell(type: string | undefined, value: unknown): Check;
+/** Minimal Standard Schema (https://standardschema.dev): zod 4, valibot, arktype implement it. */
+type StandardSchema<T = unknown> = {
+    readonly "~standard": {
+        readonly version: 1;
+        readonly vendor: string;
+        readonly validate: (value: unknown) => {
+            readonly value: T;
+            readonly issues?: undefined;
+        } | {
+            readonly issues: ReadonlyArray<{
+                readonly message: string;
+                readonly path?: ReadonlyArray<PropertyKey | {
+                    key: PropertyKey;
+                }>;
+            }>;
+        } | Promise<unknown>;
+    };
+};
+type BaseOf<T extends string> = T extends `${infer B}:${string}` ? B : T;
+type CellOf<T extends string> = T extends `${infer A},${infer Rest}` ? CellOf<A> | CellOf<Rest> : BaseOf<T> extends "Text" ? string : BaseOf<T> extends "Numeric" | "Int" ? number | null : BaseOf<T> extends "Bool" ? boolean : BaseOf<T> extends "Date" | "DateTime" ? Date | null : BaseOf<T> extends "Choice" ? string | null : BaseOf<T> extends "ChoiceList" ? string[] : BaseOf<T> extends "Ref" ? number | null : BaseOf<T> extends "RefList" | "Attachments" ? number[] : unknown;
+type ColumnValue<C> = C extends {
+    type: infer T extends string;
+    allowMultiple: true;
+} ? CellOf<T>[] : C extends {
+    type: infer T extends string;
+} ? CellOf<T> : C extends {
+    allowMultiple: true;
+} ? unknown[] : unknown;
+type RequiredName<C> = C extends {
+    optional: true;
+} ? never : C extends string ? C : C extends {
+    name: infer N extends string;
+} ? N : never;
+type OptionalName<C> = C extends {
+    optional: true;
+    name: infer N extends string;
+} ? N : never;
+type ByName<Cs, N> = Extract<Cs, N | {
+    name: N;
+}>;
+/**
+ * The mapped record a `GRIST_OPTIONS` declaration gives, for `useGrist`'s
+ * second type argument. Declare the options with `as const satisfies
+ * UseGristOptions` so the column names and types stay literal:
+ *
+ * ```ts
+ * export const GRIST_OPTIONS = {
+ *   requiredAccess: "read table",
+ *   columns: [{ name: "Title", type: "Text" }, { name: "Due", type: "Date", optional: true }],
+ * } as const satisfies UseGristOptions
+ *
+ * const w = useGrist<GristRowRecord, GristMappedRow<typeof GRIST_OPTIONS>>()
+ * w.mappedRecord?.Due // Date | null | undefined
+ * ```
+ */
+type GristMappedRow<O extends {
+    columns?: readonly unknown[];
+}> = O["columns"] extends readonly (infer C)[] ? {
+    id: number;
+} & {
+    [N in RequiredName<C>]: ColumnValue<ByName<C, N>>;
+} & {
+    [N in OptionalName<C>]?: ColumnValue<ByName<C, N>>;
+} : Record<string, unknown>;
+
+/**
+ * The alerts `mountGristWidget()` shows above a running widget: what needs the
+ * user's attention in Grist (column mapping, access, a failed write, an
+ * unlinked section). The blocking states (not connected, access refused,
+ * required columns unmapped) are `<GristBoundary>`'s, not alerts.
+ */
+
+type GristSdkAlertKind = "column-mapping" | "mapping-pending" | "section-not-linked" | "source-not-wired" | "action-error" | "access-insufficient" | "map-back-skip" | "cell-issues";
+
+/**
+ * The widget's connection to Grist: one store, one `connect()`.
+ *
+ * The template loads `grist-plugin-api.js` with a classic blocking script, so
+ * `window.grist` is there when the widget starts, or it never will be: the
+ * check is synchronous (with one more look at `load`, for a page that loads
+ * the script asynchronously). Then `grist.ready()` once, and every Grist
+ * stream (records, options, mappings, theme) feeds one immutable state that
+ * React reads through `useSyncExternalStore`. No polling, no heartbeat: the
+ * iframe lives and dies with the Grist page, and a failed call fails where it
+ * was made.
+ */
+
+type GristTheme = "light" | "dark";
+type GristWidgetActionStatus = "idle" | "running" | "error";
+/** What a widget asks Grist for (`UseGristOptions`). */
+type GristRuntimeOptions = GristReadyOptions & {
+    /** Alert kinds mountGristWidget() never shows for this widget, e.g. ["section-not-linked"]. */
+    suppressAlerts?: GristSdkAlertKind[];
+    /**
+     * Extra rules for the mapped records, as a Standard Schema (zod 4,
+     * valibot, arktype…), checked after each cell's declared type. A record
+     * that fails keeps its typed values; its issues go to `cellIssues`.
+     */
+    schema?: StandardSchema;
+};
+
+/**
+ * `useGrist()`'s methods, created once per runtime: every one is
+ * referentially stable for the widget's lifetime, and reads `grist` when
+ * called (the emulator installs and removes it in tests).
+ */
+
+type ListTablesOptions = {
+    /** Include Grist's own tables (`_grist_*`, `GristHidden_*`). */
+    includeSystem?: boolean;
+};
+type ListColumnsOptions = GristNoiseColumnsOptions & {
+    /** Include every column, Grist's helper and bookkeeping ones too. */
+    includeSystem?: boolean;
+};
+type GristColumnInfo = {
+    colId: string;
+    type?: string;
+    label?: string;
+    isFormula?: boolean;
+    formula?: string;
+    description?: string;
+};
+type GristApi = {
+    reload: () => Promise<void>;
+    fetchSelectedTable: (options?: GristFetchSelectedOptions) => Promise<GristColumnarTable>;
+    fetchTable: (tableId: string) => Promise<GristColumnarTable>;
+    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[]>;
+    table: GristTableOperations;
+    getTable: (tableId: string) => GristTableOperations;
+    applyActions: (actions: GristUserActionTuple[], options?: GristApplyUserActionsOptions) => Promise<unknown>;
+    setWidgetOptions: (options: Record<string, unknown>) => Promise<void>;
+    patchWidgetOptions: (patch: Record<string, unknown>) => Promise<void>;
+    setCursorPosition: (pos: GristCursorPos) => Promise<void>;
+    setLinkedRowSelection: (rowIds: number[] | null) => Promise<void>;
+    getAttachmentUrl: (attachmentId: string, options?: {
+        readOnly?: boolean;
+    }) => Promise<string>;
+    fetchAttachmentBlob: (attachmentId: string, options?: {
+        readOnly?: boolean;
+    }) => Promise<GristFetchedAttachmentBlob>;
+    uploadAttachment: (file: Blob | File, options?: {
+        fileName?: string;
+    }) => Promise<GristAttachmentUploadResult>;
+    fetchWithAuth: (path: string, init?: RequestInit & {
+        readOnly?: boolean;
+    }) => Promise<Response>;
+};
+
+/**
+ * What `useGrist()` shows, derived from the runtime state: status, error,
+ * column-mapping status, the mapped record, and the access check. Pure
+ * functions, so they are tested without React or Grist.
+ */
+
+/** The widget's connection to Grist, as `useGrist().status` reports it. */
+type GristWidgetStatus = "booting" | "ready" | "unavailable" | "error";
+
+/** What the widget asks Grist for: access, columns to map, and the alerts it doesn't want. */
+type UseGristOptions = GristRuntimeOptions;
+/** Derived from the selection: no row, a row, or the add-row placeholder. */
+type GristWidgetMode = "empty" | "row" | "new-row";
+/**
+ * The widget's Grist state and API. Every method is referentially stable for
+ * the widget's lifetime: safe in effect dependencies. The object itself is
+ * new whenever a value changes; depend on the members you use, not on it.
+ */
+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). */
+    isAvailable: boolean | null;
+    isReady: boolean;
+    /** Why the widget can't run (status `"error"` or `"unavailable"`), else null. */
+    error: string | null;
+    /** Grist's light or dark theme, null until Grist sends it. */
+    theme: GristTheme | null;
+    /** The selected row, raw column ids. */
+    record: GristRowRecord<TRow> | null;
+    /** The section's rows (what its filters show), raw column ids. */
+    records: GristRowRecord<TRow>[] | null;
+    /**
+     * The selected row under the declared column names, each cell the JS value
+     * its declared type promises (a cell that doesn't match is null, and in
+     * `cellIssues`); null until every required column is mapped.
+     */
+    mappedRecord: TMapped | null;
+    /** Every row of the section, like `mappedRecord`. */
+    mappedRecords: TMapped[] | null;
+    /** The mapped cells that didn't match their declared type (or the widget's `schema`), by row. */
+    cellIssues: readonly GristCellIssue[];
+    /** Declared column name → the Grist column id(s) mapped to it. */
+    mappings: GristWidgetColumnMap;
+    /** Whether every required declared column is mapped (`pending` until Grist reports mappings). */
+    columnMappingStatus: ValidateColumnMappingsResult;
+    mode: GristWidgetMode;
+    /** The Grist column id mapped to a declared name, or the name itself. */
+    resolveMappedColumnId: (name: string) => string;
+    /** A patch under declared names, as real column ids for a write (multi-column mappings are skipped). */
+    mapBack: (patch: Partial<TMapped>) => Record<string, unknown>;
+    /** The section's table id. */
+    currentTableId: string | null;
+    /** Any table as rows (full access). */
+    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;
+    actionError: string | null;
+    /** The options Grist stores for this widget, null until it sends them. */
+    widgetOptions: Record<string, unknown> | null;
+};
+/**
+ * The widget's Grist state and API. Inside `<GristWidgetProvider>` it uses the
+ * provider's connection and ignores `options`; outside one, the page's, made
+ * with the first caller's `options`.
+ */
+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. */
+declare function useGristContext<TRow = Record<string, unknown>, TMapped = Record<string, unknown>>(): UseGristResult<TRow, TMapped>;
+
+export { gristRenameColumnAction as A, gristUpdateRecordAction as B, mergeGristAttachmentCellValue as C, tableDataToRows as D, useGrist as E, useGristContext as F, useGristOptional as H, checkGristCell as o, extractGristAttachmentId as p, extractGristAttachmentIdsFromCell as q, gristAddColumnAction as r, gristAddRecordAction as s, gristAddTableAction as t, gristAddVisibleColumnAction as u, gristAttachmentCellValue as v, gristAttachmentCellValues as w, gristModifyColumnAction as x, gristRemoveColumnAction as y, gristRemoveRecordAction as z };
+export type { GristNoiseColumnsOptions as G, ListColumnsOptions as L, StandardSchema as S, UseGristOptions as U, ValidateColumnMappingsResult as V, GristAttachmentUploadResult as a, GristCellIssue as b, GristColumnInfo as c, GristColumnarTable as d, GristFetchedAttachmentBlob as e, GristMappedRow as f, GristSdkAlertKind as g, GristTheme as h, GristUserActionTuple as i, GristWidgetActionStatus as j, GristWidgetMode as k, GristWidgetStatus as l, ListTablesOptions as m, UseGristResult as n };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "grist-widget-sdk",
-  "version": "0.3.27",
+  "version": "0.4.0",
   "description": "React hooks and helpers for Grist custom widgets",
   "license": "MIT",
   "engines": {
@@ -40,16 +40,6 @@
         "default": "./dist/index.cjs"
       }
     },
-    "./advanced": {
-      "import": {
-        "types": "./dist/advanced.d.ts",
-        "default": "./dist/advanced.js"
-      },
-      "require": {
-        "types": "./dist/advanced.d.cts",
-        "default": "./dist/advanced.cjs"
-      }
-    },
     "./app": {
       "import": {
         "types": "./dist/app.d.ts",
@@ -70,16 +60,6 @@
         "default": "./dist/emulator.cjs"
       }
     },
-    "./emulator/transports": {
-      "import": {
-        "types": "./dist/emulator/transports.d.ts",
-        "default": "./dist/emulator/transports.js"
-      },
-      "require": {
-        "types": "./dist/emulator/transports.d.cts",
-        "default": "./dist/emulator/transports.cjs"
-      }
-    },
     "./emulator/testing": {
       "import": {
         "types": "./dist/emulator/testing.d.ts",
@@ -90,16 +70,6 @@
         "default": "./dist/emulator/testing.cjs"
       }
     },
-    "./emulator/devtools": {
-      "import": {
-        "types": "./dist/emulator/devtools.d.ts",
-        "default": "./dist/emulator/devtools.js"
-      },
-      "require": {
-        "types": "./dist/emulator/devtools.d.cts",
-        "default": "./dist/emulator/devtools.cjs"
-      }
-    },
     "./tsconfig/app.json": "./tsconfig/app.json",
     "./tsconfig/node.json": "./tsconfig/node.json"
   },
@@ -118,22 +88,22 @@
     "@testing-library/dom": "^10",
     "@testing-library/jest-dom": "^7.0.1",
     "@testing-library/react": "^16.3.3",
-    "@types/node": "^26.6.5",
+    "@types/node": "^26.6.6",
     "@types/react": "^19.3.0",
     "@types/react-dom": "^19.3.0",
-    "@vitejs/plugin-react": "^6.1.2",
-    "@vitest/coverage-v8": "^5.0.5",
+    "@vitejs/plugin-react": "^6.2.1",
+    "@vitest/coverage-v8": "^5.1.0",
     "eslint": "^10.13.0",
     "eslint-plugin-react-hooks": "^7.1.1",
     "fast-check": "^4.10.2",
-    "globals": "^17.13.0",
+    "globals": "^17.14.0",
     "grist-plugin-api": "^0.0.1",
     "jsdom": "^30.1.3",
     "tsup": "^9.0.0",
     "typescript": "^6.0.3",
-    "typescript-eslint": "^8.72.0",
+    "typescript-eslint": "^8.72.1",
     "vite": "^8.3.5",
-    "vitest": "^5.0.5"
+    "vitest": "^5.1.0"
   },
   "dependencies": {
     "grain-rpc": "^0.1.7",
@@ -147,6 +117,7 @@
     "test:emulator": "vitest --run --project emulator --passWithNoTests",
     "test:coverage": "vitest --run --project unit --project emulator --coverage",
     "bench": "vitest run --project bench",
+    "bench:update": "BENCH_UPDATE=1 vitest run --project bench",
     "typecheck": "tsc -p tsconfig.json --noEmit && tsc -p tsconfig.vitest.json --noEmit",
     "lint": "eslint ."
   }