grist-widget-sdk 0.2.0

package/dist/emulator/testing.js

@@ -0,0 +1,124 @@
+import {
+  resetEmbeddedHandshakeManagerForTests,
+  resetGristEventsForTests,
+  resetGristReadyCacheForTests
+} from "../chunk-XE2SKNLH.js";
+import {
+  createGristEmulator,
+  presets
+} from "../chunk-QZG7SNUG.js";
+import "../chunk-QKXKZ27D.js";
+import "../chunk-GTTD5HPO.js";
+import "../chunk-ELGVOHFD.js";
+import "../chunk-PM3B4WYV.js";
+import "../chunk-64SVRWW7.js";
+
+// src/emulator/testing/render-with-grist.tsx
+import { render } from "@testing-library/react";
+function renderWithGrist(ui, options = {}) {
+  fakeIframeContext();
+  resetGristEventsForTests();
+  resetGristReadyCacheForTests();
+  resetEmbeddedHandshakeManagerForTests();
+  const emulator = options.existing ?? createGristEmulator(options.emulator ?? { document: presets.blank() });
+  const result = render(ui, options);
+  const originalUnmount = result.unmount;
+  result.unmount = () => {
+    originalUnmount();
+    if (!options.existing) emulator.dispose();
+    resetGristReadyCacheForTests();
+    resetGristEventsForTests();
+    resetEmbeddedHandshakeManagerForTests();
+  };
+  return Object.assign(result, { emulator });
+}
+function fakeIframeContext() {
+  if (typeof window === "undefined") return;
+  if (window.self !== window.top) return;
+  try {
+    Object.defineProperty(window, "top", {
+      configurable: true,
+      get: () => ({})
+    });
+  } catch {
+  }
+}
+
+// src/emulator/testing/matchers.ts
+function actionsOf(emulator) {
+  return emulator.bus.history().filter((e) => e.type === "user-action").map((e) => e.action);
+}
+function eventsOf(emulator) {
+  return emulator.bus.history();
+}
+function predicateForKind(kind) {
+  switch (kind) {
+    case "ready":
+      return (e) => e.type === "ready";
+    case "record":
+    case "cursor":
+      return (e) => e.type === "cursor-change";
+    case "records":
+      return (e) => e.type === "data-change";
+    case "options":
+      return (e) => e.type === "options-change";
+    case "theme":
+      return (e) => e.type === "theme-change";
+  }
+}
+function waitForNextEvent(emulator, predicate, timeoutMs, label) {
+  return new Promise((resolve, reject) => {
+    const timer = setTimeout(() => {
+      off();
+      const hint = label ? ` (kind: ${label})` : "";
+      const recent = emulator.bus.history().slice(-5).map((e) => e.type).join(", ");
+      reject(
+        new Error(
+          `waitForEvent timed out after ${timeoutMs}ms${hint}.` + (recent ? ` Recent bus events: ${recent}.` : " No bus events yet.")
+        )
+      );
+    }, timeoutMs);
+    const off = emulator.bus.on((event) => {
+      if (predicate(event)) {
+        clearTimeout(timer);
+        off();
+        resolve(event);
+      }
+    });
+  });
+}
+function waitForEvent(emulator, kindOrPredicate, timeoutOrOptions = 1e3) {
+  if (typeof kindOrPredicate === "string") {
+    const opts = typeof timeoutOrOptions === "object" ? timeoutOrOptions : {};
+    const timeoutMs2 = opts.timeoutMs ?? 1e3;
+    return waitForNextEvent(emulator, predicateForKind(kindOrPredicate), timeoutMs2, kindOrPredicate);
+  }
+  const timeoutMs = typeof timeoutOrOptions === "number" ? timeoutOrOptions : 1e3;
+  return waitForNextEvent(emulator, kindOrPredicate, timeoutMs);
+}
+
+// src/emulator/testing/index.ts
+import {
+  act,
+  cleanup,
+  fireEvent,
+  render as render2,
+  screen,
+  waitFor,
+  within
+} from "@testing-library/react";
+export {
+  act,
+  actionsOf,
+  cleanup,
+  eventsOf,
+  fireEvent,
+  presets,
+  render2 as render,
+  renderWithGrist,
+  screen,
+  waitFor,
+  waitForEvent,
+  within
+};
+//# sourceMappingURL=testing.js.map

package/dist/emulator/testing.js.map

