grist-widget-sdk 0.3.20 → 0.3.26

package/dist/use-grist-types-kwxoFeub.d.ts

@@ -0,0 +1,499 @@
+import { s as GristDocApi, c as GristReplicaColumn, b as GristReplicaDocument, r 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 } from './types-D3JxUCfL.js';
+import { G as GristWidgetSnapshot, q as GristWidgetStatus, p as GristUserActionTuple, u as UseGristCoreResult, U as UseGristCoreOptions, c as GristCapabilities, g as GristColumnarTable, F as FetchGristTableRowsOptions, S as SafeParseGristTableDataOptions, h as GristSafeParseCellResult, r as ListTablesOptions, L as ListColumnsOptions, e as GristColumnInfo, b as GristAccessToken } from './use-grist-reads-DUMvJgV7.js';
+
+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>;
+
+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>;
+
+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;
+
+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;
+};
+
+export { formatColumnMappingAlertMessage as A, formatLinkStaleAlertMessage as C, formatMappingPendingAlertMessage as D, formatMappingUnreportedAlertMessage as E, formatSectionNotLinkedAlertMessage as F, formatSourceNotWiredAlertMessage as H, getAttachmentDownloadUrl as I, getAttachmentDownloadUrlForCell as J, getGristSdkAlertDescriptors as K, getGristSdkAlertSeverity as L, getGristSdkAlertTitle as M, gristAttachmentCellValue as N, gristAttachmentCellValues as O, isAccessInsufficientError as P, isWidgetSectionNotLinked as Q, loadColumnMetadataByTable as S, mergeGristAttachmentCellValue as T, orderedColumnIds as W, parseGristAttachmentUploadResponse as X, parseGristAttachmentUploadResponseIds as Y, uploadGristAttachment as Z, validateColumnMappings as _, buildReplicaColumnsFromColumnar as q, buildReplicaDocumentFromDocApi as r, extractAttachmentIdsFromUploadPayload as s, extractFirstAttachmentIdFromUploadPayload as t, extractGristAttachmentId as u, extractGristAttachmentIdsFromCell as v, fetchAttachmentBase64 as w, fetchAttachmentBase64ForCell as x, fetchAttachmentBlob as y, formatAccessInsufficientMessage as z };
+export type { BuildReplicaDocumentFromDocApiOptions as B, GristSdkAlertsWidgetSlice as G, ReplicaTableColumnMetaLite as R, UseGristOptions as U, ValidateColumnMappingsResult as V, UseGristResult as a, GetGristSdkAlertDescriptorsOptions as b, GristSdkAlertDescriptor as c, UseGristSelectionResult as d, UseGristStatusResult as e, UseGristThemeResult as f, UseGristWritesResult as g, GristAttachmentUploadResult as h, GristEncodedAttachmentList as i, GristFetchedAttachment as j, GristFetchedAttachmentBlob as k, GristSdkAlertKind as l, GristSdkAlertSeverity as m, GristTheme as n, GristWidgetActionStatus as o, GristWidgetMode as p };

package/dist/use-grist-widget-options-from-context-CGOlQ5Vc.d.cts

@@ -0,0 +1,43 @@
+type UseGristWidgetOptionsFromContextConfig<T> = {
+    /** Default values returned before Grist responds and merged with stored options. */
+    defaults: T;
+    /** Debounce window for `setOptions` writes (ms). Default: 250. */
+    debounceMs?: number;
+    /**
+     * Optional namespace key. When set, this hook reads/writes
+     * `options[namespace]` instead of the whole options blob.
+     */
+    namespace?: string;
+};
+type UseGristWidgetOptionsFromContextResult<T> = {
+    options: T;
+    /** True until Grist has responded with the initial `onOptions` payload. */
+    loading: boolean;
+    /** Replace the options object (debounced write to Grist). */
+    setOptions: (next: T) => void;
+    /** Patch a subset of keys (debounced write to Grist). */
+    patchOptions: (patch: Partial<T>) => void;
+    /** Reset to `defaults` (immediate write to Grist). */
+    reset: () => Promise<void>;
+};
+/**
+ * Typed widget options hook designed for use **inside a `<GristWidgetProvider>`**.
+ *
+ * Unlike `useGristWidgetOptions()` (which calls `useGristReady()` and conflicts
+ * with the provider), this hook reads from the provider's existing context —
+ * `widgetOptions` for reactive reads, and `patchWidgetOptions` / `setWidgetOptions`
+ * for writes.
+ *
+ * ```tsx
+ * function MyConfigPanel() {
+ *   const { options, patchOptions } = useGristWidgetOptionsFromContext({
+ *     defaults: { color: '#FF0000', showLabels: true },
+ *   })
+ *   return <input value={options.color} onChange={e => patchOptions({ color: e.target.value })} />
+ * }
+ * ```
+ */
+declare function useGristWidgetOptionsFromContext<T extends Record<string, unknown>>(config: UseGristWidgetOptionsFromContextConfig<T>): UseGristWidgetOptionsFromContextResult<T>;
+
+export { useGristWidgetOptionsFromContext as u };
+export type { UseGristWidgetOptionsFromContextConfig as U, UseGristWidgetOptionsFromContextResult as a };

