@elliemae/pui-app-bridge 2.21.3 → 2.22.0

package/dist/cjs/appBridge.js

@@ -144,12 +144,14 @@ class CAppBridge {
    * @param param0.instanceId
    * @param elementIds
    * @param param0.documentEle
+   * @param param0.elementIds
    */
   #addAppToActiveAppList = ({
     id,
     instanceId,
-    documentEle
-  }, elementIds) => {
+    documentEle,
+    elementIds
+  }) => {
     const app = this.#appRegistry.get({ id, instanceId });
     if (!app) {
       throw new Error(this.#getAppNotFoundError(id, instanceId));
@@ -164,45 +166,6 @@ class CAppBridge {
       }
     });
   };
-  #waitAndInitApplication = (options, requests) => {
-    const {
-      id,
-      instanceId,
-      containerId,
-      name,
-      hostUrl,
-      manifestPath,
-      homeRoute,
-      initialRoute,
-      history,
-      theme,
-      documentEle
-    } = options;
-    return Promise.all(requests).then(
-      this.#addAppToActiveAppList.bind(null, { id, instanceId, documentEle })
-    ).then(
-      this.#initApplication.bind(null, {
-        id,
-        instanceId,
-        containerId,
-        name,
-        hostUrl,
-        manifestPath,
-        homeRoute,
-        initialRoute,
-        history,
-        theme
-      })
-    ).catch((err) => {
-      const message = `Application load failed. Unable to load one or more resources for ${options.id} with instance id ${instanceId}. ${err.message}`;
-      this.#logger.error({
-        message,
-        appId: id,
-        exception: err
-      });
-      throw new Error(message);
-    });
-  };
   #initApplication = async ({
     id,
     instanceId,
@@ -249,30 +212,49 @@ class CAppBridge {
     });
   };
   #loadApp = async (options) => {
-    const { id, instanceId, files, name, hostUrl, documentEle, isJsModule } = options;
-    this.#logger.debug(
-      `Application ${id} with instance id ${instanceId} is loading...`
-    );
-    let assets = files;
-    const manifest = await import_loaders.ManifestLoader.get(options);
-    assets = import_loaders.ManifestLoader.getFullFileNameofAssets(manifest, files);
-    let counter = 0;
-    const requests = assets.map((fileName) => {
-      counter += 1;
-      const resourceOptions = {
+    try {
+      const { id, instanceId, files, name, hostUrl, documentEle, isJsModule } = options;
+      this.#logger.debug(
+        `Application ${id} with instance id ${instanceId} is loading...`
+      );
+      let assets = files;
+      const manifest = await import_loaders.ManifestLoader.get(options);
+      assets = import_loaders.ManifestLoader.getFullFileNameofAssets(manifest, files);
+      const cssAssets = assets.filter((fileName) => isCss(fileName));
+      const jsAssets = assets.filter((fileName) => !isCss(fileName));
+      const loadOptions = {
         name,
         hostUrl,
         documentEle,
-        fileName,
-        index: counter,
-        isJsModule
+        isESMModule: isJsModule
       };
-      return !isCss(fileName) ? this.#scriptLoader.add(resourceOptions) : this.#styleLoader.add(resourceOptions);
-    });
-    await this.#waitAndInitApplication(options, requests);
-    this.#logger.audit(
-      `Application ${id} with instance id ${instanceId} loaded`
-    );
+      const styleElementIds = await this.#styleLoader.load(
+        cssAssets,
+        loadOptions
+      );
+      const scriptElementIds = await this.#scriptLoader.load(
+        jsAssets,
+        loadOptions
+      );
+      this.#addAppToActiveAppList({
+        id,
+        instanceId,
+        documentEle,
+        elementIds: [...styleElementIds, ...scriptElementIds]
+      });
+      await this.#initApplication(options);
+      this.#logger.audit(
+        `Application ${id} with instance id ${instanceId} loaded`
+      );
+    } catch (err) {
+      const message = `Application load failed. Unable to load one or more resources for ${options.id} with instance id ${options.instanceId}. ${err.message}`;
+      this.#logger.error({
+        message,
+        appId: options.id,
+        exception: err
+      });
+      throw new Error(message);
+    }
   };
   #unloadApp = ({ id, instanceId, hostUrl, documentEle }) => {
     this.#logger.debug(

