feat(Masthead): React masthead alternate logo and tooltip options (#4401

)

### Related Ticket(s)

#3906  

### Description

The masthead now accepts an optional logo options from IBM.com translation files which allows the setting of an alternate IBM logo to use, as well as an optional tooltip when the icon is hovered over. When an alternate logo is used, settings include an expiration date and allow/deny lists for controlling paths on which it can be displayed. The tooltip can be used with both default and alternate logos.

### Changelog

**New**

- `MastheadLogo` service to determine whether an alternate logo can be used based on values passed in the object
- React `Masthead` component now accepts options from IBM.com translations for an alternate logo and tooltip
- internal `ConditionalWrapper` component 

**Changed**

- add masthead logo svg dimension styles


<!-- 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/Icon/IbmLogo.js

@@ -5,23 +5,47 @@
  * LICENSE file in the root directory of this source tree.
  */
 
+import ConditionalWrapper from '../../internal/components/ConditionalWrapper/ConditionalWrapper';
 import MastheadLogo from '@carbon/ibmdotcom-styles/icons/svg/IBM-8bar-logo--h23.svg';
+import MastheadLogoAPI from '@carbon/ibmdotcom-services/es/services/MastheadLogo/MastheadLogo';
 import PropTypes from 'prop-types';
 import React from 'react';
 import settings from 'carbon-components/es/globals/js/settings';
+import TooltipDefinition from '../../internal/vendor/carbon-components-react/components/TooltipDefinition';
 
 const { prefix } = settings;
 
 /**
  * IBM Logo 8-bar component.
  */
-const IbmLogo = ({ autoid }) => (
-  <div className={`${prefix}--header__logo`}>
-    <a aria-label="IBM®" data-autoid={autoid} href="https://www.ibm.com/">
-      <MastheadLogo />
-    </a>
-  </div>
-);
+const IbmLogo = ({ autoid, logoData }) => {
+  const useAlternateLogo = MastheadLogoAPI.setMastheadLogo(logoData);
+
+  return (
+    <div className={`${prefix}--header__logo`}>
+      <ConditionalWrapper
+        condition={logoData && logoData.tooltip !== undefined}
+        wrapper={children => (
+          <TooltipDefinition tooltipText={logoData.tooltip}>
+            {children}
+          </TooltipDefinition>
+        )}>
+        {useAlternateLogo ? (
+          <a // eslint-disable-line
+            aria-label="IBM®"
+            data-autoid={autoid}
+            href={`http://www.ibm.com${logoData.path}`}
+            dangerouslySetInnerHTML={{ __html: logoData.svg }}
+          />
+        ) : (
+          <a aria-label="IBM®" data-autoid={autoid} href={`http://www.ibm.com`}>
+            {!useAlternateLogo && <MastheadLogo />}
+          </a>
+        )}
+      </ConditionalWrapper>
+    </div>
+  );
+};
 
 export default IbmLogo;
 
@@ -30,4 +54,18 @@ IbmLogo.propTypes = {
    * data-autoid attribute for analytics
    */
   autoid: PropTypes.string,
+
+  /**
+   * Masthead logo object
+   * See [mastheadLogo](#mastheadlogo)
+   * for details.
+   */
+  logoData: PropTypes.shape({
+    svg: PropTypes.string,
+    tooltip: PropTypes.string,
+    denyList: PropTypes.array,
+    allowList: PropTypes.array,
+    expire: PropTypes.string,
+    path: PropTypes.string,
+  }),
 };

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

@@ -97,6 +97,7 @@ const Masthead = ({
   }, []);
 
   let [mastheadData, setMastheadData] = useState([]);
