@doenet/doenetml-iframe 0.7.16 → 0.7.17-dev.20260513000951.fa93129

package/README.md

@@ -4,6 +4,71 @@ This workspace contains a DoenetML viewer and editor that render inside of an if
 This allows DoenetML to be used without affecting the surrounding page.
 It also allows multiple versions of DoenetML to be used at the same time.
 
+## DoenetEditor
+
+### Programmatic control of the diagnostics panel
+
+The iframe `<DoenetEditor>` accepts the same `initialOpenTab` prop and
+`DoenetEditorHandle` ref API as the in-process `<DoenetEditor>` from
+`@doenet/doenetml`. Calls bridge into the iframe via ComLink. If the
+ref handle is invoked before the iframe has finished loading, the call
+is queued in the outer wrapper and replayed once the iframe is ready —
+consumers do not need to coordinate timing.
+
+```tsx
+import { useRef } from "react";
+import {
+    DoenetEditor,
+    type DoenetEditorHandle,
+} from "@doenet/doenetml-iframe";
+
+function App() {
+    const editorRef = useRef<DoenetEditorHandle>(null);
+    return (
+        <>
+            <button
+                onClick={() =>
+                    editorRef.current?.openDiagnosticsTab("accessibility")
+                }
+            >
+                Show accessibility violations
+            </button>
+            <DoenetEditor ref={editorRef} doenetML="..." />
+        </>
+    );
+}
+```
+
+Mount-time form (panel opens on the requested tab on first paint):
+
+```tsx
+<DoenetEditor doenetML="..." initialOpenTab="accessibility" />
+```
+
+Valid tab IDs: `"errors" | "warnings" | "info" | "accessibility" | "responses"`.
+See the `@doenet/doenetml` README for usage patterns including the lazy-mount
+"link in a different panel" scenario.
+
+### Programmatically updating the rendered view
+
+The handle also exposes `updateRenderedView()`, which forwards across the
+iframe to "press" the editor's Update button. Pair it with
+`diagnosticsSummaryCallback` (which receives the source the viewer
+rendered against as its second argument) to ensure diagnostics reflect the
+latest editor buffer:
+
+```tsx
+<button onClick={() => editorRef.current?.updateRenderedView()}>
+    Update viewer
+</button>
+```
+
+> **Note:** The handle methods are fire-and-forget across the iframe boundary.
+> Although they share the same `DoenetEditorHandle` type as the in-process
+> editor (so consumers can swap implementations), the iframe variant cannot
+> surface a completion signal or error to the caller — failures from the
+> underlying ComLink RPC are logged to the console rather than thrown.
+
 ## Development
 
 Source code in `src/iframe-viewer-index.ts` and `src/iframe-editor-index.ts`

package/index.d.ts

@@ -1,6 +1,8 @@
 import { default as default_2 } from 'react';
 import { DiagnosticRecord } from '../packages/utils/dist';
+import { DiagnosticsTabId } from '../packages/doenetml/dist';
 import { DoenetEditor as DoenetEditor_2 } from '../packages/doenetml/dist';
+import { DoenetEditorHandle } from '../packages/doenetml/dist';
 import { DoenetViewer as DoenetViewer_2 } from '../packages/doenetml/dist';
 import { ErrorRecord } from '../packages/utils/dist';
 import { mathjaxConfig } from '../packages/utils/dist';
@@ -8,16 +10,11 @@ import { WarningRecord } from '../packages/utils/dist';
 
 export { DiagnosticRecord }
 
