feat(*): add options fit and background to image sharp (#13078)

gatsby-plugin-sharp
- add `fit` and `background` options to control cropping when using fluid

gatsby-transformer-sharp
- add new `ImageFitType` type and add `fit` and `background` to `fluidNodeType` args.

## Related Issues
fixes #12972.

Author: VGoose

packages/gatsby-plugin-sharp/README.md

@@ -96,13 +96,21 @@ a base64 image to use as a placeholder) you need to implement the "blur up"
 technique popularized by Medium and Facebook (and also available as a Gatsby
 plugin for Markdown content as gatsby-remark-images).
 
+When both a `maxWidth` and `maxHeight` are provided, sharp will use `COVER` as a fit strategy by default. This might not be ideal so you can now choose between `COVER`, `CONTAIN` and `FILL` as a fit strategy. To see them in action the [CSS property object-fit](https://developer.mozilla.org/en-US/docs/Web/CSS/object-fit) comes close to its implementation.
+
+#### Note
+
+fit strategies `CONTAIN` and `FILL` will not work when `cropFocus` is assigned to [sharp.strategy][6]. The `cropFocus` option cannot be `ENTROPY` or `ATTENTION`
+
 #### Parameters
 
 - `maxWidth` (int, default: 800)
 - `maxHeight` (int)
 - `quality` (int, default: 50)
 - `sizeByPixelDensity` (bool, default: false)
 - `srcSetBreakpoints` (array of int, default: [])
+- `fit` (string, default: '[sharp.fit.cover][6]')
+- `background` (string, default: 'rgba(0,0,0,1)')
 
 #### Returns
 
@@ -308,3 +316,4 @@ pre-process your images with a tool such as [ExifTool][17].
 [15]: http://sharp.dimens.io/en/stable/api-operation/#flatten
 [16]: https://github.com/mozilla/mozjpeg
 [17]: https://www.sno.phy.queensu.ca/~phil/exiftool/
+[18]: https://www.npmjs.com/package/color

packages/gatsby-plugin-sharp/src/__tests__/process-file.js

@@ -12,6 +12,8 @@ describe(`createArgsDigest`, () => {
     grayscale: false,
     rotate: 0,
     duotone: null,
+    fit: `COVER`,
+    background: `rgb(0,0,0,1)`,
   }
 
   describe(`changes hash if used args are different`, () => {
@@ -47,12 +49,14 @@ describe(`createArgsDigest`, () => {
     testHashDifferent(`rotate change`, {
       rotate: defaultArgsBaseline.rotate + 1,
     })
-    testHashDifferent(`dutone change`, {
+    testHashDifferent(`duotone change`, {
       duotone: {
         highlight: `#ff0000`,
         shadow: `#000000`,
       },
     })
+    testHashDifferent(`fit change`, { fit: `CONTAIN` })
+    testHashDifferent(`background change`, { background: `#fff0` })
   })
 
   describe(`doesn't change hash if not used options are different`, () => {

packages/gatsby-plugin-sharp/src/process-file.js

@@ -42,6 +42,8 @@ const argsWhitelist = [
   `grayscale`,
   `rotate`,
   `duotone`,
+  `fit`,
+  `background`,
 ]
 
 /**
@@ -104,6 +106,8 @@ exports.processFile = (file, transforms, options = {}) => {
     clonedPipeline
       .resize(roundedWidth, roundedHeight, {
         position: args.cropFocus,
+        fit: args.fit,
+        background: args.background,
       })
       .png({
         compressionLevel: args.pngCompressionLevel,

packages/gatsby-transformer-sharp/src/extend-node-type.js

@@ -28,6 +28,7 @@ const {
   ImageCropFocusType,
   DuotoneGradientType,
   PotraceType,
+  ImageFitType,
 } = require(`./types`)
 
 function toArray(buf) {
@@ -285,6 +286,14 @@ const fluidNodeType = ({
         type: ImageCropFocusType,
         defaultValue: sharp.strategy.attention,
       },
+      fit: {
+        type: ImageFitType,
+        defaultValue: sharp.fit.cover,
+      },
+      background: {
+        type: GraphQLString,
+        defaultValue: `rgba(0,0,0,1)`,
+      },
       rotate: {
         type: GraphQLInt,
         defaultValue: 0,

packages/gatsby-transformer-sharp/src/types.js

@@ -19,6 +19,15 @@ const ImageFormatType = new GraphQLEnumType({
   },
 })
 
+const ImageFitType = new GraphQLEnumType({
+  name: `ImageFit`,
+  values: {
+    COVER: { value: sharp.fit.cover },
+    CONTAIN: { value: sharp.fit.contain },
+    FILL: { value: sharp.fit.fill },
+  },
+})
+
 const ImageCropFocusType = new GraphQLEnumType({
   name: `ImageCropFocus`,
   values: {
@@ -78,6 +87,7 @@ const PotraceType = new GraphQLInputObjectType({
 
 module.exports = {
   ImageFormatType,
+  ImageFitType,
   ImageCropFocusType,
   DuotoneGradientType,
   PotraceType,