From 27cc9c84e6c1323c3e1f31746949680765ee1131 Mon Sep 17 00:00:00 2001
From: James Shakespeare <jshakespeare@qz.com>
Date: Fri, 4 Dec 2020 17:30:22 -0500
Subject: [PATCH] Adds Image and ResponsiveImage className prop (#82)

* add className prop to images to override default styling

* image docs elaboration

* docs tweaks, fix indentation

* amp-img doesn't get className; only concat classNames if prop is defined
---
 src/components/Image/Image.jsx                     | 8 +++++++-
 src/components/Image/Image.stories.mdx             | 4 +++-
 src/components/ResponsiveImage/ResponsiveImage.jsx | 7 +++++++
 3 files changed, 17 insertions(+), 2 deletions(-)

diff --git a/src/components/Image/Image.jsx b/src/components/Image/Image.jsx
index ade5d4d5..cbc0c5ea 100644
--- a/src/components/Image/Image.jsx
+++ b/src/components/Image/Image.jsx
@@ -38,6 +38,7 @@ ImageAmp.propTypes = {
 function Image ( {
 	alt,
 	amp,
+	className,
 	fallbackHeight: height,
 	fallbackWidth: width,
 	loading,
@@ -63,7 +64,7 @@ function Image ( {
 	return (
 		<img
 			alt={alt}
-			className={styles.image}
+			className={className ? `${styles.image} ${className}` : styles.image}
 			decoding="async"
 			height={height}
 			loading={loading}
@@ -90,6 +91,11 @@ Image.propTypes = {
 	 */
 	amp: PropTypes.bool.isRequired,
 
+	/**
+	 * Passed verbatim to element as class attribute.
+	 */
+	className: PropTypes.string,
+
 	/**
 	 * The rendered height of the image when CSS cannot be loaded or in very old
 	 * browsers. With `fallbackWidth`, it sets the aspect ratio for the image.
diff --git a/src/components/Image/Image.stories.mdx b/src/components/Image/Image.stories.mdx
index fd143bd3..d0dad475 100644
--- a/src/components/Image/Image.stories.mdx
+++ b/src/components/Image/Image.stories.mdx
@@ -7,11 +7,13 @@ import Image from './Image';
 
 Displays an image. The `Image` component requires `fallbackHeight` and `fallbackWidth` to set aspect ratio and `sizes` and `srcSet` to provide [responsive rendering](https://developer.mozilla.org/en-US/docs/Learn/HTML/Multimedia_and_embedding/Responsive_images). They will not be calculated for you and there are no default values. Future components may provide a simpler implementation for specific use cases.
 
+The image element (`img` or `amp-img`) is rendered with some lightly opinionated but commonly needed styles: `display: block` and `width: 100%`. These styles may be overridden using the `className` prop, but whenever possible you should use a parent element to constrain the dimensions of the image.
+
 This component does not provide [art direction](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/picture), which is also a task for a future component.
 
 ## Usage guidelines
 
-- **Do** use a container to constrain the size or shape of the image. An `Image` will always expand or contract to fit the width of its container. The `Image` component purposefully does not accept a `className` prop.
+- **Do** use a container to constrain the size or shape of the image whenever possible. By default, an `Image` will expand or contract to fit the width of its container. This can be overridden using styles applied via the `className` prop. You may (rarely) want to do this in order to have an image fill its parent element by height rather than width, or in order to use the `object-fit` property.
 - **Do** understand that the `fallbackHeight` and `fallbackWidth` props are [used to set aspect ratio and help the browser reserve space](https://blog.logrocket.com/jank-free-page-loading-with-media-aspect-ratios/) for the image during initial layout.
 - **Do** [provide useful alt text](https://www.w3.org/WAI/tutorials/images/decision-tree/) for your images. Sometimes, an empty string is the most useful!
 - **Do** learn why and how to use [responsive rendering](https://developer.mozilla.org/en-US/docs/Learn/HTML/Multimedia_and_embedding/Responsive_images). It’s important to understand how `sizes` and `srcSet` work.
diff --git a/src/components/ResponsiveImage/ResponsiveImage.jsx b/src/components/ResponsiveImage/ResponsiveImage.jsx
index 0311869e..b32fc754 100644
--- a/src/components/ResponsiveImage/ResponsiveImage.jsx
+++ b/src/components/ResponsiveImage/ResponsiveImage.jsx
@@ -6,6 +6,7 @@ import { arrayFromRange, resizeWPImage } from '@quartz/js-utils';
 function ResponsiveImage( {
 	alt,
 	amp,
+	className,
 	fallbackHeight,
 	fallbackWidth,
 	sizes,
@@ -33,6 +34,7 @@ function ResponsiveImage( {
 		<Image
 			alt={alt}
 			amp={amp}
+			className={className}
 			sizes={sizes || sizesDefault}
 			src={resizeWPImage( src, fallbackWidth, fallbackHeight )}
 			srcSet={srcSet}
@@ -56,6 +58,11 @@ ResponsiveImage.propTypes = {
 	 */
 	amp: PropTypes.bool.isRequired,
 
+	/**
+	 * Passed verbatim to img or amp-img element as class attribute.
+	 */
+	className: PropTypes.string,
+
 	/**
 	 * The rendered height of the image when CSS cannot be loaded or in very old
 	 * browsers. With `fallbackWidth`, it sets the aspect ratio for the image.