Add new 'raw' image layout

docs/api-reference/next/image.md

@@ -16,6 +16,7 @@ description: Enable Image Optimization with the built-in Image component.
 
 | Version   | Changes                                                                                           |
 | --------- | ------------------------------------------------------------------------------------------------- |
+| `v12.0.11`| `raw` layout added                                                                             |
 | `v12.0.9` | `lazyRoot` prop added                                                                             |
 | `v12.0.0` | `formats` configuration added.<br/>AVIF support added.<br/>Wrapper `<div>` changed to `<span>`.   |
 | `v11.1.0` | `onLoadingComplete` and `lazyBoundary` props added.                                               |
@@ -70,6 +71,8 @@ The layout behavior of the image as the viewport changes size.
 | `fixed`               | Sized to `width` and `height` exactly                    | `1x`, `2x` (based on [imageSizes](#image-sizes))                                                            | N/A     |
 | `responsive`          | Scale to fit width of container                          | `640w`, `750w`, ... `2048w`, `3840w` (based on [imageSizes](#image-sizes) and [deviceSizes](#device-sizes)) | `100vw` |
 | `fill`                | Grow in both X and Y axes to fill container              | `640w`, `750w`, ... `2048w`, `3840w` (based on [imageSizes](#image-sizes) and [deviceSizes](#device-sizes)) | `100vw` |
+| `raw`                 | Insert the image element with no responsive behavior     | `640w`, `750w`, ... `2048w`, `3840w` (based on [imageSizes](#image-sizes) and [deviceSizes](#device-sizes)) | `100vw` |
+
 
 - [Demo the `intrinsic` layout (default)](https://image-component.nextjs.gallery/layout-intrinsic)
   - When `intrinsic`, the image will scale the dimensions down for smaller viewports, but maintain the original dimensions for larger viewports.
@@ -82,6 +85,10 @@ The layout behavior of the image as the viewport changes size.
   - When `fill`, the image will stretch both width and height to the dimensions of the parent element, provided the parent element is relative.
   - This is usually paired with the [`objectFit`](#objectFit) property.
   - Ensure the parent element has `position: relative` in their stylesheet.
+- When `raw`, the image will be rendered as a single image element with no wrappers, sizers or other responsive behavior. 
+  - Unlike other layout modes, a `raw` image will pass through the `style` property to the underlying image.
+  - If your image styling will change the size of a `raw` image, you should include the `sizes` property for proper image serving.
+  - The other layout modes are optimized for performance and should cover nearly all use cases. It is recommended to try to use those modes before using `raw`.
 - [Demo background image](https://image-component.nextjs.gallery/background)
 
 ### loader
@@ -120,7 +127,7 @@ const MyImage = (props) => {
 
 A string that provides information about how wide the image will be at different breakpoints. Defaults to `100vw` (the full width of the screen) when using `layout="responsive"` or `layout="fill"`.
 
-If you are using `layout="fill"` or `layout="responsive"`, it's important to assign `sizes` for any image that takes up less than the full viewport width.
+If you are using `layout="fill"`, `layout="responsive"`, or `layout="raw"` it's important to assign `sizes` for any image that takes up less than the full viewport width.
 
 For example, when the parent element will constrain the image to always be less than half the viewport width, use `sizes="50vw"`. Without `sizes`, the image will be sent at twice the necessary resolution, decreasing performance.
 
@@ -284,7 +291,7 @@ size, or format. Defaults to `false`.
 Other properties on the `<Image />` component will be passed to the underlying
 `img` element with the exception of the following:
 
-- `style`. Use `className` instead.
+- `style`. Only allowed on `layout="raw"` images. For others, use `className` instead.
 - `srcSet`. Use
   [Device Sizes](#device-sizes)
   instead.

docs/basic-features/image-optimization.md

@@ -181,7 +181,8 @@ The image component has several different [layout modes](/docs/api-reference/nex
 
 **Target the image with className, not based on DOM structure**
 
-Regardless of the layout mode used, the Image component will have a consistent DOM structure of one `<img>` tag wrapped by exactly one `<span>`. For some modes, it may also have a sibling `<span>` for spacing. These additional `<span>` elements are critical to allow the component to prevent layout shifts.
+For all of the standard layout modes, the Image component will have a consistent DOM structure of one `<img>` tag wrapped by exactly one `<span>`. For some modes, it may also have a sibling `<span>` for spacing. These additional `<span>` elements are critical to allow the component to prevent layout shifts.
+
 
 The recommended way to style the inner `<img>` is to set the `className` prop on the Image component to the value of an imported [CSS Module](/docs/basic-features/built-in-css-support.md#adding-component-level-css). The value of `className` will be automatically applied to the underlying `<img>` element.
 
@@ -191,6 +192,8 @@ You cannot use [styled-jsx](/docs/basic-features/built-in-css-support.md#css-in-
 
 You cannot use the `style` prop because the `<Image>` component does not pass it through to the underlying `<img>`.
 
+> An additional `raw` layout mode is provided which removes the wrapper element and allows the `style` prop. This mode still requires `height` and `width` and is recommended only for advanced use cases that aren't covered by the primary layout modes.
+
 **When using `layout='fill'`, the parent element must have `position: relative`**
 
 This is necessary for the proper rendering of the image element in that layout mode.

packages/next/client/image.tsx

@@ -48,6 +48,7 @@ const VALID_LAYOUT_VALUES = [
   'fixed',
   'intrinsic',
   'responsive',
+  'raw',
   undefined,
 ] as const
 type LayoutValue = typeof VALID_LAYOUT_VALUES[number]
@@ -107,15 +108,26 @@ export type ImageProps = Omit<
   objectFit?: ImgElementStyle['objectFit']
   objectPosition?: ImgElementStyle['objectPosition']
   onLoadingComplete?: OnLoadingComplete
-}
+} & (
+    | {
+        layout?: Omit<LayoutValue, 'raw'>
+      }
+    | {
+        layout: 'raw'
+        style: ImgElementStyle
+      }
+  )
 
 function getWidths(
   { deviceSizes, allSizes }: ImageConfig,
   width: number | undefined,
   layout: LayoutValue,
   sizes: string | undefined
 ): { widths: number[]; kind: 'w' | 'x' } {
-  if (sizes && (layout === 'fill' || layout === 'responsive')) {
+  if (
+    sizes &&
+    (layout === 'fill' || layout === 'responsive' || layout === 'raw')
+  ) {
     // Find all the "vw" percent sizes used in the sizes prop
     const viewportWidthRe = /(^|\s)(1?\d?\d)vw/g
     const percentSizes = []
@@ -134,7 +146,8 @@ function getWidths(
   if (
     typeof width !== 'number' ||
     layout === 'fill' ||
-    layout === 'responsive'
+    layout === 'responsive' ||
+    layout === 'raw'
   ) {
     return { widths: deviceSizes, kind: 'w' }
   }
@@ -425,9 +438,14 @@ export default function Image({
         `Image with src "${src}" has both "priority" and "loading='lazy'" properties. Only one should be used.`
       )
     }
-    if (sizes && layout !== 'fill' && layout !== 'responsive') {
+    if (
+      sizes &&
+      layout !== 'fill' &&
+      layout !== 'responsive' &&
+      layout !== 'raw'
+    ) {
       console.warn(
-        `Image with src "${src}" has "sizes" property but it will be ignored. Only use "sizes" with "layout='fill'" or "layout='responsive'".`
+        `Image with src "${src}" has "sizes" property but it will be ignored. Only use "sizes" with 'fill,' 'responsive,' or 'raw' layout modes.`
       )
     }
     if (placeholder === 'blur') {
@@ -456,7 +474,7 @@ export default function Image({
         `Image with src "${src}" is using unsupported "ref" property. Consider using the "onLoadingComplete" property instead.`
       )
     }
-    if ('style' in rest) {
+    if ('style' in rest && layout !== 'raw') {
       console.warn(
         `Image with src "${src}" is using unsupported "style" property. Please use the "className" property instead.`
       )
@@ -638,6 +656,22 @@ export default function Image({
     })
   }
 
+  let isRaw = false
+  const rawStyle: ImgElementStyle = {}
+
+  if (layout === 'raw') {
+    isRaw = true
+    const styleProp = 'style' in rest && rest.style ? rest.style : {}
+    Object.assign(
+      rawStyle,
+      {
+        ...(objectFit ? { objectFit } : {}),
+        ...(objectPosition ? { objectPosition } : {}),
+      },
+      styleProp
+    )
+  }
+
   let srcString: string = src
 
   if (process.env.NODE_ENV !== 'production') {
@@ -680,7 +714,46 @@ export default function Image({
     handleLoading(imgRef, srcString, layout, placeholder, onLoadingCompleteRef)
   }, [srcString, layout, placeholder, isVisible])
 
-  return (
+  return isRaw ? (
+    <>
+      <img
+        {...rest}
+        {...imgAttributes}
+        decoding="async"
+        data-nimg={layout}
+        height={heightInt}
+        width={widthInt}
+        className={className}
+        ref={imgRef}
+        style={{ ...blurStyle, ...rawStyle }}
+      />
+      {isLazy && (
+        <noscript>
+          <img
+            {...rest}
+            {...generateImgAttrs({
+              config,
+              src,
+              unoptimized,
+              layout,
+              width: widthInt,
+              quality: qualityInt,
+              sizes,
+              loader,
+            })}
+            decoding="async"
+            data-nimg={layout}
+            height={heightInt}
+            width={widthInt}
+            style={rawStyle}
+            className={className}
+            // @ts-ignore - TODO: upgrade to `@types/react@17`
+            loading={loading || 'lazy'}
+          />
+        </noscript>
+      )}
+    </>
+  ) : (
     <span style={wrapperStyle}>
       {hasSizer ? (
         <span style={sizerStyle}>

test/integration/image-component/default/pages/layout-raw.js

@@ -0,0 +1,48 @@
+import React from 'react'
+import Image from 'next/image'
+
+const Page = () => {
+  return (
+    <div>
+      <p>Layout Raw</p>
+      <div id="image-container1">
+        <Image
+          id="raw1"
+          src="/wide.png"
+          width="1200"
+          height="700"
+          layout="raw"
+          objectFit="cover"
+          loading="eager"
+        ></Image>
+      </div>
+      <div id="image-container2">
+        <Image
+          id="raw2"
+          src="/wide.png"
+          width="1200"
+          height="700"
+          objectFit="cover"
+          objectPosition="50% 50%"
+          style={{
+            paddingLeft: '4rem',
+            width: '100%',
+            objectPosition: '30% 30%',
+          }}
+          layout="raw"
+        ></Image>
+      </div>
+      <div id="image-container3">
+        <Image
+          id="raw3"
+          src="/test.png"
+          width="400"
+          height="400"
+          layout="raw"
+        ></Image>
+      </div>
+    </div>
+  )
+}
+
+export default Page

test/integration/image-component/default/pages/on-loading-complete.js

@@ -84,6 +84,16 @@ const Page = () => {
         idToCount={idToCount}
         setIdToCount={setIdToCount}
       />
+
+      <ImageWithMessage
+        id="9"
+        src={require('../public/test.png')}
+        placeholder="blur"
+        layout="raw"
+        idToCount={idToCount}
+        setIdToCount={setIdToCount}
+      />
+
       <button id="toggle" onClick={() => setClicked(!clicked)}>
         Toggle
       </button>

test/integration/image-component/default/test/index.test.js

@@ -273,6 +273,10 @@ function runTests(mode) {
         () => browser.eval(`document.getElementById("img8").currentSrc`),
         /test-rect.jpg/
       )
+      await check(
+        () => browser.eval(`document.getElementById("msg9").textContent`),
+        'loaded 1 img9 with dimensions 266x266'
+      )
     } finally {
       if (browser) {
         await browser.close()
@@ -584,6 +588,40 @@ function runTests(mode) {
     }
   })
 
+  it('should render no wrappers or sizers and minimal styling with layout-raw', async () => {
+    let browser
+    try {
+      browser = await webdriver(appPort, '/layout-raw')
+
+      const numberOfChildren = await browser.eval(
+        `document.getElementById('image-container1').children.length`
+      )
+      expect(numberOfChildren).toBe(1)
+      const childElementType = await browser.eval(
+        `document.getElementById('image-container1').children[0].nodeName`
+      )
+      expect(childElementType).toBe('IMG')
+
+      expect(await browser.elementById('raw1').getAttribute('style')).toBe(
+        'object-fit:cover'
+      )
+
+      expect(await browser.elementById('raw2').getAttribute('style')).toBe(
+        'object-fit:cover;object-position:30% 30%;padding-left:4rem;width:100%'
+      )
+
+      expect(await browser.elementById('raw3').getAttribute('style')).toBeNull()
+
+      const warnings = (await browser.log('browser'))
+        .map((log) => log.message)
+        .join('\n')
+    } finally {
+      if (browser) {
+        await browser.close()
+      }
+    }
+  })
+
   if (mode === 'dev') {
     it('should show missing src error', async () => {
       const browser = await webdriver(appPort, '/missing-src')