feat(masthead-contact): improve interactions with contact module (#9902)

### Related Ticket(s)

Closes #9369

[ADCMS-2602](https://jsw.ibm.com/browse/ADCMS-2602)

### Description

- Masthead container adds an event listener to the Document for `cm-app-ready` from the Contact Module ([source](https://github.ibm.com/live-advisor/cm-app/blob/943dfbcac5b8efde05a00c4c5558947495f96a58/js/helpers/documentEvents.js#L7))
- Stores reference to `window.CM_APP` internally to DDSMastheadContainer
- Uses internal reference to CM_APP to close with `.init()` method

### Changelog

**Changed**

- Improved UX between masthead and contact module

packages/web-components/src/components/dotcom-shell/__stories__/dotcom-shell.stories.ts

@@ -1,7 +1,7 @@
 /**
  * @license
  *
- * Copyright IBM Corp. 2020, 2022
+ * Copyright IBM Corp. 2020, 2023
  *
  * This source code is licensed under the Apache-2.0 license found in the
  * LICENSE file in the root directory of this source tree.
@@ -1208,7 +1208,23 @@ export default {
           }
         });
       }
-      return story();
+      return html`
+        ${story()}
+        <script>
+          window.digitalData.page.pageInfo.ibm.contactModuleConfiguration = {
+            contactInformationBundleKey: {
+              focusArea: 'Cloud - Automation - All',
+              languageCode: 'en',
+              regionCode: 'US',
+            },
+            contactModuleTranslationKey: {
+              languageCode: 'en',
+              regionCode: 'US',
+            },
+          };
+        </script>
+        <script src="//www.ibm.com/common/digitaladvisor/cm-app/latest/cm-app.min.js" defer></script>
+      `;
     },
   ],
   parameters: {

packages/web-components/src/components/masthead/__stories__/masthead.stories.ts

@@ -532,7 +532,23 @@ export default {
           }
         });
       }
-      return story();
+      return html`
+        ${story()}
+        <script>
+          window.digitalData.page.pageInfo.ibm.contactModuleConfiguration = {
+            contactInformationBundleKey: {
+              focusArea: 'Cloud - Automation - All',
+              languageCode: 'en',
+              regionCode: 'US',
+            },
+            contactModuleTranslationKey: {
+              languageCode: 'en',
+              regionCode: 'US',
+            },
+          };
+        </script>
+        <script src="//www.ibm.com/common/digitaladvisor/cm-app/latest/cm-app.min.js" defer></script>
+      `;
     },
   ],
   parameters: {

packages/web-components/src/components/masthead/masthead-composite.ts

@@ -1,7 +1,7 @@
 /**
  * @license
  *
- * Copyright IBM Corp. 2020, 2022
+ * Copyright IBM Corp. 2020, 2023
  *
  * This source code is licensed under the Apache-2.0 license found in the
  * LICENSE file in the root directory of this source tree.
@@ -79,6 +79,27 @@ export enum NAV_ITEMS_RENDER_TARGET {
   LEFT_NAV = 'left-nav',
 }
 
+/**
+ * Globally-scoped Contact Module variable.
+ *
+ * @see https://github.ibm.com/live-advisor/cm-app
+ */
+export interface CMApp {
+  version: string;
+  ready: boolean;
+  init: Function;
+  refresh: Function;
+  register: Function;
+  deregister: Function;
+  fireEvent: Function;
+  update: Function;
+  props: {
+    eventHandlers: any;
+    events: CustomEvent[];
+    getLoadedBundle: Function;
+  };
+}
+
 /**
  * Component that renders masthead from links, etc. data.
  *
@@ -724,6 +745,18 @@ class DDSMastheadComposite extends HostListenerMixin(LitElement) {
     resolveFn();
   };
 
+  /**
+   * Stores a reference of the globally-scoped CM_APP object within the masthead.
+   */
+  @HostListener('document:cm-app-ready')
+  // @ts-ignore: The decorator refers to this method but TS thinks this method is not referred to
+  protected _getContactModuleReference = () => {
+    // @ts-ignore: CM_APP will definitely exist if this event is fired
+    this.contactModuleApp = window.CM_APP;
+  };
+
+  contactModuleApp?: CMApp;
+
   /**
    * Whether or not a nav item has automatically been designated as "selected".
    *

packages/web-components/src/components/masthead/masthead-contact.ts

@@ -1,7 +1,7 @@
 /**
  * @license
  *
- * Copyright IBM Corp. 2022
+ * Copyright IBM Corp. 2022, 2023
  *
  * This source code is licensed under the Apache-2.0 license found in the
  * LICENSE file in the root directory of this source tree.
@@ -14,6 +14,8 @@ import Chat20 from 'carbon-web-components/es/icons/chat/20.js';
 import ddsSettings from '../../internal/vendor/@carbon/ibmdotcom-utilities/utilities/settings/settings';
 import styles from './masthead.scss';
 import DDSMastheadProfile from './masthead-profile';
+import DDSMastheadContainer from './masthead-container';
+import { CMApp } from './masthead-composite';
 
 const { prefix } = settings;
 const { stablePrefix: ddsPrefix } = ddsSettings;
@@ -45,6 +47,23 @@ class DDSMastheadContact extends DDSMastheadProfile {
     `;
   }
 
+  updated(changedProperties) {
+    if (changedProperties.has('expanded')) {
+      if (!this.expanded) {
+        const mastheadContainer = this.closest(`${ddsPrefix}-masthead-container`) as DDSMastheadContainer;
+
+        /**
+         * This is a workaround to minimize the chat module. Currently no minimize methods exist.
+         *
+         * @see https://github.ibm.com/live-advisor/cm-app
+         */
+        if (mastheadContainer.contactModuleApp) {
+          (mastheadContainer.contactModuleApp as CMApp).init();
+        }
+      }
+    }
+  }
+
   static styles = styles; // `styles` here is a `CSSResult` generated by custom WebPack loader
 }
 

