feat(fade-in-out): introducing new components

packages/react/src/components/DotcomShell/__stories__/DotcomShell.stories.js

@@ -1,13 +1,16 @@
 /**
- * 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 '@carbon/ibmdotcom-styles/scss/internal/scroll-into-view/_scroll-into-view.scss';
+import './dotcom-shell.stories.scss';
 import { select, object } from '@storybook/addon-knobs';
 import Content from './data/content';
 import DotcomShell from '../DotcomShell';
+import FadeInOut from '../../FadeInOut/FadeInOut';
 import { Micro as footerMicroStory } from '../../Footer/__stories__/Footer.stories.js';
 import { Default as footerStory } from '../../Footer/__stories__/Footer.stories.js';
 import { WithL1 as l1Story } from '../../Masthead/__stories__/Masthead.stories.js';
@@ -22,6 +25,26 @@ const footerTypeOptions = {
   micro: 'micro',
 };
 
+const selectorTargets = `
+  .bx--content-block__heading,
+  .bx--content-block__copy,
+  .bx--leadspace-block__media,
+  .bx--link-list,
+  .bx--leadspace-block__cta,
+  .bx--feature-card-block-large,
+  .bx--content-group,
+  .bx--image,
+  .bx--content-block__cta,
+  .bx--callout-with-media,
+  .bx--content-item-horizontal__item,
+  .bx--logo-grid__logo,
+  .bx--card-group__cards__col,
+  .bx--callout-quote,
+  .bx--cta-section,
+  .bx--cta-section__cta,
+  .bx--content-item
+`;
+
 export default {
   title: 'Components|Dotcom Shell',
 
@@ -301,3 +324,47 @@ WithL1.story = {
     },
   },
 };
+
+export const WithFadeAnimationsContinuous = ({ parameters }) => {
+  const { mastheadProps, footerProps } = parameters?.props?.DotcomShell ?? {};
+  return (
+    <DotcomShell mastheadProps={mastheadProps} footerProps={footerProps}>
+      <main id="main-content">
+        <div style={{ paddingTop: '6rem' }}>
+          <FadeInOut selectorTargets={selectorTargets} keepAnimations={true}>
+            <Content />
+          </FadeInOut>
+        </div>
+      </main>
+    </DotcomShell>
+  );
+};
+
+WithFadeAnimationsContinuous.story = {
+  // to avoid jest errors with Intersection Observer
+  parameters: {
+    storyshots: { disable: true },
+  },
+};
+
+export const WithFadeAnimationsOnce = ({ parameters }) => {
+  const { mastheadProps, footerProps } = parameters?.props?.DotcomShell ?? {};
+  return (
+    <DotcomShell mastheadProps={mastheadProps} footerProps={footerProps}>
+      <main id="main-content">
+        <div style={{ paddingTop: '6rem' }}>
+          <FadeInOut selectorTargets={selectorTargets}>
+            <Content />
+          </FadeInOut>
+        </div>
+      </main>
+    </DotcomShell>
+  );
+};
+
+WithFadeAnimationsOnce.story = {
+  // to avoid jest errors with Intersection Observer
+  parameters: {
+    storyshots: { disable: true },
+  },
+};

packages/react/src/components/DotcomShell/__stories__/dotcom-shell.stories.scss

@@ -0,0 +1,23 @@
+/**
+ * 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.
+ */
+
+.bx--logo-grid__logo,
+.bx--card-group__cards__col,
+.bx--content-item-wrapper > .bx--content-item {
+  &:nth-of-type(3n) {
+    --dds--fade-in-out-delay: 0;
+  }
+  &:nth-of-type(3n + 1) {
+    --dds--fade-in-out-delay: 250ms;
+  }
+  &:nth-of-type(3n + 2) {
+    --dds--fade-in-out-delay: 500ms;
+  }
+  &:nth-of-type(3n + 3) {
+    --dds--fade-in-out-delay: 750ms;
+  }
+}

packages/react/src/components/FadeInOut/FadeInOut.js