+  const [logo, setlogo] = useState([]);
   const [profileData, setProfileData] = useState({
     signedin: [],
     signedout: [],
@@ -110,6 +111,7 @@ const Masthead = ({
         if (!unmounted) {
           setMastheadData(pageData.mastheadNav.links);
           setProfileData(pageData.profileMenu);
+          setlogo(pageData?.logo);
         }
       } catch (error) {
         console.error('Error populating masthead data:', error);
@@ -233,6 +235,7 @@ const Masthead = ({
                 )}
 
                 <IbmLogo
+                  logoData={logo}
                   autoid={`${stablePrefix}--masthead-${navType}__l0-logo`}
                 />
 

packages/react/src/components/Masthead/README.stories.mdx

@@ -168,11 +168,40 @@ This allows setting a user-defined login URL. This is currently an experimental
 feature. Please see the [feature flags](#feature-flags) section for usage
 information.
 
-In order to utilize this feature, the `profileMenu.signedout` login object must
+In order to use this feature, the `profileMenu.signedout` login object must
 contain an `id: signin` entry in the corresponding translation data file. See
 [here](https://github.ibm.com/webstandards/ibm-dotcom-translations/blob/master/translations/masthead-footer/jsononly/usen.json#L1467)
 for an example.
 
+## logo
+
+The masthead can display an alternate logo and a tooltip on hover. Additionally,
+the logo can be set with an expiration date, which will revert the logo to
+default when reached. There are also allow/deny lists to control on what paths
+an alternate logo can be displayed. Leaving the `allowList` array empty serves
+as a wildcard.
+
+Please note that the `svg` dimensions are set to `58px` x `23px` and will be
+used regardless of what the asset's width/height attributes are.
+
+This feature is available only from IBM.com translation files. To enable, the
+`masthead` object must contain a `logo` object with the following structure:
+
+```javascript
+"masthead": {
+  ...
+  "logo": {
+    svg: `<svg width="58" height="23"...></svg>`, // notice template literal
+    tooltip: "Lorem ipsum dolor sit amet, consectetur adipiscing elit.",
+    denylist: ["/example-path"],
+    allowlist: [], // leave empty for wildcard
+    end: "May 5, 2021 0:00:01",
+    path: "/", // URL path, e.g. /it-it
+  },
+  ...
+}
+```
+
 #### Feature Flags
 
 To utilize the following features, set the following variables to `true` within

packages/react/src/internal/components/ConditionalWrapper/ConditionalWrapper.js

@@ -0,0 +1,53 @@
+/**
+ * Copyright IBM Corp. 2016, 2020
+ *
+ * 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 PropTypes from 'prop-types';
+
+/**
+ * Conditional wrapper internal component
+ *
+ * @param {object} props React props object
+ * @param {boolean} props.condition whether to use wrapper
+ * @param {*} props.wrapper JSX components
+ * @param {*} props.children element(s)
+ * @returns {*} JSX element
+ *
+ * @example
+ * import ConditionalWrapper from '../../internal/components/ConditionalWrapper/ConditionalWrapper';
+ *
+ * const example = ({ link, copy }) => {
+ *   return (
+ *     <ConditionalWrapper
+ *       condition={link}
+ *       wrapper={children => <a href={link}>{children}</a>}
+ *     >
+ *       <p>{children}</p>
+ *     </ConditionalWrapper>
+ *   );
+ * }
+ */
+const ConditionalWrapper = ({ condition, wrapper, children }) =>
+  condition ? wrapper(children) : children;
+
+ConditionalWrapper.propTypes = {
+  /**
+   * Condition whether to use wrapper or not
+   */
+  condition: PropTypes.bool,
+
+  /**
+   * Wrapper element
+   */
+  wrapper: PropTypes.node,
+
+  /**
+   * Children elements
+   */
+  children: PropTypes.node,
+};
+
+export default ConditionalWrapper;

packages/services/src/services/MastheadLogo/MastheadLogo.js

@@ -0,0 +1,47 @@
+/**
+ * Copyright IBM Corp. 2016, 2020
+ *
+ * This source code is licensed under the Apache-2.0 license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+class MastheadLogoAPI {
+  /**
+   * Determines whether to return custom or default IBM logo
+   *
+   * @returns {boolean} Use alternate logo or not
+   *
+   * @example
+   * import { MastheadLogoAPI } from '@carbon/ibmdotcom-services';
+   *
+   * const useAlternateLogo = MastheadLogoAPI.setMastheadLogo(logoData);
+   */
+  static setMastheadLogo(logoData) {
+    if (logoData === undefined) return false;
+
+    const currentTime = new Date().getTime();
+    const expireTime = logoData.expire
+      ? new Date(logoData.expire).getTime()
+      : null;
+    const isExpired = expireTime && currentTime > expireTime ? true : false;
+
+    if (
+      logoData.svg === null ||
+      isExpired ||
+      (logoData.denylist && logoData.denylist.indexOf(location.pathname) !== -1)
+    ) {
+      return false;
+    } else if (
+      logoData.allowlist &&
+      (logoData.allowlist.length == 0 ||
+        logoData.allowlist.indexOf(location.pathname) !== -1) &&
+      logoData.svg
+    ) {
+      return true;
+    } else {
+      return false;
+    }
+  }
+}
+
+export default MastheadLogoAPI;

packages/services/src/services/MastheadLogo/index.js

@@ -0,0 +1,8 @@
+/**
+ * Copyright IBM Corp. 2016, 2020
+ *
+ * This source code is licensed under the Apache-2.0 license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+export { default as MastheadLogo } from './MastheadLogo';

packages/services/src/services/index.js

@@ -1,5 +1,5 @@
 /**
- * Copyright IBM Corp. 2016, 2018
+ * Copyright IBM Corp. 2016, 2020
  *
  * This source code is licensed under the Apache-2.0 license found in the
  * LICENSE file in the root directory of this source tree.
@@ -10,6 +10,7 @@ export * from './DDO';
 export * from './global';
 export * from './Locale';
 export * from './MarketingSearch';
+export * from './MastheadLogo';
 export * from './Profile';
 export * from './SearchTypeahead';
 export * from './Translation';

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

@@ -49,6 +49,24 @@ $search-transition-timing: 95ms;
     @include carbon--breakpoint-down(lg) {
       padding: 0 $carbon--spacing-05;
     }
+
+    svg {
+      width: 58px;
+      height: 23px;
+    }
+  }
+
+  .#{$prefix}--tooltip__trigger.#{$prefix}--tooltip__trigger--definition,
+  .#{$prefix}--tooltip--definition {
+    .#{$prefix}--tooltip__trigger {
+      border: none;
+    }
+
+    border: none;
+
+    &.#{$prefix}--tooltip--a11y {
+      height: 100%;
+    }
   }
 }
 

packages/styles/scss/components/masthead/index.scss

@@ -8,6 +8,7 @@
 @import '../../globals/vars';
 @import '../../globals/imports';
 @import 'carbon-components/scss/components/overflow-menu/overflow-menu';
+@import 'carbon-components/scss/components/tooltip/tooltip';
 @import 'carbon-components/scss/components/ui-shell/ui-shell';
 @import 'carbon-components/scss/components/ui-shell/side-nav';
 @import '../link-with-icon/link-with-icon';