grist-widget-sdk 0.3.20 → 0.3.26

package/dist/index.d.ts

@@ -1,136 +1,21 @@
-import { l as GristDocApi, m as GristFormulaKind, c as GristReplicaColumn, b as GristReplicaDocument, a as GristReplicaTable, n as GristReplicaRow, o as GristColumnsToMap, d as GristWidgetColumnMap, G as GristRowRecord, f as GristWidgetInteraction, k as GristTableOperations, p as GristApplyUserActionsOptions, j as GristFetchSelectedOptions, e as GristCursorPos, i as GristReadyOptions, q as GristRequiredAccess, r as GristDocumentMode } from './types-YcRfo7oy.js';
-export { s as GristColumnToMap, t as GristMinimalRecord, g as GristReplicaSelection, u as GristTableNewRecord, v as GristTableOpOptions, w as GristTableUpdateRecord, x as GristTableUpsertOptions, y as GristTableUpsertRecord, h as GristWidgetConfiguration, z as GristWidgetLinkingInfo } from './types-YcRfo7oy.js';
-import { a as GristWidgetStatus, b as GristUserActionTuple, U as UseGristCoreResult, c as UseGristCoreOptions, d as GristCapabilities, e as GristColumnarTable, F as FetchGristTableRowsOptions, S as SafeParseGristTableDataOptions, f as GristSafeParseCellResult, L as ListTablesOptions, g as ListColumnsOptions, h as GristColumnInfo, i as GristAccessToken, j as GristNoiseColumnsOptions } from './use-grist-widget-options-from-context-hl-NwOwP.js';
+import { l as GristFormulaKind, c as GristReplicaColumn, b as GristReplicaDocument, a as GristReplicaTable, m as GristReplicaRow, n as GristRequiredAccess, o as GristDocumentMode, i as GristReadyOptions } from './types-D3JxUCfL.js';
+export { p as GristApplyUserActionsOptions, q as GristColumnToMap, r as GristColumnsToMap, e as GristCursorPos, s as GristDocApi, j as GristFetchSelectedOptions, t as GristMinimalRecord, g as GristReplicaSelection, G as GristRowRecord, u as GristTableNewRecord, v as GristTableOpOptions, k as GristTableOperations, w as GristTableUpdateRecord, x as GristTableUpsertOptions, y as GristTableUpsertRecord, d as GristWidgetColumnMap, h as GristWidgetConfiguration, f as GristWidgetInteraction, z as GristWidgetLinkingInfo } from './types-D3JxUCfL.js';
+import { G as GristSdkAlertsWidgetSlice, a as UseGristResult, b as GetGristSdkAlertDescriptorsOptions, c as GristSdkAlertDescriptor, U as UseGristOptions, d as UseGristSelectionResult, e as UseGristStatusResult, f as UseGristThemeResult, g as UseGristWritesResult } from './use-grist-types-kwxoFeub.js';
+export { B as BuildReplicaDocumentFromDocApiOptions, h as GristAttachmentUploadResult, i as GristEncodedAttachmentList, j as GristFetchedAttachment, k as GristFetchedAttachmentBlob, l as GristSdkAlertKind, m as GristSdkAlertSeverity, n as GristTheme, o as GristWidgetActionStatus, p as GristWidgetMode, R as ReplicaTableColumnMetaLite, V as ValidateColumnMappingsResult, q as buildReplicaColumnsFromColumnar, r as buildReplicaDocumentFromDocApi, s as extractAttachmentIdsFromUploadPayload, t as extractFirstAttachmentIdFromUploadPayload, u as extractGristAttachmentId, v as extractGristAttachmentIdsFromCell, w as fetchAttachmentBase64, x as fetchAttachmentBase64ForCell, y as fetchAttachmentBlob, z as formatAccessInsufficientMessage, A as formatColumnMappingAlertMessage, C as formatLinkStaleAlertMessage, D as formatMappingPendingAlertMessage, E as formatMappingUnreportedAlertMessage, F as formatSectionNotLinkedAlertMessage, H as formatSourceNotWiredAlertMessage, I as getAttachmentDownloadUrl, J as getAttachmentDownloadUrlForCell, K as getGristSdkAlertDescriptors, L as getGristSdkAlertSeverity, M as getGristSdkAlertTitle, N as gristAttachmentCellValue, O as gristAttachmentCellValues, P as isAccessInsufficientError, Q as isWidgetSectionNotLinked, S as loadColumnMetadataByTable, T as mergeGristAttachmentCellValue, W as orderedColumnIds, X as parseGristAttachmentUploadResponse, Y as parseGristAttachmentUploadResponseIds, Z as uploadGristAttachment, _ as validateColumnMappings } from './use-grist-types-kwxoFeub.js';
+import { a as GristNoiseColumnsOptions } from './use-grist-reads-DUMvJgV7.js';
 import { GristWidgetSnapshot } from './advanced.js';
