- require a target window only when posting a message (not when recei…

…ving), because that will not cause issues on the Cadenza end and can be handled by the custom app (by unsubscribing all subscribers)

- add CadenzaClient#destroy for conveniently unsubscribing all subscribers

(cherry picked from commit 9233dd5)

CHANGELOG.md

@@ -5,13 +5,18 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## Unreleased
+### Added
+- `CadenzaClient#destroy`
+
+### Fixed
+- To avoid errors with active subscriptions when the iframe is not visible, a target window (for postMessage communication) is now required only for _sending_ a message (and not for receiving messages). 
 
 ## 2.8.0 - 2024-05-28
 ### Added
 - `invalidateCaches` option for `CadenzaClient#reload`
 - Allow communication with parent Cadenza window (Previously, communication was possible only with an embedded Cadenza iframe.)
 - `cadenza()` overload with a single options parameter
-- `CadenzaClient#closeMe` function
+- `CadenzaClient#closeMe`
 - Documentation on listening when a custom application is closed (unload and visibilitychange events)
 
 ### Deprecated

src/cadenza.js

@@ -221,12 +221,11 @@ export class CadenzaClient {
   }
 
   get #targetWindow() {
-    if (this.#iframe) {
-      return /** @type {WindowProxy} */ (this.#requiredIframe.contentWindow);
-    }
-    const targetWindow = window.opener ?? window.parent;
-    assert(targetWindow !== window, 'Cannot find target window');
-    return /** @type {WindowProxy} */ targetWindow;
+    const targetWindow = this.#iframe
+      ? this.iframe?.contentWindow
+      : // If a window does not have a parent, its parent property is a reference to itself.
+        window.opener ?? (window.parent !== window ? window.parent : null);
+    return /** @type {WindowProxy | null} */ targetWindow;
   }
 
   get #requiredIframe() {
@@ -730,6 +729,16 @@ export class CadenzaClient {
     });
   };
 
+  /**
+   * Remove all subscriptions.
+   *
+   * @see {@link CadenzaClient#on}
+   */
+  destroy() {
+    this.#subscriptions = [];
+    window.removeEventListener('message', this.#onMessage);
+  }
+
   /**
    * Posts an event to Cadenza and returns a `Promise` for the response.
    *
@@ -766,7 +775,9 @@ export class CadenzaClient {
   #postEvent(type, detail, transfer) {
     const cadenzaEvent = { type, detail };
     this.#log('postMessage', cadenzaEvent);
-    this.#targetWindow.postMessage(cadenzaEvent, {
+    const targetWindow = this.#targetWindow;
+    assert(targetWindow != null, 'Cannot find target window');
+    targetWindow.postMessage(cadenzaEvent, {
       targetOrigin: this.#origin,
       transfer,
     });

src/cadenza.test.ts

@@ -64,7 +64,7 @@ describe('Given a Cadenza JS client instance', () => {
 
   it('Throws when attempting to show an embedding target without an iframe', () =>
     expect(() => cadenza(BASE_URL).show(EMBEDDING_TARGET_ID)).toThrow(
-      'present',
+      'Required iframe',
     ));
 
   it('Throws when attempting to reload the worksheet views without an iframe', () =>
@@ -230,6 +230,16 @@ describe('Given a Cadenza JS client instance', () => {
         expect(subscriber).not.toHaveBeenCalled());
     });
 
+    describe('When the event is sent again after the instance has been destroyed', () => {
+      beforeEach(() => {
+        cad.destroy();
+        sendEvent(EVENT.type, EVENT.detail);
+      });
+
+      it('Subscribers are not called anymore', () =>
+        expect(subscriber).not.toHaveBeenCalled());
+    });
+
     describe('When the event is sent from another origin', () => {
       beforeEach(() => sendEvent(EVENT.type, EVENT.detail, 'http://disy.net'));