package/dist/use-grist-widget-options-from-context-CGOlQ5Vc.d.ts

@@ -0,0 +1,43 @@
+type UseGristWidgetOptionsFromContextConfig<T> = {
+    /** Default values returned before Grist responds and merged with stored options. */
+    defaults: T;
+    /** Debounce window for `setOptions` writes (ms). Default: 250. */
+    debounceMs?: number;
+    /**
+     * Optional namespace key. When set, this hook reads/writes
+     * `options[namespace]` instead of the whole options blob.
+     */
+    namespace?: string;
+};
+type UseGristWidgetOptionsFromContextResult<T> = {
+    options: T;
+    /** True until Grist has responded with the initial `onOptions` payload. */
+    loading: boolean;
+    /** Replace the options object (debounced write to Grist). */
+    setOptions: (next: T) => void;
+    /** Patch a subset of keys (debounced write to Grist). */
+    patchOptions: (patch: Partial<T>) => void;
+    /** Reset to `defaults` (immediate write to Grist). */
+    reset: () => Promise<void>;
+};
+/**
+ * Typed widget options hook designed for use **inside a `<GristWidgetProvider>`**.
+ *
+ * Unlike `useGristWidgetOptions()` (which calls `useGristReady()` and conflicts
+ * with the provider), this hook reads from the provider's existing context —
+ * `widgetOptions` for reactive reads, and `patchWidgetOptions` / `setWidgetOptions`
+ * for writes.
+ *
+ * ```tsx
+ * function MyConfigPanel() {
+ *   const { options, patchOptions } = useGristWidgetOptionsFromContext({
+ *     defaults: { color: '#FF0000', showLabels: true },
+ *   })
+ *   return <input value={options.color} onChange={e => patchOptions({ color: e.target.value })} />
+ * }
+ * ```
+ */
+declare function useGristWidgetOptionsFromContext<T extends Record<string, unknown>>(config: UseGristWidgetOptionsFromContextConfig<T>): UseGristWidgetOptionsFromContextResult<T>;
+
+export { useGristWidgetOptionsFromContext as u };
+export type { UseGristWidgetOptionsFromContextConfig as U, UseGristWidgetOptionsFromContextResult as a };

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "grist-widget-sdk",
-  "version": "0.3.20",
+  "version": "0.3.26",
   "description": "React hooks and helpers for Grist custom widgets",
   "license": "MIT",
   "engines": {
@@ -50,6 +50,16 @@
         "default": "./dist/advanced.cjs"
       }
     },
+    "./app": {
+      "import": {
+        "types": "./dist/app.d.ts",
+        "default": "./dist/app.js"
+      },
+      "require": {
+        "types": "./dist/app.d.cts",
+        "default": "./dist/app.cjs"
+      }
+    },
     "./emulator": {
       "import": {
         "types": "./dist/emulator.d.ts",
@@ -89,10 +99,13 @@
         "types": "./dist/emulator/devtools.d.cts",
         "default": "./dist/emulator/devtools.cjs"
       }
-    }
+    },
+    "./tsconfig/app.json": "./tsconfig/app.json",
+    "./tsconfig/node.json": "./tsconfig/node.json"
   },
   "files": [
     "dist",
+    "tsconfig",
     "CHANGELOG.md",
     "LICENSE"
   ],

package/tsconfig/app.json

@@ -0,0 +1,38 @@
+{
+  // Shared TypeScript settings for a widget's browser code (src/).
+  //
+  //   // tsconfig.app.json
+  //   { "extends": "grist-widget-sdk/tsconfig/app.json", ... }
+  //
+  // The widget's own file keeps whatever names its files and packages:
+  // tsBuildInfoFile, paths and include (TypeScript resolves those relative
+  // to the file that declares them), and types (its own list of global type
+  // packages, e.g. "vite/client"; a list set there would replace this one).
+  //
+  // Needs TypeScript 5.8 or later (erasableSyntaxOnly). Making a check
+  // stricter can fail a widget's typecheck, so it only happens in a minor
+  // (breaking, before 1.0) release of grist-widget-sdk.
+  "compilerOptions": {
+    "target": "ES2022",
+    "useDefineForClassFields": true,
+    "lib": ["ES2022", "DOM", "DOM.Iterable"],
+    "module": "ESNext",
+    "skipLibCheck": true,
+
+    /* Bundler mode */
+    "moduleResolution": "bundler",
+    "allowImportingTsExtensions": true,
+    "verbatimModuleSyntax": true,
+    "moduleDetection": "force",
+    "noEmit": true,
+    "jsx": "react-jsx",
+
+    /* Linting */
+    "strict": true,
+    "noUnusedLocals": true,
+    "noUnusedParameters": true,
+    "erasableSyntaxOnly": true,
+    "noFallthroughCasesInSwitch": true,
+    "noUncheckedSideEffectImports": true
+  }
+}