packages/web-components/src/components/masthead/megamenu-top-nav-menu.ts

@@ -1,7 +1,7 @@
 /**
  * @license
  *
- * Copyright IBM Corp. 2020, 2022
+ * Copyright IBM Corp. 2020, 2023
  *
  * This source code is licensed under the Apache-2.0 license found in the
  * LICENSE file in the root directory of this source tree.
@@ -16,6 +16,8 @@ import DDSTopNav from './top-nav';
 import DDSTopNavMenu from './top-nav-menu';
 import DDSMegaMenuOverlay from './megamenu-overlay';
 import styles from './masthead.scss';
+import DDSMastheadContainer from './masthead-container';
+import { CMApp } from './masthead-composite';
 
 const { prefix } = settings;
 const { stablePrefix: ddsPrefix } = ddsSettings;
@@ -168,6 +170,10 @@ class DDSMegaMenuTopNavMenu extends DDSTopNavMenu {
         (item as DDSMegaMenuOverlay).active = this.expanded;
       });
 
+      const mastheadContainer = this.closest(`
+        ${ddsPrefix}-masthead-container,
+        ${ddsPrefix}-cloud-masthead-container`) as DDSMastheadContainer;
+
       // add the scrollbar width as right-margin to prevent content from shifting when
       // scrollbar disappears on megamenu expand
       const masthead: HTMLElement | null | undefined = doc
@@ -181,6 +187,14 @@ class DDSMegaMenuTopNavMenu extends DDSTopNavMenu {
         ?.shadowRoot?.querySelector('.bx--masthead__l0');
 
       if (this.expanded) {
+        /**
+         * This is a workaround to minimize the chat module. Currently no minimize methods exist.
+         *
+         * @see https://github.ibm.com/live-advisor/cm-app
+         */
+        if (mastheadContainer.contactModuleApp) {
+          (mastheadContainer.contactModuleApp as CMApp).init();
+        }
         // Ask masthead-composite to render megamenu.
         // Pause further execution until the render is complete.
         await this._requestMegaMenuRenderUpdate();