-/**
- * Render Doenet Editor constrained to an iframe. A URL pointing to a version of DoenetML
- * standalone must be provided (along with a URL to the corresponding CSS file).
- *
- * Parameters being passed to the underlying DoenetML component are passed via the `DoenetEditorProps` prop.
- * However, only serializable parameters may be passed. E.g., callbacks **cannot** be passed to the underlying
- * DoenetML component. Instead you must use the message passing interface of `DoenetEditor` to communicate
- * with the underlying DoenetML component.
- */
-export declare function DoenetEditor({ doenetML, standaloneUrl: specifiedStandaloneUrl, cssUrl: specifiedCssUrl, doenetmlVersion: specifiedDoenetmlVersion, width, height, autodetectVersion, ...doenetEditorProps }: DoenetEditorIframeProps): default_2.JSX.Element | null;
+export { DiagnosticsTabId }
+
+export declare const DoenetEditor: default_2.ForwardRefExoticComponent<Omit<DoenetEditorIframeProps, "ref"> & default_2.RefAttributes<DoenetEditorHandle>>;
+
+export { DoenetEditorHandle }
 
 export declare type DoenetEditorIframeProps = DoenetEditorProps & {
     doenetML: string;

package/index.js

@@ -25341,7 +25341,92 @@ function requireCssesc$1() {
 }
 requireCssesc$1();
 const viewerIframeJsSource = '(function() {\n  "use strict";\n  document.addEventListener("DOMContentLoaded", async () => {\n    let pause100 = function() {\n      return new Promise((resolve, _reject) => {\n        setTimeout(resolve, 100);\n      });\n    };\n    for (let i = 0; i < 10; i++) {\n      if (typeof window.renderDoenetViewerToContainer === "function") {\n        break;\n      }\n      await pause100();\n    }\n    if (typeof window.renderDoenetViewerToContainer !== "function") {\n      return messageParentFromViewer({\n        error: "Invalid DoenetML version or DoenetML package not found"\n      });\n    }\n  });\n  ComlinkViewer.expose(\n    { renderViewerWithFunctionProps },\n    ComlinkViewer.windowEndpoint(globalThis.parent)\n  );\n  function renderViewerWithFunctionProps(...args) {\n    const augmentedDoenetViewerProps = { ...doenetViewerProps };\n    augmentedDoenetViewerProps.externalVirtualKeyboardProvided = true;\n    for (const propName of doenetViewerPropsSpecified) {\n      if (!(propName in doenetViewerProps)) {\n        const idx = args.indexOf(propName);\n        if (idx !== -1) {\n          augmentedDoenetViewerProps[propName] = args[idx + 1];\n        }\n      }\n    }\n    if (!doenetViewerPropsSpecified.includes("requestScrollTo")) {\n      augmentedDoenetViewerProps.requestScrollTo = (offset) => {\n        messageParentFromViewer({ type: "scrollTo", offset });\n      };\n    }\n    window.renderDoenetViewerToContainer(\n      document.getElementById("root"),\n      void 0,\n      augmentedDoenetViewerProps\n    );\n  }\n  messageParentFromViewer({ iframeReady: true });\n  function messageParentFromViewer(data) {\n    window.parent.postMessage(\n      {\n        origin: viewerId,\n        data\n      },\n      window.parent.origin\n    );\n  }\n})();\n';
-const editorIframeJsSource = '(function() {\n  "use strict";\n  document.addEventListener("DOMContentLoaded", async () => {\n    let pause100 = function() {\n      return new Promise((resolve, _reject) => {\n        setTimeout(resolve, 100);\n      });\n    };\n    for (let i = 0; i < 10; i++) {\n      if (typeof window.renderDoenetViewerToContainer === "function") {\n        break;\n      }\n      await pause100();\n    }\n    if (typeof window.renderDoenetEditorToContainer !== "function") {\n      return messageParentFromEditor({\n        error: "Invalid DoenetML version or DoenetML package not found"\n      });\n    }\n  });\n  ComlinkEditor.expose(\n    { renderEditorWithFunctionProps },\n    ComlinkEditor.windowEndpoint(globalThis.parent)\n  );\n  function renderEditorWithFunctionProps(...args) {\n    const augmentedDoenetEditorProps = { ...doenetEditorProps };\n    augmentedDoenetEditorProps.externalVirtualKeyboardProvided = true;\n    for (const propName of doenetEditorPropsSpecified) {\n      if (!(propName in doenetEditorProps)) {\n        const idx = args.indexOf(propName);\n        if (idx !== -1) {\n          augmentedDoenetEditorProps[propName] = args[idx + 1];\n        }\n      }\n    }\n    window.renderDoenetEditorToContainer(\n      document.getElementById("root"),\n      void 0,\n      augmentedDoenetEditorProps\n    );\n  }\n  messageParentFromEditor({ iframeReady: true });\n  function messageParentFromEditor(data) {\n    window.parent.postMessage(\n      {\n        origin: editorId,\n        data\n      },\n      window.parent.origin\n    );\n  }\n})();\n';
+const editorIframeJsSource = `(function() {
+  "use strict";
+  let editorControlHandle = null;
+  document.addEventListener("DOMContentLoaded", async () => {
+    let pause100 = function() {
+      return new Promise((resolve, _reject) => {
+        setTimeout(resolve, 100);
+      });
+    };
+    for (let i = 0; i < 10; i++) {
+      if (typeof window.renderDoenetViewerToContainer === "function") {
+        break;
+      }
+      await pause100();
+    }
+    if (typeof window.renderDoenetEditorToContainer !== "function") {
+      return messageParentFromEditor({
+        error: "Invalid DoenetML version or DoenetML package not found"
+      });
+    }
+  });
+  ComlinkEditor.expose(
+    {
+      renderEditorWithFunctionProps,
+      openDiagnosticsTab(tabId) {
+        if (!editorControlHandle) {
+          console.warn(
+            "iframe DoenetEditor: openDiagnosticsTab arrived before renderEditorWithFunctionProps completed — likely a bug in the iframe wrapper's queue/replay sequencing."
+          );
+          return;
+        }
+        editorControlHandle.openDiagnosticsTab(tabId);
+      },
+      closeDiagnosticsPanel() {
+        if (!editorControlHandle) {
+          console.warn(
+            "iframe DoenetEditor: closeDiagnosticsPanel arrived before renderEditorWithFunctionProps completed — likely a bug in the iframe wrapper's queue/replay sequencing."
+          );
+          return;
+        }
+        editorControlHandle.closeDiagnosticsPanel();
+      },
+      updateRenderedView() {
+        if (!editorControlHandle) {
+          console.warn(
+            "iframe DoenetEditor: updateRenderedView arrived before renderEditorWithFunctionProps completed — likely a bug in the iframe wrapper's queue/replay sequencing."
+          );
+          return;
+        }
+        editorControlHandle.updateRenderedView();
+      }
+    },
+    ComlinkEditor.windowEndpoint(globalThis.parent)
+  );
+  function renderEditorWithFunctionProps(...args) {
+    const augmentedDoenetEditorProps = { ...doenetEditorProps };
+    augmentedDoenetEditorProps.externalVirtualKeyboardProvided = true;
+    for (const propName of doenetEditorPropsSpecified) {
+      if (!(propName in doenetEditorProps)) {
+        const idx = args.indexOf(propName);
+        if (idx !== -1) {
+          augmentedDoenetEditorProps[propName] = args[idx + 1];
+        }
+      }
+    }
+    const handle = window.renderDoenetEditorToContainer(
+      document.getElementById("root"),
+      void 0,
+      augmentedDoenetEditorProps
+    );
+    if (handle) {
+      editorControlHandle = handle;
+    }
+  }
+  messageParentFromEditor({ iframeReady: true });
+  function messageParentFromEditor(data) {
+    window.parent.postMessage(
+      {
+        origin: editorId,
+        data
+      },
+      window.parent.origin
+    );
+  }
+})();
+`;
 function createHtmlForDoenetViewer(id2, doenetML, doenetViewerProps, standaloneUrl, cssUrl) {
   const doenetViewerPropsSpecified = Object.keys(doenetViewerProps);
   return `
@@ -73675,7 +73760,7 @@ function ExternalVirtualKeyboard() {
     }
   );
 }
-const version = "0.7.16";
+const version = "0.7.17-dev.20260513000951.fa93129";
 const latestDoenetmlVersion = version;
 function DoenetViewer({
   doenetML,
@@ -73821,7 +73906,12 @@ function DoenetViewer({
     }
   ));
 }
-function DoenetEditor({
+function logComlinkError(method) {
+  return (err) => {
+    console.warn(`iframe DoenetEditor: ${method} failed`, err);
+  };
+}
+const DoenetEditor = React__default__default.forwardRef(function DoenetEditor2({
   doenetML,
   standaloneUrl: specifiedStandaloneUrl,
   cssUrl: specifiedCssUrl,
@@ -73830,12 +73920,50 @@ function DoenetEditor({
   height = "500px",
   autodetectVersion = true,
   ...doenetEditorProps
-}) {
+}, forwardedRef) {
   const [id2, _2] = React__default__default.useState(() => Math.random().toString(36).slice(2));
   const ref = React__default__default.useRef(null);
+  const editorIframeRef = React__default__default.useRef(null);
+  const pendingActions = React__default__default.useRef([]);
   const [inErrorState, setInErrorState] = React__default__default.useState(null);
   const [ignoreDetectedVersion, setIgnoreDetectedVersion] = React__default__default.useState(false);
   const [initialDiagnostics, setInitialDiagnostics] = React__default__default.useState([]);
+  React__default__default.useImperativeHandle(
+    forwardedRef,
+    () => ({
+      openDiagnosticsTab(tabId) {
+        const action = (remote) => {
+          remote.openDiagnosticsTab(tabId).catch(logComlinkError("openDiagnosticsTab"));
+        };
+        if (editorIframeRef.current) {
+          action(editorIframeRef.current);
+        } else {
+          pendingActions.current.push(action);
+        }
+      },
+      closeDiagnosticsPanel() {
+        const action = (remote) => {
+          remote.closeDiagnosticsPanel().catch(logComlinkError("closeDiagnosticsPanel"));
+        };
+        if (editorIframeRef.current) {
+          action(editorIframeRef.current);
+        } else {
+          pendingActions.current.push(action);
+        }
+      },
+      updateRenderedView() {
+        const action = (remote) => {
+          remote.updateRenderedView().catch(logComlinkError("updateRenderedView"));
+        };
+        if (editorIframeRef.current) {
+          action(editorIframeRef.current);
+        } else {
+          pendingActions.current.push(action);
+        }
+      }
+    }),
+    []
+  );
   const augmentedDoenetEditorProps = { ...doenetEditorProps };
   if (augmentedDoenetEditorProps.initialDiagnostics) {
     augmentedDoenetEditorProps.initialDiagnostics = [
@@ -73890,9 +74018,14 @@ function DoenetEditor({
               proxiedFunctions.push(proxy(prop));
             }
           }
-          editorIframe?.renderEditorWithFunctionProps(
-            ...proxiedFunctions
+          editorIframe?.renderEditorWithFunctionProps(...proxiedFunctions).catch(
+            logComlinkError("renderEditorWithFunctionProps")
           );
+          editorIframeRef.current = editorIframe;
+          const queued = pendingActions.current.splice(0);
+          for (const action of queued) {
+            action(editorIframe);
+          }
         }
       }
     };
@@ -73903,6 +74036,17 @@ function DoenetEditor({
       window.removeEventListener("message", listener);
     };
   }, []);
+  const srcDoc = createHtmlForDoenetEditor(
+    id2,
+    doenetML,
+    width,
+    augmentedDoenetEditorProps,
+    standaloneUrl,
+    cssUrl
+  );
+  React__default__default.useLayoutEffect(() => {
+    editorIframeRef.current = null;
+  }, [srcDoc]);
   if (inErrorState) {
     if (foundAutoVersion) {
       setIgnoreDetectedVersion(true);
@@ -73948,14 +74092,7 @@ function DoenetEditor({
     {
       title: "Doenet Editor",
       ref,
-      srcDoc: createHtmlForDoenetEditor(
-        id2,
-        doenetML,
-        width,
-        augmentedDoenetEditorProps,
-        standaloneUrl,
-        cssUrl
-      ),
+      srcDoc,
       style: {
         width,
         boxSizing: "content-box",
@@ -73965,7 +74102,7 @@ function DoenetEditor({
       }
     }
   ));
-}
+});
 export {
   DoenetEditor,
   DoenetViewer,