feat(ImageGallery): adds ImageGallery and ImageGalleryImage component for gallery view of photos

packages/example/src/data/nav-items.yaml

@@ -54,3 +54,5 @@
       path: /components/Tabs
     - title: Video
       path: /components/Video
+    - title: Image Gallery
+      path: /components/ImageGallery

packages/example/src/pages/components/ImageGallery.mdx

@@ -0,0 +1,130 @@
+---
+title: Image Gallery
+theme: dark
+---
+
+<PageDescription>
+
+A small scale example of the Image Gallery from the [IBM Design Language Gallery](https://www.ibm.com/design/language/gallery).
+
+</PageDescription>
+
+## Image Gallery Example
+
+Click on an image to open the gallery.
+
+<ImageGallery>
+<ImageGalleryImage
+  src="/images/IBM_Design_landing.jpg"
+  title="IBM Design"
+  alt="IBM Design"
+  col={4}
+/>
+
+<ImageGalleryImage
+  src="/images/IBM_Cloud_Logo.png"
+  title="IBM Cloud"
+  alt="IBM Cloud"
+  col={4}
+/>
+
+<ImageGalleryImage
+  src="/images/IBM_Cloud_Developers.jpg"
+  title="IBM Cloud"
+  alt="IBM Cloud"
+  col={4}
+/>
+
+<ImageGalleryImage
+  src="/images/IBM_Cloud_Data_Center.jpg"
+  title="IBM Cloud Data Center"
+  alt="IBM Cloud Data Center"
+  col={8}
+/>
+
+<ImageGalleryImage
+  src="/images/IBM_Cloud_Interconnect.jpg"
+  title="IBM Cloud Interconnect"
+  alt="IBM Cloud Interconnect"
+  col={4}
+/>
+
+<ImageGalleryImage
+  src="/images/IBM_Cloud_Notebook.jpg"
+  title="IBM Cloud Notebook"
+  alt="IBM Cloud Notebook"
+  col={4}
+/>
+
+<ImageGalleryImage
+  src="/images/IBM_Cloud_Platform_Prototype.gif"
+  title="IBM Cloud Platform"
+  alt="IBM Cloud Platform"
+  col={8}
+/>
+
+<ImageGalleryImage
+  src="/images/IBM_Cloud_Pictograms.gif"
+  title="IBM Cloud"
+  alt="IBM Cloud"
+  col={4}
+/>
+
+<ImageGalleryImage
+  src="/images/IBM_Cloud_Server.png"
+  title="IBM Cloud Server"
+  alt="IBM Cloud Server"
+  col={4}
+/>
+
+<ImageGalleryImage
+  src="/images/IBM_Cloud_Think_Keynote.jpg"
+  title="IBM Cloud Think"
+  alt="IBM Cloud Think"
+  col={4}
+/>
+</ImageGallery>
+
+## Markdown Code
+
+You can use the ImageGallery component in markdown by nesting your images inside the ImageGallery component and using the ImageGalleryImage component to define the image's location, title, alt tag, and the columns the image on the page will span at the medium and large breakpoints. There is no gallery view for mobile so the small breakpoint is not defined.
+
+Here's an example of how to use the ImageGallery and the ImageGalleryImage components in markdown.
+
+```markdown path=/components/ImageGallery.mdx src=https://gatsby-theme-carbon.now.sh
+<ImageGallery>
+
+<ImageGalleryImage
+    src="/images/IBM_Design_landing.jpg"
+    title="IBM Design"
+    alt="IBM Design"
+    colMd={2}
+    colLg={4}
+  />
+
+<ImageGalleryImage
+    src="/images/IBM_Cloud_Logo.png"
+    title="IBM Cloud"
+    alt="IBM Cloud"
+    colMd={2}
+    colLg={4}
+  />
+
+<ImageGalleryImage
+    src="/images/IBM_Cloud_Developers.jpg"
+    title="IBM Cloud"
+    alt="IBM Cloud"
+    colMd={2}
+    colLg={4}
+  />
+
+<ImageGalleryImage
+    src="/images/IBM_Cloud_Data_Center.jpg"
+    title="IBM Cloud Data Center"
+    alt="IBM Cloud Data Center"
+    colMd={4}
+    colLg={8}
+  />
+
+</ImageGallery>
+```

packages/gatsby-theme-carbon/package.json

@@ -33,6 +33,7 @@
     "classnames": "^2.2.6",
     "copy-to-clipboard": "^3.2.0",
     "emotion-theming": "^10.0.10",
+    "focus-trap-react": "^6.0.0",
     "gatsby-plugin-catch-links": "^2.0.15",
     "gatsby-plugin-emotion": "^4.0.7",
     "gatsby-plugin-manifest": "^2.1.1",

packages/gatsby-theme-carbon/src/components/ImageGallery/ImageGallery.js

@@ -0,0 +1,194 @@
+import React, { useState, useEffect, Children } from 'react';
+import ReactDOM from 'react-dom';
+import { breakpoints } from '@carbon/elements';
+import { ChevronRight32, ChevronLeft32, Close32 } from '@carbon/icons-react';
+import cx from 'classnames';
+import FocusTrap from 'focus-trap-react';
+import useMedia from 'use-media';
+import PropTypes from 'prop-types';
+import { Grid, Row, Column } from '../Grid';
+import {
+  galleryContainer,
+  inDialogGalleryContainer,
+  galleryGrid,
+  galleryRow,
+  navButtons,
+  closeButton,
+  icon,
+  navButtonsContainer,
+  firstRightNav,
+  rightNav,
+  leftNav,
+  addNoScroll,
+} from './ImageGallery.module.scss';
+
+function ImageGallery({ children }) {
+  const [portalsNode, updateNode] = useState(null);
+  const [isGalleryOpen, setIsGalleryOpen] = useState(false);
+  const [activeImageIndex, updateActiveImageIndex] = useState(null);
+  const mediaChildren = Children.toArray(children).filter(
+    child => child.props.src
+  );
+  const rightNavButton = cx({
+    [rightNav]: true,
+    [firstRightNav]: activeImageIndex === 0,
+    [navButtons]: activeImageIndex > 0,
+  });
+  const leftNavButton = cx([leftNav], [navButtons]);
+  const isMobile = useMedia({ maxWidth: breakpoints.md.width });
+
+  // Creates the node to go into the portalsNode state.
+  useEffect(() => {
+    const node = document.createElement('div');
+    document.body.appendChild(node);
+    updateNode(node);
+
+    return () => {
+      node.parentNode.removeChild(node);
+    };
+  }, []);
+
+  // Depending on if the gallery is open or not, this adds the addNoScroll class so the screen behind the modal doesn't scroll when opened.
+  useEffect(() => {
+    if (isGalleryOpen) {
+      document.body.classList.add(addNoScroll);
+    }
+
+    return () => {
+      document.body.classList.remove(addNoScroll);
+    };
+  }, [isGalleryOpen]);
+
+  // Removes addNoScroll if view is shrunk to mobile view when the gallery is open
+  useEffect(() => {
+    if (
+      (isMobile && document.body.classList.contains(addNoScroll)) ||
+      !isGalleryOpen
+    ) {
+      document.body.classList.remove(addNoScroll);
+    }
+
+    return () => {
+      if (!isMobile && isGalleryOpen) {
+        document.body.classList.add(addNoScroll);
+      }
+    };
+  }, [isGalleryOpen, isMobile]);
+
+  // Opens gallery if the breakpoint isn't mobile and the child has a src prop
+  function openGalleryForImage(child, index) {
+    return () => {
+      if (!isMobile && child.props.src) {
+        setIsGalleryOpen(true);
+        updateActiveImageIndex(index);
+      }
+    };
+  }
+
+  function closeGallery() {
+    setIsGalleryOpen(false);
+    updateActiveImageIndex(null);
+  }
+
+  function selectNextImage() {
+    if (activeImageIndex + 1 < mediaChildren.length) {
+      updateActiveImageIndex(activeImageIndex + 1);
+    }
+  }
+
+  function selectPrevImage() {
+    if (activeImageIndex - 1 >= 0) {
+      updateActiveImageIndex(activeImageIndex - 1);
+    }
+  }
+
+  function onKeyDown(event) {
+    if (event.key === 'Escape') {
+      closeGallery();
+      return;
+    }
+    if (event.key === 'ArrowLeft') {
+      selectPrevImage();
+      return;
+    }
+    if (event.key === 'ArrowRight') {
+      selectNextImage();
+    }
+  }
+
+  return (
+    <>
+      <Row className={galleryContainer}>
+        {Children.map(children, (child, index) =>
+          React.cloneElement(child, {
+            onClick: openGalleryForImage(child, index),
+          })
+        )}
+      </Row>
+      {portalsNode &&
+        isGalleryOpen &&
+        !isMobile &&
+        ReactDOM.createPortal(
+          <FocusTrap>
+            {/* Because of FocusTrap, the key down events will propagate up removing the accessibility problem that would be created by having a keydown event listener on a non-interactive element. */}
+            {/* eslint-disable-next-line jsx-a11y/no-noninteractive-element-interactions */}
+            <div
+              role="group"
+              className={inDialogGalleryContainer}
+              onKeyDown={onKeyDown}
+            >
+              <Row>
+                <Column colLg={2}>
+                  <button
+                    type="button"
+                    className={closeButton}
+                    onClick={closeGallery}
+                  >
+                    <Close32 className={icon} />
+                  </button>
+                </Column>
+              </Row>
+              <Grid className={galleryGrid}>
+                <Row className={galleryRow}>
+                  <Column colLg={3} className={navButtonsContainer}>
+                    {activeImageIndex - 1 >= 0 && (
+                      <button
+                        type="button"
+                        className={leftNavButton}
+                        onClick={selectPrevImage}
+                      >
+                        <ChevronLeft32 className={icon} />
+                      </button>
+                    )}
+                  </Column>
+                  <Column colLg={6}>
+                    {React.cloneElement(mediaChildren[activeImageIndex], {
+                      isInDialog: true,
+                    })}
+                  </Column>
+                  <Column colLg={3} className={navButtonsContainer}>
+                    {activeImageIndex + 1 < mediaChildren.length && (
+                      <button
+                        type="button"
+                        className={rightNavButton}
+                        onClick={selectNextImage}
+                      >
+                        <ChevronRight32 className={icon} />
+                      </button>
+                    )}
+                  </Column>
+                </Row>
+              </Grid>
+            </div>
+          </FocusTrap>,
+          portalsNode
+        )}
+    </>
+  );
+}
+
+ImageGallery.propTypes = {
+  children: PropTypes.arrayOf(PropTypes.element).isRequired,
+};
+
+export default ImageGallery;