fix(gatsby-image): React hydration buster on image

e2e-tests/gatsby-image/cypress/integration/fluid.js

@@ -9,7 +9,7 @@ describe(`fluid`, () => {
     cy.getTestElement(fluidTestId)
       .find(`.gatsby-image-wrapper > div`)
       .should(`have.attr`, `style`)
-      .and(`match`, /width:100%;padding-bottom/)
+      .and(`match`, /width: 100%; padding-bottom/)
   })
 
   it(`renders sizes`, () => {

e2e-tests/gatsby-image/cypress/integration/image.js

@@ -14,11 +14,11 @@ describe(`Production gatsby-image`, () => {
           .should(`eq`, 1)
       })
 
-      it(`contains position relative`, () => {
+      it(`has position relative`, () => {
         cy.getTestElement(fluidTestId)
           .find(`.gatsby-image-wrapper`)
           .should(`have.attr`, `style`)
-          .and(`contains`, `position:relative`)
+          .and(`match`, /position: relative/)
       })
     })
   })

package.json

@@ -54,6 +54,7 @@
     "jest-cli": "^24.9.0",
     "jest-environment-jsdom-fourteen": "^0.1.0",
     "jest-junit": "^10.0.0",
+    "jest-matchmedia-mock": "^1.0.1",
     "jest-serializer-path": "^0.1.15",
     "jest-silent-reporter": "^0.2.1",
     "joi": "^14.3.1",

packages/gatsby-image/src/__tests__/index.js

@@ -1,3 +1,4 @@
+import MatchMediaMock from "jest-matchmedia-mock"
 import React from "react"
 import { render, cleanup, fireEvent } from "@testing-library/react"
 import Image from "../"
@@ -117,22 +118,13 @@ const setupImages = (
   return container
 }
 