package/dist/cjs/index.html

@@ -6,7 +6,7 @@
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>Host</title>
     <script src="https://cdn.tailwindcss.com?plugins=forms"></script>
-    <script src="https://cdn.qa1.ice.com/pui-diagnostics@3" ></script>
+    <script src="https://cdn.mortgagetech.q1.ice.com/pui-diagnostics@3" ></script>
   </head>
   <body>
     <header class="bg-indigo-300 h-10 flex place-items-center">

package/dist/cjs/index.js

@@ -20,10 +20,14 @@ var index_exports = {};
 __export(index_exports, {
   CAppBridge: () => import_appBridge.CAppBridge,
   Event: () => import_microfe_common.Event,
+  ScriptLoader: () => import_script.ScriptLoader,
   ScriptingObject: () => import_microfe_common.ScriptingObject,
-  SecurityContext: () => import_common.SecurityContext
+  SecurityContext: () => import_common.SecurityContext,
+  StyleLoader: () => import_style.StyleLoader
 });
 module.exports = __toCommonJS(index_exports);
 var import_common = require("./typings/common.js");
 var import_microfe_common = require("@elliemae/microfe-common");
 var import_appBridge = require("./appBridge.js");
+var import_script = require("./loaders/script.js");
+var import_style = require("./loaders/style.js");

package/dist/cjs/loaders/script.js

