[@astrojs/image] flatten background only if alpha channel isn't suppo…

…rted (#4800)

* Use sharp flatten only when format doesnt support alpha

* Allow rgba for background prop

* Add changeset

* Adjust doc

* Fix tests

.changeset/grumpy-monkeys-watch.md

@@ -0,0 +1,5 @@
+---
+'@astrojs/image': patch
+---
+
+Prevent background flattening on formats supporting transparency

packages/integrations/image/README.md

@@ -195,15 +195,17 @@ A `number` can also be provided, useful when the aspect ratio is calculated at b
 **Default:** `undefined`
 </p>
 
-The background color to use for replacing the alpha channel with `sharp`'s `flatten` method. In case the output format
+The background color is used to fill the remaining background when using `contain` for the `fit` property.
+
+The background color is also used for replacing the alpha channel with `sharp`'s `flatten` method. In case the output format
 doesn't support transparency (i.e. `jpeg`), it's advisable to include a background color, otherwise black will be used
 as default replacement for transparent pixels.
 
 The parameter accepts a `string` as value.
 
 The parameter can be a [named HTML color](https://www.w3schools.com/tags/ref_colornames.asp), a hexadecimal
-color representation with 3 or 6 hexadecimal characters in the form `#123[abc]`, or an RGB definition in the form
-`rgb(100,100,100)`.
+color representation with 3 or 6 hexadecimal characters in the form `#123[abc]`, an RGB definition in the form
+`rgb(100,100,100)`, an RGBA definition in the form `rgba(100,100,100, 0.5)`.
 
 #### fit
 

packages/integrations/image/src/loaders/index.ts

@@ -19,7 +19,9 @@ export type ColorDefinition =
 	| NamedColor
 	| `#${string}`
 	| `rgb(${number}, ${number}, ${number})`
-	| `rgb(${number},${number},${number})`;
+	| `rgb(${number},${number},${number})`
+	| `rgba(${number}, ${number}, ${number}, ${number})`
+	| `rgba(${number},${number},${number},${number})`
 
 export type CropFit = 'cover' | 'contain' | 'fill' | 'inside' | 'outside';
 

packages/integrations/image/src/loaders/sharp.ts

@@ -1,5 +1,10 @@
 import sharp from 'sharp';
-import { ColorDefinition, isAspectRatioString, isOutputFormat } from '../loaders/index.js';
+import {
+	ColorDefinition,
+	isAspectRatioString,
+	isOutputFormat,
+	isOutputFormatSupportsAlpha,
+} from '../loaders/index.js';
 import type { OutputFormat, SSRImageService, TransformOptions } from './index.js';
 
 class SharpService implements SSRImageService {
@@ -119,13 +124,12 @@ class SharpService implements SSRImageService {
 			});
 		}
 
-		// remove alpha channel and replace with background color if requested
-		if (transform.background) {
-			sharpImage.flatten({ background: transform.background });
-		}
-
 		if (transform.format) {
 			sharpImage.toFormat(transform.format, { quality: transform.quality });
+
+			if (transform.background && !isOutputFormatSupportsAlpha(transform.format)) {
+				sharpImage.flatten({ background: transform.background });
+			}
 		}
 
 		const { data, info } = await sharpImage.toBuffer({ resolveWithObject: true });

packages/integrations/image/test/background-color-image-ssg.test.js

@@ -106,6 +106,17 @@ describe('SSG image with background - build', function () {
 			id: '#rgb-spaced',
 			bg: [105, 105, 105],
 		},
+
+		{
+			title: 'RGBA color',
+			id: '#rgba',
+			bg: [105, 105, 105],
+		},
+		{
+			title: 'RGBA color with spaces',
+			id: '#rgba-spaced',
+			bg: [105, 105, 105],
+		},
 	].forEach(({ title, id, bg }) => {
 		it(title, async () => {
 			const image = $(id);

packages/integrations/image/test/background-color-image-ssr.test.js

@@ -31,7 +31,7 @@ describe('SSR image with background', function () {
 			title: 'Hex color',
 			id: '#hex',
 			query: {
-				f: 'avif',
+				f: 'jpeg',
 				w: '256',
 				h: '256',
 				href: /^\/assets\/file-icon.\w{8}.png/,
@@ -42,7 +42,7 @@ describe('SSR image with background', function () {
 			title: 'Hex color short',
 			id: '#hex-short',
 			query: {
-				f: 'png',
+				f: 'jpeg',
 				w: '256',
 				h: '256',
 				href: /^\/assets\/file-icon.\w{8}.png/,
@@ -53,7 +53,7 @@ describe('SSR image with background', function () {
 			title: 'RGB color',
 			id: '#rgb',
 			query: {
-				f: 'webp',
+				f: 'jpeg',
 				w: '256',
 				h: '256',
 				href: /^\/assets\/file-icon.\w{8}.png/,
@@ -71,6 +71,28 @@ describe('SSR image with background', function () {
 				bg: 'rgb(105, 105, 105)',
 			},
 		},
+		{
+			title: 'RGBA color',
+			id: '#rgba',
+			query: {
+				f: 'jpeg',
+				w: '256',
+				h: '256',
+				href: /^\/assets\/file-icon.\w{8}.png/,
+				bg: 'rgb(105,105,105,0.5)',
+			},
+		},
+		{
+			title: 'RGBA color with spaces',
+			id: '#rgba-spaced',
+			query: {
+				f: 'jpeg',
+				w: '256',
+				h: '256',
+				href: /^\/assets\/file-icon.\w{8}.png/,
+				bg: 'rgb(105, 105, 105, 0.5)',
+			},
+		},
 	].forEach(({ title, id, query }) => {
 		it(title, async () => {
 			const app = await fixture.loadTestAdapterApp();

packages/integrations/image/test/fixtures/background-color-image/src/pages/index.astro

@@ -9,13 +9,17 @@ import { Image } from '@astrojs/image/components';
   <body>
 		<Image id="named" src={import('../assets/file-icon.png')} width={256} format="jpeg" background="dimgray" alt="named" />
 		<br />
-		<Image id="hex" src={import('../assets/file-icon.png')} width={256} format="avif" background="#696969" alt="hex" />
+		<Image id="hex" src={import('../assets/file-icon.png')} width={256} format="jpeg" background="#696969" alt="hex" />
 		<br />
-		<Image id="hex-short" src={import('../assets/file-icon.png')} width={256} background="#666" alt="hex-short" />
+		<Image id="hex-short" src={import('../assets/file-icon.png')} width={256} format="jpeg" background="#666" alt="hex-short" />
 		<br />
-		<Image id="rgb" src={import('../assets/file-icon.png')} width={256} format="webp" background="rgb(105,105,105)" alt="rgb" />
+		<Image id="rgb" src={import('../assets/file-icon.png')} width={256} format="jpeg" background="rgb(105,105,105)" alt="rgb" />
 		<br />
 		<Image id="rgb-spaced" src={import('../assets/file-icon.png')} width={256} format="jpeg" background="rgb(105, 105, 105)" alt="rgb-spaced" />
 		<br />
+		<Image id="rgba" src={import('../assets/file-icon.png')} width={256} format="jpeg" background="rgb(105,105,105,0.5)" alt="rgba" />
+		<br />
+		<Image id="rgba-spaced" src={import('../assets/file-icon.png')} width={256} format="jpeg" background="rgb(105, 105, 105, 0.5)" alt="rgba-spaced" />
+		<br />
   </body>
 </html>