feat(logo-grid): add logoCount and logoRatio props (#8905)

### Related Ticket(s)

Closes #8848

### Description

Adds `logoCount` and `logoRatio` props to `DDSLogoGrid`

`logoCount` takes an integer to use as a number of columns for the grid. The stylesheet will constrain that value to between 2 and 4, inclusively.

`logoRatio` takes a string matching the format `<integer><separator><integer>` and sets a custom CSS property in an inline style to use in logo-grid-item elements as an aspect ratio.

### Changelog

**New**

- Added `logoCount` and `logoRatio` props to `DDSLogoGrid`

Author: andy-blum

packages/styles/scss/components/logo-grid/_logo-grid.scss

@@ -1,5 +1,5 @@
 /**
- * Copyright IBM Corp. 2016, 2021
+ * Copyright IBM Corp. 2016, 2022
  *
  * This source code is licensed under the Apache-2.0 license found in the
  * LICENSE file in the root directory of this source tree.
@@ -36,7 +36,7 @@
     }
 
     .#{$prefix}--content-block__cta {
-      margin-top: $layout-01;
+      margin-top: $spacing-09;
 
       @include carbon--make-col-ready;
       @include carbon--make-col(1, 1);
@@ -97,25 +97,47 @@
 
   .#{$prefix}--logo-grid__row {
     display: grid;
-    grid-template-columns: 1fr;
     margin-left: calc(-1 * #{$carbon--grid-gutter} / 2);
     margin-right: calc(-1 * #{$carbon--grid-gutter} / 2);
+    grid-template-columns: repeat(2, 1fr);
 
     @include carbon--breakpoint('md') {
-      grid-template-columns: repeat(2, 1fr);
+      &.#{$prefix}--logo-grid__4-columns {
+        grid-template-columns: repeat(4, 1fr);
+      }
     }
 
     @include carbon--breakpoint('lg') {
       grid-template-columns: repeat(3, 1fr);
+
+      &.#{$prefix}--logo-grid__4-columns {
+        grid-template-columns: repeat(4, 1fr);
+      }
     }
   }
 
   .#{$prefix}--logo-grid__col,
   :host(#{$dds-prefix}-logo-grid-item) {
+    /* stylelint-disable */
+    aspect-ratio: var(--logo-ratio, '16/9');
+    /* stylelint-enable */
     padding-left: $carbon--grid-gutter--condensed / 2;
     padding-right: $carbon--grid-gutter--condensed / 2;
   }
 
+  :host(#{$dds-prefix}-logo-grid-item) {
+    display: flex;
+    align-items: stretch;
+    justify-content: center;
+
+    picture,
+    img {
+      width: 100%;
+      height: 100%;
+      object-fit: contain;
+    }
+  }
+
   .#{$prefix}--logo-grid__heading {
     @include carbon--type-style('expressive-heading-05', true);
 

packages/utilities/src/utilities/parseAspectRatio/index.js

@@ -0,0 +1,8 @@
+/**
+ * Copyright IBM Corp. 2016, 2022
+ *
+ * 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 parseAspectRatio } from './parseAspectRatio';

packages/utilities/src/utilities/parseAspectRatio/parseAspectRatio.js

@@ -0,0 +1,38 @@
+/**
+ * Copyright IBM Corp. 2016, 2022
+ *
+ * This source code is licensed under the Apache-2.0 license found in the
+ * LICENSE file in the root directory of this source tree.
+ */
+
+/**
+ * Utility to parse aspect ratios into width & height values
+ *
+ * @example
+ * import {parseAspectRatio} from '@carbon/ibmdotcom-utilities';
+ *
+ * const [width, height] = parseAspectRatio('16x9');
+ *
+ * @param {string} aspectRatioString string in format <integer><separator><integer>
+ * @returns {Array} [widthInt, heightInt]
+ */
+
+function parseAspectRatio(aspectRatioString) {
+  if (typeof aspectRatioString !== 'string') {
+    throw new TypeError(
+      `parseAspectRatio expected a string but was given a ${typeof aspectRatioString}`
+    );
+  }
+
+  const parsed = aspectRatioString.split(/[^0-9]{1}/).filter(i => i);
+
+  if (parsed.length !== 2) {
+    throw new RangeError(
+      `Parsed aspect ratio should have a length of 2, but had ${parsed.length} instead`
+    );
+  }
+
+  return parsed;
+}
+
+export default parseAspectRatio;

packages/web-components/examples/codesandbox/components/logo-grid/cdn.html

@@ -28,7 +28,7 @@
 <div class="bx--grid">
   <div class="bx--row">
     <div class="bx--col-sm-4 bx--col-lg-12">
-      <dds-logo-grid>
+      <dds-logo-grid logo-count="3" logo-ratio="2:1">
         <dds-content-block-heading>
           This is a heading
         </dds-content-block-heading>

packages/web-components/examples/codesandbox/components/logo-grid/index.html

@@ -27,7 +27,7 @@
 <div class="bx--grid">
   <div class="bx--row">
     <div class="bx--col-sm-4 bx--col-lg-12">
-      <dds-logo-grid>
+      <dds-logo-grid logo-count="3" logo-ratio="2:1">
         <dds-content-block-heading>
           This is a heading
         </dds-content-block-heading>

packages/web-components/src/components/logo-grid/__stories__/logo-grid.stories.ts

