grist-widget-sdk 0.2.0

package/dist/advanced.js

@@ -0,0 +1,825 @@
+import {
+  GristReadsContext,
+  fetchWithGristAuth,
+  getGristAccessToken,
+  useGristCore,
+  useGristReady,
+  useGristWidgetOptionsFromContext,
+  useRpcHeartbeatCoalesce
+} from "./chunk-BNBV24WM.js";
+import {
+  createGristHandshakeManager,
+  deriveCapabilities,
+  deriveErrorMessage,
+  deriveStatus,
+  initialGristSnapshot,
+  newRecordEvent,
+  optionsEvent,
+  recordEvent,
+  recordsEvent
+} from "./chunk-XE2SKNLH.js";
+import {
+  tableDataToRows
+} from "./chunk-JASMM2YC.js";
+import {
+  gristAddRecordAction,
+  gristBulkAddRecordAction,
+  gristBulkRemoveRecordAction,
+  gristBulkUpdateRecordAction,
+  gristRemoveRecordAction,
+  gristUpdateRecordAction
+} from "./chunk-64SVRWW7.js";
+
+// src/sdk/low-level-hooks/use-grist-availability.ts
+function useGristAvailability(options) {
+  const { isAvailable } = useGristCore(options);
+  return isAvailable;
+}
+
+// src/sdk/low-level-hooks/use-grist-handshake.ts
+import { useEffect, useMemo, useRef, useSyncExternalStore } from "react";
+function useGristHandshake(options = {}) {
+  const optionsRef = useRef(options);
+  optionsRef.current = options;
+  const managerRef = useRef(null);
+  if (managerRef.current === null) {
+    managerRef.current = createGristHandshakeManager(options);
+  }
+  const manager = managerRef.current;
+  useEffect(() => {
+    manager.start();
+    return () => {
+      manager.stop();
+    };
+  }, [manager]);
+  const snapshot = useSyncExternalStore(
+    manager.subscribe,
+    manager.getSnapshot,
+    initialGristSnapshot
+  );
+  const projected = useMemo(
+    () => ({
+      status: deriveStatus(snapshot),
+      error: deriveErrorMessage(snapshot),
+      capabilities: deriveCapabilities(snapshot)
+    }),
+    [snapshot]
+  );
+  return useMemo(
+    () => ({
+      snapshot,
+      status: projected.status,
+      error: projected.error,
+      capabilities: projected.capabilities,
+      reload: manager.reload,
+      restart: manager.restart
+    }),
+    [snapshot, projected, manager]
+  );
+}
+function useGristCapabilities(options = {}) {
+  return useGristHandshake(options).capabilities;
+}
+
+// src/sdk/components/grist-handshake-provider.tsx
+import {
+  createContext,
+  useContext,
+  useEffect as useEffect2,
+  useMemo as useMemo2,
+  useRef as useRef2,
+  useSyncExternalStore as useSyncExternalStore2
+} from "react";
+import { jsx } from "react/jsx-runtime";
+var GristHandshakeReactContext = createContext(null);
+function GristHandshakeProvider({ options, children }) {
+  const managerRef = useRef2(null);
+  if (managerRef.current === null) {
+    managerRef.current = createGristHandshakeManager(options ?? {});
+  }
+  const manager = managerRef.current;
+  useEffect2(() => {
+    manager.start();
+    return () => {
+      manager.stop();
+    };
+  }, [manager]);
+  const snapshot = useSyncExternalStore2(
+    manager.subscribe,
+    manager.getSnapshot,
+    initialGristSnapshot
+  );
+  const value = useMemo2(
+    () => ({
+      snapshot,
+      status: deriveStatus(snapshot),
+      error: deriveErrorMessage(snapshot),
+      capabilities: deriveCapabilities(snapshot),
+      reload: manager.reload,
+      restart: manager.restart,
+      recordRpcSuccess: manager.recordRpcSuccess,
+      recordRpcFailure: manager.recordRpcFailure
+    }),
+    [snapshot, manager]
+  );
+  return /* @__PURE__ */ jsx(GristHandshakeReactContext.Provider, { value, children });
+}
+function useGristHandshakeContext() {
+  const ctx = useContext(GristHandshakeReactContext);
+  if (!ctx) {
+    throw new Error(
+      "useGristHandshakeContext() must be used inside <GristHandshakeProvider>"
+    );
+  }
+  return ctx;
+}
+function useGristHandshakeContextOptional() {
+  return useContext(GristHandshakeReactContext);
+}
+
+// src/sdk/low-level-hooks/use-grist-record.ts
+import { useEffect as useEffect3, useRef as useRef3, useState } from "react";
+function useGristRecord(cb, options) {
+  const cbRef = useRef3(cb);
+  useEffect3(() => {
+    cbRef.current = cb;
+  }, [cb]);
+  const [mappings, setMappings] = useState(null);
+  const { docApi, error: readyError } = useGristReady({
+    requiredAccess: options?.requiredAccess ?? "read table",
+    columns: options?.columns,
+    allowSelectBy: options?.allowSelectBy,
+    hasCustomOptions: options?.hasCustomOptions,
+    onEditOptions: options?.onEditOptions
+  });
+  useEffect3(() => {
+    if (!docApi) return;
+    return recordEvent.subscribe(({ record, mappings: nextMappings }) => {
+      setMappings(nextMappings);
+      cbRef.current(record, nextMappings);
+    });
+  }, [docApi]);
+  return {
+    loading: docApi === null && !readyError,
+    error: readyError,
+    mappings
+  };
+}
+
+// src/sdk/low-level-hooks/use-grist-records.ts
+import { useEffect as useEffect4, useRef as useRef4, useState as useState2 } from "react";
+function useGristRecords(cb, options) {
+  const cbRef = useRef4(cb);
+  useEffect4(() => {
+    cbRef.current = cb;
+  }, [cb]);
+  const [mappings, setMappings] = useState2(null);
+  const { docApi, error: readyError } = useGristReady({
+    requiredAccess: options?.requiredAccess ?? "read table",
+    columns: options?.columns,
+    allowSelectBy: options?.allowSelectBy,
+    hasCustomOptions: options?.hasCustomOptions,
+    onEditOptions: options?.onEditOptions
+  });
+  useEffect4(() => {
+    if (!docApi) return;
+    return recordsEvent.subscribe(({ records, mappings: nextMappings }) => {
+      setMappings(nextMappings);
+      cbRef.current(records, nextMappings);
+    });
+  }, [docApi]);
+  return {
+    loading: docApi === null && !readyError,
+    error: readyError,
+    mappings
+  };
+}
+
+// src/sdk/low-level-hooks/use-grist-new-record.ts
+import { useEffect as useEffect5, useRef as useRef5, useState as useState3 } from "react";
+function useGristNewRecord(options) {
+  const { docApi, error: readyError } = useGristReady({
+    requiredAccess: options?.requiredAccess ?? "read table",
+    columns: options?.columns,
+    allowSelectBy: options?.allowSelectBy,
+    hasCustomOptions: options?.hasCustomOptions,
+    onEditOptions: options?.onEditOptions
+  });
+  const [isNewRecord, setIsNewRecord] = useState3(false);
+  const [mappings, setMappings] = useState3(null);
+  const subscribedRef = useRef5(false);
+  useEffect5(() => {
+    if (!docApi || subscribedRef.current) return;
+    if (typeof grist.onNewRecord !== "function") return;
+    subscribedRef.current = true;
+    return newRecordEvent.subscribe(({ mappings: nextMappings }) => {
+      setIsNewRecord(true);
+      setMappings(nextMappings);
+    });
+  }, [docApi]);
+  return {
+    isNewRecord,
+    mappings,
+    loading: docApi === null && !readyError,
+    error: readyError
+  };
+}
+
+// src/sdk/mid-level-hooks/use-grist-actions.ts
+import { useCallback, useState as useState4 } from "react";
+function useGristActions(options) {
+  const requiredAccess = options?.requiredAccess ?? "full";
+  const { docApi, error: readyError } = useGristReady({
+    requiredAccess,
+    columns: options?.columns,
+    allowSelectBy: options?.allowSelectBy,
+    hasCustomOptions: options?.hasCustomOptions,
+    onEditOptions: options?.onEditOptions
+  });
+  const [status, setStatus] = useState4("idle");
+  const [actionError, setActionError] = useState4(null);
+  const coalesceRpc = useRpcHeartbeatCoalesce();
+  const apply = useCallback(
+    async (actions, applyOptions) => {
+      if (!docApi) throw new Error("Grist docApi is not ready");
+      setStatus("running");
+      setActionError(null);
+      try {
+        const out = await coalesceRpc(() => docApi.applyUserActions(actions, applyOptions));
+        setStatus("idle");
+        return out;
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        setActionError(message);
+        setStatus("error");
+        throw err;
+      }
+    },
+    [docApi, coalesceRpc]
+  );
+  const updateRecord = useCallback(
+    (tableId, recordId, patch, applyOptions) => apply([gristUpdateRecordAction(tableId, recordId, patch)], applyOptions),
+    [apply]
+  );
+  const addRecord = useCallback(
+    (tableId, values, applyOptions) => apply([gristAddRecordAction(tableId, values)], applyOptions),
+    [apply]
+  );
+  const removeRecord = useCallback(
+    (tableId, recordId, applyOptions) => apply([gristRemoveRecordAction(tableId, recordId)], applyOptions),
+    [apply]
+  );
+  const bulkAddRecord = useCallback(
+    (tableId, values, applyOptions) => apply([gristBulkAddRecordAction(tableId, values)], applyOptions),
+    [apply]
+  );
+  const bulkUpdateRecord = useCallback(
+    (tableId, rowIds, columnarPatch, applyOptions) => apply([gristBulkUpdateRecordAction(tableId, rowIds, columnarPatch)], applyOptions),
+    [apply]
+  );
+  const bulkRemoveRecord = useCallback(
+    (tableId, rowIds, applyOptions) => apply([gristBulkRemoveRecordAction(tableId, rowIds)], applyOptions),
+    [apply]
+  );
+  return {
+    status: readyError ? "error" : status,
+    error: readyError ?? actionError,
+    apply,
+    updateRecord,
+    addRecord,
+    removeRecord,
+    bulkAddRecord,
+    bulkUpdateRecord,
+    bulkRemoveRecord
+  };
+}
+
+// src/sdk/mid-level-hooks/use-grist-mapped-record.ts
+import { useCallback as useCallback2, useEffect as useEffect6, useState as useState5 } from "react";
+function manualMapBack(patch, mappings) {
+  if (!mappings) return { ...patch };
+  const out = {};
+  for (const [name, value] of Object.entries(patch)) {
+    const target = mappings[name];
+    if (Array.isArray(target)) {
+      if (typeof console !== "undefined") {
+        console.warn(`[lib/grist] mapBack: cannot reverse-map allowMultiple field "${name}" without grist.mapColumnNamesBack`);
+      }
+      continue;
+    }
+    out[target ?? name] = value;
+  }
+  return out;
+}
+function useGristMappedRecord(options) {
+  const requiredAccess = options?.requiredAccess ?? "read table";
+  const { docApi, error: readyError } = useGristReady({
+    requiredAccess,
+    columns: options?.columns,
+    allowSelectBy: options?.allowSelectBy,
+    hasCustomOptions: options?.hasCustomOptions,
+    onEditOptions: options?.onEditOptions
+  });
+  const [rawRecord, setRawRecord] = useState5(null);
+  const [mappedRecord, setMappedRecord] = useState5(null);
+  const [mappings, setMappings] = useState5(null);
+  useEffect6(() => {
+    if (!docApi) return;
+    return recordEvent.subscribe(({ record, mappings: nextMappings }) => {
+      setRawRecord(record);
+      setMappings(nextMappings);
+      if (!record) {
+        setMappedRecord(null);
+        return;
+      }
+      if (typeof grist.mapColumnNames === "function") {
+        const mapped = grist.mapColumnNames(record);
+        setMappedRecord(
+          mapped !== null && mapped !== void 0 ? mapped : null
+        );
+        return;
+      }
+      setMappedRecord(record);
+    });
+  }, [docApi]);
+  const mapBack = useCallback2(
+    (patch) => {
+      if (typeof grist.mapColumnNamesBack === "function") {
+        return grist.mapColumnNamesBack(patch);
+      }
+      return manualMapBack(patch, mappings);
+    },
+    [mappings]
+  );
+  const resolveColumnId = useCallback2(
+    (logicalName) => {
+      const value = mappings?.[logicalName];
+      if (Array.isArray(value)) return void 0;
+      return value ?? void 0;
+    },
+    [mappings]
+  );
+  return {
+    rawRecord,
+    mappedRecord,
+    mappings,
+    loading: docApi === null && !readyError,
+    error: readyError,
+    mapBack,
+    resolveColumnId
+  };
+}
+
+// src/sdk/mid-level-hooks/use-grist-table-ops.ts
+import { useCallback as useCallback3, useState as useState6 } from "react";
+function resolveOps(tableId) {
+  if (tableId === "selected") {
+    if (!grist.selectedTable) throw new Error("grist.selectedTable is not available");
+    return grist.selectedTable;
+  }
+  if (typeof grist.getTable !== "function") {
+    throw new Error("grist.getTable is not available in this Grist version");
+  }
+  return grist.getTable(tableId);
+}
+function useGristTableOps(options) {
+  const requiredAccess = options?.requiredAccess ?? "full";
+  const tableIdOption = options?.tableId ?? "selected";
+  const { docApi, error: readyError } = useGristReady({
+    requiredAccess,
+    columns: options?.columns,
+    allowSelectBy: options?.allowSelectBy,
+    hasCustomOptions: options?.hasCustomOptions,
+    onEditOptions: options?.onEditOptions
+  });
+  const [status, setStatus] = useState6("idle");
+  const [actionError, setActionError] = useState6(null);
+  const coalesceRpc = useRpcHeartbeatCoalesce();
+  let ops = null;
+  let resolveError = null;
+  if (docApi) {
+    try {
+      ops = resolveOps(tableIdOption);
+    } catch (err) {
+      resolveError = err instanceof Error ? err.message : String(err);
+    }
+  }
+  const wrap = useCallback3(
+    async (run) => {
+      if (!ops) throw new Error("Grist table operations are not ready");
+      setStatus("running");
+      setActionError(null);
+      try {
+        const out = await coalesceRpc(() => run(ops));
+        setStatus("idle");
+        return out;
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        setActionError(message);
+        setStatus("error");
+        throw err;
+      }
+    },
+    [ops, coalesceRpc]
+  );
+  const getTableId = useCallback3(async () => {
+    if (!ops) throw new Error("Grist table operations are not ready");
+    return ops.getTableId();
+  }, [ops]);
+  const create = useCallback3(
+    (records, opOptions) => wrap((o) => o.create(records, opOptions)),
+    [wrap]
+  );
+  const update = useCallback3(
+    (records, opOptions) => wrap((o) => o.update(records, opOptions)),
+    [wrap]
+  );
+  const upsert = useCallback3(
+    (records, opOptions) => wrap((o) => o.upsert(records, opOptions)),
+    [wrap]
+  );
+  const destroy = useCallback3(
+    (recordIds) => wrap((o) => o.destroy(recordIds)),
+    [wrap]
+  );
+  return {
+    status: readyError || resolveError ? "error" : status,
+    error: readyError ?? resolveError ?? actionError,
+    getTableId,
+    create,
+    update,
+    upsert,
+    destroy
+  };
+}
+
+// src/sdk/mid-level-hooks/use-grist-rows-from-table.ts
+import { useCallback as useCallback4, useContext as useContext2, useEffect as useEffect7, useRef as useRef6, useState as useState7 } from "react";
+function useGristRowsFromTable(options) {
+  const requiredAccess = options.requiredAccess ?? "read table";
+  const { docApi, error: readyError } = useGristReady({
+    requiredAccess,
+    columns: options.columns,
+    allowSelectBy: options.allowSelectBy,
+    hasCustomOptions: options.hasCustomOptions,
+    onEditOptions: options.onEditOptions
+  });
+  const providerFetchTable = useContext2(GristReadsContext)?.fetchTable;
+  const [rows, setRows] = useState7(null);
+  const [loading, setLoading] = useState7(false);
+  const [fetchError, setFetchError] = useState7(null);
+  const transformRef = useRef6(options.transform);
+  transformRef.current = options.transform;
+  const coalesceRpc = useRpcHeartbeatCoalesce();
+  const refresh = useCallback4(async () => {
+    if (!docApi) return;
+    setLoading(true);
+    setFetchError(null);
+    try {
+      const data = providerFetchTable ? await providerFetchTable(options.tableId) : await coalesceRpc(
+        () => docApi.fetchTable(options.tableId)
+      );
+      const raw = tableDataToRows(data);
+      const t = transformRef.current;
+      setRows(t ? raw.map((r) => t(r)) : raw);
+    } catch (err) {
+      setFetchError(err instanceof Error ? err.message : String(err));
+      setRows(null);
+    } finally {
+      setLoading(false);
+    }
+  }, [docApi, providerFetchTable, options.tableId, coalesceRpc]);
+  useEffect7(() => {
+    if (docApi) void refresh();
+  }, [docApi, refresh]);
+  useEffect7(() => {
+    if (!docApi || !options.pollIntervalMs || options.pollIntervalMs <= 0) return;
+    const id = window.setInterval(() => void refresh(), options.pollIntervalMs);
+    return () => window.clearInterval(id);
+  }, [docApi, options.pollIntervalMs, refresh]);
+  return {
+    rows,
+    loading,
+    error: readyError ?? fetchError,
+    refresh
+  };
+}
+
+// src/sdk/mid-level-hooks/use-grist-access-token.ts
+import { useCallback as useCallback5, useEffect as useEffect8, useState as useState8 } from "react";
+function useGristAccessToken(options) {
+  const requiredAccess = options?.requiredAccess ?? "full";
+  const readOnlyDefault = options?.readOnly ?? false;
+  const prefetch = options?.prefetch ?? false;
+  const { docApi, error: readyError } = useGristReady({
+    requiredAccess,
+    columns: options?.columns,
+    allowSelectBy: options?.allowSelectBy,
+    hasCustomOptions: options?.hasCustomOptions,
+    onEditOptions: options?.onEditOptions
+  });
+  const [token, setToken] = useState8(null);
+  const [loading, setLoading] = useState8(false);
+  const [error, setError] = useState8(null);
+  const refresh = useCallback5(
+    async (overrides) => {
+      if (!docApi) throw new Error("Grist is not ready");
+      setLoading(true);
+      setError(null);
+      try {
+        const next = await getGristAccessToken(docApi, { readOnly: overrides?.readOnly ?? readOnlyDefault });
+        setToken(next);
+        return next;
+      } catch (err) {
+        const message = err instanceof Error ? err.message : String(err);
+        setError(message);
+        throw err;
+      } finally {
+        setLoading(false);
+      }
+    },
+    [docApi, readOnlyDefault]
+  );
+  const fetchFn = useCallback5(
+    (path, init) => {
+      if (!docApi) throw new Error("Grist is not ready");
+      return fetchWithGristAuth(docApi, path, { readOnly: readOnlyDefault, ...init });
+    },
+    [docApi, readOnlyDefault]
+  );
+  useEffect8(() => {
+    if (docApi && prefetch) void refresh();
+  }, [docApi, prefetch, refresh]);
+  return {
+    token,
+    loading,
+    error: readyError ?? error,
+    refresh,
+    fetch: fetchFn
+  };
+}
+
+// src/sdk/mid-level-hooks/use-grist-section.ts
+import { useCallback as useCallback6, useEffect as useEffect9, useState as useState9 } from "react";
+function useGristSection(options) {
+  const { docApi, error: readyError } = useGristReady({
+    requiredAccess: options?.requiredAccess ?? "read table",
+    columns: options?.columns,
+    allowSelectBy: options?.allowSelectBy,
+    hasCustomOptions: options?.hasCustomOptions,
+    onEditOptions: options?.onEditOptions
+  });
+  const [mappings, setMappings] = useState9(null);
+  const [loading, setLoading] = useState9(false);
+  const [error, setError] = useState9(null);
+  const refresh = useCallback6(async () => {
+    if (!docApi) return;
+    if (!grist.sectionApi?.mappings) {
+      setError("grist.sectionApi.mappings is not available in this Grist version");
+      return;
+    }
+    setLoading(true);
+    setError(null);
+    try {
+      const next = await grist.sectionApi.mappings();
+      setMappings(next);
+    } catch (err) {
+      setError(err instanceof Error ? err.message : String(err));
+    } finally {
+      setLoading(false);
+    }
+  }, [docApi]);
+  const configure = useCallback6(async (next) => {
+    if (!grist.sectionApi?.configure) {
+      throw new Error("grist.sectionApi.configure is not available in this Grist version");
+    }
+    await grist.sectionApi.configure(next);
+  }, []);
+  useEffect9(() => {
+    if (docApi) void refresh();
+  }, [docApi, refresh]);
+  return {
+    mappings,
+    loading,
+    error: readyError ?? error,
+    refresh,
+    configure
+  };
+}
+
+// src/sdk/mid-level-hooks/use-grist-widget-options.ts
+import { useCallback as useCallback7, useEffect as useEffect10, useMemo as useMemo3, useRef as useRef7, useState as useState10 } from "react";
+function mergeWithDefaults(defaults, stored, namespace) {
+  if (stored === null || stored === void 0) return { ...defaults };
+  const source = namespace ? stored[namespace] : stored;
+  if (!source || typeof source !== "object") return { ...defaults };
+  return { ...defaults, ...source };
+}
+function useGristWidgetOptions(config) {
+  const requiredAccess = config.requiredAccess ?? "read table";
+  const debounceMs = config.debounceMs ?? 250;
+  const hasCustomOptions = config.hasCustomOptions ?? true;
+  const { docApi, error: readyError } = useGristReady({
+    requiredAccess,
+    columns: config.columns,
+    allowSelectBy: config.allowSelectBy,
+    hasCustomOptions,
+    onEditOptions: config.onEditOptions
+  });
+  const defaultsRef = useRef7(config.defaults);
+  useEffect10(() => {
+    defaultsRef.current = config.defaults;
+  }, [config.defaults]);
+  const [options, setOptionsState] = useState10(() => ({ ...config.defaults }));
+  const [loading, setLoading] = useState10(true);
+  const [error, setError] = useState10(null);
+  const lastWrittenRef = useRef7(null);
+  const debounceRef = useRef7(null);
+  useEffect10(() => {
+    if (!docApi) return;
+    return optionsEvent.subscribe(({ options: stored }) => {
+      const merged = mergeWithDefaults(defaultsRef.current, stored, config.namespace);
+      lastWrittenRef.current = merged;
+      setOptionsState(merged);
+      setLoading(false);
+    });
+  }, [docApi, config.namespace]);
+  const flushWrite = useCallback7(
+    async (value) => {
+      try {
+        if (config.namespace) {
+          await grist.setOption(config.namespace, value);
+        } else {
+          await grist.setOptions({ ...value });
+        }
+        lastWrittenRef.current = value;
+      } catch (err) {
+        setError(err instanceof Error ? err.message : String(err));
+      }
+    },
+    [config.namespace]
+  );
+  const scheduleWrite = useCallback7(
+    (value) => {
+      if (debounceRef.current) window.clearTimeout(debounceRef.current);
+      debounceRef.current = window.setTimeout(() => {
+        debounceRef.current = null;
+        void flushWrite(value);
+      }, debounceMs);
+    },
+    [debounceMs, flushWrite]
+  );
+  useEffect10(() => {
+    return () => {
+      if (debounceRef.current) window.clearTimeout(debounceRef.current);
+    };
+  }, []);
+  const setOptionsApi = useCallback7(
+    (next) => {
+      setOptionsState(next);
+      scheduleWrite(next);
+    },
+    [scheduleWrite]
+  );
+  const patchOptionsApi = useCallback7(
+    (patch) => {
+      setOptionsState((prev) => {
+        const next = { ...prev, ...patch };
+        scheduleWrite(next);
+        return next;
+      });
+    },
+    [scheduleWrite]
+  );
+  const reset = useCallback7(async () => {
+    if (debounceRef.current) {
+      window.clearTimeout(debounceRef.current);
+      debounceRef.current = null;
+    }
+    const next = { ...defaultsRef.current };
+    setOptionsState(next);
+    await flushWrite(next);
+  }, [flushWrite]);
+  return useMemo3(
+    () => ({
+      options,
+      loading,
+      error: readyError ?? error,
+      setOptions: setOptionsApi,
+      patchOptions: patchOptionsApi,
+      reset
+    }),
+    [options, loading, readyError, error, setOptionsApi, patchOptionsApi, reset]
+  );
+}
+
+// src/sdk/use-grist-table.ts
+import { useCallback as useCallback8, useEffect as useEffect11, useState as useState11 } from "react";
+function isCurrentMode(option) {
+  return option === void 0 || option === "current";
+}
+function useGristTable(options) {
+  const requiredAccess = options?.requiredAccess ?? "read table";
+  const tableIdOption = options?.tableId ?? "current";
+  const { docApi, error: readyError } = useGristReady({
+    requiredAccess,
+    columns: options?.columns,
+    allowSelectBy: options?.allowSelectBy,
+    hasCustomOptions: options?.hasCustomOptions,
+    onEditOptions: options?.onEditOptions
+  });
+  const [tableId, setTableId] = useState11(null);
+  const [loading, setLoading] = useState11(false);
+  const [error, setError] = useState11(null);
+  const fetchTable = useCallback8(
+    async (targetTableId) => {
+      if (!docApi) throw new Error("Grist is not ready");
+      return docApi.fetchTable(targetTableId);
+    },
+    [docApi]
+  );
+  const listTables = useCallback8(async () => {
+    if (!docApi) throw new Error("Grist is not ready");
+    const out = await Promise.resolve(docApi.listTables());
+    return [...out];
+  }, [docApi]);
+  const getDocName = useCallback8(async () => {
+    if (!docApi) throw new Error("Grist is not ready");
+    return String(await Promise.resolve(docApi.getDocName()));
+  }, [docApi]);
+  const fetchSelectedTable = useCallback8(
+    async (fetchOptions) => {
+      if (!docApi) throw new Error("Grist is not ready");
+      const impl = docApi.fetchSelectedTable ?? grist.fetchSelectedTable;
+      if (!impl) throw new Error("fetchSelectedTable is not available in this Grist version");
+      const merged = { keepEncoded: false, format: "rows", ...fetchOptions };
+      return await impl(merged);
+    },
+    [docApi]
+  );
+  const fetchSelectedRecord = useCallback8(
+    async (rowId, fetchOptions) => {
+      if (!docApi) throw new Error("Grist is not ready");
+      const impl = docApi.fetchSelectedRecord ?? grist.fetchSelectedRecord;
+      if (!impl) throw new Error("fetchSelectedRecord is not available in this Grist version");
+      const merged = { keepEncoded: false, format: "rows", ...fetchOptions };
+      return await impl(rowId, merged);
+    },
+    [docApi]
+  );
+  const refresh = useCallback8(async () => {
+    if (!docApi) return;
+    if (!isCurrentMode(tableIdOption)) {
+      setTableId(tableIdOption);
+      setError(null);
+      return;
+    }
+    setLoading(true);
+    setError(null);
+    try {
+      const next = await grist.selectedTable?.getTableId();
+      setTableId(next ?? null);
+    } catch (err) {
+      setTableId(null);
+      setError(err instanceof Error ? err.message : String(err));
+    } finally {
+      setLoading(false);
+    }
+  }, [docApi, tableIdOption]);
+  useEffect11(() => {
+    if (docApi) void refresh();
+  }, [docApi, refresh]);
+  return {
+    tableId,
+    loading,
+    error: readyError ?? error,
+    refresh,
+    fetchTable,
+    listTables,
+    getDocName,
+    fetchSelectedTable,
+    fetchSelectedRecord
+  };
+}
+export {
+  GristHandshakeProvider,
+  useGristAccessToken,
+  useGristActions,
+  useGristAvailability,
+  useGristCapabilities,
+  useGristHandshake,
+  useGristHandshakeContext,
+  useGristHandshakeContextOptional,
+  useGristMappedRecord,
+  useGristNewRecord,
+  useGristReady,
+  useGristRecord,
+  useGristRecords,
+  useGristRowsFromTable,
+  useGristSection,
+  useGristTable,
+  useGristTableOps,
+  useGristWidgetOptions,
+  useGristWidgetOptionsFromContext
+};
+//# sourceMappingURL=advanced.js.map