grist-widget-sdk 0.3.26 → 0.4.0

package/dist/chunk-O7NY46QY.js

@@ -0,0 +1,1830 @@
+import {
+  buildReplicaJsonPayload,
+  coerceGristDocApiRefRowId,
+  decodeGristValue,
+  encodeGristValue
+} from "./chunk-4ZGVKGDF.js";
+
+// src/sdk/helpers/grist-table-data.ts
+function computeRowCount(data) {
+  const idCol = data.id;
+  if (Array.isArray(idCol)) return idCol.length;
+  for (const key of Object.keys(data)) {
+    const col = data[key];
+    if (Array.isArray(col)) return col.length;
+  }
+  return 0;
+}
+function decodeColumnarToReplicaRows(data, columnIds, columns, maxRows) {
+  const nFull = computeRowCount(data);
+  const n = maxRows !== void 0 ? Math.min(nFull, maxRows) : nFull;
+  const out = [];
+  for (let i = 0; i < n; i++) {
+    const row = {};
+    for (const k of columnIds) {
+      const arr = data[k];
+      const raw = Array.isArray(arr) ? arr[i] : void 0;
+      if (k === "id") {
+        row[k] = raw;
+      } else {
+        row[k] = decodeGristValue(raw, columns[k]);
+      }
+    }
+    out.push(row);
+  }
+  return out;
+}
+function tableDataToRows(data) {
+  const idCol = data.id;
+  if (!Array.isArray(idCol) || idCol.length === 0) return [];
+  const keys = Object.keys(data);
+  const n = idCol.length;
+  const rows = [];
+  for (let i = 0; i < n; i++) {
+    const row = {};
+    for (const k of keys) {
+      const col = data[k];
+      row[k] = Array.isArray(col) ? col[i] : void 0;
+    }
+    rows.push(row);
+  }
+  return rows;
+}
+function manualSortKey(row) {
+  const v = row.manualSort;
+  if (typeof v === "number" && !Number.isNaN(v)) return v;
+  if (typeof v === "string" && v.trim() !== "") {
+    const n = Number(v);
+    if (!Number.isNaN(n)) return n;
+  }
+  return null;
+}
+function sortRowsByGristOrder(rows) {
+  const hasManual = rows.some((r) => manualSortKey(r) !== null);
+  if (!hasManual) {
+    return [...rows].sort((a, b) => {
+      const ida = typeof a.id === "number" ? a.id : 0;
+      const idb = typeof b.id === "number" ? b.id : 0;
+      return ida - idb;
+    });
+  }
+  return [...rows].sort((a, b) => {
+    const ma = manualSortKey(a);
+    const mb = manualSortKey(b);
+    if (ma !== null && mb !== null && ma !== mb) return ma - mb;
+    if (ma !== null && mb === null) return -1;
+    if (ma === null && mb !== null) return 1;
+    const ida = typeof a.id === "number" ? a.id : 0;
+    const idb = typeof b.id === "number" ? b.id : 0;
+    return ida - idb;
+  });
+}
+function materializeGristRowsFromColumnar(data, options) {
+  const order = options?.order ?? "grist";
+  let rows;
+  if (options?.columns) {
+    const columnIds = Object.keys(data);
+    rows = decodeColumnarToReplicaRows(data, columnIds, options.columns);
+  } else {
+    rows = tableDataToRows(data);
+  }
+  if (order === "none") return rows;
+  if (order === "id") {
+    return [...rows].sort((a, b) => {
+      const ida = typeof a.id === "number" ? a.id : 0;
+      const idb = typeof b.id === "number" ? b.id : 0;
+      return ida - idb;
+    });
+  }
+  return sortRowsByGristOrder(rows);
+}
+async function fetchGristTableRows(docApi, tableId, options) {
+  const data = await docApi.fetchTable(tableId);
+  return materializeGristRowsFromColumnar(data, options);
+}
+
+// src/sdk/helpers/grist-schema-formula.ts
+function inferGristFormulaKind(isFormula, formulaTrimmed) {
+  if (formulaTrimmed.length > 0) return isFormula ? "computed" : "trigger";
+  return isFormula ? "empty_slot" : "none";
+}
+function resolveGristFormulaKind(col) {
+  if (col.formulaKind) return col.formulaKind;
+  const f = col.formula?.trim() ?? "";
+  if (f.length > 0) return col.isFormula === true ? "computed" : "trigger";
+  return col.isFormula === true ? "empty_slot" : "none";
+}
+
+// src/sdk/helpers/grist-widget-options.ts
+function parseGristWidgetOptionsCell(raw) {
+  if (raw == null || raw === "") return void 0;
+  if (typeof raw === "string") {
+    try {
+      const parsed = JSON.parse(raw);
+      if (parsed && typeof parsed === "object" && !Array.isArray(parsed)) {
+        return parsed;
+      }
+    } catch {
+      return void 0;
+    }
+    return void 0;
+  }
+  if (typeof raw === "object" && !Array.isArray(raw)) {
+    return raw;
+  }
+  return void 0;
+}
+function readStyleColor(style, key) {
+  const v = style[key];
+  return typeof v === "string" ? v : void 0;
+}
+function normalizeGristChoiceListEntries(widgetOptions) {
+  if (!widgetOptions) return [];
+  const rawChoices = widgetOptions.choices;
+  if (!Array.isArray(rawChoices)) return [];
+  const choiceOptionsRaw = widgetOptions.choiceOptions;
+  const choiceOptions = choiceOptionsRaw && typeof choiceOptionsRaw === "object" && !Array.isArray(choiceOptionsRaw) ? choiceOptionsRaw : {};
+  const out = [];
+  for (const c of rawChoices) {
+    const value = typeof c === "string" ? c : c != null ? String(c) : "";
+    if (!value) continue;
+    const style = choiceOptions[value] ?? {};
+    out.push({
+      value,
+      label: value,
+      fillColor: readStyleColor(style, "fillColor"),
+      textColor: readStyleColor(style, "textColor")
+    });
+  }
+  return out;
+}
+
+// src/sdk/helpers/grist-attachment-download.ts
+function attachmentIdFromObjectRecord(record) {
+  for (const candidate of [record.id, record.attachmentId, record.fileId]) {
+    if (candidate === void 0 || candidate === null) continue;
+    return String(candidate);
+  }
+  return void 0;
+}
+function extractGristAttachmentIdsFromCell(value) {
+  const out = [];
+  const seen = /* @__PURE__ */ new Set();
+  const push = (id) => {
+    if (seen.has(id)) return;
+    seen.add(id);
+    out.push(id);
+  };
+  const walk = (v) => {
+    if (v === void 0 || v === null) return;
+    if (typeof v === "number") {
+      push(String(v));
+      return;
+    }
+    if (typeof v === "string") {
+      const trimmed = v.trim();
+      if (!trimmed) return;
+      if (/^\d+$/.test(trimmed)) {
+        push(trimmed);
+        return;
+      }
+      try {
+        walk(JSON.parse(trimmed));
+      } catch {
+      }
+      return;
+    }
+    if (Array.isArray(v)) {
+      for (const item of v) walk(item);
+      return;
+    }
+    if (typeof v === "object") {
+      const record = v;
+      const direct = attachmentIdFromObjectRecord(record);
+      if (direct !== void 0) {
+        push(direct);
+        return;
+      }
+      for (const nested of Object.values(record)) walk(nested);
+    }
+  };
+  walk(value);
+  return out;
+}
+function extractGristAttachmentId(value) {
+  return extractGristAttachmentIdsFromCell(value)[0];
+}
+async function getAttachmentDownloadUrl(docApi, attachmentId, options) {
+  const getAccessToken = docApi.getAccessToken;
+  if (!getAccessToken) {
+    throw new Error("getAccessToken is not available on docApi");
+  }
+  const { token, baseUrl } = await getAccessToken({ readOnly: options?.readOnly ?? false });
+  return `${baseUrl}/attachments/${attachmentId}/download?auth=${token}`;
+}
+async function fetchBytesFromSignedAttachmentUrl(url) {
+  const response = await fetch(url);
+  const contentType = response.headers.get("content-type")?.trim() || "application/octet-stream";
+  if (!response.ok) {
+    throw new Error(`Attachment download failed (${response.status})`);
+  }
+  const buffer = await response.arrayBuffer();
+  return { buffer, contentType };
+}
+async function fetchAttachmentBlob(docApi, attachmentId, options) {
+  const url = await getAttachmentDownloadUrl(docApi, attachmentId, options);
+  const { buffer, contentType } = await fetchBytesFromSignedAttachmentUrl(url);
+  return { blob: new Blob([buffer], { type: contentType }), contentType };
+}
+
+// src/sdk/helpers/grist-fetch-with-auth.ts
+var TOKEN_TTL_MS = 45e3;
+var cache = /* @__PURE__ */ new Map();
+var inFlight = /* @__PURE__ */ new Map();
+function cacheKey(readOnly) {
+  return readOnly ? "ro" : "rw";
+}
+async function getGristAccessToken(docApi, options) {
+  if (!docApi.getAccessToken) {
+    throw new Error("getAccessToken is not available on docApi (need higher access level)");
+  }
+  const readOnly = options?.readOnly ?? false;
+  const key = cacheKey(readOnly);
+  const now = Date.now();
+  const hit = cache.get(key);
+  if (hit && now - hit.fetchedAt < TOKEN_TTL_MS) {
+    return hit.token;
+  }
+  const pending = inFlight.get(key);
+  if (pending) return pending;
+  const next = docApi.getAccessToken({ readOnly }).then((token) => {
+    cache.set(key, { token, fetchedAt: Date.now() });
+    inFlight.delete(key);
+    return token;
+  });
+  inFlight.set(key, next);
+  return next;
+}
+function clearGristAccessTokenCache() {
+  cache.clear();
+  inFlight.clear();
+}
+async function fetchWithGristAuth(docApi, path, init) {
+  const readOnly = init?.readOnly ?? false;
+  let token;
+  try {
+    token = await getGristAccessToken(docApi, { readOnly });
+  } catch (err) {
+    clearGristAccessTokenCache();
+    throw err;
+  }
+  const isAbsolute = /^https?:\/\//i.test(path);
+  const cleanPath = isAbsolute ? path : path.startsWith("/") ? path : `/${path}`;
+  const url = isAbsolute ? new URL(path) : new URL(`${token.baseUrl.replace(/\/$/, "")}${cleanPath}`);
+  const gristOrigin = new URL(token.baseUrl).origin;
+  if (url.origin !== gristOrigin) {
+    throw new Error(
+      `fetchWithGristAuth: refusing to send the Grist access token to ${url.origin}; absolute URLs must point at this document's Grist instance (${gristOrigin}). Use plain fetch() for other hosts.`
+    );
+  }
+  if (!url.searchParams.has("auth")) url.searchParams.set("auth", token.token);
+  const headers = new Headers(init?.headers ?? {});
+  headers.delete("Authorization");
+  const response = await fetch(url.toString(), { ...init, headers });
+  if (response.status === 401) {
+    clearGristAccessTokenCache();
+    const retryToken = await getGristAccessToken(docApi, { readOnly });
+    url.searchParams.set("auth", retryToken.token);
+    return fetch(url.toString(), { ...init, headers });
+  }
+  return response;
+}
+
+// src/sdk/helpers/grist-attachment-upload.ts
+var ATTACHMENTS_COLUMN = { type: "Attachments" };
+function parseGristAttachmentUploadResponseIds(raw, options) {
+  const trimmed = raw.trim();
+  if (!trimmed) {
+    throw new Error("Attachment upload returned an empty response.");
+  }
+  let parsed;
+  try {
+    parsed = JSON.parse(trimmed);
+  } catch {
+    if (options?.strict) {
+      throw new Error("Attachment upload returned non-JSON response.");
+    }
+    parsed = trimmed;
+  }
+  return extractAttachmentIdsFromUploadPayload(parsed, options);
+}
+function extractAttachmentIdsFromUploadPayload(parsed, options) {
+  if (options?.strict) {
+    return extractAttachmentIdsFromUploadPayloadStrict(parsed);
+  }
+  const first = extractFirstAttachmentIdFromUploadPayload(parsed);
+  if (first !== void 0) {
+    if (Array.isArray(parsed)) {
+      const ids = [];
+      const seen = /* @__PURE__ */ new Set();
+      for (const item of parsed) {
+        const id = coerceAttachmentId(item);
+        if (id && !seen.has(id)) {
+          seen.add(id);
+          ids.push(id);
+        }
+      }
+      return ids.length > 0 ? ids : [first];
+    }
+    return [first];
+  }
+  throw new Error("Attachment upload returned an unexpected response shape.");
+}
+function extractAttachmentIdsFromUploadPayloadStrict(parsed) {
+  if (typeof parsed === "number" && Number.isFinite(parsed)) {
+    return [String(parsed)];
+  }
+  if (Array.isArray(parsed)) {
+    const ids = [];
+    const seen = /* @__PURE__ */ new Set();
+    for (const item of parsed) {
+      if (typeof item !== "number" || !Number.isFinite(item)) {
+        throw new Error("Attachment upload returned an unexpected response shape.");
+      }
+      const id = String(item);
+      if (!seen.has(id)) {
+        seen.add(id);
+        ids.push(id);
+      }
+    }
+    if (ids.length === 0) {
+      throw new Error("Attachment upload returned an empty id list.");
+    }
+    return ids;
+  }
+  throw new Error("Attachment upload returned an unexpected response shape.");
+}
+function extractFirstAttachmentIdFromUploadPayload(parsed) {
+  if (typeof parsed === "number" && Number.isFinite(parsed)) {
+    return String(parsed);
+  }
+  if (typeof parsed === "string" && parsed.trim()) {
+    return parsed.trim();
+  }
+  if (Array.isArray(parsed)) {
+    for (const item of parsed) {
+      const id = coerceAttachmentId(item);
+      if (id) return id;
+    }
+    return void 0;
+  }
+  if (parsed && typeof parsed === "object") {
+    const record = parsed;
+    for (const key of ["id", "attachmentId", "fileId"]) {
+      const id = coerceAttachmentId(record[key]);
+      if (id) return id;
+    }
+  }
+  return void 0;
+}
+function coerceAttachmentId(value) {
+  if (typeof value === "number" && Number.isFinite(value)) {
+    return String(value);
+  }
+  if (typeof value === "string" && value.trim()) {
+    return value.trim();
+  }
+  return void 0;
+}
+function normalizeAttachmentIdForWire(id) {
+  const numeric = typeof id === "number" ? id : Number(id);
+  if (Number.isFinite(numeric) && String(numeric) === String(id).trim()) {
+    return numeric;
+  }
+  return typeof id === "number" ? String(id) : id.trim();
+}
+function gristAttachmentCellValues(attachmentIds) {
+  const items = attachmentIds.map(normalizeAttachmentIdForWire);
+  const encoded = encodeGristValue(items, ATTACHMENTS_COLUMN);
+  if (!Array.isArray(encoded) || encoded[0] !== "L") {
+    return ["L", ...items];
+  }
+  return encoded;
+}
+function gristAttachmentCellValue(attachmentId) {
+  return gristAttachmentCellValues([attachmentId]);
+}
+function mergeGristAttachmentCellValue(existingCell, newIds) {
+  const existing = extractGristAttachmentIdsFromCell(existingCell);
+  const merged = [];
+  const seen = /* @__PURE__ */ new Set();
+  const push = (raw) => {
+    const id = String(raw).trim();
+    if (!id || seen.has(id)) return;
+    seen.add(id);
+    merged.push(id);
+  };
+  for (const id of existing) push(id);
+  for (const id of newIds) push(id);
+  return gristAttachmentCellValues(merged);
+}
+var UPLOAD_HEADERS = {
+  "X-Requested-With": "XMLHttpRequest",
+  Accept: "application/json"
+};
+async function uploadGristAttachment(docApi, file, options) {
+  const form = new FormData();
+  const fileName = options?.fileName ?? (file instanceof File && file.name ? file.name : "upload");
+  form.append("upload", file, fileName);
+  let response;
+  try {
+    response = await fetchWithGristAuth(docApi, "/attachments", {
+      method: "POST",
+      body: form,
+      readOnly: false,
+      headers: UPLOAD_HEADERS
+    });
+  } catch (err) {
+    const msg = err instanceof Error ? err.message : String(err);
+    if (/failed to fetch/i.test(msg)) {
+      const widgetOrigin = typeof globalThis.location !== "undefined" ? globalThis.location.origin : "this widget origin";
+      throw new Error(
+        `Attachment upload was blocked by the Grist host (CORS). The browser could not POST from ${widgetOrigin} to the document API. If upload worked from a dev URL (e.g. ngrok) but fails after deploy, add the new widget URL to your Grist server CORS allowlist (see grist-core#2040).`,
+        { cause: err }
+      );
+    }
+    throw err;
+  }
+  const raw = await response.text();
+  if (!response.ok) {
+    throw new Error(
+      raw.trim() ? `Attachment upload failed (${response.status}): ${raw.slice(0, 200)}` : `Attachment upload failed (${response.status})`
+    );
+  }
+  const ids = parseGristAttachmentUploadResponseIds(raw);
+  return { ids, firstId: ids[0] };
+}
+
+// src/sdk/runtime/cells.ts
+var ok = (value) => ({ ok: true, value });
+var bad = (message2) => ({ ok: false, message: message2 });
+function formulaError(value) {
+  if (Array.isArray(value) && value[0] === "E") return String(value[1] ?? "error");
+  if (value && typeof value === "object" && value.constructor?.name === "RaisedException") {
+    return String(value.name ?? "error");
+  }
+  return null;
+}
+function rowIdOf(value) {
+  if (typeof value === "number" && Number.isInteger(value)) return value === 0 ? null : value;
+  if (value && typeof value === "object" && typeof value.rowId === "number") {
+    const id = value.rowId;
+    return id === 0 ? null : id;
+  }
+  if (Array.isArray(value) && value[0] === "R" && typeof value[2] === "number") return value[2] === 0 ? null : value[2];
+  return void 0;
+}
+function idsOf(value) {
+  if (value === null || value === void 0) return [];
+  const list = Array.isArray(value) ? value[0] === "L" ? value.slice(1) : value : value && typeof value === "object" && Array.isArray(value.rowIds) ? value.rowIds : void 0;
+  return list?.every((v) => typeof v === "number") ? list : void 0;
+}
+function checkOne(base, value) {
+  switch (base) {
+    case "Any":
+      return ok(value);
+    case "Text":
+      return value === null || typeof value === "string" ? ok(value ?? "") : bad("not text");
+    case "Numeric":
+      return value === null || typeof value === "number" && Number.isFinite(value) ? ok(value) : bad("not a number");
+    case "Int":
+      return value === null || typeof value === "number" && Number.isInteger(value) ? ok(value) : bad("not an integer");
+    case "Bool":
+      return value === null || typeof value === "boolean" ? ok(value ?? false) : bad("not true or false");
+    case "Date":
+    case "DateTime":
+      if (value === null) return ok(null);
+      if (value instanceof Date && !Number.isNaN(value.getTime())) return ok(value);
+      if (typeof value === "number" && Number.isFinite(value)) return ok(new Date(value * 1e3));
+      return bad("not a date");
+    case "Choice":
+      return value === null || typeof value === "string" ? ok(value) : bad("not a choice");
+    case "ChoiceList": {
+      if (value === null || value === void 0) return ok([]);
+      const list = Array.isArray(value) ? value[0] === "L" ? value.slice(1) : value : void 0;
+      return list?.every((v) => typeof v === "string") ? ok(list) : bad("not a list of choices");
+    }
+    case "Ref": {
+      if (value === null) return ok(null);
+      const id = rowIdOf(value);
+      return id === void 0 ? bad("not a reference") : ok(id);
+    }
+    case "RefList":
+    case "Attachments": {
+      const ids = idsOf(value);
+      return ids === void 0 ? bad(base === "RefList" ? "not a list of references" : "not a list of attachments") : ok(ids);
+    }
+    default:
+      return ok(value);
+  }
+}
+function checkGristCell(type, value) {
+  const error = formulaError(value);
+  if (error) return bad(`formula error (${error})`);
+  const bases = (type ?? "Any").split(",").map((t) => t.trim().split(":")[0]).filter(Boolean);
+  if (bases.length === 0 || bases.includes("Any")) return ok(value === void 0 ? null : value);
+  let first = null;
+  for (const base of bases) {
+    const check = checkOne(base, value);
+    if (check.ok) return check;
+    first ?? (first = check);
+  }
+  return first;
+}
+var nameOf = (c) => typeof c === "string" ? c : c.name;
+var typeOf = (c) => typeof c === "string" ? void 0 : c.type;
+var isOptional = (c) => typeof c === "object" && c.optional === true;
+function mapAndCheck(record, columns, mappings, schema) {
+  if (!record) return { value: null, issues: [] };
+  if (!columns?.length) return { value: record, issues: [] };
+  if (mappings === null) return { value: null, issues: [] };
+  const rowId = typeof record.id === "number" ? record.id : 0;
+  const out = { id: record.id };
+  const issues = [];
+  for (const col of columns) {
+    const name = nameOf(col);
+    const real = mappings[name];
+    const take = (raw) => {
+      const check = checkGristCell(typeOf(col), raw);
+      if (check.ok) return check.value;
+      issues.push({ rowId, column: name, message: check.message, value: raw });
+      return null;
+    };
+    if (Array.isArray(real) && real.length > 0) out[name] = real.map((r) => take(record[r]));
+    else if (typeof real === "string" && real) out[name] = take(record[real]);
+    else if (!isOptional(col)) return { value: null, issues: [] };
+  }
+  if (schema) {
+    const result = schema["~standard"].validate(out);
+    if (result instanceof Promise) {
+      issues.push({ rowId, column: "", message: "the schema validates asynchronously; useGrist() needs a synchronous one", value: out });
+    } else if ("issues" in result && result.issues) {
+      for (const issue of result.issues) {
+        const key = issue.path?.[0];
+        const column = key === void 0 ? "" : String(typeof key === "object" ? key.key : key);
+        issues.push({ rowId, column, message: issue.message, value: column ? out[column] : out });
+      }
+    } else if ("value" in result) {
+      return { value: result.value, issues };
+    }
+  }
+  return { value: out, issues };
+}
+
+// src/sdk/use-grist.ts
+import { createContext, useCallback, useContext, useEffect, useMemo, useSyncExternalStore } from "react";
+
+// src/sdk/helpers/build-replica-document.ts
+var FORMULA_PREVIEW_MAX = 500;
+function readCellStr(table, key, rowIndex) {
+  const col = table[key];
+  if (!Array.isArray(col)) return void 0;
+  const v = col[rowIndex];
+  if (v === null || v === void 0) return void 0;
+  if (typeof v === "string") return v;
+  if (typeof v === "number" || typeof v === "boolean") return String(v);
+  return void 0;
+}
+function readCellNum(table, key, rowIndex) {
+  const col = table[key];
+  if (!Array.isArray(col)) return void 0;
+  const v = col[rowIndex];
+  if (typeof v === "number" && !Number.isNaN(v)) return v;
+  if (typeof v === "string" && v.trim() !== "") {
+    const n = Number(v);
+    if (!Number.isNaN(n)) return n;
+  }
+  return void 0;
+}
+function pickColumnMeta(meta) {
+  if (!meta) return {};
+  const out = {};
+  if (meta.colRef !== void 0) out.colRef = meta.colRef;
+  if (meta.type) out.type = meta.type;
+  if (meta.label) out.label = meta.label;
+  if (meta.parentPos !== void 0) out.parentPos = meta.parentPos;
+  if (meta.isFormula) out.isFormula = true;
+  const formulaRaw = meta.formula?.trim() ?? "";
+  out.formulaKind = inferGristFormulaKind(Boolean(meta.isFormula), formulaRaw);
+  if (formulaRaw) {
+    out.formula = formulaRaw.length > FORMULA_PREVIEW_MAX ? `${formulaRaw.slice(0, FORMULA_PREVIEW_MAX)}...` : formulaRaw;
+  }
+  if (meta.description) out.description = meta.description;
+  if (meta.widgetOptions && Object.keys(meta.widgetOptions).length > 0) {
+    out.widgetOptions = meta.widgetOptions;
+  }
+  if (meta.displayColRef !== void 0) out.displayColRef = meta.displayColRef;
+  if (meta.visibleColRef !== void 0) out.visibleColRef = meta.visibleColRef;
+  return out;
+}
+async function loadColumnMetadataByTable(docApi) {
+  const byTable = /* @__PURE__ */ new Map();
+  try {
+    const tables = await docApi.fetchTable("_grist_Tables");
+    const columns = await docApi.fetchTable("_grist_Tables_column");
+    const tableIds = tables.tableId;
+    const tableInternalIds = tables.id;
+    if (!Array.isArray(tableIds) || !Array.isArray(tableInternalIds)) return byTable;
+    const internalIdToTableId = /* @__PURE__ */ new Map();
+    for (let i = 0; i < tableInternalIds.length; i++) {
+      const tid = tableIds[i];
+      const iid = coerceGristDocApiRefRowId(tableInternalIds[i]);
+      if (typeof tid === "string" && iid !== void 0) internalIdToTableId.set(iid, tid);
+    }
+    const parentIds = columns.parentId;
+    const colIds = columns.colId;
+    const columnIds = columns.id;
+    if (!Array.isArray(parentIds) || !Array.isArray(colIds) || !Array.isArray(columnIds) || parentIds.length !== colIds.length || colIds.length !== columnIds.length) {
+      return byTable;
+    }
+    const n = parentIds.length;
+    for (let i = 0; i < n; i++) {
+      const parentRowId = coerceGristDocApiRefRowId(parentIds[i]);
+      const colRef = coerceGristDocApiRefRowId(columnIds[i]);
+      const colId = colIds[i];
+      if (parentRowId === void 0 || colRef === void 0 || typeof colId !== "string") continue;
+      const tableId = internalIdToTableId.get(parentRowId);
+      if (!tableId) continue;
+      let colMap = byTable.get(tableId);
+      if (!colMap) {
+        colMap = /* @__PURE__ */ new Map();
+        byTable.set(tableId, colMap);
+      }
+      const parentPos = readCellNum(columns, "parentPos", i);
+      const isFormulaCol = columns.isFormula;
+      const isFormula = Array.isArray(isFormulaCol) ? Boolean(isFormulaCol[i]) : false;
+      const woCol = columns.widgetOptions;
+      const widgetOptions = Array.isArray(woCol) && i < woCol.length ? parseGristWidgetOptionsCell(woCol[i]) : void 0;
+      const displayColRef = coerceGristDocApiRefRowId(
+        Array.isArray(columns.displayCol) ? columns.displayCol[i] : void 0
+      );
+      const visibleColRef = coerceGristDocApiRefRowId(
+        Array.isArray(columns.visibleCol) ? columns.visibleCol[i] : void 0
+      );
+      colMap.set(colId, {
+        colRef,
+        type: readCellStr(columns, "type", i),
+        label: readCellStr(columns, "label", i),
+        parentPos: parentPos !== void 0 ? parentPos : void 0,
+        isFormula,
+        formula: readCellStr(columns, "formula", i),
+        description: readCellStr(columns, "description", i) ?? readCellStr(columns, "descr", i),
+        widgetOptions,
+        displayColRef,
+        visibleColRef
+      });
+    }
+  } catch {
+  }
+  return byTable;
+}
+function orderedColumnIds(data, metaByCol) {
+  const keys = Object.keys(data).filter((k) => Array.isArray(data[k]));
+  keys.sort((a, b) => {
+    const pa = metaByCol.get(a)?.parentPos;
+    const pb = metaByCol.get(b)?.parentPos;
+    if (pa !== void 0 && pb !== void 0 && pa !== pb) return pa - pb;
+    if (pa !== void 0 && pb === void 0) return -1;
+    if (pa === void 0 && pb !== void 0) return 1;
+    return a.localeCompare(b);
+  });
+  return keys;
+}
+function buildReplicaColumnsFromColumnar(data, colMeta) {
+  const columnIds = orderedColumnIds(data, colMeta);
+  const columns = {};
+  for (const colId of columnIds) {
+    const arr = data[colId];
+    if (!Array.isArray(arr)) continue;
+    const meta = colMeta.get(colId);
+    columns[colId] = pickColumnMeta(meta);
+  }
+  return columns;
+}
+function rowModeFromIncludeRows(includeRows) {
+  if (includeRows === false) return "schema-only";
+  if (includeRows === "samples") return "schema+samples";
+  return "schema+data";
+}
+async function buildReplicaDocumentFromDocApi(docApi, options) {
+  const includeSystemTableData = options?.includeSystemTableData ?? false;
+  const includeRows = options?.includeRows ?? "samples";
+  const sampleRowLimit = options?.sampleRowLimit ?? 10;
+  const rowMode = rowModeFromIncludeRows(includeRows);
+  const metaByTable = await loadColumnMetadataByTable(docApi);
+  let docName;
+  try {
+    docName = String(await Promise.resolve(docApi.getDocName()));
+  } catch {
+    docName = void 0;
+  }
+  const tableIdsRaw = await Promise.resolve(docApi.listTables());
+  const tableIds = Array.isArray(tableIdsRaw) ? [...tableIdsRaw] : [];
+  const tables = {};
+  for (const tableId of tableIds) {
+    const omitData = !includeSystemTableData && tableId.startsWith("_grist");
+    if (omitData) {
+      tables[tableId] = {
+        rowCount: 0,
+        dataOmitted: true,
+        dataOmittedReason: "Row scan skipped for tables whose id starts with `_grist` unless `includeSystemTableData` is true.",
+        columns: {}
+      };
+      continue;
+    }
+    try {
+      const data = await docApi.fetchTable(tableId);
+      const rowCount = computeRowCount(data);
+      const colMeta = metaByTable.get(tableId) ?? /* @__PURE__ */ new Map();
+      const columnIds = orderedColumnIds(data, colMeta);
+      const columns = buildReplicaColumnsFromColumnar(data, colMeta);
+      const table = { columns, rowCount };
+      if (includeRows === "full") {
+        table.rows = decodeColumnarToReplicaRows(data, columnIds, columns);
+      } else if (includeRows === "samples") {
+        table.rows = decodeColumnarToReplicaRows(data, columnIds, columns, sampleRowLimit);
+      }
+      tables[tableId] = table;
+    } catch (err) {
+      tables[tableId] = {
+        rowCount: 0,
+        error: err instanceof Error ? err.message : String(err),
+        columns: {}
+      };
+    }
+  }
+  const out = {
+    generatedAt: (/* @__PURE__ */ new Date()).toISOString(),
+    docName,
+    mode: rowMode,
+    tables
+  };
+  if (options?.source !== void 0 && options.source !== "") {
+    out.source = options.source;
+  }
+  return out;
+}
+
+// src/sdk/helpers/grist-columns-filters.ts
+var NOISE_COLUMN_FORMULAS = /* @__PURE__ */ new Set(["now()"]);
+function normalizeFormulaForComparison(formula) {
+  return formula.trim().toLowerCase().replace(/\s+/g, "");
+}
+function isGristNoiseColumn(colId, col, options) {
+  const excludeId = options?.excludeId ?? true;
+  const excludeGristHelpers = options?.excludeGristHelpers ?? true;
+  const excludeLoggingColumns = options?.excludeLoggingColumns ?? true;
+  const excludeManualSort = options?.excludeManualSort ?? false;
+  if (excludeId && colId === "id") return true;
+  if (excludeManualSort && colId === "manualSort") return true;
+  if (excludeGristHelpers && colId.startsWith("gristHelper_")) return true;
+  if (excludeLoggingColumns) {
+    const formula = typeof col?.formula === "string" ? normalizeFormulaForComparison(col.formula) : "";
+    if (formula && NOISE_COLUMN_FORMULAS.has(formula)) return true;
+    if (formula.startsWith("user.")) return true;
+  }
+  return false;
+}
+
+// src/sdk/runtime/api.ts
+var ACCESS_ERROR = [/access not granted/i, /need higher access level/i, /requires.*full.*access/i, /RPC_ONCALL_ERROR Access/i];
+function isAccessInsufficientError(message2) {
+  return ACCESS_ERROR.some((re) => re.test(message2));
+}
+var message = (err) => err instanceof Error ? err.message : String(err);
+function createGristApi(runtime) {
+  const docApi = () => {
+    if (runtime.getState().connection !== "ready" || typeof grist === "undefined" || !grist.docApi) {
+      throw new Error('Grist is not ready: wait for useGrist().status === "ready".');
+    }
+    return grist.docApi;
+  };
+  const read = async (fn) => {
+    try {
+      const out = await fn();
+      if (runtime.getState().readError) runtime.update({ readError: null });
+      return out;
+    } catch (err) {
+      if (isAccessInsufficientError(message(err))) runtime.update({ readError: message(err) });
+      throw err;
+    }
+  };
+  const write = async (fn) => {
+    runtime.update({ actionStatus: "running", actionError: null });
+    try {
+      const out = await fn();
+      runtime.update({ actionStatus: "idle" });
+      return out;
+    } catch (err) {
+      runtime.update({ actionStatus: "error", actionError: message(err) });
+      throw err;
+    }
+  };
+  const tableOps = (resolve) => ({
+    getTableId: () => resolve().getTableId(),
+    create: ((records, opts) => write(() => resolve().create(records, opts))),
+    update: (records, opts) => write(() => resolve().update(records, opts)),
+    upsert: (records, opts) => write(() => resolve().upsert(records, opts)),
+    destroy: (ids) => write(() => resolve().destroy(ids))
+  });
+  const tables = /* @__PURE__ */ new Map();
+  return {
+    reload: () => runtime.reload(),
+    fetchSelectedTable: (options) => read(async () => {
+      const impl = docApi().fetchSelectedTable ?? grist.fetchSelectedTable;
+      if (!impl) throw new Error("fetchSelectedTable is not available in this Grist version");
+      return await impl({ keepEncoded: false, ...options });
+    }),
+    fetchTable: (tableId) => read(async () => await docApi().fetchTable(tableId)),
+    fetchTableRows: (tableId, options) => read(() => fetchGristTableRows(docApi(), tableId, options ?? {})),
+    listTables: (options) => read(async () => {
+      const all = [...await docApi().listTables()];
+      return options?.includeSystem ? all : all.filter((t) => !t.startsWith("_grist") && !t.startsWith("GristHidden_"));
+    }),
+    listColumns: (tableId, options) => read(async () => {
+      const meta = (await loadColumnMetadataByTable(docApi())).get(tableId);
+      if (!meta) return [];
+      const noise = {
+        excludeId: options?.excludeId ?? true,
+        excludeGristHelpers: options?.excludeGristHelpers ?? true,
+        excludeLoggingColumns: options?.excludeLoggingColumns ?? true,
+        excludeManualSort: options?.excludeManualSort ?? true
+      };
+      return [...meta].filter(([colId, m]) => options?.includeSystem || !isGristNoiseColumn(colId, m, noise)).map(([colId, m]) => ({ colId, type: m.type, label: m.label, isFormula: m.isFormula, formula: m.formula, description: m.description }));
+    }),
+    table: tableOps(() => {
+      if (!grist.selectedTable) throw new Error("grist.selectedTable is not available in this Grist version");
+      return grist.selectedTable;
+    }),
+    getTable: (tableId) => {
+      let ops = tables.get(tableId);
+      if (!ops) {
+        tables.set(
+          tableId,
+          ops = tableOps(() => {
+            if (typeof grist.getTable !== "function") throw new Error("grist.getTable is not available in this Grist version");
+            return grist.getTable(tableId);
+          })
+        );
+      }
+      return ops;
+    },
+    applyActions: (actions, options) => write(() => docApi().applyUserActions(actions, options)),
+    setWidgetOptions: async (options) => {
+      await grist.setOptions(options);
+    },
+    patchWidgetOptions: async (patch) => {
+      const current = await grist.getOptions() ?? {};
+      await grist.setOptions({ ...current, ...patch });
+    },
+    setCursorPosition: async (pos) => {
+      if (!grist.setCursorPos) throw new Error("setCursorPos is not available in this Grist version");
+      await grist.setCursorPos(pos);
+    },
+    setLinkedRowSelection: async (rowIds) => {
+      if (!grist.setSelectedRows) throw new Error("setSelectedRows is not available in this Grist version");
+      await grist.setSelectedRows(rowIds);
+    },
+    getAttachmentUrl: (id, options) => read(() => getAttachmentDownloadUrl(docApi(), id, options)),
+    fetchAttachmentBlob: (id, options) => read(() => fetchAttachmentBlob(docApi(), id, options)),
+    uploadAttachment: (file, options) => write(() => uploadGristAttachment(docApi(), file, options)),
+    fetchWithAuth: (path, init) => read(() => fetchWithGristAuth(docApi(), path, init))
+  };
+}
+
+// src/sdk/helpers/grist-mappings.ts
+function asColumnSpec(entry) {
+  return typeof entry === "string" ? { name: entry } : entry;
+}
+function validateColumnMappings(spec, mappings) {
+  const missing = [];
+  const emptyMultiples = [];
+  if (!spec) return { ok: true, pending: false, missing, emptyMultiples };
+  const m = mappings ?? {};
+  for (const raw of spec) {
+    const col = asColumnSpec(raw);
+    if (col.optional) continue;
+    const value = m[col.name];
+    if (col.allowMultiple) {
+      if (value === void 0) {
+        missing.push(col.name);
+      } else if (!Array.isArray(value) || value.length === 0) {
+        emptyMultiples.push(col.name);
+      }
+    } else {
+      if (value === void 0 || value === null || value === "") missing.push(col.name);
+    }
+  }
+  return {
+    ok: missing.length === 0 && emptyMultiples.length === 0,
+    pending: false,
+    missing,
+    emptyMultiples
+  };
+}
+
+// src/sdk/runtime/derive.ts
+var ACCESS_RANK = { none: 0, "read table": 1, full: 2 };
+function parseAccess(raw) {
+  return raw === "none" || raw === "read table" || raw === "full" ? raw : null;
+}
+function accessLabel(level) {
+  return level === "full" ? "Full document access" : level === "read table" ? "Read selected table" : "No document access";
+}
+function accessDenied(state) {
+  return state.grantedAccess !== null && ACCESS_RANK[state.grantedAccess] < ACCESS_RANK[state.declaredAccess];
+}
+function deriveStatus(state) {
+  switch (state.connection) {
+    case "connecting":
+      return "booting";
+    case "not-embedded":
+    case "unavailable":
+      return "unavailable";
+    case "error":
+      return "error";
+    case "ready":
+      return accessDenied(state) ? "error" : "ready";
+  }
+}
+function deriveError(state) {
+  if (state.connection === "not-embedded") return "This page is not embedded in a Grist document.";
+  if (state.connection === "unavailable") return "The Grist plugin API (grist-plugin-api.js) did not load.";
+  if (state.connection === "error") return state.connectionError;
+  if (state.connection === "ready" && accessDenied(state)) {
+    return `Grist granted "${accessLabel(state.grantedAccess)}"; this widget needs "${accessLabel(state.declaredAccess)}". Set the access level in the Custom widget settings.`;
+  }
+  return null;
+}
+var MAPPINGS_OK = Object.freeze({ ok: true, pending: false, missing: [], emptyMultiples: [] });
+var MAPPINGS_PENDING = Object.freeze({ ok: true, pending: true, missing: [], emptyMultiples: [] });
+function deriveColumnMappingStatus(columns, mappings) {
+  if (!columns?.length) return MAPPINGS_OK;
+  if (mappings === null) return MAPPINGS_PENDING;
+  return validateColumnMappings(columns, mappings);
+}
+function mapBackPatch(patch, mappings) {
+  const fields = {};
+  const skipped = [];
+  for (const [name, value] of Object.entries(patch)) {
+    if (value === void 0) continue;
+    const real = mappings[name];
+    if (Array.isArray(real)) skipped.push(name);
+    else fields[typeof real === "string" && real ? real : name] = value;
+  }
+  return { fields, skipped };
+}
+
+// src/sdk/helpers/grist-widget-interaction.ts
+function parseGristWidgetLinkingInfo(raw) {
+  if (!raw || typeof raw !== "object" || !("asTarget" in raw)) return void 0;
+  const linking = raw;
+  return {
+    asTarget: linking.asTarget == null ? null : String(linking.asTarget),
+    asSource: Boolean(linking.asSource)
+  };
+}
+function normalizeWidgetInteraction(interaction) {
+  if (!interaction || typeof interaction !== "object") return interaction;
+  const raw = interaction;
+  const access_level = typeof raw.access_level === "string" ? raw.access_level : typeof raw.accessLevel === "string" ? raw.accessLevel : void 0;
+  const linking = parseGristWidgetLinkingInfo(raw.linking);
+  return {
+    ...interaction,
+    ...access_level ? { access_level } : {},
+    ...linking ? { linking } : {}
+  };
+}
+
+// src/sdk/runtime/host.ts
+var HostStream = class {
+  constructor(bind) {
+    this.bind = bind;
+    this.listeners = /* @__PURE__ */ new Set();
+    this.bound = false;
+    this.has = false;
+  }
+  subscribe(listener) {
+    this.listeners.add(listener);
+    if (!this.bound) {
+      this.bound = true;
+      try {
+        this.bind((value) => this.emit(value));
+      } catch (err) {
+        console.error("[grist-widget-sdk] could not subscribe to a Grist event:", err);
+      }
+    }
+    if (this.has) listener(this.last);
+    return () => {
+      this.listeners.delete(listener);
+    };
+  }
+  peek() {
+    return this.last;
+  }
+  /** Tests: deliver a value as if Grist had sent it. */
+  emit(value) {
+    this.has = true;
+    this.last = value;
+    for (const l of [...this.listeners]) l(value);
+  }
+  /** Tests: forget the binding, so a new `window.grist` binds afresh. */
+  reset() {
+    this.listeners.clear();
+    this.bound = false;
+    this.has = false;
+    this.last = void 0;
+  }
+};
+var asMappings = (m) => m && typeof m === "object" ? m : null;
+var recordStream = new HostStream((emit) => {
+  grist.onRecord((record, mappings) => emit({ record, mappings: asMappings(mappings) }), { keepEncoded: false });
+  const fetchSelectedRecord = grist.fetchSelectedRecord ?? grist.docApi?.fetchSelectedRecord;
+  if (typeof grist.on !== "function" || typeof fetchSelectedRecord !== "function") return;
+  let lastRowId;
+  grist.on("message", async (msg) => {
+    const host = msg;
+    if (!host?.tableId || typeof host.rowId !== "number" || host.rowId === lastRowId) return;
+    lastRowId = host.rowId;
+    try {
+      const record = await fetchSelectedRecord(host.rowId, { keepEncoded: false });
+      emit({ record, mappings: recordStream.peek()?.mappings ?? null });
+    } catch (err) {
+      console.error("[grist-widget-sdk] fetchSelectedRecord on a cursor move failed:", err);
+    }
+  });
+});
+var recordsStream = new HostStream((emit) => {
+  grist.onRecords((records, mappings) => emit({ records, mappings: asMappings(mappings) }), {
+    keepEncoded: false,
+    format: "rows"
+  });
+});
+var optionsStream = new HostStream((emit) => {
+  grist.onOptions(
+    (options, interaction) => emit({
+      options: options ? { ...options } : null,
+      interaction: normalizeWidgetInteraction(interaction ?? null)
+    })
+  );
+});
+var newRecordStream = new HostStream((emit) => {
+  if (typeof grist.onNewRecord !== "function") return;
+  grist.onNewRecord((mappings) => emit({ mappings: asMappings(mappings) }));
+});
+var messageStream = new HostStream((emit) => {
+  if (typeof grist.on !== "function") return;
+  grist.on("message", (msg) => emit(msg));
+});
+var ALL_STREAMS = [recordStream, recordsStream, optionsStream, newRecordStream, messageStream];
+
+// src/sdk/runtime/ready.ts
+var ACCESS_RANK2 = {
+  none: 0,
+  "read table": 1,
+  full: 2
+};
+var inFlight2 = null;
+var lastAccess = null;
+var lastColumnNames = null;
+function columnNamesOf(columns) {
+  return new Set((columns ?? []).map((c) => typeof c === "string" ? c : c.name));
+}
+function shouldReinit(next, nextColumns) {
+  if (!lastAccess) return true;
+  if (ACCESS_RANK2[next] > ACCESS_RANK2[lastAccess]) return true;
+  for (const name of nextColumns) {
+    if (!lastColumnNames?.has(name)) return true;
+  }
+  return false;
+}
+function ensureGristReady(payload) {
+  const access = payload.requiredAccess ?? "read table";
+  const columns = columnNamesOf(payload.columns);
+  if (inFlight2 && !shouldReinit(access, columns)) return inFlight2;
+  lastAccess = access;
+  lastColumnNames = columns;
+  const next = Promise.resolve().then(() => {
+    const result = grist.ready(payload);
+    return result instanceof Promise ? result : Promise.resolve();
+  });
+  inFlight2 = next.catch((err) => {
+    inFlight2 = null;
+    lastAccess = null;
+    lastColumnNames = null;
+    throw err;
+  });
+  return inFlight2;
+}
+function resetGristReady() {
+  inFlight2 = null;
+  lastAccess = null;
+  lastColumnNames = null;
+}
+
+// src/sdk/helpers/grist-theme-payload.ts
+function parseGristThemePayload(payload) {
+  if (!payload || typeof payload !== "object") return null;
+  const raw = payload;
+  const top = raw.theme;
+  if (top === "light" || top === "dark") return top;
+  if (top && typeof top === "object") {
+    const appearance = top.appearance;
+    if (appearance === "light" || appearance === "dark") return appearance;
+  }
+  return null;
+}
+
+// src/sdk/runtime/runtime.ts
+var READY_TIMEOUT_MS = 3e4;
+function initialRuntimeState(options = {}) {
+  return {
+    connection: "connecting",
+    connectionError: null,
+    declaredAccess: options.requiredAccess ?? "read table",
+    grantedAccess: null,
+    record: null,
+    records: null,
+    isNewRecord: false,
+    mappings: null,
+    widgetOptions: null,
+    interaction: null,
+    currentTableId: null,
+    theme: null,
+    actionStatus: "idle",
+    actionError: null,
+    readError: null,
+    mapBackSkipped: []
+  };
+}
+function isEmbedded() {
+  try {
+    return typeof window !== "undefined" && window.self !== window.top;
+  } catch {
+    return true;
+  }
+}
+var hasGrist = () => typeof grist !== "undefined" && grist !== null;
+function createGristRuntime(options = {}) {
+  let state = initialRuntimeState(options);
+  const listeners = /* @__PURE__ */ new Set();
+  let starts = 0;
+  let stopStreams = null;
+  let attempt = 0;
+  const update = (patch) => {
+    let changed = false;
+    for (const key of Object.keys(patch)) {
+      if (!Object.is(state[key], patch[key])) changed = true;
+    }
+    if (!changed) return;
+    state = { ...state, ...patch };
+    for (const l of [...listeners]) l();
+  };
+  const payload = {
+    requiredAccess: options.requiredAccess ?? "read table",
+    columns: options.columns ?? [],
+    ...options.allowSelectBy !== void 0 ? { allowSelectBy: options.allowSelectBy } : {},
+    ...options.hasCustomOptions !== void 0 ? { hasCustomOptions: options.hasCustomOptions } : {},
+    ...options.onEditOptions ? { onEditOptions: options.onEditOptions } : {}
+  };
+  const refreshTable = async () => {
+    try {
+      const tableId = await grist.selectedTable?.getTableId();
+      if (tableId) update({ currentTableId: tableId });
+    } catch {
+    }
+  };
+  const refreshMappings = async () => {
+    if (typeof grist.sectionApi?.mappings !== "function") return;
+    try {
+      const mappings = await grist.sectionApi.mappings();
+      if (state.mappings === null) update({ mappings: mappings ?? {} });
+    } catch {
+    }
+  };
+  const connect = async () => {
+    const mine = ++attempt;
+    update({ connection: "connecting", connectionError: null });
+    let timer;
+    try {
+      await Promise.race([
+        ensureGristReady(payload),
+        new Promise((_, reject) => {
+          timer = setTimeout(() => reject(new Error(`Grist did not answer grist.ready() within ${READY_TIMEOUT_MS / 1e3} s.`)), READY_TIMEOUT_MS);
+        })
+      ]);
+    } catch (err) {
+      if (mine === attempt) update({ connection: "error", connectionError: err instanceof Error ? err.message : String(err) });
+      return;
+    } finally {
+      clearTimeout(timer);
+    }
+    if (mine !== attempt) return;
+    update({ connection: "ready" });
+    await Promise.all([refreshMappings(), refreshTable()]);
+  };
+  const listen = () => {
+    const offs = [
+      // Copies: a host may reuse one record object and mutate it in place.
+      recordStream.subscribe(
+        ({ record, mappings }) => update({
+          record: record ? { ...record } : null,
+          isNewRecord: false,
+          ...mappings ? { mappings } : {}
+        })
+      ),
+      recordsStream.subscribe(({ records, mappings }) => {
+        update({ records: records.map((r) => ({ ...r })), ...mappings ? { mappings } : {} });
+        void refreshTable();
+      }),
+      optionsStream.subscribe(
+        ({ options: widgetOptions, interaction }) => update({
+          widgetOptions,
+          interaction,
+          grantedAccess: parseAccess(interaction?.access_level) ?? state.grantedAccess
+        })
+      ),
+      newRecordStream.subscribe(({ mappings }) => update({ isNewRecord: true, ...mappings ? { mappings } : {} })),
+      messageStream.subscribe((msg) => {
+        const theme = parseGristThemePayload(msg);
+        if (theme) update({ theme });
+      })
+    ];
+    return () => offs.forEach((off) => off());
+  };
+  const begin = () => {
+    if (!isEmbedded()) return update({ connection: "not-embedded" });
+    if (!hasGrist()) {
+      if (typeof document !== "undefined" && document.readyState !== "complete" && typeof window !== "undefined") {
+        window.addEventListener("load", () => hasGrist() ? begin() : update({ connection: "unavailable" }), { once: true });
+        return;
+      }
+      return update({ connection: "unavailable" });
+    }
+    stopStreams ?? (stopStreams = listen());
+    void connect();
+  };
+  return {
+    options,
+    getState: () => state,
+    subscribe(listener) {
+      listeners.add(listener);
+      return () => listeners.delete(listener);
+    },
+    start() {
+      if (starts++ === 0) begin();
+      return () => {
+        if (--starts > 0) return;
+        stopStreams?.();
+        stopStreams = null;
+      };
+    },
+    async reload() {
+      if (!hasGrist() || !isEmbedded()) return begin();
+      resetGristReady();
+      update({ mappings: null });
+      stopStreams ?? (stopStreams = listen());
+      await connect();
+    },
+    update
+  };
+}
+
+// src/sdk/use-grist.ts
+var GristContext = createContext(null);
+GristContext.displayName = "GristContext";
+function useGristRuntime() {
+  return useContext(GristContext);
+}
+function newConnection(options) {
+  const runtime = createGristRuntime(options);
+  return { runtime, api: createGristApi(runtime) };
+}
+var pageConnection = null;
+function resetGristForTests() {
+  pageConnection = null;
+  resetGristReady();
+  for (const s of ALL_STREAMS) s.reset();
+}
+var GristContextProvider = GristContext.Provider;
+var serverState = () => initialRuntimeState();
+function useGristState(connection) {
+  const { runtime } = connection;
+  useEffect(() => runtime.start(), [runtime]);
+  return useSyncExternalStore(runtime.subscribe, runtime.getState, serverState);
+}
+var NO_ISSUES = Object.freeze([]);
+function useMapped(state, options) {
+  const { record, records, mappings } = state;
+  const { columns, schema } = options;
+  return useMemo(() => {
+    const issues = [];
+    const rows = records && (columns?.length ? mappings !== null : true) ? records.map((r) => {
+      const out = mapAndCheck(r, columns, mappings, schema);
+      issues.push(...out.issues);
+      return out.value;
+    }) : null;
+    const selected = mapAndCheck(record, columns, mappings, schema);
+    if (record && !records?.some((r) => r.id === record.id)) issues.push(...selected.issues);
+    const mappedRecords = rows && rows.every((r) => r !== null) ? rows : null;
+    return { record: selected.value, records: mappedRecords, issues: issues.length ? issues : NO_ISSUES };
+  }, [record, records, mappings, columns, schema]);
+}
+function buildResult(state, mapped, connection, mapBack, resolveMappedColumnId) {
+  const { runtime, api } = connection;
+  const status = deriveStatus(state);
+  const columns = runtime.options.columns;
+  return {
+    ...api,
+    status,
+    isAvailable: state.connection === "connecting" ? null : state.connection !== "not-embedded" && state.connection !== "unavailable",
+    isReady: status === "ready",
+    error: deriveError(state),
+    theme: state.theme,
+    record: state.record,
+    records: state.records,
+    mappedRecord: mapped.record,
+    mappedRecords: mapped.records,
+    cellIssues: mapped.issues,
+    mappings: state.mappings ?? EMPTY_MAPPINGS,
+    columnMappingStatus: deriveColumnMappingStatus(columns, state.mappings),
+    mode: state.isNewRecord ? "new-row" : state.record ? "row" : "empty",
+    resolveMappedColumnId,
+    mapBack,
+    currentTableId: state.currentTableId,
+    actionStatus: state.actionStatus,
+    actionError: state.actionError,
+    widgetOptions: state.widgetOptions
+  };
+}
+var EMPTY_MAPPINGS = Object.freeze({});
+function useGristResult(connection) {
+  const state = useGristState(connection);
+  const mappings = state.mappings ?? EMPTY_MAPPINGS;
+  const { runtime } = connection;
+  const resolveMappedColumnId = useCallback(
+    (name) => {
+      const real = mappings[name];
+      if (typeof real === "string" && real) return real;
+      if (Array.isArray(real) && typeof real[0] === "string") return real[0];
+      return name;
+    },
+    [mappings]
+  );
+  const mapBack = useCallback(
+    (patch) => {
+      const { fields, skipped } = mapBackPatch(patch, mappings);
+      const previous = runtime.getState().mapBackSkipped;
+      if (previous.join("\0") !== skipped.join("\0")) runtime.update({ mapBackSkipped: skipped });
+      return fields;
+    },
+    [mappings, runtime]
+  );
+  const mapped = useMapped(state, runtime.options);
+  return useMemo(
+    () => buildResult(state, mapped, connection, mapBack, resolveMappedColumnId),
+    [state, mapped, connection, mapBack, resolveMappedColumnId]
+  );
+}
+function useGrist(options) {
+  const fromProvider = useContext(GristContext);
+  const connection = fromProvider ?? (pageConnection ?? (pageConnection = newConnection(options)));
+  return useGristResult(connection);
+}
+function useGristOptional() {
+  const fromProvider = useContext(GristContext);
+  const result = useGristResult(fromProvider ?? DETACHED);
+  return fromProvider ? result : null;
+}
+function useGristContext() {
+  if (!useContext(GristContext)) {
+    throw new Error("useGristContext() must be used inside <GristWidgetProvider> (mountGristWidget renders one).");
+  }
+  return useGrist();
+}
+var DETACHED = (() => {
+  const state = initialRuntimeState();
+  const runtime = {
+    options: {},
+    getState: () => state,
+    subscribe: () => () => {
+    },
+    start: () => () => {
+    },
+    reload: async () => {
+    },
+    update: () => {
+    }
+  };
+  return { runtime, api: createGristApi(runtime) };
+})();
+function useNearestGristState() {
+  const connection = useContext(GristContext);
+  const state = useGristState(connection ?? DETACHED);
+  const { issues } = useMapped(state, (connection ?? DETACHED).runtime.options);
+  return { connection, state, cellIssues: issues };
+}
+
+// src/sdk/components/grist-widget-provider.tsx
+import { useState } from "react";
+import { jsx } from "react/jsx-runtime";
+function GristWidgetProvider({ options, children }) {
+  const [connection] = useState(() => newConnection(options));
+  return /* @__PURE__ */ jsx(GristContextProvider, { value: connection, children });
+}
+
+// src/sdk/components/grist-boundary.tsx
+import { useCallback as useCallback2, useState as useState2 } from "react";
+import { Fragment, jsx as jsx2, jsxs } from "react/jsx-runtime";
+var shellStyle = {
+  alignItems: "center",
+  background: "var(--background)",
+  boxSizing: "border-box",
+  color: "var(--foreground)",
+  display: "flex",
+  flexDirection: "column",
+  justifyContent: "center",
+  minHeight: "100%",
+  padding: "clamp(16px, 5vh, 32px)",
+  width: "100%"
+};
+var cardStyle = {
+  background: "var(--card)",
+  border: "1px solid var(--border)",
+  borderRadius: 12,
+  boxShadow: "0 1px 3px rgb(0 0 0 / 0.12)",
+  maxWidth: 420,
+  padding: "20px 22px",
+  textAlign: "center",
+  width: "100%"
+};
+var titleStyle = {
+  color: "var(--foreground)",
+  fontSize: 15,
+  fontWeight: 600,
+  lineHeight: 1.35,
+  margin: 0
+};
+var messageStyle = {
+  color: "var(--muted-foreground)",
+  fontSize: 14,
+  lineHeight: 1.5,
+  margin: "10px 0 0"
+};
+var buttonStyle = {
+  background: "var(--background)",
+  border: "1px solid var(--border)",
+  borderRadius: 8,
+  color: "var(--foreground)",
+  cursor: "pointer",
+  fontSize: 13,
+  fontWeight: 500,
+  marginTop: 16,
+  padding: "8px 14px"
+};
+function GristBoundaryScreen({
+  title,
+  message: message2,
+  tone = "default",
+  showRetry = false,
+  actions,
+  retryLabel = "Try reconnecting",
+  retryBusyLabel = "Reconnecting\u2026"
+}) {
+  return /* @__PURE__ */ jsx2("div", { style: shellStyle, role: tone === "error" ? "alert" : "status", children: /* @__PURE__ */ jsxs("div", { style: cardStyle, children: [
+    /* @__PURE__ */ jsx2("h2", { style: titleStyle, children: title }),
+    /* @__PURE__ */ jsx2("p", { style: messageStyle, children: message2 }),
+    showRetry && actions ? /* @__PURE__ */ jsx2(
+      "button",
+      {
+        disabled: actions.isReloading,
+        onClick: () => void actions.reload(),
+        style: {
+          ...buttonStyle,
+          cursor: actions.isReloading ? "not-allowed" : "pointer",
+          opacity: actions.isReloading ? 0.7 : 1
+        },
+        type: "button",
+        children: actions.isReloading ? retryBusyLabel : retryLabel
+      }
+    ) : null
+  ] }) });
+}
+function boundaryScreen(state, columns) {
+  switch (state.connection) {
+    case "connecting":
+      return { title: "Connecting to Grist", message: "Asking Grist for the access this widget needs\u2026" };
+    case "not-embedded":
+      return {
+        title: "Open inside Grist",
+        message: "Open this page as a custom widget inside a Grist document (it runs in an embedded panel, not on its own).",
+        retry: true
+      };
+    case "unavailable":
+      return {
+        title: "Open inside Grist",
+        message: "The Grist plugin did not load. Reload the page, or open this URL as a custom widget inside a Grist document.",
+        retry: true
+      };
+    case "error":
+      return {
+        title: "Something went wrong",
+        message: state.connectionError ?? "Something went wrong connecting to Grist. Try again, or reload the page.",
+        tone: "error",
+        retry: true
+      };
+  }
+  if (accessDenied(state)) {
+    return {
+      title: "More access needed",
+      message: `Set Access level to at least "${accessLabel(state.declaredAccess)}" in the Custom widget settings.`,
+      tone: "error",
+      retry: true
+    };
+  }
+  const mapping = deriveColumnMappingStatus(columns, state.mappings);
+  if (mapping.pending) return { title: "Connecting to Grist", message: "Waiting for Grist to report the column mapping\u2026" };
+  if (!mapping.ok) {
+    return {
+      title: "Map your columns",
+      message: "Open the widget settings in Grist (Creator Panel \u2192 Custom widget) and connect each required column to your table."
+    };
+  }
+  return null;
+}
+function GristBoundary({ children }) {
+  const connection = useGristRuntime();
+  if (!connection) throw new Error("<GristBoundary> must be used inside <GristWidgetProvider> (mountGristWidget renders both).");
+  const state = useGristState(connection);
+  const [isReloading, setIsReloading] = useState2(false);
+  const reload = useCallback2(async () => {
+    setIsReloading(true);
+    try {
+      await connection.runtime.reload();
+    } catch (err) {
+      console.error("[grist-widget-sdk] reload failed:", err);
+    } finally {
+      setIsReloading(false);
+    }
+  }, [connection]);
+  const screen = boundaryScreen(state, connection.runtime.options.columns);
+  if (!screen) return /* @__PURE__ */ jsx2(Fragment, { children });
+  return /* @__PURE__ */ jsx2(
+    GristBoundaryScreen,
+    {
+      title: screen.title,
+      message: screen.message,
+      tone: screen.tone,
+      showRetry: screen.retry,
+      actions: { reload, isReloading },
+      retryLabel: screen.tone === "error" ? "Try again" : "Try reconnecting",
+      retryBusyLabel: screen.tone === "error" ? "Retrying\u2026" : "Reconnecting\u2026"
+    }
+  );
+}
+
+// src/sdk/use-grist-schema.ts
+import { useCallback as useCallback3, useEffect as useEffect2, useMemo as useMemo2, useState as useState3 } from "react";
+function filterReplicaDocumentColumns(document2, options, extraExcludeColumn) {
+  return {
+    ...document2,
+    tables: Object.fromEntries(
+      Object.entries(document2.tables).map(([tableId, table]) => [
+        tableId,
+        {
+          ...table,
+          columns: Object.fromEntries(
+            Object.entries(table.columns ?? {}).filter(([colId, col]) => {
+              if (isGristNoiseColumn(colId, col, options)) return false;
+              if (extraExcludeColumn?.({ tableId, colId, col })) return false;
+              return true;
+            })
+          )
+        }
+      ])
+    )
+  };
+}
+function useGristSchema(options) {
+  const requiredAccess = options?.requiredAccess ?? "read table";
+  const requestedTableId = options?.tableId;
+  const excludeSystemTableData = options?.excludeSystemTableData ?? true;
+  const replicaRowMode = options?.replicaRowMode ?? "schema+samples";
+  const sampleRowLimit = options?.sampleRowLimit ?? 10;
+  const replicaSource = options?.source;
+  const excludeId = options?.excludeId ?? true;
+  const excludeGristHelpers = options?.excludeGristHelpers ?? true;
+  const excludeLoggingColumns = options?.excludeLoggingColumns ?? true;
+  const excludeManualSort = options?.excludeManualSort ?? false;
+  const extraExcludeColumn = options?.extraExcludeColumn;
+  const w = useGrist({
+    requiredAccess,
+    columns: options?.columns,
+    allowSelectBy: options?.allowSelectBy,
+    hasCustomOptions: options?.hasCustomOptions,
+    onEditOptions: options?.onEditOptions
+  });
+  const connection = useGristRuntime();
+  const isAvailable = w.isAvailable;
+  const readyError = w.status === "error" || w.status === "unavailable" ? w.error : null;
+  const docApi = w.isReady && typeof grist !== "undefined" ? grist.docApi ?? null : null;
+  const [document2, setDocument] = useState3(null);
+  const [loading, setLoading] = useState3(false);
+  const [error, setError] = useState3(null);
+  const includeRowsForBuild = replicaRowMode === "schema-only" ? false : replicaRowMode === "schema+data" ? "full" : "samples";
+  const load = useCallback3(async () => {
+    if (!docApi) return;
+    setLoading(true);
+    setError(null);
+    try {
+      const buildOpts = {
+        includeSystemTableData: !excludeSystemTableData,
+        includeRows: includeRowsForBuild,
+        sampleRowLimit,
+        source: replicaSource
+      };
+      const raw = await buildReplicaDocumentFromDocApi(docApi, buildOpts);
+      const filtered = filterReplicaDocumentColumns(
+        raw,
+        {
+          excludeId,
+          excludeGristHelpers,
+          excludeLoggingColumns,
+          excludeManualSort
+        },
+        extraExcludeColumn
+      );
+      setDocument(filtered);
+    } catch (err) {
+      const message2 = err instanceof Error ? err.message : String(err);
+      setDocument(null);
+      setError(message2);
+      if (isAccessInsufficientError(message2)) connection?.runtime.update({ readError: message2 });
+    } finally {
+      setLoading(false);
+    }
+  }, [
+    docApi,
+    connection,
+    excludeSystemTableData,
+    replicaRowMode,
+    sampleRowLimit,
+    excludeId,
+    excludeGristHelpers,
+    excludeLoggingColumns,
+    excludeManualSort,
+    extraExcludeColumn,
+    replicaSource
+  ]);
+  useEffect2(() => {
+    if (docApi) void load();
+  }, [docApi, load]);
+  const buildDocumentJson = useCallback3((target, options2) => {
+    const includeRows = options2?.includeRows ?? "full";
+    const space = options2?.space ?? 2;
+    const payload = buildReplicaJsonPayload(target, {
+      includeRows,
+      sampleRowLimit: options2?.sampleRowLimit ?? sampleRowLimit
+    });
+    return JSON.stringify(payload, null, space);
+  }, [sampleRowLimit]);
+  const getDocumentJson = useCallback3(
+    (options2) => {
+      if (!document2) return null;
+      return buildDocumentJson(document2, options2);
+    },
+    [document2, buildDocumentJson]
+  );
+  const table = useMemo2(() => {
+    if (!document2 || !requestedTableId) return null;
+    const slice = document2.tables[requestedTableId];
+    if (!slice) return null;
+    return { tableId: requestedTableId, ...slice };
+  }, [document2, requestedTableId]);
+  const buildTableJson = useCallback3(
+    (target, options2) => {
+      const includeRows = options2?.includeRows ?? "full";
+      const limit = options2?.sampleRowLimit ?? sampleRowLimit;
+      const space = options2?.space ?? 2;
+      const { tableId, ...rest } = target;
+      let body = { ...rest };
+      if (includeRows === "none") {
+        const { rows: _r, ...r } = body;
+        body = r;
+      } else if (includeRows === "samples") {
+        const r = body.rows ?? [];
+        body = { ...body, rows: r.slice(0, limit) };
+      }
+      return JSON.stringify({ tableId, ...body }, null, space);
+    },
+    [sampleRowLimit]
+  );
+  const getTableJson = useCallback3(
+    (options2) => {
+      if (!table) return null;
+      return buildTableJson(table, options2);
+    },
+    [table, buildTableJson]
+  );
+  const noiseColumnMatcher = useCallback3(
+    (colId, col) => isGristNoiseColumn(colId, col, {
+      excludeId,
+      excludeGristHelpers,
+      excludeLoggingColumns,
+      excludeManualSort
+    }),
+    [excludeId, excludeGristHelpers, excludeLoggingColumns, excludeManualSort]
+  );
+  const sortColumns = useCallback3((colIds, columns) => {
+    return [...colIds].sort((a, b) => {
+      const la = (columns[a]?.label || a).toLowerCase();
+      const lb = (columns[b]?.label || b).toLowerCase();
+      if (la !== lb) return la.localeCompare(lb);
+      return a.localeCompare(b);
+    });
+  }, []);
+  return {
+    isAvailable,
+    document: document2,
+    replicaDocument: document2,
+    table,
+    documentJson: document2 ? buildDocumentJson(document2) : null,
+    getDocumentJson,
+    buildDocumentJson,
+    tableJson: table ? buildTableJson(table) : null,
+    getTableJson,
+    buildTableJson,
+    isNoiseColumnId: noiseColumnMatcher,
+    sortColumnIds: sortColumns,
+    loading,
+    error: readyError ?? error,
+    reload: load
+  };
+}
+
+// src/sdk/use-widget-metadata.ts
+import { useEffect as useEffect3 } from "react";
+function useWidgetMetadata(input) {
+  useEffect3(() => {
+    if (!input) return;
+    const { title, description } = input;
+    const canonicalUrl = window.location.href;
+    document.title = title;
+    setMetaTag("name", "title", title);
+    setMetaTag("name", "description", description);
+    setMetaTag("property", "og:title", title);
+    setMetaTag("property", "og:description", description);
+    setMetaTag("property", "og:type", "website");
+    setMetaTag("property", "og:url", canonicalUrl);
+    setMetaTag("name", "twitter:card", "summary");
+    setMetaTag("name", "twitter:title", title);
+    setMetaTag("name", "twitter:description", description);
+  }, [input]);
+}
+function setMetaTag(key, value, content) {
+  let meta = document.head.querySelector(
+    `meta[${key}="${value}"]`
+  );
+  if (!meta) {
+    meta = document.createElement("meta");
+    meta.setAttribute(key, value);
+    document.head.appendChild(meta);
+  }
+  meta.setAttribute("content", content);
+}
+
+export {
+  tableDataToRows,
+  resolveGristFormulaKind,
+  normalizeGristChoiceListEntries,
+  extractGristAttachmentIdsFromCell,
+  extractGristAttachmentId,
+  gristAttachmentCellValues,
+  gristAttachmentCellValue,
+  mergeGristAttachmentCellValue,
+  isAccessInsufficientError,
+  deriveStatus,
+  deriveColumnMappingStatus,
+  checkGristCell,
+  parseGristWidgetLinkingInfo,
+  resetGristForTests,
+  useGrist,
+  useGristOptional,
+  useGristContext,
+  useNearestGristState,
+  GristWidgetProvider,
+  GristBoundary,
+  useGristSchema,
+  useWidgetMetadata
+};
+//# sourceMappingURL=chunk-O7NY46QY.js.map