-export { k as GristCellValue, l as GristColumnLike, m as GristSafeParseIssue, n as GristSafeParseIssueCode, o as GristSafeRefListValue, p as GristSafeRefValue, q as GristSafeTableCellIssue, r as GristSafeTableCellMeta, s as GristTableRowsOrder, t as SafeParseGristTableDataResult, u as SafeParseGristValuesOptions, v as UseGristWidgetOptionsFromContextConfig, w as UseGristWidgetOptionsFromContextResult, x as computeRowCount, y as decodeColumnarToReplicaRows, z as fetchGristRow, A as fetchGristTableRows, B as fetchWithGristAuth, C as findRowIndexById, D as getGristAccessToken, E as gristAddColumnAction, H as gristAddRecordAction, I as gristAddTableAction, J as gristAddVisibleColumnAction, K as gristBulkAddRecordAction, M as gristBulkRemoveRecordAction, N as gristBulkUpdateRecordAction, O as gristCellValueSchema, P as gristDuplicateTableAction, Q as gristModifyColumnAction, R as gristRemoveColumnAction, T as gristRemoveRecordAction, V as gristRemoveTableAction, W as gristRenameColumnAction, X as gristRenameTableAction, Y as gristReplaceTableDataAction, Z as gristSafeRefListValueSchema, _ as gristSafeRefValueSchema, $ as gristSetDocumentInfoAction, a0 as gristUpdateRecordAction, a1 as inferDisplayHelpersByRef, a2 as isGristNoiseColumn, a3 as materializeGristRowsFromColumnar, a4 as rowAtIndex, a5 as safeParseGristTableData, a6 as safeParseGristValues, a7 as safeParseRowsToDisplayRows, a8 as sortRowsByGristOrder, a9 as tableDataToRows, aa as useGristWidgetOptionsFromContext } from './use-grist-widget-options-from-context-hl-NwOwP.js';
+export { F as FetchGristTableRowsOptions, b as GristAccessToken, c as GristCapabilities, d as GristCellValue, e as GristColumnInfo, f as GristColumnLike, g as GristColumnarTable, h as GristSafeParseCellResult, i as GristSafeParseIssue, j as GristSafeParseIssueCode, k as GristSafeRefListValue, l as GristSafeRefValue, m as GristSafeTableCellIssue, n as GristSafeTableCellMeta, o as GristTableRowsOrder, p as GristUserActionTuple, q as GristWidgetStatus, L as ListColumnsOptions, r as ListTablesOptions, S as SafeParseGristTableDataOptions, s as SafeParseGristTableDataResult, t as SafeParseGristValuesOptions, U as UseGristCoreOptions, u as UseGristCoreResult, v as computeRowCount, w as decodeColumnarToReplicaRows, x as fetchGristRow, y as fetchGristTableRows, z as fetchWithGristAuth, A as findRowIndexById, B as getGristAccessToken, C as gristAddColumnAction, D as gristAddRecordAction, E as gristAddTableAction, H as gristAddVisibleColumnAction, I as gristBulkAddRecordAction, J as gristBulkRemoveRecordAction, K as gristBulkUpdateRecordAction, M as gristCellValueSchema, N as gristDuplicateTableAction, O as gristModifyColumnAction, P as gristRemoveColumnAction, Q as gristRemoveRecordAction, R as gristRemoveTableAction, T as gristRenameColumnAction, V as gristRenameTableAction, W as gristReplaceTableDataAction, X as gristSafeRefListValueSchema, Y as gristSafeRefValueSchema, Z as gristSetDocumentInfoAction, _ as gristUpdateRecordAction, $ as inferDisplayHelpersByRef, a0 as isGristNoiseColumn, a1 as materializeGristRowsFromColumnar, a2 as rowAtIndex, a3 as safeParseGristTableData, a4 as safeParseGristValues, a5 as safeParseRowsToDisplayRows, a6 as sortRowsByGristOrder, a7 as tableDataToRows } from './use-grist-reads-DUMvJgV7.js';
 import * as react from 'react';
 import { ReactNode } from 'react';
+export { U as UseGristWidgetOptionsFromContextConfig, a as UseGristWidgetOptionsFromContextResult, u as useGristWidgetOptionsFromContext } from './use-grist-widget-options-from-context-CGOlQ5Vc.js';
 import 'zod';
 
