feat(universal-banner): introducing component (#8237)

### Related Ticket(s)
#6814

### Description
Introducing the Universal Banner component, along with some scroll interactions between the Masthead, L1, and ToC mobile.

### Changelog

**New**

- new `universal-banner` component along with its child components

**Changed**

- scroll interaction algorithm in `dotcom-shell-composite`

<!-- 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 -->
<!-- *** "RTL": React / Web Components (RTL) -->
<!-- *** "feature flag": React / Web Components (experimental) -->

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

@@ -188,6 +188,10 @@ $search-transition-timing: 95ms;
     transition-timing-function: $search-transition;
     transition-duration: 300ms;
     background-color: $ui-background;
+
+    &[with-banner] {
+      top: $spacing-13;
+    }
   }
 
   :host(#{$dds-prefix}-megamenu-overlay),

packages/styles/scss/components/universal-banner/_universal-banner.scss

@@ -0,0 +1,274 @@
+//
+// Copyright IBM Corp. 2019, 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 '../../globals/imports';
+@import '../../globals/vars';
+
+:host(#{$dds-prefix}-universal-banner) {
+  @include carbon--theme($carbon--theme--g100, true);
+
+  display: block;
+  background-color: $ui-background;
+
+  .#{$prefix}--universal-banner-layout-container {
+    display: grid;
+    grid-template-rows: 1fr;
+
+    margin: 0 auto;
+    max-width: 99rem;
+
+    background-color: $ui-background;
+    max-height: $spacing-13;
+
+    @include carbon--breakpoint('md') {
+      grid-template-columns: 2fr 1fr;
+    }
+  }
+
+  .#{$prefix}--universal-banner-text-container,
+  .#{$prefix}--universal-banner-cta-container {
+    padding-top: $spacing-05;
+    padding-bottom: $spacing-05;
+
+    @include carbon--breakpoint('lg') {
+      padding-top: $spacing-07;
+      padding-bottom: $spacing-07;
+    }
+  }
+
+  .#{$prefix}--universal-banner-image-container {
+    max-height: $spacing-13;
+  }
+
+  &[has-image] {
+    ::slotted(#{$dds-prefix}-image) {
+      height: $spacing-13;
+    }
+
+    .#{$prefix}--universal-banner-layout-container {
+      @include carbon--breakpoint('sm') {
+        grid-template-columns: 1fr;
+
+        .#{$prefix}--universal-banner-text-container {
+          margin-left: $spacing-05;
+        }
+
+        .#{$prefix}--universal-banner-image-container {
+          display: none;
+        }
+      }
+
+      @include carbon--breakpoint('md') {
+        grid-template-columns: 2fr 1fr;
+
+        .#{$prefix}--universal-banner-text-container {
+          margin-left: $spacing-07;
+        }
+      }
+    }
+
+    &[image-width='4-col'] {
+      .#{$prefix}--universal-banner-layout-container {
+        @include carbon--breakpoint('lg') {
+          grid-template-columns: 1fr 2fr 1fr;
+
+          .#{$prefix}--universal-banner-image-container {
+            display: block;
+            margin-right: $spacing-03;
+          }
+
+          .#{$prefix}--universal-banner-text-container {
+            margin-left: $spacing-06;
+          }
+
+          .#{$prefix}--universal-banner-cta-container {
+            margin-left: calc(-1 * #{$spacing-03});
+          }
+        }
+
+        @include carbon--breakpoint('max') {
+          .#{$prefix}--universal-banner-image-container {
+            margin-right: $spacing-02;
+          }
+
+          .#{$prefix}--universal-banner-text-container {
+            margin-left: 1.75rem;
+          }
+
+          .#{$prefix}--universal-banner-cta-container {
+            margin-left: calc(-1 * #{$spacing-04});
+          }
+
+          ::slotted(#{$dds-prefix}-button-cta) {
+            width: calc(100% - #{$spacing-13});
+          }
+        }
+      }
+    }
+
+    &[image-width='8-col'] {
+      .#{$prefix}--universal-banner-layout-container {
+        @include carbon--breakpoint('lg') {
+          grid-template-columns: 2fr 1fr 1fr;
+
+          .#{$prefix}--universal-banner-image-container {
+            display: block;
+            margin-right: $spacing-05;
+          }
+
+          .#{$prefix}--universal-banner-text-container {
+            margin-left: $spacing-05;
+          }
+
+          .#{$prefix}--universal-banner-cta-container {
+            margin-left: calc(-1 * #{$spacing-03});
+          }
+
+          ::slotted(#{$dds-prefix}-universal-banner-heading) {
+            @include carbon--type-style('body-short-02');
+
+            font-weight: carbon--font-weight('semibold');
+          }
+
+          ::slotted(#{$dds-prefix}-universal-banner-copy) {
+            @include carbon--type-style('body-short-02');
+
+            margin-top: 0;
+          }
+        }
+
+        @include carbon--breakpoint('max') {
+          .#{$prefix}--universal-banner-cta-container {
+            margin-left: calc(-1 * #{$spacing-04});
+          }
+
+          ::slotted(#{$dds-prefix}-button-cta) {
+            width: calc(100% - #{$spacing-13});
+          }
+        }
+      }
+    }
+  }
+
+  .#{$prefix}--universal-banner-text-container {
+    @include carbon--theme($carbon--theme--g100, true);
+
+    margin-left: $spacing-05;
+
+    @include carbon--breakpoint('md') {
+      margin-left: $spacing-07;
+    }
+
+    @include carbon--breakpoint('lg') {
+      margin-left: $spacing-07;
+    }
+
+    @include carbon--breakpoint('max') {
+      margin-left: $spacing-08;
+      margin-right: 3.5rem;
+    }
+  }
+
+  .#{$prefix}--universal-banner-cta-container {
+    @include carbon--theme($carbon--theme--g100, true);
+
+    position: relative;
+    margin-left: $spacing-05;
+
+    @include carbon--breakpoint-down('md') {
+      padding-top: 0;
+    }
+
+    @include carbon--breakpoint('md') {
+      margin-left: $spacing-09;
+      margin-right: $spacing-07;
+    }
+
+    @include carbon--breakpoint('lg') {
+      margin-left: $spacing-11;
+      margin-right: $spacing-08;
+    }
+
+    @include carbon--breakpoint('xlg') {
+      margin-left: 6.25rem;
+      margin-right: 0;
+    }
+
+    @include carbon--breakpoint('max') {
+      margin-left: 7.5rem;
+    }
+  }
+
+  ::slotted(#{$dds-prefix}-button-cta) {
+    @include carbon--theme($carbon--theme--g100, true);
+
+    width: calc(100% + #{$spacing-05});
+    display: block;
+    max-width: 320px;
+
+    @include carbon--breakpoint-down('md') {
+      display: none;
+    }
+
+    @include carbon--breakpoint('lg') {
+      width: calc(100% + #{$spacing-06});
+    }
+
+    @include carbon--breakpoint('xlg') {
+      width: calc(100% - #{$spacing-12});
+    }
+
+    @include carbon--breakpoint('max') {
+      width: calc(100% + #{$spacing-05});
+    }
+  }
+
+  #{$dds-prefix}-link-with-icon {
+    @include carbon--breakpoint('md') {
+      display: none;
+    }
+  }
+}
+
+:host(#{$dds-prefix}-universal-banner-heading) {
+  @include carbon--type-style('expressive-paragraph-01', true);
+
+  display: block;
+  color: $text-01;
+  max-width: 960px;
+
+  @include carbon--breakpoint('lg') {
+    width: calc(100% - #{$spacing-10});
+  }
+
+  @include carbon--breakpoint('lg') {
+    width: calc(100% - #{$spacing-10});
+  }
+
+  @include carbon--breakpoint('xlg') {
+    width: calc(100% - #{$spacing-07});
+  }
+}
+
+:host(#{$dds-prefix}-universal-banner-copy) {
+  @include carbon--type-style('expressive-heading-01', true);
+
+  display: block;
+  color: $text-01;
+
+  margin-top: $spacing-03;
+
+  @include carbon--breakpoint('lg') {
+    margin-top: $spacing-05;
+  }
+}
+
+:host(#{$dds-prefix}-universal-banner-image) {
+  .#{$prefix}--image__img {
+    object-fit: fill;
+  }
+}

packages/styles/scss/ibm-dotcom-styles.scss

@@ -56,6 +56,7 @@
 @import 'components/pictogram-item/pictogram-item';
 @import 'components/quote/quote';
 @import 'components/tableofcontents/tableofcontents';
+@import 'components/universal-banner/universal-banner';
 @import 'components/video-player/video-player';
 @import 'components/audio-player/audio-player';
 

packages/web-components/examples/codesandbox/components-react/universal-banner/.gitignore

@@ -0,0 +1,2 @@
+/build
+/node_modules

packages/web-components/examples/codesandbox/components-react/universal-banner/index.html

@@ -0,0 +1,24 @@
+<!--
+@license
+
+Copyright IBM Corp. 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.
+-->
+
+<!DOCTYPE html>
+<html lang="en">
+  <head>
+    <meta charset="utf-8" />
+    <meta name="viewport" content="width=device-width, initial-scale=1, shrink-to-fit=no">
+    <title>Carbon for IBM.com Web Components example with React</title>
+  </head>
+  <body>
+    <noscript>
+      You need to enable JavaScript to run this app.
+    </noscript>
+    <div id="root"></div>
+    <script type="module" src="index.js"></script>
+  </body>
+</html>

packages/web-components/examples/codesandbox/components-react/universal-banner/package.json

@@ -0,0 +1,35 @@
+{
+  "name": "ibmdotcom-web-components-react-universal-banner-example",
+  "version": "0.1.0",
+  "private": true,
+  "description": "Sample project for getting started with the Web Components from Carbon for IBM.com with React.",
+  "license": "Apache-2",
+  "scripts": {
+    "start": "webpack serve"
+  },
+  "dependencies": {
+    "@carbon/ibmdotcom-web-components": "canary",
+    "@carbon/icons-react": "~10.22.0",
+    "carbon-components": "~10.23.0",
+    "lit-element": "^2.5.1",
+    "lit-html": "^1.4.1",
+    "lodash-es": "^4.17.0",
+    "prop-types": "^15.7.0",
+    "react": "^17.0.0",
+    "react-dom": "^17.0.0",
+    "react-redux": "^7.2.0"
+  },
+  "devDependencies": {
+    "@babel/core": "^7.0.0",
+    "@babel/preset-react": "^7.10.0",
+    "@types/lodash-es": "^4.17.0",
+    "@types/react": "^16.9.0",
+    "babel-loader": "^8.2.0",
+    "css-loader": "^4.3.0",
+    "html-webpack-plugin": "^4.5.0",
+    "style-loader": "^2.0.0",
+    "webpack": "^4.0.0",
+    "webpack-cli": "^4.0.0",
+    "webpack-dev-server": "^3.11.0"
+  }
+}

packages/web-components/examples/codesandbox/components-react/universal-banner/sandbox.config.json

@@ -0,0 +1,3 @@
+{
+  "template": "node"
+}