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

…rted (withastro#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>