grist-widget-sdk 0.3.27 → 0.4.0

package/dist/advanced.d.cts

@@ -1,822 +0,0 @@
-import { a8 as GristTerminationReason, a9 as GristGeneration, aa as GristMappingSource, G as GristWidgetSnapshot, c as GristCapabilities } from './use-grist-reads-DpjVuI0H.cjs';
-import { UseGristCoreOptions, GristWidgetStatus, GristUserActionTuple, GristAccessToken, GristColumnarTable } from './index.cjs';
-export { ab as GristAuthz, e as GristColumnInfo, ac as GristConfig, ad as GristCurrentTableState, ae as GristLifecycle, af as GristLifecyclePhase, ag as GristLink, ah as GristLinkState, ai as GristMappingComplete, aj as GristMappingIncomplete, ak as GristMappingState, al as GristStreamFreshness, am as GristSync, L as ListColumnsOptions, r as ListTablesOptions } from './use-grist-reads-DpjVuI0H.cjs';
-import { GristRequiredAccess, GristColumnsToMap, GristWidgetColumnMap, GristReadyOptions, GristDocApi, GristApplyUserActionsOptions, GristTableNewRecord, GristTableOpOptions, GristMinimalRecord, GristTableUpdateRecord, GristTableUpsertRecord, GristTableUpsertOptions, GristRowRecord, GristFetchSelectedOptions } from './index.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';
-
-/**
- * Action union for the handshake state machine.
- *
- * Every action that can mutate the snapshot is listed here as a discriminated
- * union — exhaustiveness checks in the reducer rely on it.
- *
- * Actions either:
- *   - target a single axis (e.g. `RPC_SUCCESS` → link), OR
- *   - target multiple axes via a single transition (e.g. `NEGOTIATE_SUCCESS`
- *     advances lifecycle AND authz at once).
- *
- * Generation-carrying actions can be **dropped** by the reducer if their
- * `generation` is older than the snapshot's current generation; this is the
- * primary defence against stale events arriving after a reload/restart.
- */
-
-type GristLifecycleAction = {
-    type: "DETECT_START";
-    atMs: number;
-} | {
-    type: "DETECT_TICK";
-    attempts: number;
-    atMs: number;
-} | {
-    type: "DETECT_AVAILABLE";
-    atMs: number;
-} | {
-    type: "DETECT_TIMEOUT";
-    attempts: number;
-    atMs: number;
-} | {
-    type: "NOT_EMBEDDED";
-    atMs: number;
-} | {
-    type: "NEGOTIATE_START";
-    access: GristRequiredAccess;
-    atMs: number;
-} | {
-    type: "NEGOTIATE_SUCCESS";
-    access: GristRequiredAccess;
-    grantedLevel: GristRequiredAccess;
-    atMs: number;
-} | {
-    type: "NEGOTIATE_FAIL";
-    reason: GristTerminationReason;
-    atMs: number;
-} | {
-    type: "TERMINATE";
-    reason: GristTerminationReason;
-    atMs: number;
-};
-type GristLinkAction = {
-    type: "RPC_SUCCESS";
-    atMs: number;
-} | {
-    type: "RPC_FAILURE";
-    atMs: number;
-    kind: "timeout" | "rejected" | "other";
-} | {
-    type: "HEARTBEAT_OK";
-    atMs: number;
-} | {
-    type: "HEARTBEAT_FAIL";
-    atMs: number;
-};
-type GristAuthzAction = {
-    type: "AUTHZ_REPORT";
-    /** Effective access level reported by Grist (`onOptions` / `interaction.access_level`). */
-    level: GristRequiredAccess;
-    atMs: number;
-    generation: GristGeneration;
-};
-type GristGenerationAction = {
-    type: "BUMP_GENERATION";
-    atMs: number;
-    reason: "reload" | "restart" | "link_recovery" | "widening";
-};
-type GristMappingAction = {
-    type: "MAPPING_DECLARE";
-    declared: GristColumnsToMap;
-    atMs: number;
-    generation: GristGeneration;
-} | {
-    type: "MAPPING_REPORT";
-    source: GristMappingSource;
-    payload: GristWidgetColumnMap | null;
-    atMs: number;
-    generation: GristGeneration;
-} | {
-    type: "MAPPING_INVALIDATE";
-    atMs: number;
-    generation: GristGeneration;
-} | {
-    type: "MAPPING_INVALIDATION_RESOLVE";
-    atMs: number;
-    generation: GristGeneration;
-} | {
-    type: "MAPPING_TIMEOUT";
-    atMs: number;
-    generation: GristGeneration;
-};
-type GristSyncStream = "record" | "records" | "options" | "newRecord";
-type GristSyncAction = {
-    type: "STREAM_RECEIVED";
-    stream: GristSyncStream;
-    payloadHash: string;
-    atMs: number;
-    generation: GristGeneration;
-} | {
-    type: "STREAM_WARMING";
-    stream: GristSyncStream;
-    atMs: number;
-} | {
-    type: "STREAM_STALE";
-    stream: GristSyncStream;
-    atMs: number;
-    reason: "link_lost" | "tab_hidden" | "host_quiet";
-} | {
-    type: "CURRENT_TABLE_KNOWN";
-    tableId: string;
-    atMs: number;
-} | {
-    type: "CURRENT_TABLE_REFRESH_START";
-    atMs: number;
-} | {
-    type: "CURRENT_TABLE_ERROR";
-    message: string;
-    atMs: number;
-};
-type GristAction = GristLifecycleAction | GristLinkAction | GristAuthzAction | GristGenerationAction | GristMappingAction | GristSyncAction;
-
-/**
- * Pure reducer for the handshake state machine.
- *
- * Contract
- * --------
- *   - **Pure**: `(snapshot, action, ctx) => nextSnapshot`. No I/O, no globals,
- *     no Date.now() — callers pass timestamps via `action.atMs` and (optionally)
- *     a context object for the {@link MappingResolver}.
- *   - **Total**: every (snapshot.lifecycle.phase × action.type) pair returns
- *     either an updated snapshot or the identity snapshot.
- *   - **Idempotent for replays**: same generation-stamped action applied twice
- *     leaves the snapshot unchanged (`payloadHash` short-circuit on streams,
- *     resolver hash short-circuit on mappings).
- *   - **Generation-safe**: any action carrying a `generation` lower than the
- *     current snapshot generation is dropped silently — this is what makes
- *     the SDK robust to late events after reload/restart.
- *
- * The reducer never throws. Invariant violations are surfaced via
- * `./invariants.ts` if the caller opts in.
- */
-
-/**
- * Tuning knobs. Pass `Partial<ReducerConfig>` to override defaults; values
- * are read by the reducer at each step.
- */
-type ReducerConfig = {
-    /** Stale-pings threshold before link transitions to `stale`. */
-    staleAfterMissed: number;
-    /** Stale-pings threshold before link transitions to `lost`. */
-    lostAfterMissed: number;
-};
-
-/**
- * Environment abstraction for the handshake effects layer.
- *
- * Why an abstraction
- * ------------------
- * The detect / negotiate / heartbeat effects need access to:
- *   - the `grist` global (or absence thereof),
- *   - `window.self !== window.top` to detect iframe embedding,
- *   - timers (`setTimeout`, `clearTimeout`),
- *   - the wall clock (`performance.now()` or `Date.now()`),
- *   - `navigator.connection?.effectiveType` for adaptive policy.
- *
- * Putting these behind a small interface lets us test the manager and effects
- * **without touching `window`**, using deterministic fake timers and stubbed
- * detectors / negotiators.
- *
- * Production code calls {@link createBrowserEnvironment()} which returns an
- * adapter against `globalThis`. Tests pass {@link createTestEnvironment} or a
- * hand-rolled stub.
- */
-
-type GristEnvironment = {
-    /** Wall-clock ms (monotonic preferred but not required). */
-    now(): number;
-    /** Schedule a callback. */
-    setTimeout(cb: () => void, ms: number): TimerHandle;
-    /** Cancel a timer. */
-    clearTimeout(handle: TimerHandle): void;
-    /**
-     * Probe whether the `grist` global is present in this realm.
-     * Returns `{ embedded }` when the global exists; `null` otherwise.
-     */
-    probeGrist(): {
-        embedded: boolean;
-    } | null;
-    /**
-     * Snapshot of the `grist` global. Effects use this once detection has
-     * succeeded; callers must NOT cache the result across `restart()`.
-     */
-    getGrist(): GristLike | null;
-    /** Adaptive detection budget hint (ms). `null` if unknown. */
-    effectiveTypeHint(): EffectiveTypeHint | null;
-    /** Add a listener for `visibilitychange` / `online` / `focus`. Returns cleanup. */
-    onVisibilityChange?(listener: (visible: boolean) => void): () => void;
-    onOnline?(listener: () => void): () => void;
-};
-type TimerHandle = ReturnType<typeof setTimeout> | number | {
-    __opaque: true;
-};
-type EffectiveTypeHint = "slow-2g" | "2g" | "3g" | "4g" | "5g";
-/**
- * Subset of `window.grist` actually used by handshake effects. Mirrors the
- * declared shape in `grist-global.d.ts` but only the pieces we need.
- */
-type GristLike = {
-    ready: (options?: GristReadyOptions) => Promise<void> | void;
-    docApi: GristDocApi | null | undefined;
-    onRecord?: (cb: (record: Record<string, unknown> | null, mappings?: GristWidgetColumnMap | null) => void, options?: {
-        keepEncoded?: boolean;
-    }) => void;
-    onRecords?: (cb: (records: Record<string, unknown>[], mappings?: GristWidgetColumnMap | null) => void, options?: {
-        keepEncoded?: boolean;
-        format?: string;
-    }) => void;
-    onOptions?: (cb: (options: Record<string, unknown> | null, interaction: unknown) => void) => void;
-    onNewRecord?: (cb: (mappings: GristWidgetColumnMap | null) => void) => void;
-    sectionApi?: {
-        mappings: () => Promise<GristWidgetColumnMap | null>;
-    };
-};
-
-/**
- * Detect effect — poll for `window.grist` with exponential backoff inside a
- * finite, optionally adaptive budget.
- *
- * Outputs (dispatched to the manager):
- *   - DETECT_START      (once, at start)
- *   - DETECT_TICK       (each unsuccessful poll, with attempts count)
- *   - DETECT_AVAILABLE  (grist global present AND embedded)
- *   - NOT_EMBEDDED      (grist global present but `self === top`)
- *   - DETECT_TIMEOUT    (budget consumed without detection)
- *
- * The effect aborts on `signal.aborted` and clears its pending timer.
- *
- * Pure of `window`: relies on the {@link GristEnvironment} adapter so the
- * effect is fully unit-testable with a virtual clock.
- */
-
-type DetectOptions = {
-    /** Custom poll sequence in ms. Index past end uses last value. */
-    pollSequenceMs?: readonly number[];
-    /** Total wall-clock budget across all polls. */
-    budgetMs?: number;
-};
-
-/**
- * Negotiate effect — issue `grist.ready(payload)` race-d against a timeout
- * and an external `AbortSignal`.
- *
- * Dispatches:
- *   - NEGOTIATE_START
- *   - NEGOTIATE_SUCCESS   (grist.ready resolved AND `docApi` is present)
- *   - NEGOTIATE_FAIL      (reason: ready_failed | ready_timeout | manual_terminate)
- *
- * The effect never throws to the caller. Aborts before resolution silently
- * stop dispatching.
- */
-
-type NegotiateOptions = {
-    /** Max ms to wait for `grist.ready` to resolve. */
-    timeoutMs?: number;
-    /**
-     * Custom implementation of `grist.ready(payload)`. Defaults to calling
-     * `grist.ready` directly via the env. Production callers (the provider)
-     * inject a wrapper that routes through `ensureGristReady()` so the
-     * page-level singleton dedupes concurrent ready calls.
-     */
-    readyImpl?: (payload: GristReadyOptions) => Promise<void> | void;
-};
-
-/**
- * Subscriptions effect — bind Grist event streams once and feed the handshake
- * machine with generation-stamped, hash-deduplicated dispatches.
- *
- * Why a dedicated effect
- * ----------------------
- * The SDK already has a {@link "../../subscriptions"} module that owns the
- * one-time binding to `grist.on*` and the BehaviorSubject-style cache. We do
- * NOT re-bind here — instead, we install a single listener per stream that
- * forwards into the handshake reducer.
- *
- * Generation discipline: every dispatched action carries the CURRENT manager
- * generation read at the moment the event arrives. The reducer enforces
- * `action.generation >= snapshot.generation`, so events arriving after a
- * `reload()` / `restart()` that bumped generation are dropped automatically.
- *
- * Hash: payloads are reduced to a compact, deterministic string so duplicates
- * (e.g. emulator triple-replay of initial state) become no-ops at the reducer.
- */
-
-type SubscriptionsHandle = {
-    cancel(): void;
-};
-/**
- * Pluggable binder type. The default {@link defaultSubscriptionsBinder}
- * subscribes to the SDK's singleton {@link GristEvent} instances. Tests can
- * supply a stub that never touches the real `grist` global.
- */
-type SubscriptionsBinder = (ctx: SubscriptionsContext) => SubscriptionsHandle;
-type SubscriptionsContext = {
-    dispatch: (action: GristAction) => void;
-    /**
-     * Snapshot generation provider. Must be read lazily (inside the callback)
-     * because `generation` is monotone but mutates over the lifetime of the
-     * subscription.
-     */
-    getGeneration: () => GristGeneration;
-    /** Hook for the mapping effect: receive payloads in arrival order. */
-    onRecordPayload?: (mappings: Record<string, unknown> | null | undefined) => void;
-    onRecordsPayload?: (mappings: Record<string, unknown> | null | undefined) => void;
-    onOptionsPayload?: (options: Record<string, unknown> | null) => void;
-    onNewRecordPayload?: (mappings: Record<string, unknown> | null | undefined) => void;
-};
-
-/**
- * Mappings effect — feed column-mapping payloads into the reducer from the
- * three Grist sources (`sectionApi.mappings()`, `onRecord`, `onRecords`,
- * `onNewRecord`) and trigger the mapping timeout if nothing arrives in time.
- *
- * Inputs:
- *   - `declared`  — `columns` from the provider options.
- *   - `getGeneration()` — current snapshot generation (for stale-drop).
- *   - `getGrist()` — environment accessor to `grist.sectionApi.mappings()`.
- *
- * Outputs:
- *   - `MAPPING_DECLARE` (once at start when `declared.length > 0`)
- *   - `MAPPING_REPORT`  (one per source payload received)
- *   - `MAPPING_TIMEOUT` (if no payload after `timeoutMs`)
- *
- * The effect does NOT subscribe to grist events directly — it consumes them
- * via the {@link SubscriptionsContext} payload callbacks. This keeps the
- * single-binding contract of `subscriptions.ts` intact (one `grist.onRecord`
- * binding per page).
- */
-
-type MappingsOptions = {
-    /**
-     * Time after `MAPPING_DECLARE` before falling back to `unreported` state.
-     * Default 5 000 ms.
-     */
-    timeoutMs?: number;
-    /**
-     * If true, dispatch `MAPPING_INVALIDATE` whenever a payload differs from
-     * the last applied mappings. Default false — graceful invalidation requires
-     * a `mappingsChange: true` envelope flag the SDK doesn't currently surface,
-     * so we leave it opt-in for tests.
-     */
-    invalidateOnDiff?: boolean;
-};
-
-/**
- * Heartbeat effect — periodically verify the RPC channel is alive.
- *
- * Strategy
- * --------
- *   1. Schedule a ping every `intervalMs` (default 30 s).
- *   2. The ping calls a cheap RPC (default `grist.docApi.getDocName()`).
- *   3. Success → `HEARTBEAT_OK`. Failure / timeout → `HEARTBEAT_FAIL`.
- *   4. Any externally-observed RPC success (the caller invokes
- *      {@link HeartbeatHandle.recordRpcSuccess}) coalesces with the heartbeat
- *      and reschedules the next ping — we don't burn a request when natural
- *      traffic already proves the link.
- *   5. Tab hidden? Pause via `env.onVisibilityChange`. Resume on `visible`.
- *
- * The effect is **purely an observer**: it never mutates application state
- * directly — it only dispatches actions the reducer consumes.
- */
-
-type HeartbeatOptions = {
-    /** How often to issue a probe when no natural RPC traffic occurred. */
-    intervalMs?: number;
-    /** Max time to wait for the probe before counting it as a failure. */
-    pingTimeoutMs?: number;
-    /** If true, pause the heartbeat when the document becomes hidden. */
-    pauseWhenHidden?: boolean;
-    /**
-     * Probe used when the interval elapses. Defaults to
-     * `() => env.getGrist().docApi.getDocName()`. Tests pass a controlled stub.
-     */
-    probe?: () => Promise<unknown>;
-};
-
-/**
- * GristHandshakeManager — single owner of the handshake snapshot.
- *
- * Responsibilities
- * ----------------
- * 1. Hold the snapshot and the {@link GristReducerContext}.
- * 2. Run effects (detect → negotiate → subscriptions + mappings) in order.
- * 3. Bump generation on `reload()` / `restart()` and propagate cancellation
- *    through a per-generation {@link AbortController}.
- * 4. Notify subscribers on each snapshot change (interface compatible with
- *    React's `useSyncExternalStore`).
- *
- * The manager is a **class**, not a hook. React hooks subscribe to it via the
- * standard `subscribe` / `getSnapshot` pair so unit tests can drive the
- * manager directly with a virtual clock — no React needed.
- */
-
-type ManagerOptions = GristReadyOptions & {
-    detect?: DetectOptions;
-    negotiate?: NegotiateOptions;
-    mappings?: MappingsOptions;
-    heartbeat?: HeartbeatOptions | false;
-    reducerConfig?: Partial<ReducerConfig>;
-    /**
-     * Where to read `grist`, timers, and platform hints from. Defaults to a
-     * browser adapter. Tests pass {@link createTestEnvironment}.
-     */
-    env?: GristEnvironment;
-    /**
-     * Binder for grist event streams. Defaults to
-     * {@link defaultSubscriptionsBinder} which wires the SDK's singleton
-     * {@link "../../subscriptions"} module. Tests can pass `noopSubscriptionsBinder`
-     * to avoid touching the real `grist` global.
-     */
-    subscriptionsBinder?: SubscriptionsBinder;
-    /**
-     * Called when the manager catches an unexpected internal error.
-     * Telemetry hook — does not affect reducer state.
-     */
-    onError?: (err: unknown, where: string) => void;
-    /**
-     * Called from inside {@link ManagerControls.reload} BEFORE generation bump.
-     * Production callers route `resetGristReadySingleton()` through here so
-     * the page-level ready singleton is cleared and the next negotiate effect
-     * issues a fresh `grist.ready` instead of re-using the cached promise.
-     */
-    onBeforeReload?: () => void;
-};
-
-type UseGristAvailabilityOptions = Pick<UseGristCoreOptions, "availabilityMaxAttempts" | "availabilityIntervalMs" | "logWhenNotEmbedded">;
-/**
- * Handshake-backed availability — projects `isAvailable` from the FSM.
- */
-declare function useGristAvailability(options?: UseGristAvailabilityOptions): boolean | null;
-
-type UseGristReadyOptions = GristReadyOptions & {
-    availabilityMaxAttempts?: number;
-    availabilityIntervalMs?: number;
-    logWhenNotEmbedded?: boolean;
-};
-type UseGristReadyResult = {
-    isAvailable: boolean | null;
-    docApi: GristDocApi | null;
-    error: string | null;
-    reload: () => Promise<void>;
-};
-/**
- * Handshake-backed `grist.ready` — delegates to {@link useGristCore} (FSM).
- *
- * Prefer `<GristWidgetProvider>` + `useGrist()` for full widget state; use this
- * hook when you only need `docApi` and connection status.
- */
-declare function useGristReady(options?: UseGristReadyOptions): UseGristReadyResult;
-
-/**
- * `useGristHandshake()` — React adapter over {@link GristHandshakeManager}.
- *
- * Exposes the full {@link GristWidgetSnapshot} plus derived
- * {@link GristCapabilities}, plus `reload()` / `restart()` controls.
- *
- * Identity stability
- * ------------------
- * The snapshot reference changes whenever the reducer produces a new
- * snapshot. Capabilities are memoized by snapshot identity, so consumers
- * branching on a single capability (e.g. `canWriteRecords`) avoid extra
- * re-renders unless that boolean actually flips.
- *
- * SSR-safe: `getServerSnapshot` returns the initial snapshot deterministically.
- */
-
-type UseGristHandshakeOptions = ManagerOptions;
-type UseGristHandshakeResult = {
-    snapshot: GristWidgetSnapshot;
-    status: GristWidgetStatus;
-    error: string | null;
-    capabilities: GristCapabilities;
-    reload: () => void;
-    restart: () => void;
-};
-/**
- * Mount a handshake manager local to the component subtree. Multiple
- * widgets in the same page should NOT call this in parallel — instead,
- * mount a single `<GristWidgetProvider>` at the app root.
- *
- * In tests, pass `options.env` (see `createTestEnvironment`) to drive the
- * machine with a virtual clock.
- */
-declare function useGristHandshake(options?: UseGristHandshakeOptions): UseGristHandshakeResult;
-/**
- * Convenience hook — equivalent to `useGristHandshake().capabilities` but
- * skips returning the full snapshot. Intended for leaf components that only
- * need to gate UI on `canRender` / `canWriteRecords` / etc.
- */
-declare function useGristCapabilities(options?: UseGristHandshakeOptions): GristCapabilities;
-
-/**
- * `useAmbientGristHandshake()` — observe an already-mounted handshake
- * manager without ever creating one.
- *
- * `useGristHandshake()` / `<GristHandshakeProvider>` both mount their OWN
- * manager, which calls the real `grist.ready()` independently of any
- * `<GristWidgetProvider>` elsewhere on the page. That's fine for a widget's
- * single app-root provider, but wrong for read-only UI (a connection-status
- * chip, a debug overlay) that must share the *same* handshake as the real
- * widget rather than run a second, competing one. This hook only reads
- * whatever manager a `<GristWidgetProvider>` ancestor already published;
- * it returns `null` outside one instead of falling back to creating its own.
- */
-
-type UseAmbientGristHandshakeResult = {
-    snapshot: GristWidgetSnapshot;
-    status: GristWidgetStatus;
-    error: string | null;
-    capabilities: GristCapabilities;
-    reload: () => void;
-    restart: () => void;
-};
-/**
- * Returns `null` when mounted outside a `<GristWidgetProvider>` — there is
- * no ambient manager to observe, and this hook intentionally never creates
- * one. Mount inside `<GristWidgetProvider>` to get a live value.
- */
-declare function useAmbientGristHandshake(): UseAmbientGristHandshakeResult | null;
-
-type GristHandshakeContextValue = {
-    snapshot: GristWidgetSnapshot;
-    status: GristWidgetStatus;
-    error: string | null;
-    capabilities: GristCapabilities;
-    reload: () => void;
-    restart: () => void;
-    recordRpcSuccess: () => void;
-    recordRpcFailure: () => void;
-};
-type GristHandshakeProviderProps = {
-    options?: ManagerOptions;
-    children: ReactNode;
-};
-/**
- * Mount a single {@link GristHandshakeManager} for the React subtree and
- * expose its snapshot via context.
- *
- * The manager is created **once** on first mount; the `options` prop is
- * captured at that time. To re-create the manager with new options, unmount
- * and re-mount the provider (e.g. via a `key`).
- */
-declare function GristHandshakeProvider({ options, children }: GristHandshakeProviderProps): react.JSX.Element;
-/**
- * Read the handshake context. Throws if no `<GristHandshakeProvider>` is
- * mounted in the tree.
- *
- * Use {@link useGristHandshakeContextOptional} when the provider is optional
- * (e.g. when the same component is sometimes used standalone).
- */
-declare function useGristHandshakeContext(): GristHandshakeContextValue;
-/** Non-throwing variant. */
-declare function useGristHandshakeContextOptional(): GristHandshakeContextValue | null;
-
-type UseGristRecordSubscriptionResult = {
-    loading: boolean;
-    error: string | null;
-    /** Latest mappings from `grist.onRecord` (logical name → real column id, or `string[]` for `allowMultiple`). */
-    mappings: GristWidgetColumnMap | null;
-};
-/**
- * Subscribes to the currently-selected row in the widget's section.
- *
- * The Grist event is shared across all hook instances (no leak).
- */
-declare function useGristRecord(cb: (record: Record<string, unknown> | null, mappings: GristWidgetColumnMap | null) => void, options?: GristReadyOptions): UseGristRecordSubscriptionResult;
-
-/**
- * Subscribes to the full row set visible in the widget's section
- * (filters, sorts, and linked rows applied).
- */
-declare function useGristRecords(cb: (records: Record<string, unknown>[], mappings: GristWidgetColumnMap | null) => void, options?: GristReadyOptions): UseGristRecordSubscriptionResult;
-
-type UseGristNewRecordResult = {
-    /** True when the user has selected the blank "new row" placeholder. */
-    isNewRecord: boolean;
-    /** Mappings reported by Grist alongside the new-record event. */
-    mappings: GristWidgetColumnMap | null;
-    loading: boolean;
-    error: string | null;
-};
-/**
- * Subscribes to `grist.onNewRecord` — fires when the user selects the blank
- * row in the linked section. Useful for form-style widgets that need to
- * switch into "create" mode.
- *
- * `isNewRecord` is reset to `false` whenever a real `onRecord` payload arrives,
- * so callers don't need to manage that themselves.
- */
-declare function useGristNewRecord(options?: GristReadyOptions): UseGristNewRecordResult;
-
-type GristActionsStatus = "idle" | "running" | "error";
-type UseGristActionsOptions = Pick<GristReadyOptions, "requiredAccess" | "columns" | "allowSelectBy" | "hasCustomOptions" | "onEditOptions">;
-type UseGristActionsResult = {
-    status: GristActionsStatus;
-    error: string | null;
-    /** Apply raw user actions. `applyOptions.desc` is shown in the document undo stack. */
-    apply: (actions: GristUserActionTuple[], applyOptions?: GristApplyUserActionsOptions) => Promise<unknown>;
-    updateRecord: (tableId: string, recordId: number, patch: Record<string, unknown>, applyOptions?: GristApplyUserActionsOptions) => Promise<unknown>;
-    addRecord: (tableId: string, values: Record<string, unknown>, applyOptions?: GristApplyUserActionsOptions) => Promise<unknown>;
-    removeRecord: (tableId: string, recordId: number, applyOptions?: GristApplyUserActionsOptions) => Promise<unknown>;
-    bulkAddRecord: (tableId: string, values: Record<string, unknown[]>, applyOptions?: GristApplyUserActionsOptions) => Promise<unknown>;
-    bulkUpdateRecord: (tableId: string, rowIds: number[], columnarPatch: Record<string, unknown[]>, applyOptions?: GristApplyUserActionsOptions) => Promise<unknown>;
-    bulkRemoveRecord: (tableId: string, rowIds: number[], applyOptions?: GristApplyUserActionsOptions) => Promise<unknown>;
-};
-declare function useGristActions(options?: UseGristActionsOptions): UseGristActionsResult;
-
-type UseGristMappedRecordResult<T> = {
-    rawRecord: Record<string, unknown> | null;
-    mappedRecord: T | null;
-    /** Current column mappings reported by Grist. */
-    mappings: GristWidgetColumnMap | null;
-    loading: boolean;
-    error: string | null;
-    /**
-     * Reverse-map a logical patch (`{ logicalName: value }`) into a real-column
-     * patch (`{ realColId: value }`) ready for `applyUserActions` /
-     * `useGristTableOps.update`.
-     * Falls back to `grist.mapColumnNamesBack` when present, otherwise resolves
-     * names manually from `mappings` (single-mapped columns only).
-     */
-    mapBack: (patch: Partial<T>) => Record<string, unknown>;
-    /** Resolve a single logical name to its current real column id. */
-    resolveColumnId: (logicalName: keyof T & string) => string | undefined;
-};
-/**
- * Subscribes to the selected row, applies `grist.mapColumnNames` so widget code
- * sees logical column names, and exposes `mapBack` for safe writes.
- */
-declare function useGristMappedRecord<T = Record<string, unknown>>(options?: GristReadyOptions): UseGristMappedRecordResult<T>;
-
-type GristTableOpsStatus = "idle" | "running" | "error";
-type UseGristTableOpsOptions = {
-    /**
-     * Table to operate on:
-     * - `"selected"` (default): use `grist.selectedTable` (the widget's current table).
-     * - any other string: use `grist.getTable(tableId)`.
-     */
-    tableId?: "selected" | string;
-    /** Defaults to `"full"` since these operations write to the document. */
-    requiredAccess?: GristReadyOptions["requiredAccess"];
-} & Pick<GristReadyOptions, "columns" | "allowSelectBy" | "hasCustomOptions" | "onEditOptions">;
-type UseGristTableOpsResult = {
-    status: GristTableOpsStatus;
-    error: string | null;
-    /** Resolves the runtime tableId (only meaningful when `tableId` is `"selected"`). */
-    getTableId: () => Promise<string>;
-    create: (records: GristTableNewRecord | GristTableNewRecord[], opOptions?: GristTableOpOptions) => Promise<GristMinimalRecord | GristMinimalRecord[]>;
-    update: (records: GristTableUpdateRecord | GristTableUpdateRecord[], opOptions?: GristTableOpOptions) => Promise<void>;
-    upsert: (records: GristTableUpsertRecord | GristTableUpsertRecord[], opOptions?: GristTableUpsertOptions) => Promise<void>;
-    destroy: (recordIds: number | number[]) => Promise<void>;
-};
-/**
- * Strongly-typed CRUD wrapper around Grist's `TableOperations` (`grist.selectedTable`
- * or `grist.getTable(tableId)`). Prefer this over hand-rolled `applyUserActions`.
- *
- * @see https://support.getgrist.com/code/interfaces/TableOperations.TableOperations/
- */
-declare function useGristTableOps(options?: UseGristTableOpsOptions): UseGristTableOpsResult;
-
-type UseGristRowsFromTableOptions<T> = {
-    tableId: string;
-    /** Re-fetch on a fixed cadence (ms). Default: disabled. */
-    pollIntervalMs?: number;
-    /** Map raw rows to a domain shape (e.g. `decodeGristValue` your columns). */
-    transform?: (row: GristRowRecord) => GristRowRecord<T>;
-    requiredAccess?: GristReadyOptions["requiredAccess"];
-} & Pick<GristReadyOptions, "columns" | "allowSelectBy" | "hasCustomOptions" | "onEditOptions">;
-type UseGristRowsFromTableResult<T> = {
-    rows: GristRowRecord<T>[] | null;
-    loading: boolean;
-    error: string | null;
-    /** Force a re-fetch (call after writes that should be reflected immediately). */
-    refresh: () => Promise<void>;
-};
-/**
- * Subscribes to a full table's rows via `docApi.fetchTable`.
- *
- * Unlike `useGristRecords` (which is bound to the widget's selected section),
- * this hook works against any table id and **doesn't auto-update on Grist
- * writes from elsewhere** — call `refresh()` after your own writes, or set
- * `pollIntervalMs` for polling.
- */
-declare function useGristRowsFromTable<T = Record<string, unknown>>(options: UseGristRowsFromTableOptions<T>): UseGristRowsFromTableResult<T>;
-
-type UseGristAccessTokenOptions = {
-    /** Default for all token requests issued by this hook. */
-    readOnly?: boolean;
-    /** Pre-fetch a token on mount so `token` is non-null when widgets render. */
-    prefetch?: boolean;
-    /** Defaults to `"full"` since tokens are used for REST calls. */
-    requiredAccess?: GristReadyOptions["requiredAccess"];
-} & Pick<GristReadyOptions, "columns" | "allowSelectBy" | "hasCustomOptions" | "onEditOptions">;
-type UseGristAccessTokenResult = {
-    token: GristAccessToken | null;
-    loading: boolean;
-    error: string | null;
-    /** Request a fresh token (Grist tokens are short-lived; do not cache aggressively). */
-    refresh: (overrides?: {
-        readOnly?: boolean;
-    }) => Promise<GristAccessToken>;
-    /** `fetch()` against Grist's REST API with auth attached. */
-    fetch: (path: string, init?: RequestInit & {
-        readOnly?: boolean;
-    }) => Promise<Response>;
-};
-/**
- * Exposes `docApi.getAccessToken` plus a ready-to-use `fetch` for calling
- * Grist's REST API (e.g. attachments, records, sql) from a widget.
- */
-declare function useGristAccessToken(options?: UseGristAccessTokenOptions): UseGristAccessTokenResult;
-
-type UseGristSectionResult = {
-    /** Current widget ↔ section column mappings, refreshed on demand. */
-    mappings: GristWidgetColumnMap | null;
-    loading: boolean;
-    error: string | null;
-    /** Re-read mappings from `sectionApi`. */
-    refresh: () => Promise<void>;
-    /**
-     * Update the widget's declared `ColumnsToMap` (and other ready options) after
-     * mount. Use this to dynamically request more columns once the user has
-     * configured the widget.
-     */
-    configure: (options: GristReadyOptions) => Promise<void>;
-};
-/**
- * Wraps Grist's `sectionApi` (`mappings()` + `configure()`) so widgets can
- * inspect/refresh the column mapping and re-declare requirements without
- * touching `grist` directly.
- */
-declare function useGristSection(options?: GristReadyOptions): UseGristSectionResult;
-
-type UseGristWidgetOptionsConfig<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 inside `grist.setOptions`. When set, this hook reads/writes
-     * `grist.setOption(namespace, value)` instead of the whole options blob — useful
-     * to share the options bag with `hasCustomOptions` / unrelated widget state.
-     */
-    namespace?: string;
-    requiredAccess?: GristReadyOptions["requiredAccess"];
-} & Pick<GristReadyOptions, "columns" | "allowSelectBy" | "hasCustomOptions" | "onEditOptions">;
-type UseGristWidgetOptionsResult<T> = {
-    options: T;
-    /** True until Grist has responded with the initial `onOptions` payload. */
-    loading: boolean;
-    error: string | null;
-    /** 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>;
-};
-/**
- * Persist a typed object of widget settings via `grist.onOptions` / `setOptions`.
- *
- * - Defaults are returned immediately (no flicker before Grist responds).
- * - Writes are debounced and batched.
- * - `hasCustomOptions` defaults to `true` so Grist exposes the gear icon — pass
- *   `hasCustomOptions: false` to opt out.
- */
-declare function useGristWidgetOptions<T extends Record<string, unknown>>(config: UseGristWidgetOptionsConfig<T>): UseGristWidgetOptionsResult<T>;
-
-type UseGristTableOptions = {
-    requiredAccess?: GristRequiredAccess;
-    /**
-     * `'current'` (default): follow the widget’s selected table.
-     * Any other string: fixed table id (no `grist.selectedTable` polling).
-     */
-    tableId?: "current" | string;
-} & Pick<GristReadyOptions, "columns" | "allowSelectBy" | "hasCustomOptions" | "onEditOptions">;
-type UseGristTableResult = {
-    tableId: string | null;
-    loading: boolean;
-    error: string | null;
-    refresh: () => Promise<void>;
-    fetchTable: (targetTableId: string) => Promise<GristColumnarTable>;
-    listTables: () => Promise<string[]>;
-    getDocName: () => Promise<string>;
-    fetchSelectedTable: (fetchOptions?: GristFetchSelectedOptions) => Promise<GristColumnarTable>;
-    fetchSelectedRecord: (rowId: number, fetchOptions?: GristFetchSelectedOptions) => Promise<Record<string, unknown>>;
-};
-/**
- * Selected or fixed table id plus document reads — no raw `docApi` on the result.
- */
-declare function useGristTable(options?: UseGristTableOptions): UseGristTableResult;
-
-export { GristCapabilities, GristGeneration, GristHandshakeProvider, GristMappingSource, GristTerminationReason, GristWidgetSnapshot, useAmbientGristHandshake, useGristAccessToken, useGristActions, useGristAvailability, useGristCapabilities, useGristHandshake, useGristHandshakeContext, useGristHandshakeContextOptional, useGristMappedRecord, useGristNewRecord, useGristReady, useGristRecord, useGristRecords, useGristRowsFromTable, useGristSection, useGristTable, useGristTableOps, useGristWidgetOptions };
-export type { GristActionsStatus, GristHandshakeContextValue, GristHandshakeProviderProps, GristTableOpsStatus, UseAmbientGristHandshakeResult, UseGristAccessTokenOptions, UseGristAccessTokenResult, UseGristActionsOptions, UseGristActionsResult, UseGristHandshakeOptions, UseGristHandshakeResult, UseGristMappedRecordResult, UseGristNewRecordResult, UseGristReadyOptions, UseGristReadyResult, UseGristRecordSubscriptionResult, UseGristRowsFromTableOptions, UseGristRowsFromTableResult, UseGristSectionResult, UseGristTableOpsOptions, UseGristTableOpsResult, UseGristTableOptions, UseGristTableResult, UseGristWidgetOptionsConfig, UseGristWidgetOptionsResult };