@@ -0,0 +1 @@
+{"version":3,"sources":["../../src/emulator/testing/render-with-grist.tsx","../../src/emulator/testing/matchers.ts","../../src/emulator/testing/index.ts"],"sourcesContent":["/**\n * `renderWithGrist(ui, options)` — drop-in replacement for\n * `@testing-library/react`'s `render(ui)` that boots a Grist emulator\n * (inline transport) and exposes it to the test.\n *\n * The emulator is mounted as `window.grist`. The SDK hooks (`useGrist`,\n * `useGristReady`, etc.) detect it via the same path they use in production.\n *\n * Cleanup is automatic when the test's container unmounts.\n */\n\nimport type { ReactElement } from \"react\"\n\nimport { render, type RenderOptions, type RenderResult } from \"@testing-library/react\"\n\nimport { resetEmbeddedHandshakeManagerForTests } from \"../../sdk/internal/embedded-handshake-manager\"\nimport { resetGristReadyCacheForTests } from \"../../sdk/internal/ready-singleton\"\nimport { resetGristEventsForTests } from \"../../sdk/internal/subscriptions\"\nimport { createGristEmulator } from \"../create-grist-emulator\"\nimport type { CreateGristEmulatorOptions, GristEmulator } from \"../create-grist-emulator\"\nimport { presets } from \"../templates\"\n\nexport type RenderWithGristOptions = RenderOptions & {\n  emulator?: CreateGristEmulatorOptions\n  /** Skip mounting the emulator; you bring your own. Useful for shared fixtures. */\n  existing?: GristEmulator\n}\n\nexport type RenderWithGristResult = RenderResult & {\n  emulator: GristEmulator\n}\n\nexport function renderWithGrist(\n  ui: ReactElement,\n  options: RenderWithGristOptions = {}\n): RenderWithGristResult {\n  // Make `window.self !== window.top` evaluate to `true` so\n  // `useGristAvailability` reports the widget as embedded. We only do this in\n  // jsdom; real browsers already enforce this distinction for iframes.\n  fakeIframeContext()\n\n  resetGristEventsForTests()\n  resetGristReadyCacheForTests()\n  resetEmbeddedHandshakeManagerForTests()\n\n  const emulator =\n    options.existing ??\n    createGristEmulator(options.emulator ?? { document: presets.blank() })\n\n  const result = render(ui, options)\n  const originalUnmount = result.unmount\n  result.unmount = () => {\n    originalUnmount()\n    if (!options.existing) emulator.dispose()\n    resetGristReadyCacheForTests()\n    resetGristEventsForTests()\n    resetEmbeddedHandshakeManagerForTests()\n  }\n  return Object.assign(result, { emulator })\n}\n\nfunction fakeIframeContext() {\n  if (typeof window === \"undefined\") return\n  if (window.self !== window.top) return // already iframe-like\n  try {\n    Object.defineProperty(window, \"top\", {\n      configurable: true,\n      get: () => ({}),\n    })\n  } catch {\n    // Some jsdom versions block redefinition; fail silently — tests using\n    // `useGristAvailability` will need to bypass it explicitly in that case.\n  }\n}\n","/**\n * Vitest helpers to assert what the widget did to the document.\n *\n * Usage:\n *\n *   const { emulator } = renderWithGrist(<MyWidget />)\n *   await userEvent.click(screen.getByText(\"Add\"))\n *   expect(actionsOf(emulator)).toContainEqual([\"AddRecord\", \"Tasks\", null, { title: \"X\" }])\n */\n\nimport type { GristEmulator } from \"../create-grist-emulator\"\nimport type { EmulatorEvent } from \"../core/event-bus\"\n\nexport function actionsOf(emulator: GristEmulator): unknown[][] {\n  return emulator.bus\n    .history()\n    .filter((e: EmulatorEvent): e is Extract<EmulatorEvent, { type: \"user-action\" }> => e.type === \"user-action\")\n    .map((e) => e.action as unknown[])\n}\n\nexport function eventsOf(emulator: GristEmulator): readonly EmulatorEvent[] {\n  return emulator.bus.history()\n}\n\n/** Bus event kinds aligned with grist host callbacks (see inline transport). */\nexport type WaitForEventKind = \"ready\" | \"record\" | \"records\" | \"options\" | \"theme\" | \"cursor\"\n\nexport type WaitForEventOptions = {\n  timeoutMs?: number\n}\n\nfunction predicateForKind(kind: WaitForEventKind): (event: EmulatorEvent) => boolean {\n  switch (kind) {\n    case \"ready\":\n      return (e) => e.type === \"ready\"\n    case \"record\":\n    case \"cursor\":\n      return (e) => e.type === \"cursor-change\"\n    case \"records\":\n      return (e) => e.type === \"data-change\"\n    case \"options\":\n      return (e) => e.type === \"options-change\"\n    case \"theme\":\n      return (e) => e.type === \"theme-change\"\n  }\n}\n\nfunction waitForNextEvent(\n  emulator: GristEmulator,\n  predicate: (event: EmulatorEvent) => boolean,\n  timeoutMs: number,\n  label?: string\n): Promise<EmulatorEvent> {\n  return new Promise((resolve, reject) => {\n    const timer = setTimeout(() => {\n      off()\n      const hint = label ? ` (kind: ${label})` : \"\"\n      const recent = emulator.bus\n        .history()\n        .slice(-5)\n        .map((e) => e.type)\n        .join(\", \")\n      reject(\n        new Error(\n          `waitForEvent timed out after ${timeoutMs}ms${hint}.` +\n            (recent ? ` Recent bus events: ${recent}.` : \" No bus events yet.\")\n        )\n      )\n    }, timeoutMs)\n    const off = emulator.bus.on((event) => {\n      if (predicate(event)) {\n        clearTimeout(timer)\n        off()\n        resolve(event)\n      }\n    })\n  })\n}\n\nexport function waitForEvent(\n  emulator: GristEmulator,\n  kind: WaitForEventKind,\n  options?: WaitForEventOptions\n): Promise<EmulatorEvent>\nexport function waitForEvent(\n  emulator: GristEmulator,\n  predicate: (event: EmulatorEvent) => boolean,\n  timeoutMs?: number\n): Promise<EmulatorEvent>\nexport function waitForEvent(\n  emulator: GristEmulator,\n  kindOrPredicate: WaitForEventKind | ((event: EmulatorEvent) => boolean),\n  timeoutOrOptions: number | WaitForEventOptions = 1000\n): Promise<EmulatorEvent> {\n  if (typeof kindOrPredicate === \"string\") {\n    const opts = typeof timeoutOrOptions === \"object\" ? timeoutOrOptions : {}\n    const timeoutMs = opts.timeoutMs ?? 1000\n    return waitForNextEvent(emulator, predicateForKind(kindOrPredicate), timeoutMs, kindOrPredicate)\n  }\n  const timeoutMs = typeof timeoutOrOptions === \"number\" ? timeoutOrOptions : 1000\n  return waitForNextEvent(emulator, kindOrPredicate, timeoutMs)\n}\n","/**\n * Test entry point — `grist-widget-sdk/emulator/testing`.\n *\n * Bundles `renderWithGrist`, matchers, document presets, and the most-used\n * @testing-library/react primitives so a typical test file only needs one\n * import line:\n *\n *   import {\n *     renderWithGrist, presets, screen, fireEvent, waitFor, actionsOf,\n *   } from \"grist-widget-sdk/emulator/testing\"\n */\n\nexport { renderWithGrist } from \"./render-with-grist\"\nexport type {\n  RenderWithGristOptions,\n  RenderWithGristResult,\n} from \"./render-with-grist\"\n\nexport {\n  actionsOf,\n  eventsOf,\n  waitForEvent,\n  type WaitForEventKind,\n  type WaitForEventOptions,\n} from \"./matchers\"\n\n// Document fixtures (re-export from the emulator entry for convenience).\nexport { presets } from \"../templates\"\n\n// @testing-library/react convenience re-exports — see apps/docs/work.md\nexport {\n  act,\n  cleanup,\n  fireEvent,\n  render,\n  screen,\n  waitFor,\n  within,\n} from \"@testing-library/react\"\nexport type { RenderOptions, RenderResult } from \"@testing-library/react\"\n"],"mappings":";;;;;;;;;;;;;;;;AAaA,SAAS,cAAqD;AAmBvD,SAAS,gBACd,IACA,UAAkC,CAAC,GACZ;AAIvB,oBAAkB;AAElB,2BAAyB;AACzB,+BAA6B;AAC7B,wCAAsC;AAEtC,QAAM,WACJ,QAAQ,YACR,oBAAoB,QAAQ,YAAY,EAAE,UAAU,QAAQ,MAAM,EAAE,CAAC;AAEvE,QAAM,SAAS,OAAO,IAAI,OAAO;AACjC,QAAM,kBAAkB,OAAO;AAC/B,SAAO,UAAU,MAAM;AACrB,oBAAgB;AAChB,QAAI,CAAC,QAAQ,SAAU,UAAS,QAAQ;AACxC,iCAA6B;AAC7B,6BAAyB;AACzB,0CAAsC;AAAA,EACxC;AACA,SAAO,OAAO,OAAO,QAAQ,EAAE,SAAS,CAAC;AAC3C;AAEA,SAAS,oBAAoB;AAC3B,MAAI,OAAO,WAAW,YAAa;AACnC,MAAI,OAAO,SAAS,OAAO,IAAK;AAChC,MAAI;AACF,WAAO,eAAe,QAAQ,OAAO;AAAA,MACnC,cAAc;AAAA,MACd,KAAK,OAAO,CAAC;AAAA,IACf,CAAC;AAAA,EACH,QAAQ;AAAA,EAGR;AACF;;;AC5DO,SAAS,UAAU,UAAsC;AAC9D,SAAO,SAAS,IACb,QAAQ,EACR,OAAO,CAAC,MAA2E,EAAE,SAAS,aAAa,EAC3G,IAAI,CAAC,MAAM,EAAE,MAAmB;AACrC;AAEO,SAAS,SAAS,UAAmD;AAC1E,SAAO,SAAS,IAAI,QAAQ;AAC9B;AASA,SAAS,iBAAiB,MAA2D;AACnF,UAAQ,MAAM;AAAA,IACZ,KAAK;AACH,aAAO,CAAC,MAAM,EAAE,SAAS;AAAA,IAC3B,KAAK;AAAA,IACL,KAAK;AACH,aAAO,CAAC,MAAM,EAAE,SAAS;AAAA,IAC3B,KAAK;AACH,aAAO,CAAC,MAAM,EAAE,SAAS;AAAA,IAC3B,KAAK;AACH,aAAO,CAAC,MAAM,EAAE,SAAS;AAAA,IAC3B,KAAK;AACH,aAAO,CAAC,MAAM,EAAE,SAAS;AAAA,EAC7B;AACF;AAEA,SAAS,iBACP,UACA,WACA,WACA,OACwB;AACxB,SAAO,IAAI,QAAQ,CAAC,SAAS,WAAW;AACtC,UAAM,QAAQ,WAAW,MAAM;AAC7B,UAAI;AACJ,YAAM,OAAO,QAAQ,WAAW,KAAK,MAAM;AAC3C,YAAM,SAAS,SAAS,IACrB,QAAQ,EACR,MAAM,EAAE,EACR,IAAI,CAAC,MAAM,EAAE,IAAI,EACjB,KAAK,IAAI;AACZ;AAAA,QACE,IAAI;AAAA,UACF,gCAAgC,SAAS,KAAK,IAAI,OAC/C,SAAS,uBAAuB,MAAM,MAAM;AAAA,QACjD;AAAA,MACF;AAAA,IACF,GAAG,SAAS;AACZ,UAAM,MAAM,SAAS,IAAI,GAAG,CAAC,UAAU;AACrC,UAAI,UAAU,KAAK,GAAG;AACpB,qBAAa,KAAK;AAClB,YAAI;AACJ,gBAAQ,KAAK;AAAA,MACf;AAAA,IACF,CAAC;AAAA,EACH,CAAC;AACH;AAYO,SAAS,aACd,UACA,iBACA,mBAAiD,KACzB;AACxB,MAAI,OAAO,oBAAoB,UAAU;AACvC,UAAM,OAAO,OAAO,qBAAqB,WAAW,mBAAmB,CAAC;AACxE,UAAMA,aAAY,KAAK,aAAa;AACpC,WAAO,iBAAiB,UAAU,iBAAiB,eAAe,GAAGA,YAAW,eAAe;AAAA,EACjG;AACA,QAAM,YAAY,OAAO,qBAAqB,WAAW,mBAAmB;AAC5E,SAAO,iBAAiB,UAAU,iBAAiB,SAAS;AAC9D;;;ACvEA;AAAA,EACE;AAAA,EACA;AAAA,EACA;AAAA,EACA,UAAAC;AAAA,EACA;AAAA,EACA;AAAA,EACA;AAAA,OACK;","names":["timeoutMs","render"]}