grist-widget-sdk 0.2.0

package/dist/index.d.ts

@@ -0,0 +1,825 @@
+import { d as GristDocApi, g as GristFormulaKind, j as GristReplicaColumn, k as GristReplicaDocument, n as GristReplicaTable, l as GristReplicaRow, b as GristColumnsToMap, w as GristWidgetColumnMap, p as GristRowRecord, y as GristWidgetInteraction, s as GristTableOperations, G as GristApplyUserActionsOptions, f as GristFetchSelectedOptions, c as GristCursorPos, i as GristReadyOptions, o as GristRequiredAccess, e as GristDocumentMode } from './types-Fb2wplkv.js';
+export { a as GristColumnToMap, h as GristMinimalRecord, m as GristReplicaSelection, q as GristTableNewRecord, r as GristTableOpOptions, t as GristTableUpdateRecord, u as GristTableUpsertOptions, v as GristTableUpsertRecord, x as GristWidgetConfiguration, z as GristWidgetLinkingInfo } from './types-Fb2wplkv.js';
+import { E as GristWidgetSnapshot, H as GristWidgetStatus, D as GristUserActionTuple, N as UseGristCoreResult, U as UseGristCoreOptions, b as GristCapabilities, f as GristColumnarTable, F as FetchGristTableRowsOptions, S as SafeParseGristTableDataOptions, s as GristSafeParseCellResult, J as ListTablesOptions, L as ListColumnsOptions, d as GristColumnInfo, G as GristAccessToken, r as GristNoiseColumnsOptions } from './use-grist-widget-options-from-context-BFhQBGRY.js';
+export { c as GristCellValue, e as GristColumnLike, t as GristSafeParseIssue, u as GristSafeParseIssueCode, v as GristSafeRefListValue, w as GristSafeRefValue, x as GristSafeTableCellIssue, y as GristSafeTableCellMeta, B as GristTableRowsOrder, K as SafeParseGristTableDataResult, M as SafeParseGristValuesOptions, O as UseGristWidgetOptionsFromContextConfig, P as UseGristWidgetOptionsFromContextResult, Q as computeRowCount, R as decodeColumnarToReplicaRows, T as fetchGristRow, V as fetchGristTableRows, W as fetchWithGristAuth, X as findRowIndexById, Y as getGristAccessToken, Z as gristAddColumnAction, _ as gristAddRecordAction, $ as gristAddTableAction, a0 as gristAddVisibleColumnAction, a1 as gristBulkAddRecordAction, a2 as gristBulkRemoveRecordAction, a3 as gristBulkUpdateRecordAction, a4 as gristCellValueSchema, a5 as gristDuplicateTableAction, a6 as gristModifyColumnAction, a7 as gristRemoveColumnAction, a8 as gristRemoveRecordAction, a9 as gristRemoveTableAction, aa as gristRenameColumnAction, ab as gristRenameTableAction, ac as gristReplaceTableDataAction, ad as gristSafeRefListValueSchema, ae as gristSafeRefValueSchema, af as gristSetDocumentInfoAction, ag as gristUpdateRecordAction, ah as inferDisplayHelpersByRef, ai as isGristNoiseColumn, aj as materializeGristRowsFromColumnar, ak as rowAtIndex, al as safeParseGristTableData, am as safeParseGristValues, an as safeParseRowsToDisplayRows, ao as sortRowsByGristOrder, ap as tableDataToRows, aq as useGristWidgetOptionsFromContext } from './use-grist-widget-options-from-context-BFhQBGRY.js';
+import * as react_jsx_runtime from 'react/jsx-runtime';
+import { ReactNode } from 'react';
+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.
+ */
+declare function normalizeReplicaTableInput<T extends GristReplicaTable>(table: T): T & {
+    rows: GristReplicaRow[];
+};
+/** Apply {@link normalizeReplicaTableInput} to every table; shallow-copies the document shell. */
+declare function normalizeReplicaDocumentInput<T extends GristReplicaDocument>(doc: T): T;
+/** How row arrays appear in serialized replica JSON from {@link buildReplicaJsonPayload}. */
+type ReplicaJsonIncludeRows = "none" | "samples" | "full";
+/**
+ * Clone a replica document for JSON output: strip rows, cap to first N, or pass through.
+ * Does not mutate the source document.
+ */
+declare function buildReplicaJsonPayload(doc: GristReplicaDocument, options: {
+    includeRows: ReplicaJsonIncludeRows;
+    sampleRowLimit?: number;
+}): GristReplicaDocument;
+
+/**
+ * Grist stores column widget configuration in `_grist_Tables_column.widgetOptions`
+ * as a JSON string. Choice fields use `choices: string[]` plus optional
+ * `choiceOptions: Record<string, Style>` (e.g. `fillColor`, `textColor`).
+ *
+ * @see https://github.com/gristlabs/grist-core/blob/main/app/client/widgets/ChoiceEditor.js
+ */
+/** One selectable choice for UI (value stored in the cell is `value`). */
+type GristChoiceListEntry = {
+    value: string;
+    label: string;
+    fillColor?: string;
+    textColor?: string;
+};
+/**
+ * Parse a cell value from `_grist_Tables_column.widgetOptions` into a plain object.
+ */
+declare function parseGristWidgetOptionsCell(raw: unknown): Record<string, unknown> | undefined;
+/**
+ * Normalizes Grist Choice / ChoiceList widgetOptions into a flat list for dropdowns.
+ * `choices` entries are string labels (the stored cell value). Per-choice styling
+ * lives in `choiceOptions[label]`.
+ */
+declare function normalizeGristChoiceListEntries(widgetOptions: Record<string, unknown> | undefined): GristChoiceListEntry[];
+
+/**
+ * Encoding helpers for Grist cell values.
+ *
+ * Grist sends some types as marshalled tuples or numeric epochs. This file
+ * exposes pure decode/encode functions so widget code never has to spelunk
+ * Grist's wire format.
+ *
+ * References: Grist `grist/RowRecord` and `grist/DocActions` typings.
+ */
+
+/** `["E", "ErrorClass", "message", traceback?]` — Grist error sentinel. */
+type GristEncodedError = ["E", string, string?, string?];
+/** `["L", ...items]` — list (used for ChoiceList, RefList, Attachments). */
+type GristEncodedList = ["L", ...unknown[]];
+/** `["D", epochSeconds, "tz/Name"]` — DateTime with timezone. */
+type GristEncodedDateTime = ["D", number, string];
+/** `["d", epochSeconds]` — Date (no time). */
+type GristEncodedDate = ["d", number];
+/** `["R", tableId, rowId]` — explicit reference. */
+type GristEncodedRef = ["R", string, number];
+/** `["r", rowId]` — bare reference (when table is contextual). */
+type GristEncodedBareRef = ["r", number];
+/** `["P", encoded]` — pending marker. */
+type GristEncodedPending = ["P"];
+type GristDecodedValue = null | string | number | boolean | Date | GristDecodedValue[] | {
+    __error: true;
+    type: string;
+    message?: string;
+    traceback?: string;
+} | {
+    __ref: true;
+    tableId?: string;
+    rowId: number;
+};
+/**
+ * Normalises a Grist `fetchTable` cell that points at a row in another table.
+ * Most payloads use a bare numeric row id, but `Ref:*` values may appear as
+ * `["R", tableId, rowId]` or `["r", rowId]` (same shape as {@link decodeGristValue}).
+ */
+declare function coerceGristDocApiRefRowId(value: unknown): number | undefined;
+/**
+ * Decodes a Grist cell value into an idiomatic JS value.
+ *
+ * Pass the column's metadata (from `useGristSchema` or `_grist_Tables_column`)
+ * for type-aware decoding (e.g. `Date` columns return `Date` even when stored as a number).
+ */
+declare function decodeGristValue(value: unknown, column?: GristReplicaColumn): GristDecodedValue;
+/** Convenience: true when the cell is a Grist error sentinel. */
+declare function isGristCellError(value: unknown): value is GristEncodedError;
+/**
+ * Encodes a JS value into Grist's expected wire form for a given column type.
+ *
+ * Use before passing values to `applyUserActions` or `TableOperations.update`
+ * for `Date`, `DateTime`, `Ref`, `RefList`, and `ChoiceList` columns.
+ */
+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.
+ *
+ * Blocking states (`booting`, `unavailable`, `error`) map to full-screen chrome
+ * via `<GristBoundary>`. Non-blocking degradations stay on the alert path
+ * ({@link getGristSdkAlertDescriptors}).
+ */
+
+type GristBoundaryBlockingKind = "booting" | "unavailable" | "error";
+type GristBoundaryBootPhase = "idle" | "detecting" | "negotiating" | "generic";
+type GristBoundaryView = {
+    mode: "blocking";
+    kind: GristBoundaryBlockingKind;
+    bootPhase?: GristBoundaryBootPhase;
+    title: string;
+    message: string;
+    showRetry: boolean;
+} | {
+    mode: "ready";
+};
+/**
+ * Human-readable boot label from lifecycle phase (for spinners / progress UI).
+ */
+declare function deriveBoundaryBootLabel(snapshot: GristWidgetSnapshot): string;
+declare function deriveBoundaryBootPhase(snapshot: GristWidgetSnapshot): GristBoundaryBootPhase;
+/**
+ * Turn internal handshake errors into short, actionable copy for `<GristBoundary>`.
+ */
+declare function formatBoundaryUserMessage(raw: string | null, snapshot: GristWidgetSnapshot): string;
+/**
+ * Classify how `<GristBoundary>` should render: full-screen blocking vs children.
+ */
+declare function deriveBoundaryView(snapshot: GristWidgetSnapshot): GristBoundaryView;
+/** Copy for `gate="canRender"` while column mappings are not yet usable. */
+declare const GRIST_BOUNDARY_PREPARING_COPY: {
+    readonly title: "Map your columns";
+    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;
+/**
+ * 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}.
+ */
+declare function useGristSdkAlertDescriptors(widget?: GristSdkAlertsWidgetSlice | UseGristResult, options?: GetGristSdkAlertDescriptorsOptions): GristSdkAlertDescriptor[];
+
+type GristWidgetProviderProps = {
+    options?: UseGristOptions;
+    children: ReactNode;
+};
+/**
+ * Sets up Grist once at the app root. Prefer slice hooks (`useGristSelection`,
+ * `useGristWrites`, …) in large widgets; use `useGristContext()` when you need everything.
+ *
+ * Owns a {@link GristHandshakeManager} and mounts the slice / full-result context
+ * tree underneath it so `useRpcHeartbeatCoalesce()` in slice hooks sees the manager
+ * (ordering required — see `tests/sdk/handshake-rpc-coalesce.test.tsx`).
+ */
+declare function GristWidgetProvider({ options, children }: GristWidgetProviderProps): react_jsx_runtime.JSX.Element;
+/**
+ * Access the full `UseGristResult` from inside a `<GristWidgetProvider>`.
+ *
+ * The returned object updates whenever any Grist state changes (record selection,
+ * widget options, etc.). Individual methods on the result (e.g. `w.fetchTable`,
+ * `w.listTables`) are referentially stable and safe to use in `useEffect` deps.
+ * See `UseGristResult` JSDoc for details.
+ */
+declare function useGristContext<TRow = Record<string, unknown>, TMapped = Record<string, unknown>>(): UseGristResult<TRow, TMapped>;
+declare function useGristOptional<TRow = Record<string, unknown>, TMapped = Record<string, unknown>>(): UseGristResult<TRow, TMapped> | null;
+
+/**
+ * Primary Grist hook — use inside `<GristWidgetProvider>` via `useGristContext()`,
+ * or standalone in a single-leaf widget.
+ */
+declare function useGrist<TRow = Record<string, unknown>, TMapped = Record<string, unknown>>(options?: UseGristOptions): UseGristResult<TRow, TMapped>;
+
+/**
+ * Slice subscriber: status + current-table info. Re-renders on status, error,
+ * `currentTableId`, or `currentTableLoading` changes only.
+ *
+ * Must be called inside `<GristWidgetProvider>` — for standalone usage use
+ * `useGrist()` directly.
+ */
+declare function useGristStatus(): GristStatusSliceValue;
+/**
+ * Slice subscriber for the selection / mappings / widget-options stream.
+ * Must be called inside `<GristWidgetProvider>`.
+ */
+declare function useGristSelection<TRow = Record<string, unknown>, TMapped = Record<string, unknown>>(): UseGristSelectionResult<TRow, TMapped>;
+/**
+ * Slice subscriber for writes (`table`, `getTable`, `applyActions`, `actionStatus`).
+ * Must be called inside `<GristWidgetProvider>`.
+ */
+declare function useGristWrites(): UseGristTableOpsBoundResult;
+/**
+ * Slice subscriber for the host theme. Must be called inside `<GristWidgetProvider>`.
+ */
+declare function useGristTheme(): UseGristThemeResult;
+
+type GristBoundaryGate = "ready" | "canRender";
+type GristBoundaryProps = {
+    /**
+     * Pass an explicit widget instance (e.g. when not using `<GristWidgetProvider>`).
+     * Otherwise the boundary reads from the nearest provider.
+     */
+    widget?: UseGristResult;
+    /**
+     * When `"canRender"`, children render only after mappings are usable
+     * (`capabilities.canRender`). Use for widgets that require mapped columns.
+     */
+    gate?: GristBoundaryGate;
+    /** Rendered while `grist.ready` is in flight. */
+    bootingFallback?: ReactNode;
+    /** Shown when `gate="canRender"` and mappings are not yet usable. */
+    preparingFallback?: ReactNode;
+    /** Rendered when the widget is not embedded in Grist (e.g. opened directly). */
+    unavailableFallback?: ReactNode | ((actions: GristBoundaryActions) => ReactNode);
+    /** Rendered on any error from `useGristReady`, subscriptions, or actions. */
+    errorFallback?: (error: string, actions: GristBoundaryActions) => ReactNode;
+    /**
+     * Delay before showing "unavailable" UI. Helps avoid false negatives on slow
+     * networks where the plugin API handshake arrives late.
+     */
+    unavailableGraceMs?: number;
+    children: ReactNode;
+};
+type GristBoundaryActions = {
+    reload: () => Promise<void>;
+    isReloading: boolean;
+};
+type GristBoundaryScreenProps = {
+    title: string;
+    message: string;
+    /** Affects WAI-ARIA role only (`alert` vs `status`); copy uses the same neutral styles. */
+    tone?: "default" | "error";
+    showRetry?: boolean;
+    actions?: GristBoundaryActions;
+    retryLabel?: string;
+    retryBusyLabel?: string;
+};
+/** Centered full-viewport chrome for booting / unavailable / error states. */
+declare function GristBoundaryScreen({ title, message, tone, showRetry, actions, retryLabel, retryBusyLabel, }: GristBoundaryScreenProps): react_jsx_runtime.JSX.Element;
+/**
+ * Standardised loading / unavailable / error chrome for a Grist widget.
+ *
+ * ```tsx
+ * <GristWidgetProvider options={{ requiredAccess: "full" }}>
+ *   <GristBoundary>
+ *     <MyWidget />
+ *   </GristBoundary>
+ * </GristWidgetProvider>
+ * ```
+ */
+declare function GristBoundary({ widget, gate, bootingFallback, preparingFallback, unavailableFallback, errorFallback, unavailableGraceMs, children, }: GristBoundaryProps): react_jsx_runtime.JSX.Element;
+
+type ColumnExcludeContext = {
+    tableId: string;
+    colId: string;
+    col: GristReplicaColumn;
+};
+type UseGristSchemaOptions = {
+    requiredAccess?: GristRequiredAccess;
+    tableId?: string;
+    excludeSystemTableData?: boolean;
+    /**
+     * How row bodies are included in the replica document.
+     * Default `schema+samples`.
+     */
+    replicaRowMode?: GristDocumentMode;
+    /** When `replicaRowMode` is `schema+samples`, max rows per table. Default 10. */
+    sampleRowLimit?: number;
+    /** Stored on the replica as `source` (e.g. for logging). */
+    source?: string;
+} & GristNoiseColumnsOptions & {
+    extraExcludeColumn?: (ctx: ColumnExcludeContext) => boolean;
+} & Pick<GristReadyOptions, "columns" | "allowSelectBy" | "hasCustomOptions" | "onEditOptions">;
+/** Selected table slice with `tableId` for consumers that expect it on the object. */
+type GristSchemaTableView = GristReplicaTable & {
+    tableId: string;
+};
+/** Options for `getDocumentJson` / `buildDocumentJson` on the return value of {@link useGristSchema}. */
+type ReplicaDocumentJsonOptions = {
+    /** How row arrays appear in JSON. Default `full` (all rows currently on the document). */
+    includeRows?: ReplicaJsonIncludeRows;
+    /** Cap per table when `includeRows` is `samples`. Default 10. */
+    sampleRowLimit?: number;
+    space?: number;
+};
+type UseGristSchemaResult = {
+    isAvailable: boolean | null;
+    /** Canonical replica document. */
+    document: GristReplicaDocument | null;
+    /** Same reference as `document`. */
+    replicaDocument: GristReplicaDocument | null;
+    table: GristSchemaTableView | null;
+    documentJson: string | null;
+    getDocumentJson: (options?: ReplicaDocumentJsonOptions) => string | null;
+    buildDocumentJson: (document: GristReplicaDocument, options?: ReplicaDocumentJsonOptions) => string;
+    tableJson: string | null;
+    getTableJson: (options?: ReplicaDocumentJsonOptions) => string | null;
+    buildTableJson: (table: GristSchemaTableView, options?: ReplicaDocumentJsonOptions) => string;
+    isNoiseColumnId: (colId: string, col?: GristReplicaColumn) => boolean;
+    sortColumnIds: (colIds: string[], columns: Record<string, GristReplicaColumn>) => string[];
+    loading: boolean;
+    error: string | null;
+    reload: () => Promise<void>;
+};
+/**
+ * Grist replica-document hook: metadata + optional decoded `rows` per table.
+ */
+declare function useGristSchema(options?: UseGristSchemaOptions): UseGristSchemaResult;
+
+type UseWidgetMetadataInput = {
+    title: string;
+    description: string;
+    syncToParent?: boolean;
+};
+declare function useWidgetMetadata(input?: UseWidgetMetadataInput | null): void;
+
+export { type BuildReplicaDocumentFromDocApiOptions, FetchGristTableRowsOptions, GRIST_BOUNDARY_PREPARING_COPY, type GetGristSdkAlertDescriptorsOptions, GristAccessToken, GristApplyUserActionsOptions, type GristAttachmentUploadResult, GristBoundary, type GristBoundaryActions, type GristBoundaryBlockingKind, type GristBoundaryBootPhase, type GristBoundaryGate, type GristBoundaryProps, GristBoundaryScreen, type GristBoundaryView, GristCapabilities, type GristChoiceListEntry, GristColumnInfo, GristColumnarTable, GristColumnsToMap, GristCursorPos, type GristDecodedValue, GristDocApi, GristDocumentMode, type GristEncodedAttachmentList, type GristEncodedBareRef, type GristEncodedDate, type GristEncodedDateTime, type GristEncodedError, type GristEncodedList, type GristEncodedPending, type GristEncodedRef, GristFetchSelectedOptions, type GristFetchedAttachment, type GristFetchedAttachmentBlob, GristFormulaKind, GristNoiseColumnsOptions, GristReadyOptions, GristReplicaColumn, GristReplicaDocument, GristReplicaRow, GristReplicaTable, GristRequiredAccess, GristRowRecord, GristSafeParseCellResult, type GristSchemaTableView, type GristSdkAlertDescriptor, type GristSdkAlertKind, type GristSdkAlertSeverity, type GristSdkAlertsWidgetSlice, GristTableOperations, type GristTheme, GristUserActionTuple, type GristWidgetActionStatus, GristWidgetColumnMap, GristWidgetInteraction, type GristWidgetMode, GristWidgetProvider, type GristWidgetProviderProps, GristWidgetStatus, ListColumnsOptions, ListTablesOptions, type ReplicaDocumentJsonOptions, type ReplicaJsonIncludeRows, type ReplicaTableColumnMetaLite, SafeParseGristTableDataOptions, type UseGristOptions, type UseGristResult, type UseGristSchemaOptions, type UseGristSchemaResult, type UseWidgetMetadataInput, type ValidateColumnMappingsResult, 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 };