@@ -29,23 +29,77 @@ class ScriptLoader {
   constructor(logger) {
     this.#logger = logger;
   }
-  add = ({
-    name,
-    hostUrl,
+  /**
+   * Creates a modulepreload link element for performance optimization.
+   * @param href.href
+   * @param href - The URL of the script to preload
+   * @param href.isESMModule
+   * @param href.documentEle
+   * @remarks
+   * Modulepreload hints allow the browser to fetch and cache the module script
+   * earlier in the page load lifecycle, improving performance.
+   * The crossorigin attribute is set to 'anonymous' to match the script loading behavior
+   * and prevent CORS issues with cross-origin resources.
+   * @private
+   */
+  #preLoadScript = ({
+    href,
+    isESMModule = true,
+    documentEle
+  }) => {
+    const link = documentEle.createElement("link");
+    link.rel = isESMModule ? "modulepreload" : "preload";
+    link.href = href;
+    link.crossOrigin = "anonymous";
+    if (!isESMModule) {
+      link.as = "script";
+    }
+    documentEle.head.appendChild(link);
+  };
+  /**
+   * Dynamically adds a script element to the document.
+   * @param options - Configuration options for the script
+   * @param options.name - The name of the application or script
+   * @param options.hostUrl - The base URL where the script is hosted
+   * @param options.documentEle - The document object where the script should be added
+   * @param options.fileName - The filename of the script to load
+   * @param options.index - An index used to generate a unique script ID
+   * @param options.isESMModule - Whether the script should be loaded as an ES module (default: true)
+   * @param options.id
+   * @param options.href
+   * @returns A promise that resolves with the script element's ID when the script loads successfully
+   * @throws Will reject with an error if the script fails to load
+   * @example
+   * ```typescript
+   * await scriptLoader.add({
+   *   name: 'myApp',
+   *   hostUrl: 'https://cdn.example.com',
+   *   documentEle: document,
+   *   fileName: 'main.js',
+   *   index: 0,
+   *   isESMModule: true
+   * });
+   * ```
+   */
+  #loadScript = ({
+    id,
+    href,
     documentEle,
-    fileName,
-    index,
-    isJsModule = true
+    isESMModule = true
   }) => new Promise((resolve, reject) => {
-    const url = new URL(fileName, hostUrl);
     const ele = documentEle.createElement("script");
-    ele.id = `${APP_SCRIPT_ID_PREFIX}${name.toLowerCase()}-${index}`;
-    ele.src = (0, import_utils.removeDoubleSlash)(url.href);
+    ele.id = id;
+    ele.src = (0, import_utils.removeDoubleSlash)(href);
+    ele.crossOrigin = "anonymous";
     ele.nonce = "__CSP_NONCE__";
-    if (!(0, import_utils.isJSDOM)() && isJsModule) ele.type = "module";
+    if (!(0, import_utils.isJSDOM)() && isESMModule) ele.type = "module";
     else ele.async = false;
     ele.onload = resolve.bind(null, ele.id);
     ele.onerror = (err) => {
+      this.#logger.error({
+        message: `Error loading script ${ele.src}`,
+        exception: new Error(err)
+      });
       reject(
         new Error(`Unable to load script ${ele.src}`, {
           cause: new Error(err)
@@ -54,6 +108,78 @@ class ScriptLoader {
     };
     documentEle.head.appendChild(ele);
   });
+  /**
+   * Loads multiple script assets sequentially, with CDN scripts loaded before non-CDN scripts.
+   * @param assets - Array of script URLs (either full HTTP/HTTPS URLs or relative paths)
+   * @param options - Configuration options for loading the scripts
+   * @param options.name - The name of the application (used for generating script IDs)
+   * @param options.hostUrl - The base URL for resolving relative script paths
+   * @param options.documentEle - The document object where scripts should be added
+   * @param options.isESMModule - Whether scripts should be loaded as ES modules (default: true)
+   * @returns A promise that resolves with an array of script element IDs when all scripts are loaded
+   * @remarks
+   * This method:
+   * - Partitions assets into CDN (HTTP/HTTPS) and non-CDN (relative) arrays in a single pass
+   * - Creates modulepreload links for all assets for performance optimization
+   * - Loads CDN scripts sequentially first (they may set global variables needed by non-CDN scripts)
+   * - Then loads non-CDN scripts sequentially
+   * - Sequential execution ensures proper dependency resolution and initialization order
+   * @example
+   * ```typescript
+   * const scriptIds = await scriptLoader.load(
+   *   ['https://cdn.example.com/lib.js', 'app.js', 'config.js'],
+   *   {
+   *     name: 'myApp',
+   *     hostUrl: 'https://example.com',
+   *     documentEle: document,
+   *     isESMModule: true
+   *   }
+   * );
+   * ```
+   */
+  load = async (assets, options) => {
+    const { documentEle, isESMModule } = options;
+    const httpPattern = /^https?:\/\//i;
+    const { cdnAssets, nonCdnAssets } = assets.reduce(
+      (acc, fileName, index) => {
+        const id = `${APP_SCRIPT_ID_PREFIX}${options.name.toLowerCase()}-${index}`;
+        if (httpPattern.test(fileName)) {
+          acc.cdnAssets.push({ id, href: fileName });
+          this.#preLoadScript({ href: fileName, documentEle, isESMModule });
+        } else {
+          const url = new URL(fileName, options.hostUrl);
+          acc.nonCdnAssets.push({ id, href: url.href });
+          this.#preLoadScript({ href: url.href, documentEle, isESMModule });
+        }
+        return acc;
+      },
+      {
+        cdnAssets: [],
+        nonCdnAssets: []
+      }
+    );
+    for (const { href, id } of [...cdnAssets, ...nonCdnAssets]) {
+      await this.#loadScript({
+        id,
+        href,
+        documentEle,
+        isESMModule
+      });
+    }
+    return [...cdnAssets, ...nonCdnAssets].map((asset) => asset.id);
+  };
+  /**
+   * Removes a script element from the document by its ID.
+   * @param elementId - The ID of the script element to remove (default: '')
+   * @param documentEle - The document object from which to remove the script (default: document)
+   * @returns A promise that resolves when the script element has been removed
+   * @remarks
+   * If the element with the specified ID is not found, a warning is logged but the promise still resolves.
+   * @example
+   * ```typescript
+   * await scriptLoader.remove('ice-script-myapp-0', document);
+   * ```
+   */
   remove = (elementId = "", documentEle = document) => new Promise((resolve) => {
     const ele = documentEle.getElementById(elementId);
     if (!ele) {
@@ -63,6 +189,19 @@ class ScriptLoader {
     ele.remove();
     resolve();
   });
+  /**
+   * Removes all script elements from the document that match a specific host URL pattern.
+   * @param hostUrl - The host URL pattern to match against script sources
+   * @param documentEle - The document object from which to remove scripts
+   * @remarks
+   * This method iterates through all script elements in reverse order and removes any script
+   * whose `src` attribute matches the provided host URL pattern (case-insensitive).
+   * This is useful for cleaning up dynamically imported scripts from a specific host.
+   * @example
+   * ```typescript
+   * scriptLoader.removeDynamicImportedScripts('https://cdn.example.com', document);
+   * ```
+   */
   removeDynamicImportedScripts = (hostUrl, documentEle) => {
     const hostPattern = new RegExp(hostUrl, "i");
     const scriptElements = documentEle.getElementsByTagName("script");
@@ -72,6 +211,19 @@ class ScriptLoader {
       if (hostPattern.test(src)) scriptEle.remove();
     }
   };
+  /**
+   * Removes all prefetch link elements from the document that match a specific host URL pattern.
+   * @param hostUrl - The host URL pattern to match against link hrefs
+   * @param documentEle - The document object from which to remove prefetch links
+   * @remarks
+   * This method queries all elements with `rel="prefetch"` and removes any link whose `href`
+   * attribute matches the provided host URL pattern (case-insensitive). This is useful for
+   * cleaning up resource hints that are no longer needed.
+   * @example
+   * ```typescript
+   * scriptLoader.removePrefetchLinks('https://cdn.example.com', document);
+   * ```
+   */
   removePrefetchLinks = (hostUrl, documentEle) => {
     const hostPattern = new RegExp(hostUrl, "i");
     const prefetchElements = documentEle.querySelectorAll('[rel="prefetch"]');

package/dist/cjs/loaders/style.js

@@ -29,21 +29,45 @@ class StyleLoader {
   constructor(logger) {
     this.#logger = logger;
   }
-  add = ({
-    name,
-    hostUrl,
-    documentEle,
-    fileName,
-    index
+  /**
+   * Dynamically adds a stylesheet link element to the document.
+   * @param options - Configuration options for the stylesheet
+   * @param options.name - The name of the application or stylesheet
+   * @param options.hostUrl - The base URL where the stylesheet is hosted
+   * @param options.documentEle - The document object where the stylesheet should be added
+   * @param options.fileName - The filename of the stylesheet to load
+   * @param options.index - An index used to generate a unique stylesheet ID
+   * @param options.id
+   * @param options.href
+   * @returns A promise that resolves with the link element's ID when the stylesheet loads successfully
+   * @throws Will reject with an error if the stylesheet fails to load
+   * @example
+   * ```typescript
+   * await styleLoader.add({
+   *   name: 'myApp',
+   *   hostUrl: 'https://cdn.example.com',
+   *   documentEle: document,
+   *   fileName: 'main.css',
+   *   index: 0
+   * });
+   * ```
+   */
+  #loadStyle = ({
+    id,
+    href,
+    documentEle
   }) => new Promise((resolve, reject) => {
     const ele = documentEle.createElement("link");
-    ele.id = `${APP_STYLE_ID_PREFIX}${name.toLowerCase()}-${index}`;
+    ele.id = id;
     ele.nonce = "__CSP_NONCE__";
     ele.rel = "stylesheet";
-    const url = new URL(fileName, hostUrl);
-    ele.href = (0, import_utils.removeDoubleSlash)(url.href);
+    ele.href = (0, import_utils.removeDoubleSlash)(href);
     ele.onload = resolve.bind(null, ele.id);
     ele.onerror = (err) => {
+      this.#logger.error({
+        message: `Error loading stylesheet ${ele.href}`,
+        exception: new Error(err)
+      });
       reject(
         new Error(`Unable to load stylesheet ${ele.href}`, {
           cause: new Error(err)
@@ -52,6 +76,57 @@ class StyleLoader {
     };
     documentEle.head.appendChild(ele);
   });
+  /**
+   * Loads multiple stylesheet assets in parallel.
+   * @param assets - Array of stylesheet filenames (relative paths)
+   * @param options - Configuration options for loading the stylesheets
+   * @param options.name - The name of the application (used for generating stylesheet IDs)
+   * @param options.hostUrl - The base URL for resolving stylesheet paths
+   * @param options.documentEle - The document object where stylesheets should be added
+   * @returns A promise that resolves with an array of stylesheet element IDs when all stylesheets are loaded
+   * @remarks
+   * This method loads all stylesheets in parallel using Promise.all for optimal performance.
+   * Each stylesheet is assigned a unique ID based on the application name and its index.
+   * Unlike scripts, stylesheets don't typically have execution order dependencies.
+   * @example
+   * ```typescript
+   * const styleIds = await styleLoader.load(
+   *   ['main.css', 'theme.css', 'components.css'],
+   *   {
+   *     name: 'myApp',
+   *     hostUrl: 'https://example.com',
+   *     documentEle: document
+   *   }
+   * );
+   * ```
+   */
+  load = async (assets, options) => {
+    const elementIds = [];
+    const loadPromises = assets.map((fileName, index) => {
+      const url = new URL(fileName, options.hostUrl);
+      const id = `${APP_STYLE_ID_PREFIX}${options.name.toLowerCase()}-${index}`;
+      elementIds.push(id);
+      return this.#loadStyle({
+        id,
+        href: url.href,
+        documentEle: options.documentEle
+      });
+    });
+    await Promise.all(loadPromises);
+    return elementIds;
+  };
+  /**
+   * Removes a stylesheet link element from the document by its ID.
+   * @param elementId - The ID of the stylesheet element to remove (default: '')
+   * @param documentEle - The document object from which to remove the stylesheet (default: document)
+   * @returns A promise that resolves when the stylesheet element has been removed
+   * @remarks
+   * If the element with the specified ID is not found, a warning is logged but the promise still resolves.
+   * @example
+   * ```typescript
+   * await styleLoader.remove('ice-style-myapp-0', document);
+   * ```
+   */
   remove = (elementId = "", documentEle = document) => new Promise((resolve) => {
     const ele = documentEle.getElementById(elementId);
     if (!ele) {
@@ -61,6 +136,20 @@ class StyleLoader {
     ele.remove();
     resolve();
   });
+  /**
+   * Removes all stylesheet link elements from the document that match a specific host URL pattern.
+   * @param hostUrl - The host URL pattern to match against stylesheet hrefs
+   * @param documentEle - The document object from which to remove stylesheets
+   * @remarks
+   * This method queries all elements with `rel="stylesheet"` and removes any link whose `href`
+   * attribute matches the provided host URL pattern (case-insensitive). This is useful for
+   * cleaning up dynamically imported stylesheets from a specific host.
+   * The iteration happens in reverse order to safely remove elements while iterating.
+   * @example
+   * ```typescript
+   * styleLoader.removeDynamicImportedStyles('https://cdn.example.com', document);
+   * ```
+   */
   removeDynamicImportedStyles = (hostUrl, documentEle) => {
     const hostPattern = new RegExp(hostUrl, "i");
     const prefetchElements = documentEle.querySelectorAll('[rel="stylesheet"]');

package/dist/esm/appBridge.js

@@ -129,12 +129,14 @@ class CAppBridge {
    * @param param0.instanceId
    * @param elementIds
    * @param param0.documentEle
+   * @param param0.elementIds
    */
   #addAppToActiveAppList = ({
     id,
     instanceId,
-    documentEle
-  }, elementIds) => {
+    documentEle,
+    elementIds
+  }) => {
     const app = this.#appRegistry.get({ id, instanceId });
     if (!app) {
       throw new Error(this.#getAppNotFoundError(id, instanceId));
@@ -149,45 +151,6 @@ class CAppBridge {
       }
     });
   };
-  #waitAndInitApplication = (options, requests) => {
-    const {
-      id,
-      instanceId,
-      containerId,
-      name,
-      hostUrl,
-      manifestPath,
-      homeRoute,
-      initialRoute,
-      history,
-      theme,
-      documentEle
-    } = options;
-    return Promise.all(requests).then(
-      this.#addAppToActiveAppList.bind(null, { id, instanceId, documentEle })
-    ).then(
-      this.#initApplication.bind(null, {
-        id,
-        instanceId,
-        containerId,
-        name,
-        hostUrl,
-        manifestPath,
-        homeRoute,
-        initialRoute,
-        history,
-        theme
-      })
-    ).catch((err) => {
-      const message = `Application load failed. Unable to load one or more resources for ${options.id} with instance id ${instanceId}. ${err.message}`;
-      this.#logger.error({
-        message,
-        appId: id,
-        exception: err
-      });
-      throw new Error(message);
-    });
-  };
   #initApplication = async ({
     id,
     instanceId,
