grist-widget-sdk 0.3.27 → 0.4.0

package/dist/index.d.cts

@@ -1,276 +1,35 @@
-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.cjs';
-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.cjs';
-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-DdOLEJXN.cjs';
-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-DdOLEJXN.cjs';
-import { a as GristNoiseColumnsOptions } from './use-grist-reads-DpjVuI0H.cjs';
-import { GristWidgetSnapshot } from './advanced.cjs';
-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-DpjVuI0H.cjs';
+import { U as UseGristOptions, G as GristNoiseColumnsOptions } from './use-grist-BK0eke9K.cjs';
+export { a as GristAttachmentUploadResult, b as GristCellIssue, c as GristColumnInfo, d as GristColumnarTable, e as GristFetchedAttachmentBlob, f as GristMappedRow, g as GristSdkAlertKind, h as GristTheme, i as GristUserActionTuple, j as GristWidgetActionStatus, k as GristWidgetMode, l as GristWidgetStatus, L as ListColumnsOptions, m as ListTablesOptions, S as StandardSchema, n as UseGristResult, V as ValidateColumnMappingsResult, o as checkGristCell, p as extractGristAttachmentId, q as extractGristAttachmentIdsFromCell, r as gristAddColumnAction, s as gristAddRecordAction, t as gristAddTableAction, u as gristAddVisibleColumnAction, v as gristAttachmentCellValue, w as gristAttachmentCellValues, x as gristModifyColumnAction, y as gristRemoveColumnAction, z as gristRemoveRecordAction, A as gristRenameColumnAction, B as gristUpdateRecordAction, C as mergeGristAttachmentCellValue, D as tableDataToRows, E as useGrist, F as useGristContext, H as useGristOptional } from './use-grist-BK0eke9K.cjs';
 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.cjs';
-import 'zod';
-
-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;
-
-/**
- * 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;
-
-/**
- * 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.";
-};
-
-/**
- * React hook: widget slice + optional handshake snapshot for
- * {@link getGristSdkAlertDescriptors}.
- */
-declare function useGristSdkAlertDescriptors(widget?: GristSdkAlertsWidgetSlice | UseGristResult, options?: GetGristSdkAlertDescriptorsOptions): GristSdkAlertDescriptor[];
+import { a as GristReplicaTable, l as GristRequiredAccess, m as GristDocumentMode, e as GristReplicaColumn, i as GristReadyOptions, G as GristReplicaDocument, n as GristFormulaKind } from './types-DBStn0Dk.cjs';
+export { o as GristApplyUserActionsOptions, p as GristColumnToMap, q as GristColumnsToMap, c as GristCursorPos, j as GristFetchSelectedOptions, r as GristReplicaRow, f as GristRowRecord, k as GristTableOperations, b as GristWidgetColumnMap, d as GristWidgetInteraction } from './types-DBStn0Dk.cjs';
 
 type GristWidgetProviderProps = {
+    /** Read once, at mount: what the widget asks Grist for. */
     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`).
+ * Connects to Grist for the widgets below it: `useGrist()` under it reads this
+ * connection. `mountGristWidget()` renders it; render it yourself only for a
+ * page that manages its own React root.
  */
 declare function GristWidgetProvider({ options, children }: GristWidgetProviderProps): react.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(): UseGristStatusResult;
-/**
- * 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(): UseGristWritesResult;
-/**
- * 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.Element;
 /**
- * Standardised loading / unavailable / error chrome for a Grist widget.
- *
- * ```tsx
- * <GristWidgetProvider options={{ requiredAccess: "full" }}>
- *   <GristBoundary>
- *     <MyWidget />
- *   </GristBoundary>
- * </GristWidgetProvider>
- * ```
+ * Renders the widget once Grist is connected, has granted the access it
+ * declares, and every required declared column is mapped; until then, a
+ * screen that says what is missing (with a retry where one can help).
+ * Requires `<GristWidgetProvider>`; `mountGristWidget()` renders both.
  */
-declare function GristBoundary({ widget, gate, bootingFallback, preparingFallback, unavailableFallback, errorFallback, unavailableGraceMs, children, }: GristBoundaryProps): react.JSX.Element;
+declare function GristBoundary({ children }: GristBoundaryProps): react.JSX.Element;
+
+/** How row arrays appear in serialized replica JSON from {@link buildReplicaJsonPayload}. */
+type ReplicaJsonIncludeRows = "none" | "samples" | "full";
 
 type ColumnExcludeContext = {
     tableId: string;
@@ -332,9 +91,71 @@ declare function useGristSchema(options?: UseGristSchemaOptions): UseGristSchema
 type UseWidgetMetadataInput = {
     title: string;
     description: string;
-    syncToParent?: boolean;
 };
 declare function useWidgetMetadata(input?: UseWidgetMetadataInput | null): void;
 
-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 };
+/**
+ * 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?];
+type GristDecodedValue = null | string | number | boolean | Date | GristDecodedValue[] | {
+    __error: true;
+    type: string;
+    message?: string;
+    traceback?: string;
+} | {
+    __ref: true;
+    tableId?: string;
+    rowId: number;
+};
+/**
+ * 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;
+
+/**
+ * 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;
+};
+/**
+ * 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[];
+
+/** Use when `formulaKind` may be missing (e.g. older document builds). */
+declare function resolveGristFormulaKind(col: GristReplicaColumn): GristFormulaKind;
+
+export { GristBoundary, GristDocumentMode, GristFormulaKind, GristNoiseColumnsOptions, GristReadyOptions, GristReplicaColumn, GristReplicaDocument, GristReplicaTable, GristRequiredAccess, GristWidgetProvider, UseGristOptions, decodeGristValue, encodeGristValue, isGristCellError, normalizeGristChoiceListEntries, resolveGristFormulaKind, useGristSchema, useWidgetMetadata };
+export type { GristBoundaryProps, GristChoiceListEntry, GristSchemaTableView, GristWidgetProviderProps, ReplicaDocumentJsonOptions, UseGristSchemaOptions, UseGristSchemaResult, UseWidgetMetadataInput };