feat(cta): introduce card CTA (#3855)

### Related Ticket(s)

Refs #3556.

### Description

Introduces the following components:

* `<dds-card-cta>`, the card variant of CTA
* `<dds-card-cta-footer>`, the footer part of card CTA
* `<dds-feature-cta>`, the feature card variant of CTA (Note: Doesn't have some UI in feature card block for now due to pending work)
* `<dds-feature-cta-footer>`, the footer part of feature CTA
* `<dds-cta-composite>`, non-API-integration portion of `<dds-cta-container>`
* `<dds-markdown>`, a markdown renderer

`<dds-cta-container>` is now wired to video player API portion of our Redux store to provide default video caption.

Some other misc changes to make things work, etc.:

* A change to `<dds-link-with-icon>` to allow inherited classes to override text/icon contents
* Separted g11n formater for video duration from one for video caption. Also made the default formatter defined in `<dds-video-player>` reusable from other components
* A change to `<dds-card>` to allow inherited classes to override the copy/images contents
* Some changes to `<dds-card-footer>`:
  * One to allow inherited classes to override the copy content
  * One to utilize `bx--card__footer__icon-left` CSS class that was introduced recently
* Introduced `hasGrid` story parameter. If it's set, the shared decorator of the stories provides better stying to accomodate grid
* Some Storybook environment-specific grid classes (`dds-ce-demo-devenv--grid--card` and `dds-ce-demo-devenv--grid-row`) to make stories with grids look better
* An API to allow CTA icon to be overriden
* A fix to `<dds-video-player-container>` whose `mapStateToProps()` interface had redundant property

### Changelog

**New**

* `<dds-card-cta>`, the card variant of CTA
* `<dds-card-cta-footer>`, the footer part of card CTA
* `<dds-feature-cta>`, the feature card variant of CTA (Note: Doesn't have some UI in feature card block for now due to pending work)
* `<dds-feature-cta-footer>`, the footer part of feature CTA
* `<dds-cta-composite>`, non-API-integration portion of `<dds-cta-container>`
* `<dds-markdown>`, a markdown renderer
* An API to allow CTA icon to be overriden

**Changed**

* A change to `<dds-link-with-icon>` to allow inherited classes to override text/icon contents
* Separted g11n formater for video duration from one for video caption. Also made the default formatter defined in `<dds-video-player>` reusable from other components
* A change to `<dds-card>` to allow inherited classes to override the copy/images contents
* Some changes to `<dds-card-footer>`:
  * One to allow inherited classes to override the copy content
  * One to utilize `bx--card__footer__icon-left` CSS class that was introduced recently
* Introduced `hasGrid` story parameter. If it's set, the shared decorator of the stories provides better stying to accomodate grid
* Some Storybook environment-specific grid classes (`dds-ce-demo-devenv--grid--card` and `dds-ce-demo-devenv--grid-row`) to make stories with grids look better
* A fix to `<dds-video-player-container>` whose `mapStateToProps()` interface had redundant property

Author: asudoh

packages/styles/scss/components/card/index.scss

@@ -13,7 +13,8 @@
 
 @mixin card {
   .#{$prefix}--card,
-  :host(#{$dds-prefix}-card) {
+  :host(#{$dds-prefix}-card),
+  :host(#{$dds-prefix}-card-cta) {
     background-color: $ui-01;
     text-decoration: none;
     display: flex;
@@ -54,48 +55,6 @@
       margin-bottom: $carbon--spacing-03;
       color: $text-02;
     }
-    ::slotted(svg[slot='footer']),
-    .#{$prefix}--card__cta,
-    .#{$prefix}--card__cta a,
-    .#{$prefix}--card__cta a:visited {
-      color: $interactive-04;
-    }
-
-    .#{$prefix}--card__cta__copy {
-      margin-right: $carbon--spacing-03;
-      color: $interactive-04;
-      @include carbon--type-style('body-short-02');
-    }
-
-    .#{$prefix}--card__footer,
-    :host(#{$dds-prefix}-feature-card-footer) {
-      display: flex;
-      margin-top: auto;
-
-      .#{$prefix}--card__footer__copy {
-        margin-bottom: -$carbon--spacing-01;
-      }
-
-      svg {
-        fill: currentColor;
-        display: block;
-        align-self: center;
-        min-width: 20px;
-      }
-    }
-
-    .#{$prefix}--card__footer__icon-left {
-      justify-content: flex-end;
-      flex-direction: row-reverse;
-
-      .#{$prefix}--card__cta {
-        margin-right: $carbon--spacing-03;
-      }
-
-      .#{$prefix}--card__cta__copy {
-        margin-right: 0;
-      }
-    }
 
     .#{$prefix}--card:focus,
     .#{$prefix}--card:visited,