@@ -234,30 +197,49 @@ class CAppBridge {
     });
   };
   #loadApp = async (options) => {
-    const { id, instanceId, files, name, hostUrl, documentEle, isJsModule } = options;
-    this.#logger.debug(
-      `Application ${id} with instance id ${instanceId} is loading...`
-    );
-    let assets = files;
-    const manifest = await ManifestLoader.get(options);
-    assets = ManifestLoader.getFullFileNameofAssets(manifest, files);
-    let counter = 0;
-    const requests = assets.map((fileName) => {
-      counter += 1;
-      const resourceOptions = {
+    try {
+      const { id, instanceId, files, name, hostUrl, documentEle, isJsModule } = options;
+      this.#logger.debug(
+        `Application ${id} with instance id ${instanceId} is loading...`
+      );
+      let assets = files;
+      const manifest = await ManifestLoader.get(options);
+      assets = ManifestLoader.getFullFileNameofAssets(manifest, files);
+      const cssAssets = assets.filter((fileName) => isCss(fileName));
+      const jsAssets = assets.filter((fileName) => !isCss(fileName));
+      const loadOptions = {
         name,
         hostUrl,
         documentEle,
-        fileName,
-        index: counter,
-        isJsModule
+        isESMModule: isJsModule
       };
-      return !isCss(fileName) ? this.#scriptLoader.add(resourceOptions) : this.#styleLoader.add(resourceOptions);
-    });
-    await this.#waitAndInitApplication(options, requests);
-    this.#logger.audit(
-      `Application ${id} with instance id ${instanceId} loaded`
-    );
+      const styleElementIds = await this.#styleLoader.load(
+        cssAssets,
+        loadOptions
+      );
+      const scriptElementIds = await this.#scriptLoader.load(
+        jsAssets,
+        loadOptions
+      );
+      this.#addAppToActiveAppList({
+        id,
+        instanceId,
+        documentEle,
+        elementIds: [...styleElementIds, ...scriptElementIds]
+      });
+      await this.#initApplication(options);
+      this.#logger.audit(
+        `Application ${id} with instance id ${instanceId} loaded`
+      );
+    } catch (err) {
+      const message = `Application load failed. Unable to load one or more resources for ${options.id} with instance id ${options.instanceId}. ${err.message}`;
+      this.#logger.error({
+        message,
+        appId: options.id,
+        exception: err
+      });
+      throw new Error(message);
+    }
   };
   #unloadApp = ({ id, instanceId, hostUrl, documentEle }) => {
     this.#logger.debug(

package/dist/esm/index.html

@@ -6,7 +6,7 @@
     <meta name="viewport" content="width=device-width, initial-scale=1.0" />
     <title>Host</title>
     <script src="https://cdn.tailwindcss.com?plugins=forms"></script>
-    <script src="https://cdn.qa1.ice.com/pui-diagnostics@3" ></script>
+    <script src="https://cdn.mortgagetech.q1.ice.com/pui-diagnostics@3" ></script>
   </head>
   <body>
     <header class="bg-indigo-300 h-10 flex place-items-center">

package/dist/esm/index.js

@@ -1,9 +1,13 @@
 import { SecurityContext } from "./typings/common.js";
 import { Event, ScriptingObject } from "@elliemae/microfe-common";
 import { CAppBridge } from "./appBridge.js";
+import { ScriptLoader } from "./loaders/script.js";
+import { StyleLoader } from "./loaders/style.js";
 export {
   CAppBridge,
   Event,
+  ScriptLoader,
   ScriptingObject,
-  SecurityContext
+  SecurityContext,
+  StyleLoader
 };