feat: add new insertElement() function for SPA widgets (#240)

Author: kwliou

packages/experiment-tag/src/experiment.ts

@@ -706,7 +706,8 @@ export class DefaultWebExperimentClient implements WebExperimentClient {
           .firstElementChild ?? undefined;
     }
     // Inject
-    const utils = getInjectUtils();
+    const state = { cancelled: false }; // individual state per injection
+    const utils = getInjectUtils(state);
     this.appliedInjections.add(id);
     try {
       const fn = this.globalScope[id];
@@ -728,6 +729,7 @@ export class DefaultWebExperimentClient implements WebExperimentClient {
     // Push the mutation
     this.appliedMutations[flagKey][variantKey][INJECT_ACTION][id] = {
       revert: () => {
+        state.cancelled = true;
         utils.remove?.();
         style?.remove();
         script?.remove();

packages/experiment-tag/src/util/inject-utils.ts

@@ -7,6 +7,26 @@ export interface InjectUtils {
    */
   waitForElement(selector: string): Promise<Element>;
 
+  /**
+   * Inserts an element into the DOM at the specified selectors.
+   * Re-inserts element whenever it gets removed
+   * Returns a promise that is resolved the first time the element is inserted.
+   *
+   * @param element The element to insert.
+   * @param  options The insertion options.
+   * @param options.parentSelector The parent selector to insert the element into.
+   * @param options.insertBeforeSelector The sibling selector to insert the element before.
+   * @param callback Optional callback to be called after every insertion.
+   */
+  insertElement(
+    element: Element,
+    options: {
+      parentSelector: string;
+      insertBeforeSelector: string | null;
+    },
+    callback?: () => void,
+  ): Promise<void>;
+
   /**
    * Function which can be set inside injected javascript code. This function is
    * called on page change, when experiments are re-evaluated.
@@ -19,21 +39,32 @@ export interface InjectUtils {
   remove: (() => void) | undefined;
 }
 
-export const getInjectUtils = (): InjectUtils =>
+export const getInjectUtils = (state: { cancelled: boolean }): InjectUtils =>
   ({
     async waitForElement(selector: string): Promise<Element> {
+      let observer: MutationObserver | undefined = undefined;
+
+      const findElement = () => {
+        if (state.cancelled) {
+          observer?.disconnect();
+          return;
+        }
+
+        return document.querySelector(selector);
+      };
+
       // If selector found in DOM, then return directly.
-      const elem = document.querySelector(selector);
+      const elem = findElement();
       if (elem) {
         return elem;
       }
 
       return new Promise<Element>((resolve) => {
         // An observer that is listening for all DOM mutation events.
-        const observer = new MutationObserver(() => {
-          const elem = document.querySelector(selector);
+        observer = new MutationObserver(() => {
+          const elem = findElement();
           if (elem) {
-            observer.disconnect();
+            observer?.disconnect();
             resolve(elem);
           }
         });
@@ -46,4 +77,62 @@ export const getInjectUtils = (): InjectUtils =>
         });
       });
     },
+
+    insertElement(
+      element: Element,
+      options: {
+        parentSelector: string;
+        insertBeforeSelector: string | null;
+      },
+      callback?: () => void,
+    ): Promise<void> {
+      return new Promise((resolve) => {
+        let rateLimit = 0;
+        let observer: MutationObserver | undefined = undefined;
+
+        const checkElementInserted = () => {
+          if (state.cancelled) {
+            observer?.disconnect();
+            return;
+          }
+
+          if (element.isConnected && element.ownerDocument === document) {
+            return; // element was already inserted
+          }
+
+          if (rateLimit >= 10) {
+            return;
+          }
+          rateLimit++;
+          setTimeout(() => rateLimit--, 1000);
+
+          const parent = document.querySelector(options.parentSelector);
+          if (!parent) {
+            return;
+          }
+          const sibling = options.insertBeforeSelector
+            ? parent.querySelector(options.insertBeforeSelector)
+            : null;
+
+          if (options.insertBeforeSelector && !sibling) {
+            // wait until matching sibling is found before inserting
+            return;
+          }
+
+          parent.insertBefore(element, sibling);
+          callback?.();
+          resolve();
+        };
+
+        checkElementInserted();
+        observer = new MutationObserver(checkElementInserted);
+
+        // Observe on all document changes.
+        observer.observe(document.documentElement, {
+          childList: true,
+          subtree: true,
+          attributes: true,
+        });
+      });
+    },
   } as InjectUtils);