+let matchMedia
 describe(`<Image />`, () => {
-  const OLD_MATCH_MEDIA = window.matchMedia
-  beforeEach(() => {
-    // None of the media conditions above match.
-    window.matchMedia = jest.fn(media =>
-      media === `only screen and (min-width: 1024px)`
-        ? {
-            matches: true,
-          }
-        : {
-            matches: false,
-          }
-    )
+  beforeAll(() => {
+    matchMedia = new MatchMediaMock()
   })
   afterEach(() => {
-    window.matchMedia = OLD_MATCH_MEDIA
+    matchMedia.clear()
   })
 
   it(`should render fixed size images`, () => {
@@ -221,6 +213,9 @@ describe(`<Image />`, () => {
   })
 
   it(`should select the correct mocked image of fluid variants provided.`, () => {
+    const mediaQuery = `only screen and (min-width: 1024px)`
+    matchMedia.useMediaQuery(mediaQuery)
+
     const tripleFluidImageShapeMock = fluidImagesShapeMock.concat({
       aspectRatio: 5,
       src: `test_image_4.jpg`,
@@ -251,6 +246,9 @@ describe(`<Image />`, () => {
   })
 
   it(`should select the correct mocked image of fixed variants provided.`, () => {
+    const mediaQuery = `only screen and (min-width: 1024px)`
+    matchMedia.useMediaQuery(mediaQuery)
+
     const tripleFixedImageShapeMock = fixedImagesShapeMock.concat({
       width: 1024,
       height: 768,

packages/gatsby-image/src/index.js

@@ -18,6 +18,23 @@ const logDeprecationNotice = (prop, replacement) => {
   }
 }
 
+// DJB2a (XOR variant) is a simple hashing function, reduces input to 32-bits
+const SEED = 5381
+function djb2a(str) {
+  let h = SEED
+
+  for (let i = 0; i < str.length; i++) {
+    h = (h * 33) ^ str.charCodeAt(i)
+  }
+
+  // Cast to 32-bit uint
+  return h >>> 0
+}
+
+// Converts string input to a 32-bit base36 string (0-9, a-z)
+// '_' prefix to prevent invalid first chars for CSS class names
+const getShortKey = input => `_` + djb2a(input).toString(36)
+
 // Handle legacy props during their deprecation phase
 const convertProps = props => {
   let convertedProps = { ...props }
@@ -54,7 +71,7 @@ const convertProps = props => {
  * @param currentData  {{media?: string}[]}   The props to check for images.
  * @return {boolean}
  */
-const hasArtDirectionSupport = currentData =>
+const isUsingArtDirection = currentData =>
   !!currentData &&
   Array.isArray(currentData) &&
   currentData.some(image => typeof image.media !== `undefined`)
@@ -85,7 +102,7 @@ const getImageSrcKey = ({ fluid, fixed }) => {
  * @return {{src: string, media?: string, maxWidth?: Number, maxHeight?: Number}}
  */
 const getCurrentSrcData = currentData => {
-  if (isBrowser && hasArtDirectionSupport(currentData)) {
+  if (isBrowser && isUsingArtDirection(currentData)) {
     // Do we have an image for the current Viewport?
     const foundMedia = currentData.findIndex(matchesMedia)
     if (foundMedia !== -1) {
@@ -193,6 +210,32 @@ function groupByMedia(imageVariants) {
   return [...withMedia, ...without]
 }
 
+// For Art Direction: SSR + Initial load, removed upon rehydration
+// Ensures correct CSS for image variants is applied
+const ResponsiveQueries = ({ imageVariants, selectorClass }) => {
+  const variantRule = ({ width, height, aspectRatio }) => {
+    // '!important' required due to overriding inline styles
+    // 'aspectRatio' == fluid data
+    const styleOverride = aspectRatio
+      ? `padding-bottom: ${100 / aspectRatio}% !important;`
+      : `width: ${width}px !important; height: ${height}px !important;`
+
+    return `.${selectorClass} { ${styleOverride} }`
+  }
+
+  const base = variantRule(imageVariants.find(v => !v.media))
+  return (
+    <>
+      {base && <style>{base}</style>}
+      {imageVariants
+        .filter(v => v.media)
+        .map(v => (
+          <style media={v.media}>{variantRule(v)}</style>
+        ))}
+    </>
+  )
+}
+
 function generateTracedSVGSources(imageVariants) {
   return imageVariants.map(({ src, media, tracedSVG }) => (
     <source key={src} media={media} srcSet={tracedSVG} />
@@ -352,15 +395,48 @@ class Image extends React.Component {
       imgLoaded: false,
       imgCached: false,
       fadeIn: !this.seenBefore && props.fadeIn,
+      isHydrated: false,
     }
 
     this.imageRef = React.createRef()
     this.placeholderRef = props.placeholderRef || React.createRef()
     this.handleImageLoaded = this.handleImageLoaded.bind(this)
     this.handleRef = this.handleRef.bind(this)
+
+    // Supports Art Direction feature to correctly render image variants
+    const imageVariants = props.fluid || props.fixed
+    if (isUsingArtDirection(imageVariants)) {
+      this.uniqueKey =
+        !isBrowser && getShortKey(imageVariants.map(v => v.srcSet).join(``))
+
+      // When image variant changes, adapt via render immediately instead of delaying
+      // until new image request triggers 'onload' event.
+      // Can be verified on 'slow 3G' with no initial cache.
+      if (isBrowser) {
+        this.handleVariantChange = this.handleVariantChange.bind(this)
+        const base = imageVariants.find(v => !v.media)
+
+        this.mq = { base }
+        this.mq.queries = imageVariants.filter(v => v.media)
+        this.mq.queries.forEach(v => {
+          this.mq[v.media] = v
+          const mql = window.matchMedia(v.media)
+          if (mql.addEventListener) {
+            mql.addEventListener(`change`, this.handleVariantChange)
+          } else {
+            // Deprecated 'MediaQueryList' API, <Safari 14, IE, <Edge 16
+            mql.addListener(this.handleVariantChange)
+          }
+        })
+      }
+    }
   }
 
   componentDidMount() {
+    this.setState({
+      isHydrated: isBrowser,
+    })
+
     if (this.state.isVisible && typeof this.props.onStartLoad === `function`) {
       this.props.onStartLoad({ wasCached: inImageCache(this.props) })
     }
@@ -413,13 +489,31 @@ class Image extends React.Component {
   handleImageLoaded() {
     activateCacheForImage(this.props)
 
-    this.setState({ imgLoaded: true })
+    if (!this.state.imgLoaded) {
+      this.setState({ imgLoaded: true })
+    }
 
     if (this.props.onLoad) {
       this.props.onLoad()
     }
   }
 
+  // 'window.matchMedia()' events on image variants media conditions.
+  // If variant is not in image cache when triggered, resets the image
+  // loading state so that the placeholder is visible instead of blank.
+  handleVariantChange(e) {
+    const match =
+      (e.matches && this.mq[e.media]) ||
+      this.mq.queries.find(matchesMedia) ||
+      this.mq.base
+
+    this.seenBefore = imageCache[match.src]
+    this.setState({
+      imgLoaded: this.seenBefore,
+      imgCached: this.seenBefore,
+    })
+  }
+
   render() {
     const {
       title,
@@ -439,6 +533,12 @@ class Image extends React.Component {
       draggable,
     } = convertProps(this.props)
 
+    // Avoid render logic on client until component mounts (hydration complete)
+    // Prevents using mismatched initial state from the hydration phase
+    if (isBrowser && !this.state.isHydrated) {
+      return null
+    }
+
     const shouldReveal = this.state.fadeIn === false || this.state.imgLoaded
     const shouldFadeIn = this.state.fadeIn === true && !this.state.imgCached
 
@@ -470,13 +570,18 @@ class Image extends React.Component {
       itemProp,
     }
 
-    if (fluid) {
-      const imageVariants = fluid
-      const image = getCurrentSrcData(fluid)
+    const imageVariants = fluid || fixed
+    const image = getCurrentSrcData(imageVariants)
+
+    const activeVariant = getShortKey(image.srcSet)
+    const uniqueKey = this.uniqueKey
 
+    if (fluid) {
       return (
         <Tag
-          className={`${className ? className : ``} gatsby-image-wrapper`}
+          className={`${
+            (className ? className : ``) + (uniqueKey ? uniqueKey : ``)
+          } gatsby-image-wrapper`}
           style={{
             position: `relative`,
             overflow: `hidden`,
@@ -485,8 +590,14 @@ class Image extends React.Component {
             ...style,
           }}
           ref={this.handleRef}
-          key={`fluid-${JSON.stringify(image.srcSet)}`}
+          key={activeVariant}
         >
+          {uniqueKey && (
+            <ResponsiveQueries
+              imageVariants={imageVariants}
+              selectorClass={uniqueKey}
+            />
+          )}
           {/* Preserve the aspect ratio. */}
           <Tag
             aria-hidden
@@ -579,9 +690,6 @@ class Image extends React.Component {
     }
 
     if (fixed) {
-      const imageVariants = fixed
-      const image = getCurrentSrcData(fixed)
-
       const divStyle = {
         position: `relative`,
         overflow: `hidden`,
@@ -597,11 +705,19 @@ class Image extends React.Component {
 
       return (
         <Tag
-          className={`${className ? className : ``} gatsby-image-wrapper`}
+          className={`${
+            (className ? className : ``) + (uniqueKey ? uniqueKey : ``)
+          } gatsby-image-wrapper`}
           style={divStyle}
           ref={this.handleRef}
-          key={`fixed-${JSON.stringify(image.srcSet)}`}
+          key={activeVariant}
         >
+          {uniqueKey && (
+            <ResponsiveQueries
+              imageVariants={imageVariants}
+              selectorClass={uniqueKey}
+            />
+          )}
           {/* Show a solid background color. */}
           {bgColor && (
             <Tag

yarn.lock

@@ -13458,6 +13458,11 @@ jest-matcher-utils@^24.9.0:
     jest-get-type "^24.9.0"
     pretty-format "^24.9.0"
 
+jest-matchmedia-mock@^1.0.1:
+  version "1.0.1"
+  resolved "https://registry.yarnpkg.com/jest-matchmedia-mock/-/jest-matchmedia-mock-1.0.1.tgz#da1c75be82a3b3e46e6c8ae195aa54e4a6032eb4"
+  integrity sha512-IXk2AnldfsCRmhB4pFY0Eb9mk2NxFqOgOwA4DxKOJ22T5bn/j3DzM5s3cdKxuEowmpuXK1gPXAIlVGIC+kb/fA==
+
 jest-message-util@^22.4.0, jest-message-util@^22.4.3:
   version "22.4.3"
   resolved "https://registry.yarnpkg.com/jest-message-util/-/jest-message-util-22.4.3.tgz#cf3d38aafe4befddbfc455e57d65d5239e399eb7"