@@ -146,6 +105,68 @@
     }
   }
 
+  .#{$prefix}--card .#{$prefix}--card__cta,
+  .#{$prefix}--card .#{$prefix}--card__cta a,
+  .#{$prefix}--card .#{$prefix}--card__cta a:visited,
+  .#{$prefix}--card ::slotted(svg[slot='footer']),
+  :host(#{$dds-prefix}-card-footer)
+    .#{$dds-prefix}-ce--card__footer
+    ::slotted(svg[slot='icon']),
+  :host(#{$dds-prefix}-card-cta-footer)
+    .#{$dds-prefix}-ce--card__footer
+    ::slotted(svg[slot='icon']) {
+    color: $interactive-04;
+  }
+
+  .#{$prefix}--card .#{$prefix}--card__footer,
+  :host(#{$dds-prefix}-card-footer),
+  :host(#{$dds-prefix}-card-cta-footer),
+  :host(#{$dds-prefix}-feature-card-footer),
+  :host(#{$dds-prefix}-feature-cta-footer) {
+    margin-top: auto; /* Moves the footer down to the bottom in the card */
+
+    .#{$prefix}--card__cta__copy {
+      margin-right: $carbon--spacing-03;
+      color: $interactive-04;
+      @include carbon--type-style('body-short-02');
+    }
+
+    .#{$prefix}--card__footer__copy {
+      margin-bottom: -$carbon--spacing-01;
+    }
+
+    svg,
+    ::slotted(svg[slot='icon']) {
+      display: block;
+      min-width: 20px;
+    }
+
+    .#{$prefix}--card__footer__icon-left {
+      justify-content: flex-end;
+      flex-direction: row-reverse;
+
+      svg.#{$prefix}--card__cta,
+      ::slotted(svg[slot='icon']) {
+        margin-right: $carbon--spacing-03;
+      }
+
+      .#{$prefix}--card__cta__copy {
+        margin-right: 0;
+      }
+    }
+  }
+
+  .#{$prefix}--card .#{$prefix}--card__footer,
+  .#{$dds-prefix}-ce--card__footer {
+    display: flex;
+  }
+
+  .#{$prefix}--card .#{$prefix}--card__footer svg,
+  .#{$dds-prefix}-ce--card__footer ::slotted(svg[slot='icon']) {
+    fill: currentColor;
+    align-self: center;
+  }
+
   .#{$prefix}--card--inverse,
   :host(#{$dds-prefix}-card)[color-scheme='inverse'] {
     background-color: $inverse-02;
@@ -162,13 +183,19 @@
     &:hover {
       background-color: $inverse-hover-ui;
     }
+  }
 
