feat(Megamenu): react megamenu updates for HC & AI (carbon-design-sys…

…tem#5043)

### Related Ticket(s)

React stand alone: Change Mega Menu HC + AI updates component carbon-design-system#4653

### Description

**NOTE** please merge in the web components version first: carbon-design-system#5016 as this branch is based off that one!

HC & AI updates for the Megamenu

You can view the changes in the `Custom Data` story under Masthead

<img width="1615" alt="Screen Shot 2021-01-29 at 7 17 16 PM" src="https://user-images.githubusercontent.com/54281166/106340611-61b05900-6268-11eb-9f6c-cd51048b0abf.png">

<img width="341" alt="Screen Shot 2021-01-29 at 7 16 53 PM" src="https://user-images.githubusercontent.com/54281166/106340606-5f4dff00-6268-11eb-9644-2c82f2bc19f2.png">


### Changelog

**New**

- added necessary data to the `Custom Navigation` masthead story so we can view the design updates
- heading and description copy passed to `Megamenu`

**Changed**

- calculate how many highlighted menu items there are and set a classname to the last highlighted menu item to set border for mobile nav

<!-- React and Web Component deploy previews are enabled by default. -->
<!-- To enable additional available deploy previews, apply the following -->
<!-- labels for the corresponding package: -->
<!-- *** "package: services": Services -->
<!-- *** "package: utilities": Utilities -->
<!-- *** "package: styles": Carbon Expressive -->
<!-- *** "RTL": React / Web Components (RTL) -->
<!-- *** "feature flag": React / Web Components (experimental) -->

packages/react/src/components/Masthead/MastheadLeftNav.js

@@ -87,6 +87,7 @@ const MastheadLeftNav = ({
           autoid={autoid}
           selected={selected}
           navType={rest.navType}
+          heading={link.menuSections[0]?.heading}
           dataTitle={dataTitle}>
           {renderNavSections(
             link.menuSections,
@@ -180,17 +181,32 @@ const preventOutFocus = (target, isSideNavExpanded) => {
 function renderNavSections(sections, backButtonText, autoid, navType) {
   const sectionItems = [];
   sections.forEach(section => {
-    section.menuItems.forEach((item, j) => {
-      const dataAutoId = `${autoid}-list${j}`;
+    // get array of highlighted menu items to render first
+    let highlightedItems = [];
+    const menu = [];
+
+    section.menuItems.forEach(item => {
+      if (item.highlighted) return highlightedItems.push(item);
+      return menu.push(item);
+    });
+
+    const menuItems = highlightedItems.concat(menu);
+    const highlightedCount = highlightedItems.length;
+
+    menuItems.forEach((item, k) => {
+      const dataAutoId = `${autoid}-list${k}`;
       if (item.megapanelContent) {
         sectionItems.push(
           <SideNavMenuWithBackFoward
             title={item.title}
             titleUrl={item.url}
+            lastHighlighted={
+              highlightedCount !== 0 && k + 1 === highlightedCount
+            }
             backButtonText={backButtonText}
             autoid={dataAutoId}
             navType={navType}
-            key={j}>
+            key={k}>
             {renderNavItem(item.megapanelContent.quickLinks.links, dataAutoId)}
             <button
               className={`${prefix}--masthead__focus`}
@@ -207,24 +223,26 @@ function renderNavSections(sections, backButtonText, autoid, navType) {
         sectionItems.push(
           <SideNavMenuItem
             href={item.url}
+            className={
+              highlightedCount !== 0 &&
+              k + 1 === highlightedCount &&
+              `${prefix}--masthead__side-nav__last-highlighted`
+            }
             data-autoid={dataAutoId}
             key={item.title}>
             {item.title}
           </SideNavMenuItem>
         );
       }
-
-      if (j === section.menuItems.length - 1) {
-        sectionItems.push(
-          <button
-            className={`${prefix}--masthead__focus`}
-            onFocus={e => {
-              preventOutFocus(e.target.parentElement.querySelector('a'), true);
-            }}
-            aria-hidden={true}></button>
-        );
-      }
     });
+    sectionItems.push(
+      <button
+        className={`${prefix}--masthead__focus`}
+        onFocus={e => {
+          preventOutFocus(e.target.parentElement.querySelector('a'), true);
+        }}
+        aria-hidden={true}></button>
+    );
   });
 
   return sectionItems;

packages/react/src/components/Masthead/MastheadMegaMenu/CategoryLink.js

@@ -1,9 +1,11 @@
 /**
- * Copyright IBM Corp. 2016, 2020
+ * Copyright IBM Corp. 2016, 2021
  *
  * This source code is licensed under the Apache-2.0 license found in the
  * LICENSE file in the root directory of this source tree.
  */
+import ArrowRight16 from '@carbon/icons-react/es/arrow--right/16';
+import { LinkWithIcon } from '../../LinkWithIcon';
 import PropTypes from 'prop-types';
 import React from 'react';
 import settings from 'carbon-components/es/globals/js/settings';
@@ -13,15 +15,28 @@ const { prefix } = settings;
 /**
  * Category sublink
  */
-const CategoryLink = ({ href, title, ...rest }) => (
-  <a
-    tabIndex={0}
-    href={href}
-    className={`${prefix}--masthead__megamenu__category-sublink`}
-    data-autoid={`${rest.autoid}-item${rest.index}`}>
-    {title}
-  </a>
-);
+const CategoryLink = ({ href, title, highlighted, ...rest }) => {
+  return (
+    <>
+      {highlighted ? (
+        <LinkWithIcon
+          className={`${prefix}--masthead__megamenu__category-sublink--highlighted`}
+          href={href}>
+          <span>{title}</span>
+          <ArrowRight16 />
+        </LinkWithIcon>
+      ) : (
+        <a
+          tabIndex={0}
+          href={href}
+          className={`${prefix}--masthead__megamenu__category-sublink`}
+          data-autoid={`${rest.autoid}-item${rest.index}`}>
+          {title}
+        </a>
+      )}
+    </>
+  );
+};
 
 CategoryLink.propTypes = {
   /**
@@ -33,6 +48,11 @@ CategoryLink.propTypes = {
    * Category sublink text
    */
   title: PropTypes.string.isRequired,
+
+  /**
+   * Determines whether to render regular link style or link with icon
+   */
+  highlighted: PropTypes.bool,
 };
 
 export default CategoryLink;

packages/react/src/components/Masthead/MastheadMegaMenu/MegaMenu.js

@@ -11,6 +11,9 @@ import NavigationGroup from './NavigationGroup';
 import PropTypes from 'prop-types';
 import React from 'react';
 import RightNavigation from './RightNavigation';
+import settings from 'carbon-components/es/globals/js/settings';
+
+const { prefix } = settings;
 
 /**
  * Masthead megamenu component.
@@ -28,21 +31,32 @@ const MegaMenu = ({ data, ...rest }) => {
 
   const hasHighlights = highlightedItems.length !== 0;
 
+  const heading = data.menuSections[0]?.heading;
+
   return (
     <NavigationGroup>
       {hasHighlights && (
         <LeftNavigation>
+          {heading && (
+            <p className={`${prefix}--masthead__megamenu__copy`}>{heading}</p>
+          )}
           {highlightedItems.map((item, i) => (
             <CategoryGroup
               autoid={rest.autoid}
               key={i}
               href={item.url}
               title={item.title}>
+              {item.megapanelContent?.description && (
+                <p className={`${prefix}--masthead__megamenu__copy`}>
+                  {item.megapanelContent?.description}
+                </p>
+              )}
               {item.megapanelContent?.quickLinks?.links.map(
-                ({ title, url }, key) => (
+                ({ title, url, highlightedLink }, key) => (
                   <CategoryLink
                     href={url}
                     title={title}
+                    highlighted={highlightedLink}
                     autoid={`${rest.autoid}-list${i}`}
                     key={key}
                   />