@@ -0,0 +1,200 @@
+/**
+ * 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 React, { useCallback, useEffect, useRef } from 'react';
+import { breakpoints } from '@carbon/layout';
+import PropTypes from 'prop-types';
+import settings from 'carbon-components/es/globals/js/settings';
+const { prefix } = settings;
+
+/**
+ * Amount of columns used for calculation.
+ *
+ * @private
+ */
+const _colSpan = 3;
+
+/**
+ * Utility handles fade transition for selected elements.
+ *
+ * @example
+ * import { FadeInOut } from '@carbon/ibmdotcom-react';
+ * import '@carbon/ibmdotcom-styles/scss/internal/scroll-into-view/_scroll-into-view.scss';
+ *
+ * As an example, the function can be called to target all instances of the
+ * elements in a list:
+ *
+ * const list = '.bx--content-block, .bx--content-group';
+ *
+ * For default values of 400ms and 'one and done' play:
+ * <FadeInOut selectorTargets={selectorTargets}>
+ *   // some content
+ * </FadeInOut>
+ *
+ * With 'continuous play' option:
+ * <FadeInOut selectorTargets={selectorTargets} keepAnimations={true}>
+ *   // some content
+ * </FadeInOut>
+ *
+ * For custom delay time, set within targeted class in the application's CSS code as such:
+ *
+ * .bx--content-block {
+ *   --#{$dds-prefix}--fade-in-out-delay: 250ms;
+ * }
+ *
+ */
+const FadeInOut = ({ children, selectorTargets, keepAnimations }) => {
+  /**
+   * Outer div component ref for using with query selector.
+   *
+   * @private
+   */
+  const _componentRef = useRef(null);
+
+  /**
+   * Intersection Observer that watches outer viewport.
+   *
+   * @private
+   */
+  const _rootObserver = useRef(null);
+
+  /**
+   * Intersection observer that watches the inner viewport.
+   *
+   * @private
+   */
+  const _innerObserver = useRef(null);
+
+  /**
+   * Resize observer to trigger rootMargin recalculations
+   *
+   * @private
+   */
+  const _resizeObserver = useRef(null);
+
+  /**
+   * Create observers upon render and update.
+   */
+  useEffect(() => {
+    _rootObserver.current = new IntersectionObserver(handleExit);
+    _resizeObserver.current = new ResizeObserver(handleResize);
+
+    if (selectorTargets) {
+      _componentRef.current.querySelectorAll(selectorTargets).forEach(item => {
+        _rootObserver?.current.observe(item);
+      });
+    }
+    _resizeObserver.current.observe(document.documentElement);
+
+    return () => {
+      _rootObserver.current.disconnect();
+      _innerObserver.current.disconnect();
+      _resizeObserver.current.disconnect();
+      _rootObserver.current = null;
+      _innerObserver.current = null;
+      _resizeObserver.current = null;
+    };
+  }, [_componentRef, selectorTargets, handleEntrance, handleResize]);
+
+  /**
+   * Handler to add recalculated rootMargin to a new instance of
+   * inner observer after clearing old one first.
+   *
+   * The calculation is done to retrieve the best fitting top and bottom
+   * margin for the fade animation to trigger/remove from elements in a
+   * user's screen.
+   *
+   * The resulting value is the optimal point where a user's attention will be
+   * grabbed by the animation without restricting their view and perception of
+   * the adopting website. The displayed elements will keep the user's attention
+   * for a longer time as they scroll down the website.
+   *
+   * @private
+   */
+  const handleResize = useCallback(() => {
+    if (_innerObserver.current) {
+      _innerObserver.current.disconnect();
+      _innerObserver.current = null;
+    }
+
+    _innerObserver.current = new IntersectionObserver(handleEntrance, {
+      rootMargin: `-${(
+        (document.documentElement.clientHeight * _colSpan) /
+        breakpoints.max.columns
+      ).toString()}px 0px`,
+    });
+
+    if (selectorTargets) {
+      _componentRef.current.querySelectorAll(selectorTargets).forEach(item => {
+        _innerObserver?.current.observe(item);
+      });
+    }
+  }, [_componentRef, _innerObserver, selectorTargets, handleEntrance]);
+
+  /**
+   * Handler to add fade animation to element
+   *
+   * @param {*} records observed elements
+   * @private
+   *
+   */
+  const handleEntrance = useCallback(
+    records => {
+      records.forEach(({ intersectionRatio, target }) => {
+        if (intersectionRatio > 0) {
+          target.classList.remove(`${prefix}--fade-out`);
+          target.classList.add(`${prefix}--fade-in`);
+          if (!keepAnimations) {
+            _rootObserver.current.unobserve(target);
+            _innerObserver.current.unobserve(target);
+          }
+        }
+      });
+    },
+    [keepAnimations, _rootObserver, _innerObserver]
+  );
+
+  /**
+   * Handler to remove element from view
+   *
+   * @param {*} records observed elements
+   * @private
+   *
+   */
+  function handleExit(records) {
+    records.forEach(({ intersectionRatio, target }) => {
+      if (intersectionRatio == 0) {
+        target.classList.remove(`${prefix}--fade-in`);
+        target.classList.add(`${prefix}--fade-out`);
+      }
+    });
+  }
+
+  return <div ref={_componentRef}>{children}</div>;
+};
+
+FadeInOut.propTypes = {
+  /**
+   * Component(s) to render within the component
+   */
+  children: PropTypes.oneOfType([
+    PropTypes.arrayOf(PropTypes.node),
+    PropTypes.node,
+  ]).isRequired,
+
+  /**
+   * List of elements to be targeted
+   */
+  selectorTargets: PropTypes.string,
+
+  /**
+   * Boolean to define if animation is continuous
+   */
+  keepAnimations: PropTypes.bool,
+};
+
+export default FadeInOut;

packages/react/src/components/FadeInOut/index.js

@@ -0,0 +1,7 @@
+/**
+ * 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.
+ */
+export { default as FadeInOut } from './FadeInOut';

packages/styles/scss/internal/scroll-into-view/_scroll-into-view.scss

@@ -0,0 +1,24 @@
+/**
+ * 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 '../../globals/vars';
+@import '../../globals/imports';
+
+:root {
+  --#{$dds-prefix}--fade-in-out-delay: 0s;
+}
+
+.#{$prefix}--fade-in {
+  transition-timing-function: carbon--motion(entrance, expressive);
+  transition-duration: $duration--slow-01;
+  transition-delay: var(--#{$dds-prefix}--fade-in-out-delay);
+  opacity: 1;
+}
+
+.#{$prefix}--fade-out {
+  opacity: 0;
+}

packages/utilities/src/utilities/index.js

@@ -1,5 +1,5 @@
 /**
- * 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.

packages/web-components/src/components/dotcom-shell/__stories__/dotcom-shell.stories.scss

@@ -0,0 +1,25 @@
+/**
+ * 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.
+ */
+
+/* stylelint-disable selector-type-no-unknown */
+dds-logo-grid-item,
+dds-card-group-item,
+dds-cta-section-item {
+  &:nth-of-type(3n) {
+    --dds--fade-in-out-delay: 0;
+  }
+  &:nth-of-type(3n + 1) {
+    --dds--fade-in-out-delay: 250ms;
+  }
+  &:nth-of-type(3n + 2) {
+    --dds--fade-in-out-delay: 500ms;
+  }
+  &:nth-of-type(3n + 3) {
+    --dds--fade-in-out-delay: 750ms;
+  }
+}
+/* stylelint-enable selector-type-no-unknown */