-type GristFetchedAttachment = {
-    base64: string;
-    contentType: string;
-};
-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;
-/**
- * Signed Grist download URL for a single attachment id (`getAccessToken` + query auth).
- */
-declare function getAttachmentDownloadUrl(docApi: GristDocApi, attachmentId: string, options?: {
-    readOnly?: boolean;
-}): Promise<string>;
-/** URL for the `index`’th attachment in a cell value (0-based). */
-declare function getAttachmentDownloadUrlForCell(docApi: GristDocApi, cellValue: unknown, index: number, options?: {
-    readOnly?: boolean;
-}): Promise<string | null>;
-/** Token + URL + fetch for one attachment id. */
-declare function fetchAttachmentBase64(docApi: GristDocApi, attachmentId: string, options?: {
-    readOnly?: boolean;
-}): Promise<GristFetchedAttachment>;
-/** Download attachment bytes as a `Blob` (preferred for large files). */
-declare function fetchAttachmentBlob(docApi: GristDocApi, attachmentId: string, options?: {
-    readOnly?: boolean;
-}): Promise<GristFetchedAttachmentBlob>;
-/** Download the `index`’th attachment in a cell (0-based). */
-declare function fetchAttachmentBase64ForCell(docApi: GristDocApi, cellValue: unknown, index: number, options?: {
-    readOnly?: boolean;
-}): Promise<GristFetchedAttachment | null>;
-
-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;
-};
-/**
- * Parse the body of `POST /attachments` (widget or REST).
- * Grist returns a JSON array of attachment ids, e.g. `[42]` or `[101, 102]`.
- */
-declare function parseGristAttachmentUploadResponseIds(raw: string, options?: {
-    strict?: boolean;
-}): string[];
-/**
- * First attachment id from an upload response (see {@link parseGristAttachmentUploadResponseIds}).
- */
-declare function parseGristAttachmentUploadResponse(raw: string, options?: {
-    strict?: boolean;
-}): string;
-declare function extractAttachmentIdsFromUploadPayload(parsed: unknown, options?: {
-    strict?: boolean;
-}): string[];
-/** @deprecated Prefer {@link extractAttachmentIdsFromUploadPayload}. */
-declare function extractFirstAttachmentIdFromUploadPayload(parsed: unknown): string | undefined;
-/** 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;
-/**
- * Upload a file to the current document via `POST /attachments`.
- *
- * Uses `getAccessToken({ readOnly: false })` and `?auth=` (see Grist widget docs).
- * Requires document **full** access in the widget.
- */
-declare function uploadGristAttachment(docApi: GristDocApi, file: Blob | File, options?: {
-    fileName?: string;
-}): Promise<GristAttachmentUploadResult>;
-
 declare function inferGristFormulaKind(isFormula: boolean, formulaTrimmed: string): GristFormulaKind;
 /** Use when `formulaKind` may be missing (e.g. older document builds). */
 declare function resolveGristFormulaKind(col: GristReplicaColumn): GristFormulaKind;
 /** Serialize cell values for JSON output. */
 declare function serializeJsonFriendly(value: unknown): unknown;
 
-type ReplicaTableColumnMetaLite = {
-    colRef?: number;
-    type?: string;
-    label?: string;
-    parentPos?: number;
-    isFormula?: boolean;
-    formula?: string;
-    description?: string;
-    widgetOptions?: Record<string, unknown>;
-    displayColRef?: number;
-    visibleColRef?: number;
-};
-declare function loadColumnMetadataByTable(docApi: GristDocApi): Promise<Map<string, Map<string, ReplicaTableColumnMetaLite>>>;
-declare function orderedColumnIds(data: Record<string, unknown[]>, metaByCol: Map<string, ReplicaTableColumnMetaLite>): string[];
-/** Build replica column metadata from columnar `fetchTable` + `_grist_Tables_column` maps. */
-declare function buildReplicaColumnsFromColumnar(data: Record<string, unknown[]>, colMeta: Map<string, ReplicaTableColumnMetaLite>): Record<string, GristReplicaColumn>;
-type BuildReplicaDocumentFromDocApiOptions = {
-    /** When false (default), skip fetching row data for `tableId` starting with `_grist`. */
-    includeSystemTableData?: boolean;
-    /**
-     * Row bodies: omit (`false`), first N (`samples`), or full decode (`full`).
-     * Default `samples`.
-     */
-    includeRows?: false | "samples" | "full";
-    /** Max rows per table when `includeRows` is `samples`. Default 10. */
-    sampleRowLimit?: number;
-    /** Set on the replica as `source` for host logging / provenance. */
-    source?: string;
-};
-/**
- * Build {@link GristReplicaDocument} from a host `docApi`:
- * metadata from `_grist_Tables` / `_grist_Tables_column` when readable, plus optional decoded `rows`.
- *
- * Prefer {@link useGrist}'s `buildReplicaDocumentFromDocApi()` when you already use the primary hook.
- */
-declare function buildReplicaDocumentFromDocApi(docApi: GristDocApi, options?: BuildReplicaDocumentFromDocApiOptions): Promise<GristReplicaDocument>;
-
 /**
  * Ensure `rows` is a concrete array for emulator / merge logic.
  * Call at host boundaries (`createDocument`, tests); JSON may still omit `rows` for schema-only.
@@ -233,29 +118,6 @@ declare function isGristCellError(value: unknown): value is GristEncodedError;
  */
 declare function encodeGristValue(value: unknown, column?: GristReplicaColumn): unknown;
 