-    .#{$prefix}--card__cta,
-    .#{$prefix}--card__cta a,
-    .#{$prefix}--card__cta a:visited,
-    .#{$prefix}--card__cta__copy {
-      color: $inverse-link;
-    }
+  .#{$prefix}--card--inverse .#{$prefix}--card__cta,
+  .#{$prefix}--card--inverse .#{$prefix}--card__cta a,
+  .#{$prefix}--card--inverse .#{$prefix}--card__cta a:visited,
+  .#{$prefix}--card--inverse .#{$prefix}--card__cta__copy,
+  :host(#{$dds-prefix}-feature-card-footer)
+    .#{$dds-prefix}-ce--card__footer
+    ::slotted(svg[slot='icon']),
+  :host(#{$dds-prefix}-feature-cta-footer)
+    .#{$dds-prefix}-ce--card__footer
+    ::slotted(svg[slot='icon']) {
+    color: $inverse-link;
   }
 }
 

packages/styles/scss/components/feature-card/_feature-card.scss

@@ -13,7 +13,8 @@
 
 @mixin feature-card {
   .#{$prefix}--feature-card,
-  :host(#{$dds-prefix}-feature-card) {
+  :host(#{$dds-prefix}-feature-card),
+  :host(#{$dds-prefix}-feature-cta) {
     padding-top: aspect-ratio(1, 1);
     position: relative;
     @include carbon--breakpoint('md') {

packages/styles/scss/components/link-with-icon/_link-with-icon.scss

@@ -12,7 +12,8 @@
 
 @mixin link-with-icon {
   .#{$prefix}--link-with-icon,
-  :host(#{$dds-prefix}-link-with-icon) {
+  :host(#{$dds-prefix}-link-with-icon),
+  :host(#{$dds-prefix}-text-cta) {
     display: flex;
 
     span {

packages/utilities/src/utilities/formatVideoCaption/__tests__/formatVideoCaption.test.js

@@ -0,0 +1,56 @@
+/**
+ * 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.
+ */
+
+import { formatVideoCaption, formatVideoDuration } from '../';
+
+describe('g11n formatter for video caption', () => {
+  describe('Formatting caption', () => {
+    it('should support empty caption', async () => {
+      expect(formatVideoCaption()).toBe('');
+    });
+
+    it('should support name-only caption', async () => {
+      expect(formatVideoCaption({ name: 'foo' })).toBe('foo');
+    });
+
+    it('should support duration-only caption', async () => {
+      expect(formatVideoCaption({ duration: '1:30' })).toBe('1:30');
+    });
+
+    it('should support a caption with the name and the duration', async () => {
+      expect(formatVideoCaption({ name: 'foo', duration: '1:30' })).toBe(
+        'foo (1:30)'
+      );
+    });
+
+    it('should support a caption zero duration', async () => {
+      expect(formatVideoCaption({ name: 'foo', duration: 0 })).toBe('foo (0)');
+    });
+  });
+
+  describe('Formatting duration', () => {
+    it('should support undefined duration', async () => {
+      expect(formatVideoDuration()).toBeUndefined();
+    });
+
+    it('should support null duration', async () => {
+      expect(formatVideoDuration({ duration: null })).toBeNull();
+    });
+
+    it('should fill zero for minutes', async () => {
+      expect(formatVideoDuration({ duration: 30000 })).toBe('0:30');
+    });
+
+    it('should fill zero for seconds', async () => {
+      expect(formatVideoDuration({ duration: 65000 })).toBe('1:05');
+    });
+
+    it('should support more than 1 minute', async () => {
+      expect(formatVideoDuration({ duration: 90000 })).toBe('1:30');
+    });
+  });
+});

packages/utilities/src/utilities/formatVideoCaption/formatVideoCaption.js

@@ -0,0 +1,42 @@
+/**
+ * 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.
+ */
+
+/**
+ * The default g11n formatter for video caption, combining video name and video duration.
+ * Components using this function should have a mechanism to allow translators
+ * to replace it with one accomodating the preferences of specific locale.
+ *
+ * @param {object} [options] The options, with a video name and a formatted video duration.
+ * @param {string} [options.duration] The video duration.
+ * @param {string} [options.name] The video name.
+ * @returns {string} The formatted video caption.
+ */
+export function formatVideoCaption({ duration, name } = {}) {
+  return !name || (duration !== 0 && !duration)
+    ? name || duration || ''
+    : `${name} (${duration})`;
+}
+
+/**
+ * The default g11n formatter for video duration.
+ * Components using this function should have a mechanism to allow translators
+ * to replace it with one accomodating the preferences of specific locale,
+ * or to replace it with general-purpose g11n formatting library.
+ * (e.g. moment, though it's too big for us to make it a hard dependency)
+ *
+ * @param {object} [options] The options, with a video duration.
+ * @param {number} [options.duration] The video duration, in seconds.
+ * @returns {string} The formatted video duration.
+ */
+export function formatVideoDuration({ duration } = {}) {
+  const minutes = Math.floor((duration ?? 0) / 60000);
+  const seconds = Math.floor(((duration ?? 0) / 1000) % 60);
+  const fillSeconds = Array.from({
+    length: 2 - String(seconds).length + 1,
+  }).join('0');
+  return duration == null ? duration : `${minutes}:${fillSeconds}${seconds}`;
+}

packages/utilities/src/utilities/formatVideoCaption/index.js

@@ -0,0 +1,8 @@
+/**
+ * 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.
+ */
+
+export * from './formatVideoCaption';

packages/utilities/src/utilities/index.js

@@ -10,6 +10,7 @@ export * from './calculateTotalWidth';
 export * from './decodeString';
 export * from './escaperegexp';
 export * from './featureflag';
+export * from './formatVideoCaption';
 export * from './geolocation';
 export * from './ipcinfoCookie';
 export * from './markdownToHtml';

packages/web-components/.storybook/config.ts

@@ -8,6 +8,7 @@
  */
 
 import { html } from 'lit-html'; // eslint-disable-line import/first
+import { classMap } from 'lit-html/directives/class-map';
 import { configure, addDecorator, addParameters, setCustomElements } from '@storybook/web-components'; // eslint-disable-line import/first
 import { withKnobs } from '@storybook/addon-knobs';
 import customElements from '../custom-elements.json';
@@ -46,19 +47,19 @@ addParameters({
 // The TS configuration for `@storybook/web-components` does not seem to allow returning `TemplateResult` in decorators,
 // using `TemplateResult` in decorators seems to work with `@storybook/web-components` actually
 // @ts-ignore
-addDecorator(story => {
+addDecorator((story, { parameters }) => {
   const result = story();
   const { hasMainTag } = result as any;
+  const { hasGrid } = parameters;
+  const classes = classMap({
+    'dds-ce-demo-devenv--container': true,
+    'dds-ce-demo-devenv--container--has-grid': hasGrid,
+  });
   return html`
     <style>
       ${containerStyles}
     </style>
-    <div
-      name="main-content"
-      data-floating-menu-container
-      role="${hasMainTag ? 'none' : 'main'}"
-      class="dds-ce-demo-devenv--container"
-    >
+    <div name="main-content" data-floating-menu-container role="${hasMainTag ? 'none' : 'main'}" class="${classes}">
       ${result}
     </div>
   `;

packages/web-components/.storybook/container.scss

@@ -46,3 +46,17 @@ body {
   align-items: center;
   position: relative;
 }
+
+.dds-ce-demo-devenv--container--has-grid {
+  align-items: stretch;
+}
+
+.dds-ce-demo-devenv--grid--card {
+  margin-left: 0;
+  margin-right: 0;
+}
+
+.dds-ce-demo-devenv--grid-row {
+  flex-direction: column;
+  align-items: center;
+}

packages/web-components/examples/codesandbox/components/cta/card/.gitignore

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

packages/web-components/examples/codesandbox/components/cta/card/index.html

@@ -0,0 +1,35 @@
+<!--
+@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.
+-->
+
+<html>
+  <head>
+    <title>@carbon/ibmdotcom-web-components example</title>
+    <meta charset="UTF-8" />
+    <script type="module">
+      import '@carbon/ibmdotcom-web-components/es/components/cta/card-cta.js';
+    </script>
+    <style type="text/css">
+      body {
+        font-family: 'IBM Plex Sans', 'Helvetica Neue', Arial, sans-serif;
+        display: flex;
+        flex-direction: column;
+        align-items: center;
+      }
+
+      body > * {
+        width: 37.5%;
+      }
+    </style>
+  </head>
+  <body>
+    <dds-card-cta href="https://www.ibm.com/" type="local">
+      Copy text
+    </dds-card-cta>
+  </body>
+</html>