feat(masthead): spacing style regression fix and maintainability refactor (#11252)

## Related Ticket(s)

Resolves #11251 

## Description

This PR mostly refactors masthead source code to be more maintainable and removes dead code. Other than the style fixes, it should result in no visible changes to the masthead.

## Changelog

### Styles
#### Changed
- Makes necessary functions available to Sass stylesheets to fix style regressions.

#### Removed
- Removes Cloud-specific masthead styles.
---
### Services Store
#### Changed
- Deprecates `MastheadProfileContent` type.
- Deprecates `Translation.mastheadNav` in favor of `Translation.masthead.nav`.
- Deprecates `Translation.profileMenu` in favor of `Translation.masthead.profileMenu`.

#### Removed
- Removes references to v1 data structures that are no longer in use.
---
### IBM.com Web Components
#### Changed
- Deprecates the `navLinks` Masthead Composite property in favor of the more descriptive `l0Data` property.
- Splits out the Masthead Composite's main `render` method into more digestible render methods per logical section.
- Untangles the knot that was the `renderNavItems` method by providing dedicated `renderTopNav` and `renderLeftNav` methods for the desktop and mobile experiences.
- Extracts distinct chunks of logic into their own methods for readability and in some cases reuse across the newly split render methods.

#### Removed
- Removes Cloud-specific masthead.
- Removes non-functional `customNavLinks` property. Use `l0Data` or `l1Data` instead.
- Removes masthead v1's leftover CTA functionality.

Author: jkaeser

packages/services-store/src/actions/__tests__/translateAPI.test.ts

@@ -38,14 +38,10 @@ const mockTranslation: Partial<Translation> = {
       },
       {
         title: 'menu-title-foo',
-        menuSections: [
+        submenu: [
           {
-            menuItems: [
-              {
-                title: 'menu-item-title-bar',
-                url: 'https://carbon-design-system.github.io/carbon-for-ibm-dotcom/canary/web-components/bar',
-              },
-            ],
+            title: 'menu-item-title-bar',
+            url: 'https://carbon-design-system.github.io/carbon-for-ibm-dotcom/canary/web-components/bar',
           },
         ],
       },
@@ -54,7 +50,7 @@ const mockTranslation: Partial<Translation> = {
 };
 
 const endpoint =
-  '/common/carbon-for-ibm-dotcom/translations/masthead-footer/v2';
+  '/common/carbon-for-ibm-dotcom/translations/masthead-footer/v2.1';
 
 describe('Redux actions for `TranslateAPI`', () => {
   it('dispatches the action to set translation data', () => {

packages/services-store/src/reducers/__tests__/translateAPI.test.ts

@@ -25,14 +25,10 @@ const mockTranslation: Partial<Translation> = {
       },
       {
         title: 'menu-title-foo',
-        menuSections: [
+        submenu: [
           {
-            menuItems: [
-              {
-                title: 'menu-item-title-bar',
-                url: 'https://carbon-design-system.github.io/carbon-for-ibm-dotcom/canary/web-components/bar',
-              },
-            ],
+            title: 'menu-item-title-bar',
+            url: 'https://carbon-design-system.github.io/carbon-for-ibm-dotcom/canary/web-components/bar',
           },
         ],
       },

packages/services-store/src/types/translateAPI.ts

@@ -1,7 +1,7 @@
 /**
  * @license
  *
- * Copyright IBM Corp. 2020, 2023
+ * Copyright IBM Corp. 2020, 2024
  *
  * This source code is licensed under the Apache-2.0 license found in the
  * LICENSE file in the root directory of this source tree.
@@ -29,69 +29,29 @@ export interface BasicLinkSet {
   links: BasicLink[];
 }
 
-/**
- * A feature in mega panel.
- */
-export interface MegapanelFeature {
-  heading?: string;
-  imageUrl?: string;
-  linkTitle?: string;
-  linkUrl?: string;
-}
-
-/**
- * A content in mega panel.
- */
-export interface MegapanelContent {
-  headingTitle?: string;
-  headingUrl?: string;
-  description?: string;
-  quickLinks: BasicLinkSet;
-  feature: MegapanelFeature;
+export interface L0Menu {
+  items: L0MenuItem[];
 }
 
-/**
- * A menu item in masthead.
- */
-export interface MastheadMenuItem {
-  title: string;
-  titleEnglish?: string;
-  url?: string;
-  highlighted?: boolean;
-  megaPanelViewAll?: boolean;
-  megapanelContent?: MegapanelContent;
+export interface L0MenuItem extends BasicLink {
+  submenu?: L0Megamenu | BasicLink[];
 }
 
-/**
- * A menu section in masthead.
- */
-export interface MastheadMenuSection {
-  heading?: string;
-  menuItems: MastheadMenuItem[];
+export interface L0Megamenu {
+  sections: Megapanel[];
+  highlights?: MegapanelLinkGroup[];
+  viewAll?: BasicLink;
 }
 
-/**
- * An item in masthead.
- */
-export interface MastheadLink {
-  title: string;
-  titleEnglish?: string;
-  url?: string;
-  hasMenu?: boolean;
-  hasMegapanel?: boolean;
-  megamenuLayout?: 'tab' | 'list';
-  menuSections?: MastheadMenuSection[];
+export interface Megapanel {
+  heading?: BasicLink;
+  groups: MegapanelLinkGroup[];
+  viewAll?: BasicLink;
 }
 
-/**
- * A menu section for masthead
- *
- * @deprecated
- */
-export interface LegacyMastheadL1 {
-  title: string;
-  url?: string;
-  menuItems?: MastheadLink[];
+export interface MegapanelLinkGroup {
+  heading?: BasicLink;
+  links?: BasicLink[];
 }
 
 /**
@@ -176,12 +136,13 @@ export interface MastheadLogoData {
 
 /**
  * Cloud Masthead Profile content
+ *
+ * @deprecated
  */
 export interface MastheadProfileContent {
   iconLabel: string;
   links: MastheadProfileItem[];
   ctaButtons: MastheadProfileItem[];
-  contactUsButton: string;
 }
 
 /**
@@ -194,11 +155,16 @@ export interface MiscLabels {
  * The translation data for ibm.com sites
  */
 export interface Translation {
+  /**
+   * Main masthead navigation data.
+   *
+   * @deprecated Use masthead.nav instead.
+   */
   mastheadNav: {
     /**
      * The nav links.
      */
-    links: MastheadLink[];
+    links: L0MenuItem[];
   };
 
   /**
@@ -211,8 +177,25 @@ export interface Translation {
    */
   footerThin: BasicLink[];
 
+  /**
+   * Masthead items other than main navigation
+   */
+  masthead: {
+    logo: MastheadLogoData;
+    nav: L0MenuItem[];
+    contact: MastheadProfileItem;
+    profileMenu: {
+      unauthenticated: MastheadProfileItem[];
+      authenticated: MastheadProfileItem[];
+      signedin: MastheadProfileContent;
+      signedout: MastheadProfileContent;
+    };
+  };
+
   /**
    * The profile menus.
+   *
+   * @deprecated Use masthead.profileMenu instead.
    */
   profileMenu: {
     /**
@@ -226,18 +209,6 @@ export interface Translation {
     signedout: MastheadProfileItem[];
   };
 
-  /**
-   * Cloud masthead items
-   */
-  masthead: {
-    logo: MastheadLogoData;
-    contact: MastheadProfileContent;
-    profileMenu: {
-      signedout: MastheadProfileContent;
-      signedin: MastheadProfileContent;
-    };
-  };
-
   /**
    * Miscellaneous translations
    */
@@ -296,29 +267,3 @@ export interface TranslateAPIState {
    */
   errorsRequestTranslation?: { [language: string]: Error };
 }
-
-// New for v2.1.0
-export interface L0Menu {
-  items: L0MenuItem[];
-}
-
-export interface L0MenuItem extends BasicLink {
-  submenu?: L0Megamenu | BasicLink[];
-}
-
-export interface L0Megamenu {
-  sections: Megapanel[];
-  highlights?: MegapanelLinkGroup[];
-  viewAll?: BasicLink;
-}
-
-export interface Megapanel {
-  heading?: BasicLink;
-  groups: MegapanelLinkGroup[];
-  viewAll?: BasicLink;
-}
-
-export interface MegapanelLinkGroup {
-  heading?: BasicLink;
-  links?: BasicLink[];
-}

packages/styles/scss/components/masthead/_masthead-l1.scss

@@ -13,6 +13,7 @@
 @use '@carbon/styles/scss/themes' as *;
 @use '@carbon/styles/scss/type' as *;
 @use '@carbon/styles/scss/utilities' as *;
+@use '@carbon/styles/scss/utilities/convert' as *;
 @use '@carbon/styles/scss/components/button/tokens' as *;
 @use '../../globals/vars' as *;
 @use 'vars' as *;

packages/styles/scss/components/masthead/_masthead-megamenu.scss

@@ -12,6 +12,7 @@
 @use '@carbon/styles/scss/theme' as *;
 @use '@carbon/styles/scss/type' as *;
 @use '@carbon/styles/scss/utilities' as *;
+@use '@carbon/styles/scss/utilities/convert' as *;
 @use '../../globals/utils/flex-grid' as *;
 @use '../../globals/vars' as *;
 
@@ -78,7 +79,6 @@
     .#{$prefix}--header__menu-title[aria-expanded='false']
       + .#{$prefix}--header__menu {
       ::slotted(#{$c4d-prefix}-megamenu),
-      ::slotted(#{$c4d-prefix}-cloud-megamenu),
       .#{$prefix}--masthead__megamenu {
         animation: $transition-expansion motion(standard, expressive) collapse;
       }
@@ -99,7 +99,6 @@
       visibility: visible;
 
       ::slotted(#{$c4d-prefix}-megamenu),
-      ::slotted(#{$c4d-prefix}-cloud-megamenu),
       .#{$prefix}--masthead__megamenu {
         animation: $transition-expansion motion(standard, expressive) expand;
       }
@@ -121,7 +120,6 @@
   }
 
   :host(#{$c4d-prefix}-megamenu),
-  :host(#{$c4d-prefix}-cloud-megamenu),
   .#{$prefix}--masthead__megamenu {
     @include box-shadow;
     --#{$c4d-prefix}-masthead-max-height: calc(

packages/styles/scss/components/masthead/_masthead.scss

@@ -17,7 +17,9 @@
 @use '@carbon/styles/scss/theme' as *;
 @use '@carbon/styles/scss/themes' as *;
 @use '@carbon/styles/scss/type' as *;
+@use '@carbon/styles/scss/layout' as layout;
 @use '@carbon/styles/scss/utilities' as *;
+@use '@carbon/styles/scss/utilities/convert' as *;
 @use '../../globals/vars' as *;
 @use '../link-with-icon';
 @use 'vars' as *;
@@ -266,8 +268,9 @@
   }
 
   :host(#{$c4d-prefix}-masthead-composite),
-  :host(#{$c4d-prefix}-masthead-container),
-  :host(#{$c4d-prefix}-cloud-masthead-container) {
+  :host(#{$c4d-prefix}-masthead-container) {
+    @include layout.emit-layout-tokens();
+
     position: relative;
     z-index: 900;
     display: block;

packages/utilities/src/utilities/StickyHeader/StickyHeader.js

@@ -1,5 +1,5 @@
 /**
- * Copyright IBM Corp. 2016, 2023
+ * Copyright IBM Corp. 2016, 2024
  *
  * This source code is licensed under the Apache-2.0 license found in the
  * LICENSE file in the root directory of this source tree.

packages/web-components/.env.example

@@ -19,4 +19,3 @@ KALTURA_UICONF_ID=<Kaltura uiconf id, e.g. 12905712>
 
 # Feature Flags
 C4D_FLAGS_ALL=<Boolean flag to turn on all feature flags>
-C4D_CLOUD_MASTHEAD=<Boolean flag to turn on/off cloud masthead>