-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[];
-};
-/**
- * Verifies that the current Grist mappings cover every required column declared
- * in `grist.ready({ columns })`.
- *
- * Use this before reading `mappedRecord` so you can render a "please configure
- * the widget" prompt instead of a confusing `null`.
- */
-declare function validateColumnMappings(spec: GristColumnsToMap | undefined | null, mappings: GristWidgetColumnMap | null | undefined): ValidateColumnMappingsResult;
-
 /**
  * Pure projections from the handshake snapshot for boundary / shell UI.
  *
@@ -295,359 +157,6 @@ declare const GRIST_BOUNDARY_PREPARING_COPY: {
     readonly message: "Open the widget settings in Grist (Creator Panel → Custom widget) and connect each required column to your table.";
 };
 
-type GristWidgetMode = "empty" | "row" | "new-row";
-type UseGristSelectionOptions = {
-    columns?: GristColumnsToMap;
-    subscribeToWidgetOptions?: boolean;
-    subscribeToNewRecord?: boolean;
-};
-type UseGristSelectionResult<TRow = Record<string, unknown>, TMapped = Record<string, unknown>> = {
-    record: GristRowRecord<TRow> | null;
-    records: GristRowRecord<TRow>[] | null;
-    mappedRecord: TMapped | null;
-    mappings: GristWidgetColumnMap;
-    recordsMappings: GristWidgetColumnMap | null;
-    columnMappingStatus: ValidateColumnMappingsResult;
-    mode: GristWidgetMode;
-    resolveMappedColumnId: (logicalFieldName: string) => string;
-    mapBack: (patch: Partial<TMapped>) => Record<string, unknown>;
-    mapBackSkipped: readonly string[];
-    isNewRecord: boolean;
-    newRecordMappings: GristWidgetColumnMap | null;
-    widgetOptions: Record<string, unknown> | null;
-    widgetInteraction: GristWidgetInteraction | null;
-};
-
-/**
- * Minimal widget slice for deriving non-fatal SDK callouts. Any
- * {@link import("../use-grist").UseGristResult} satisfies this.
- */
-type GristSdkAlertsWidgetSlice = {
-    status: GristWidgetStatus;
-    columnMappingStatus: ValidateColumnMappingsResult;
-    actionError: string | null;
-    /**
-     * Last access-insufficient error from a read method (`fetchTable`, etc.).
-     * When set and matching the access-error pattern, an "access-insufficient"
-     * alert is emitted — same as for `actionError`.
-     */
-    readError?: string | null;
-    /**
-     * Logical column names that the most recent `mapBack(...)` call could not
-     * reverse-map (e.g. `allowMultiple` columns where one logical name resolves
-     * to several real columns).
-     */
-    mapBackSkipped?: readonly string[];
-    /** Selection mode from `useGrist()` — used for section-not-linked detection. */
-    mode?: GristWidgetMode;
-    /** `onOptions` settings from Grist (`InteractionOptions`). */
-    widgetInteraction?: GristWidgetInteraction | null;
-    /**
-     * Alert kinds suppressed via `UseGristOptions.suppressAlerts`.
-     * Consumed automatically by `useGristSdkAlertDescriptors`.
-     */
-    suppressAlerts?: readonly GristSdkAlertKind[];
-    /**
-     * Whether the widget declared `allowSelectBy: true` — used to distinguish
-     * "section-not-linked" (expects incoming link) from "source-not-wired"
-     * (expects to drive other sections).
-     */
-    allowSelectBy?: boolean;
-};
-type GristSdkAlertKind = "column-mapping" | "mapping-pending" | "mapping-unreported" | "link-stale" | "section-not-linked" | "source-not-wired" | "current-table-error" | "action-error" | "access-insufficient" | "map-back-skip";
-/** Classic callout level for host styling: info / warning / error. */
-type GristSdkAlertSeverity = "info" | "warning" | "error";
-type GristSdkAlertDescriptor = {
-    id: string;
-    kind: GristSdkAlertKind;
-    severity: GristSdkAlertSeverity;
-    title: string;
-    /** Suggested WAI-ARIA role for the host shell. */
-    ariaRole: "status" | "alert";
-    message: string;
-};
-type GetGristSdkAlertDescriptorsOptions = {
-    /**
-     * Handshake snapshot from `useGristHandshake()` / the provider manager.
-     * Enables link-stale, mapping-unreported, and current-table alerts that are
-     * not visible on the widget slice alone.
-     */
-    snapshot?: GristWidgetSnapshot;
-    /** Appended to {@link formatColumnMappingAlertMessage} when a mapping alert is emitted. */
-    columnMappingHint?: string;
-    /** Appended to the map-back-skip message. */
-    mapBackHint?: string;
-    /** Override copy for {@link formatMappingPendingAlertMessage}. */
-    mappingPendingHint?: string;
-    /** Appended to {@link formatSectionNotLinkedAlertMessage}. */
-    sectionNotLinkedHint?: string;
-    /** Appended to {@link formatSourceNotWiredAlertMessage}. */
-    sourceNotWiredHint?: string;
-    /** Appended to {@link formatAccessInsufficientMessage}. */
-    accessInsufficientHint?: string;
-    /**
-     * Alert kinds to omit from the output. Useful for widgets that intentionally
-     * operate without a link source (`["section-not-linked"]`) or handle certain
-     * conditions in their own UI.
-     */
-    suppressKinds?: readonly GristSdkAlertKind[];
-};
-/** Default alert title for shadcn / toast shells. */
-declare function getGristSdkAlertTitle(kind: GristSdkAlertKind): string;
-/** Suggested severity for host styling (destructive vs muted). */
-declare function getGristSdkAlertSeverity(kind: GristSdkAlertKind): GristSdkAlertSeverity;
-/**
- * Human-readable text for an incomplete column mapping (when
- * `columnMappingStatus.ok` is false).
- */
-declare function formatColumnMappingAlertMessage(status: ValidateColumnMappingsResult, hint?: string): string;
-declare function formatMappingPendingAlertMessage(hint?: string): string;
-declare function formatMappingUnreportedAlertMessage(hint?: string): string;
-declare function formatLinkStaleAlertMessage(snapshot: GristWidgetSnapshot): string;
-/**
- * True when Grist reports this section is not a link target (no selector drives
- * the cursor / `onRecord` stream). Requires `linking` on `widgetInteraction` so
- * older hosts do not trigger false positives.
- */
-declare function isWidgetSectionNotLinked(interaction: GristWidgetInteraction | null | undefined): boolean;
-declare function formatSectionNotLinkedAlertMessage(hint?: string): string;
-declare function formatSourceNotWiredAlertMessage(hint?: string): string;
-/**
- * Non-fatal SDK messages to show while `status === "ready"` (e.g. incomplete
- * mappings, stale link, or `actionError` when not promoted to `status === "error"`).
- * Host apps map each descriptor to their own UI (shadcn Alert, toast, etc.).
- *
- * Pass `options.snapshot` (from `useGristHandshake()` or the provider manager)
- * for FSM-only signals: link stale, mapping unreported, current-table errors.
- */
-declare function getGristSdkAlertDescriptors(widget: GristSdkAlertsWidgetSlice, options?: GetGristSdkAlertDescriptorsOptions): GristSdkAlertDescriptor[];
-/**
- * Heuristic: returns `true` when `actionError` looks like it was caused by
- * insufficient access rights rather than a domain / schema error.
- */
-declare function isAccessInsufficientError(message: string): boolean;
-declare function formatAccessInsufficientMessage(hint?: string): string;
-
-type GristWidgetActionStatus = "idle" | "running" | "error";
-type UseGristTableOpsBoundResult = {
-    table: GristTableOperations;
-    getTable: (tableId: string) => GristTableOperations;
-    actionStatus: GristWidgetActionStatus;
-    actionError: string | null;
-    applyActions: (actions: GristUserActionTuple[], applyOptions?: GristApplyUserActionsOptions) => Promise<unknown>;
-};
-
-type GristTheme = "light" | "dark";
-type UseGristThemeResult = {
-    theme: GristTheme | null;
-};
-
-type UseGristCurrentTableResult = {
-    currentTableId: string | null;
-    currentTableLoading: boolean;
-    refreshCurrentTable: () => Promise<void>;
-    tableError: string | null;
-};
-
-type GristCoreContextValue = UseGristCoreResult & {
-    tableError: string | null;
-};
-type GristStatusSliceValue = GristCoreContextValue & UseGristCurrentTableResult;
-
-type ComposeGristWidgetOptions = UseGristCoreOptions & UseGristSelectionOptions & {
-    /**
-     * Alert kinds that should never be emitted for this widget.
-     * E.g. `["section-not-linked"]` for widgets that don't need a link source.
-     */
-    suppressAlerts?: GristSdkAlertKind[];
-};
-
-type UseGristOptions = ComposeGristWidgetOptions;
-/** Return type of `useGristStatus()`: connection state plus current-table info. */
-type UseGristStatusResult = GristStatusSliceValue;
-/** Return type of `useGristWrites()`. */
-type UseGristWritesResult = UseGristTableOpsBoundResult;
-/**
- * The full Grist widget state and API surface.
- *
- * **Method stability:** all function-typed fields (`fetchTable`, `listTables`,
- * `patchWidgetOptions`, `getTable`, etc.) are `useCallback`-wrapped internally
- * and **referentially stable** as long as the underlying `docApi` hasn't changed.
- * You can safely use individual methods in React dependency arrays:
- *
- * ```tsx
- * // GOOD — w.listTables is stable, effect only runs once
- * useEffect(() => { void w.listTables().then(setTables) }, [w.listTables])
- *
- * // BAD — w is a new object whenever any Grist state changes (record, options, …)
- * useEffect(() => { void w.listTables().then(setTables) }, [w])
- * ```
- *
- * The `UseGristResult` object itself is **not** referentially stable — it updates
- * whenever any reactive field changes (e.g. `record`, `widgetOptions`, `mode`).
- * Do **not** use the whole object as a `useEffect` / `useMemo` dependency.
- */
-type UseGristResult<TRow = Record<string, unknown>, TMapped = Record<string, unknown>> = {
-    /** @access `"none"` — Connection state. */
-    status: GristWidgetStatus;
-    /** @access `"none"` — `true` if the page is inside a Grist iframe. */
-    isAvailable: boolean | null;
-    /** @access `"none"` — Convenience for `status === "ready"`. */
-    isReady: boolean;
-    /** @access `"none"` — Connection-level error string. */
-    error: string | null;
-    /**
-     * Handshake-derived gates (`canRender`, `canWriteRecords`, …).
-     * Prefer `capabilities.canRender` over re-deriving from `columnMappingStatus` alone.
-     * @access `"none"`
-     */
-    capabilities: GristCapabilities;
-    /** @access `"none"` — Re-run the handshake from scratch. */
-    reload: () => Promise<void>;
-    /** @access `"none"` — Resolved Grist theme (`"light" | "dark"`) or `null` before ready. */
-    theme: GristTheme | null;
-    /** @access `"read table"` — Currently selected row (raw column ids). */
-    record: GristRowRecord<TRow> | null;
-    /** @access `"read table"` — All visible rows in the section (raw column ids). */
-    records: GristRowRecord<TRow>[] | null;
-    /** @access `"read table"` — Selected row with logical column names. `null` if required mappings are missing. */
-    mappedRecord: TMapped | null;
-    /** @access `"read table"` — Logical → real column id map for the single-record stream. */
-    mappings: GristWidgetColumnMap;
-    /** @access `"read table"` — Logical → real column id map for the multi-record stream. */
-    recordsMappings: GristWidgetColumnMap | null;
-    /** @access `"read table"` — Required-column gating result. */
-    columnMappingStatus: ValidateColumnMappingsResult;
-    /** @access `"read table"` — Derived from selection state: `"empty"`, `"row"`, or `"new-row"`. */
-    mode: GristWidgetMode;
-    /** @access `"read table"` — One-shot column resolution (returns `name` as a fallback). */
-    resolveMappedColumnId: (logicalFieldName: string) => string;
-    /** @access `"read table"` — Reverse-map a logical-name patch to real column ids for writes. */
-    mapBack: (patch: Partial<TMapped>) => Record<string, unknown>;
-    /**
-     * Logical column names that the most recent `mapBack(...)` call could not
-     * reverse-map (typically `allowMultiple` columns).
-     *
-     * Used by {@link import("./helpers/grist-sdk-alerts").getGristSdkAlertDescriptors}
-     * to surface a non-fatal alert.
-     * @access `"read table"`
-     */
-    mapBackSkipped: readonly string[];
-    /** @access `"read table"` — `true` when the cursor is on the new-row placeholder. */
-    isNewRecord: boolean;
-    /** @access `"read table"` — Logical → real map for the new-row placeholder. */
-    newRecordMappings: GristWidgetColumnMap | null;
-    /** @access `"read table"` — `onOptions` payload from Grist, includes `access_level`. */
-    widgetInteraction: GristWidgetInteraction | null;
-    /** @access `"read table"` — Current section's table id. */
-    currentTableId: string | null;
-    /** @access `"read table"` — `true` while the SDK re-reads `selectedTable.getTableId()`. */
-    currentTableLoading: boolean;
-    /** @access `"read table"` — Force a re-read of the current table id. */
-    refreshCurrentTable: () => Promise<void>;
-    /**
-     * Last access-insufficient error from a read method (`fetchTable`, `listColumns`, …).
-     * `null` when no error or after a successful call clears it.
-     * Consumed by {@link import("./helpers/grist-sdk-alerts").getGristSdkAlertDescriptors}
-     * to surface the "access-insufficient" alert.
-     * @access `"none"`
-     */
-    readError: string | null;
-    /** @access `"full"` — Raw columnar payload for any table. Requires full document access. */
-    fetchTable: (tableId: string) => Promise<GristColumnarTable>;
-    /** @access `"full"` — Row-shaped, decoded, optionally safe-parsed read of any table. Requires full document access. */
-    fetchTableRows: {
-        <T extends Record<string, unknown> = Record<string, unknown>>(tableId: string, options: FetchGristTableRowsOptions & {
-            safeParse: true | Omit<SafeParseGristTableDataOptions, "columns" | "order">;
-        }): Promise<GristRowRecord<{
-            [K in keyof T]: GristSafeParseCellResult<T[K]> | null;
-        }>[]>;
-        <T extends Record<string, unknown> = Record<string, unknown>>(tableId: string, options?: FetchGristTableRowsOptions): Promise<GristRowRecord<T>[]>;
-    };
-    /** @access `"full"` — Fetch a single row by id from any table. Requires full document access. */
-    fetchRow: <T = Record<string, unknown>>(tableId: string, rowId: number) => Promise<GristRowRecord<T> | null>;
-    /** @access `"read table"` — List table ids (system/hidden tables filtered by default). */
-    listTables: (options?: ListTablesOptions) => Promise<string[]>;
-    /** @access `"full"` — Column metadata without fetching rows. Requires full document access. */
-    listColumns: (tableId: string, options?: ListColumnsOptions) => Promise<GristColumnInfo[]>;
-    /** @access `"read table"` — Document name. */
-    getDocName: () => Promise<string>;
-    /** @access `"full"` — Build a replica document snapshot from the live doc API. Requires full document access. */
-    buildReplicaDocumentFromDocApi: (options?: BuildReplicaDocumentFromDocApiOptions) => Promise<GristReplicaDocument>;
-    /** @access `"read table"` — Raw columnar read of the current section. */
-    fetchSelectedTable: (fetchOptions?: GristFetchSelectedOptions) => Promise<GristColumnarTable>;
-    /** @access `"read table"` — Single row from the current section. */
-    fetchSelectedRecord: (rowId: number, fetchOptions?: GristFetchSelectedOptions) => Promise<Record<string, unknown>>;
-    /** @access `"full"` — CRUD operations on the current table (`create`, `update`, `upsert`, `destroy`). */
-    table: GristTableOperations;
-    /** @access `"full"` — Memoized CRUD operations for any table by id. */
-    getTable: (tableId: string) => GristTableOperations;
-    /** @access `"full"` — Last write status (`"idle"`, `"running"`, `"error"`). */
-    actionStatus: GristWidgetActionStatus;
-    /** @access `"full"` — Last write error message. */
-    actionError: string | null;
-    /** @access `"full"` — Apply user-action tuples atomically (schema + data mutations). */
-    applyActions: (actions: GristUserActionTuple[], applyOptions?: GristApplyUserActionsOptions) => Promise<unknown>;
-    /** @access `"read table"` — Current widget options from Grist's `onOptions` stream. */
-    widgetOptions: Record<string, unknown> | null;
-    /** @access `"read table"` — Fetch the current widget options imperatively. */
-    getWidgetOptions: () => Promise<Record<string, unknown> | null>;
-    /** @access `"read table"` — Fetch a single widget option by key. */
-    getWidgetOption: (key: string) => Promise<unknown>;
-    /** @access `"full"` — Set a single widget option. */
-    setWidgetOption: (key: string, value: unknown) => Promise<void>;
-    /** @access `"full"` — Replace all widget options. */
-    setWidgetOptions: (next: Record<string, unknown>) => Promise<void>;
-    /** @access `"full"` — Merge a patch into existing widget options. */
-    patchWidgetOptions: (patch: Record<string, unknown>) => Promise<void>;
-    /** @access `"full"` — Remove all widget options. */
-    clearWidgetOptions: () => Promise<void>;
-    /** @access `"read table"` — Move the host cursor to a row / field / section. */
-    setCursorPosition: (pos: GristCursorPos) => Promise<void>;
-    /** @access `"read table"` — Set the widget's linked row selection (requires `allowSelectBy`). */
-    setLinkedRowSelection: (rowIds: null | number[]) => Promise<void>;
-    /** @access `"full"` — Signed download URL for an attachment. */
-    getAttachmentUrl: (attachmentId: string, options?: {
-        readOnly?: boolean;
-    }) => Promise<string>;
-    /** @access `"full"` — Fetch an attachment as a base64-encoded string. */
-    fetchAttachmentBase64: (attachmentId: string, options?: {
-        readOnly?: boolean;
-    }) => Promise<GristFetchedAttachment>;
-    /** @access `"full"` — Fetch an attachment as a Blob. */
-    fetchAttachmentBlob: (attachmentId: string, options?: {
-        readOnly?: boolean;
-    }) => Promise<GristFetchedAttachmentBlob>;
-    /** @access `"full"` — Obtain a short-lived access token for the Grist REST API. */
-    getAccessToken: (options?: {
-        readOnly?: boolean;
-    }) => Promise<GristAccessToken>;
-    /** @access `"full"` — `fetch()` with the doc access token attached. Path is relative to the document API root. */
-    fetchWithAuth: (path: string, init?: RequestInit & {
-        readOnly?: boolean;
-    }) => Promise<Response>;
-    /** @access `"full"` — Upload a file via `POST /attachments` (returns attachment ids). */
-    uploadAttachment: (file: Blob | File, options?: {
-        fileName?: string;
-    }) => Promise<GristAttachmentUploadResult>;
-    /** @access `"read table"` — Re-issue `grist.ready()` with new options. */
-    configure: (options: GristReadyOptions) => Promise<void>;
-    /** @access `"read table"` — Force a re-read of `sectionApi.mappings()`. */
-    refreshMappings: () => Promise<GristWidgetColumnMap | null>;
-    /**
-     * Alert kinds suppressed via `UseGristOptions.suppressAlerts`.
-     * Consumed automatically by `useGristSdkAlertDescriptors`.
-     * @access `"none"`
-     */
-    suppressAlerts?: readonly GristSdkAlertKind[];
-    /**
-     * Whether the widget declared `allowSelectBy: true` in its options.
-     * Used by the alert system to distinguish "section-not-linked" from "source-not-wired".
-     * @access `"none"`
-     */
-    allowSelectBy?: boolean;
-};
-
 /**
  * React hook: widget slice + optional handshake snapshot for
  * {@link getGristSdkAlertDescriptors}.
@@ -827,5 +336,5 @@ type UseWidgetMetadataInput = {
 };
 declare function useWidgetMetadata(input?: UseWidgetMetadataInput | null): void;
 
-export { FetchGristTableRowsOptions, GRIST_BOUNDARY_PREPARING_COPY, GristAccessToken, GristApplyUserActionsOptions, GristBoundary, GristBoundaryScreen, GristCapabilities, GristColumnInfo, GristColumnarTable, GristColumnsToMap, GristCursorPos, GristDocApi, GristDocumentMode, GristFetchSelectedOptions, GristFormulaKind, GristNoiseColumnsOptions, GristReadyOptions, GristReplicaColumn, GristReplicaDocument, GristReplicaRow, GristReplicaTable, GristRequiredAccess, GristRowRecord, GristSafeParseCellResult, GristTableOperations, GristUserActionTuple, GristWidgetColumnMap, GristWidgetInteraction, GristWidgetProvider, GristWidgetStatus, ListColumnsOptions, ListTablesOptions, SafeParseGristTableDataOptions, UseGristCoreOptions, UseGristCoreResult, buildReplicaColumnsFromColumnar, buildReplicaDocumentFromDocApi, buildReplicaJsonPayload, coerceGristDocApiRefRowId, decodeGristValue, deriveBoundaryBootLabel, deriveBoundaryBootPhase, deriveBoundaryView, encodeGristValue, extractAttachmentIdsFromUploadPayload, extractFirstAttachmentIdFromUploadPayload, extractGristAttachmentId, extractGristAttachmentIdsFromCell, fetchAttachmentBase64, fetchAttachmentBase64ForCell, fetchAttachmentBlob, formatAccessInsufficientMessage, formatBoundaryUserMessage, formatColumnMappingAlertMessage, formatLinkStaleAlertMessage, formatMappingPendingAlertMessage, formatMappingUnreportedAlertMessage, formatSectionNotLinkedAlertMessage, formatSourceNotWiredAlertMessage, getAttachmentDownloadUrl, getAttachmentDownloadUrlForCell, getGristSdkAlertDescriptors, getGristSdkAlertSeverity, getGristSdkAlertTitle, gristAttachmentCellValue, gristAttachmentCellValues, inferGristFormulaKind, isAccessInsufficientError, isGristCellError, isWidgetSectionNotLinked, loadColumnMetadataByTable, mergeGristAttachmentCellValue, normalizeGristChoiceListEntries, normalizeReplicaDocumentInput, normalizeReplicaTableInput, orderedColumnIds, parseGristAttachmentUploadResponse, parseGristAttachmentUploadResponseIds, parseGristWidgetOptionsCell, resolveGristFormulaKind, serializeJsonFriendly, uploadGristAttachment, useGrist, useGristContext, useGristOptional, useGristSchema, useGristSdkAlertDescriptors, useGristSelection, useGristStatus, useGristTheme, useGristWrites, useWidgetMetadata, validateColumnMappings };
-export type { BuildReplicaDocumentFromDocApiOptions, GetGristSdkAlertDescriptorsOptions, GristAttachmentUploadResult, GristBoundaryActions, GristBoundaryBlockingKind, GristBoundaryBootPhase, GristBoundaryGate, GristBoundaryProps, GristBoundaryView, GristChoiceListEntry, GristDecodedValue, GristEncodedAttachmentList, GristEncodedBareRef, GristEncodedDate, GristEncodedDateTime, GristEncodedError, GristEncodedList, GristEncodedPending, GristEncodedRef, GristFetchedAttachment, GristFetchedAttachmentBlob, GristSchemaTableView, GristSdkAlertDescriptor, GristSdkAlertKind, GristSdkAlertSeverity, GristSdkAlertsWidgetSlice, GristTheme, GristWidgetActionStatus, GristWidgetMode, GristWidgetProviderProps, ReplicaDocumentJsonOptions, ReplicaJsonIncludeRows, ReplicaTableColumnMetaLite, UseGristOptions, UseGristResult, UseGristSchemaOptions, UseGristSchemaResult, UseGristSelectionResult, UseGristStatusResult, UseGristThemeResult, UseGristWritesResult, UseWidgetMetadataInput, ValidateColumnMappingsResult };
+export { GRIST_BOUNDARY_PREPARING_COPY, GetGristSdkAlertDescriptorsOptions, GristBoundary, GristBoundaryScreen, GristDocumentMode, GristFormulaKind, GristNoiseColumnsOptions, GristReadyOptions, GristReplicaColumn, GristReplicaDocument, GristReplicaRow, GristReplicaTable, GristRequiredAccess, GristSdkAlertDescriptor, GristSdkAlertsWidgetSlice, GristWidgetProvider, UseGristOptions, UseGristResult, UseGristSelectionResult, UseGristStatusResult, UseGristThemeResult, UseGristWritesResult, buildReplicaJsonPayload, coerceGristDocApiRefRowId, decodeGristValue, deriveBoundaryBootLabel, deriveBoundaryBootPhase, deriveBoundaryView, encodeGristValue, formatBoundaryUserMessage, inferGristFormulaKind, isGristCellError, normalizeGristChoiceListEntries, normalizeReplicaDocumentInput, normalizeReplicaTableInput, parseGristWidgetOptionsCell, resolveGristFormulaKind, serializeJsonFriendly, useGrist, useGristContext, useGristOptional, useGristSchema, useGristSdkAlertDescriptors, useGristSelection, useGristStatus, useGristTheme, useGristWrites, useWidgetMetadata };
+export type { GristBoundaryActions, GristBoundaryBlockingKind, GristBoundaryBootPhase, GristBoundaryGate, GristBoundaryProps, GristBoundaryView, GristChoiceListEntry, GristDecodedValue, GristEncodedBareRef, GristEncodedDate, GristEncodedDateTime, GristEncodedError, GristEncodedList, GristEncodedPending, GristEncodedRef, GristSchemaTableView, GristWidgetProviderProps, ReplicaDocumentJsonOptions, ReplicaJsonIncludeRows, UseGristSchemaOptions, UseGristSchemaResult, UseWidgetMetadataInput };