@@ -1,7 +1,7 @@
 /**
  * @license
  *
- * Copyright IBM Corp. 2020, 2021
+ * Copyright IBM Corp. 2020, 2022
  *
  * This source code is licensed under the Apache-2.0 license found in the
  * LICENSE file in the root directory of this source tree.
@@ -12,17 +12,18 @@ import '../../content-block/content-block-heading';
 import '../logo-grid-item';
 import '../logo-grid-link';
 import '../../card/card-heading';
-import { boolean, text } from '@storybook/addon-knobs';
+import { boolean, text, select } from '@storybook/addon-knobs';
 import { html } from 'lit-element';
 import ArrowRight20 from 'carbon-web-components/es/icons/arrow--right/20.js';
 import logos from './data/logos.js';
 import readme from './README.stories.mdx';
 import textNullable from '../../../../.storybook/knob-text-nullable';
 
 export const Default = ({ parameters }) => {
-  const { heading, logosGroup, hideBorder, showCta, ctaCopy, ctaHref } = parameters?.props?.LogoGrid ?? {};
+  const { heading, logoCount, logoRatio, logosGroup, hideBorder, showCta, ctaCopy, ctaHref } = parameters?.props?.LogoGrid ?? {};
+
   return html`
-    <dds-logo-grid ?hide-border="${hideBorder}">
+    <dds-logo-grid ?hide-border="${hideBorder}" logo-count="${logoCount}" logo-ratio="${logoRatio}">
       <dds-content-block-heading>
         ${heading}
       </dds-content-block-heading>
@@ -65,6 +66,13 @@ export default {
     knobs: {
       LogoGrid: ({ groupId }) => ({
         heading: textNullable('Heading (heading)', 'Our customers', groupId),
+        logoCount: select('Column count (logoCount)', { 'Default (3)': '3', '4': '4' }, '3', groupId),
+        logoRatio: select(
+          'Logo aspect ratio (logoRatio)',
+          { 'Default (4:3)': '4:3', '16:9': '16:9', '2:1': '2:1' },
+          '4:3',
+          groupId
+        ),
         logosGroup: logos,
         hideBorder: boolean('Hide border (hideBorder): Hide the bottom border', false, groupId),
         showCta: boolean('Display CTA:', false, groupId),
@@ -76,6 +84,8 @@ export default {
       default: {
         LogoGrid: {
           heading: 'Our customers',
+          logoCount: '3',
+          logoRatio: '4:3',
           logosGroup: logos,
           hideBorder: false,
           showCta: false,

packages/web-components/src/components/logo-grid/logo-grid.ts

@@ -1,14 +1,16 @@
 /**
  * @license
  *
- * Copyright IBM Corp. 2020, 2021
+ * Copyright IBM Corp. 2020, 2022
  *
  * 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 { css, customElement, html, property, TemplateResult } from 'lit-element';
+import { classMap } from 'lit-html/directives/class-map';
 import settings from 'carbon-components/es/globals/js/settings.js';
-import ddsSettings from '@carbon/ibmdotcom-utilities/es/utilities/settings/settings';
+import ddsSettings from '../../internal/vendor/@carbon/ibmdotcom-utilities/utilities/settings/settings';
+import parseAspectRatio from '../../internal/vendor/@carbon/ibmdotcom-utilities/utilities/parseAspectRatio/parseAspectRatio';
 import DDSContentBlock from '../content-block/content-block';
 import '../horizontal-rule/horizontal-rule';
 import '../content-block/content-block-heading';
@@ -26,10 +28,16 @@ const { stablePrefix: ddsPrefix } = ddsSettings;
 @customElement(`${ddsPrefix}-logo-grid`)
 class DDSLogoGrid extends StableSelectorMixin(DDSContentBlock) {
   protected _renderInnerBody() {
-    const { _hasContent: hasContent, _hasMedia: hasMedia } = this;
+    const { _hasContent: hasContent, _hasMedia: hasMedia, logoCount } = this;
+
+    const rowClasses = {
+      [`${prefix}--logo-grid__row`]: true,
+      [`${prefix}--logo-grid__${logoCount}-columns`]: logoCount,
+    };
+
     return html`
       <div ?hidden="${!hasContent && !hasMedia}" class="${prefix}--content-block__children ${prefix}--content-layout__body">
-        <div class="${prefix}--logo-grid__row">
+        <div class="${classMap(rowClasses)}">
           ${this._renderContent()}${this._renderMedia()}
         </div>
       </div>
@@ -53,6 +61,39 @@ class DDSLogoGrid extends StableSelectorMixin(DDSContentBlock) {
   @property({ attribute: 'hide-border', reflect: true, type: Boolean })
   hideBorder = false;
 
+  /**
+   * Integer value that determines the number of columns in the grid.
+   *
+   * While any non-zero integer will work, styles will constrain values to between
+   * two and four.
+   */
+  @property({ attribute: 'logo-count', reflect: true })
+  logoCount?;
+
+  /**
+   * Aspect ratio of grid cells.
+   *
+   * Values should match the format `<integer><divider-character><integer>`.
+   * Any non-digit character can work as a divider.
+   */
+  @property({ attribute: 'logo-ratio', reflect: true })
+  logoRatio?;
+
+  updated(changedProperties) {
+    const { logoRatio } = this;
+    if (changedProperties.has('logoRatio')) {
+      if (logoRatio) {
+        const ratioSplit = parseAspectRatio(logoRatio);
+        if (ratioSplit.length === 2) {
+          const [w, h] = ratioSplit;
+          this.style.setProperty('--logo-ratio', `${w}/${h}`);
+        }
+      } else {
+        this.style.removeProperty('--logo-ratio');
+      }
+    }
+  }
+
   render() {
     return html`
       <div class="${prefix}--content-layout--logo-grid">

packages/web-components/tests/snapshots/dds-logo-grid.md

@@ -16,7 +16,7 @@
       class="bx--content-block__children bx--content-layout__body"
       hidden=""
     >
-      <div class="bx--logo-grid__row">
+      <div class="bx--logo-grid__row bx--logo-grid__undefined-columns">
         <slot>
         </slot>
         <slot name="media">