Geoprv/responsive images loader

CHANGELOG.md

@@ -11,6 +11,12 @@ Changelog
 
 _Note: Gaps between patch versions are faulty, broken or test releases._
 
+## v4.0.0-beta.160 (2024-03-12)
+
+#### :rocket: New Feature
+
+* Added a new webpack loader for responsive images `build/webpack/loaders/responsive-images-loader`
+
 ## v4.0.0-beta.159 (2024-11-27)
 
 #### :bug: Bug Fix

build/webpack/loaders/responsive-images-loader/CHANGELOG.md

@@ -0,0 +1,16 @@
+Changelog
+=========
+
+> **Tags:**
+> - :boom:       [Breaking Change]
+> - :rocket:     [New Feature]
+> - :bug:        [Bug Fix]
+> - :memo:       [Documentation]
+> - :house:      [Internal]
+> - :nail_care:  [Polish]
+
+## v4.0.0-beta.160 (2024-03-12)
+
+#### :rocket: New Feature
+
+* Initial release

build/webpack/loaders/responsive-images-loader/README.md

@@ -0,0 +1,161 @@
+# build/webpack/loaders/responsive-images-loader
+
+The loader is used to compress and convert responsive images.
+It utilizes the [responsiveLoader](https://github.com/dazuaz/responsive-loader/tree/master)
+library underneath for each conversion operation.
+
+### Usage
+
+By default, this loader is configured to be used with the `responsive` query parameter.
+This means that you just need to require the desired image and specify this parameter.
+
+```ss
+< .my-image v-image = require('path/to/image.png?responsive')
+```
+
+Please note that the image you want to apply the loader to should be in the highest quality.
+
+The loader returns the following structure:
+
+```js
+({
+  // 4e3edf6d108c0701 - the image hash
+  // 346 - 2x size of the original image
+  // png - the format of the original image
+  src: '4e3edf6d108c0701-346.png',
+  sources: [
+    {
+      type: 'png',
+      srcset: {
+        '1x': 'f6506a0261a44c16-173.png',
+        '2x': '4e3edf6d108c0701-346.png',
+        '3x': '19b08609ec6e1165-521.png'
+      }
+    },
+    {
+      type: 'webp',
+      srcset: {
+        '1x': '4e62cb10bc2b3029-173.webp',
+        '2x': 'f49d341fedd8bdc5-346.webp',
+        '3x': '4ca48b9469e44566-521.webp'
+      }
+    },
+    {
+      type: 'avif',
+      srcset: {
+        '1x': '71842fd826667798-173.avif',
+        '2x': '8da0057becea6b31-346.avif',
+        '3x': 'b6d75fb5bdf3121b-521.avif'
+      }
+    }
+  ]
+})
+```
+
+Please note that this loader is only applied in production mode.
+In development mode, the image will be processed using `url-loader`, which will either return the inline image or the path to the image:
+
+```js
+require('path/to/small-image.png?responsive'); // {src: 'data:image/png;base64,.....'}
+require('path/to/huge-image.png?responsive'); // {src: 'path/to/huge-image.png'}
+```
+
+### Options
+
+In addition to the [options](https://github.com/dazuaz/responsive-loader/tree/master#options) provided by the
+`responsive-loader`, this loader also offers a few additional ones.
+
+Please note that the options can be specified using only JSON5 notation for a specific image.
+For example:
+
+```js
+require('image.png?{responsive:true,key1:value1,key2:value2}');
+```
+
+The `responsive` field in the above example is the `resourceQuery` of the loader.
+This parameter is required and should always be set to `true`
+if you want to process your image using this loader.
+
+Alternatively, you can also override the `responsiveImagesOpts` method that specifies
+the base options for every image in `config/default`.
+
+The additional options are the following:
+
+#### defaultSrcPath ['2x.[original image extension]']
+
+The path for the default image in the `src` field.
+The format should be in the following pattern: `[resolution].[extension]`.
+
+Example of usage:
+
+```js
+require('path/to/image.png?{responsive:true,defaultSrcPath:"1x.jpg"}');
+
+/*
+{
+  src: '[hash]-[width].jpg' // Here will be the hashed image scaled by 1x of its original size
+}
+*/
+```
+
+#### formats ['webp', 'avif']
+
+The formats to convert your image to.
+
+#### sizes [1, 2, 3]
+
+Although this option is specified in the `responsive-loader` options,
+it works differently with this loader.
+The numbers you provide indicate the scaling that should be applied to
+the image (1x, 2x, etc.), not the size in pixels.
+
+#### baseSrc [undefined]
+
+If this option is passed, it will be returned in the resulting object only in production.
+It's useful if you have your assets on a static server and you want to specify the base path to the image on it:
+
+```ss
+< . v-image = require('path/to/image.png?{responsive:true,baseSrc:"path/on/static/server"}')
+
+/*
+{
+  src: '...',
+  sources: [...],
+  baseSrc: 'path/on/static/server'
+}
+*/
+```
+
+### Providing multiple custom options
+
+Here is an example of providing multiple options for a specific image:
+
+```js
+require('path/to/image.png?{responsive:true,formats:["webp"],sizes:[1,2,3,4],defaultSrcPath:"3x.png"}');
+
+/*
+{
+  src: '41225eda88e198f9-390.png',
+  sources: [
+    {
+      type: 'png',
+      srcset: {
+        '1x': '00013521e68e82ad-130.png',
+        '2x': '1275606184e9d451-260.png',
+        '3x': '41225eda88e198f9-390.png',
+        '4x': '19b08609ec6e1165-521.png'
+      }
+    },
+    {
+      type: 'webp',
+      srcset: {
+        '1x': '7bc796c1451c0938-130.webp',
+        '2x': '65885d25dc384e15-260.webp',
+        '3x': '1b814b2471ed305d-390.webp',
+        '4x': '4ca48b9469e44566-521.webp'
+      }
+    }
+  ]
+}
+*/
+```

build/webpack/loaders/responsive-images-loader/adapter.js

@@ -0,0 +1,108 @@
+/*!
+ * V4Fire Client Core
+ * https://github.com/V4Fire/Client
+ *
+ * Released under the MIT license
+ * https://github.com/V4Fire/Client/blob/master/LICENSE
+ */
+
+'use strict';
+
+const sharp = require('sharp');
+
+/**
+ * Implementation of the 'Adapter' interface
+ * @see https://github.com/dazuaz/responsive-loader/tree/master#writing-your-own-adapter
+ */
+class Adapter {
+	constructor(imagePath) {
+		this.image = sharp(imagePath);
+	}
+
+	/**
+	 * Returns metadata of the image
+	 *
+	 * @returns {import('@v4fire/storybook-framework-webpack5').Metadata}
+	 * @see https://github.com/dazuaz/responsive-loader/tree/master#writing-your-own-adapter
+	 */
+	metadata() {
+		return this.image.metadata();
+	}
+
+	/**
+	 * Scales the image to the provided amount of its original size and converts to the specified formats
+	 *
+	 * @param {{width: number, mime: string, options: object}} data - information and the image and provided options
+	 * @returns {Promise<{data: Buffer, width: number, height: number}>}
+	 * @see https://github.com/dazuaz/responsive-loader/tree/master#writing-your-own-adapter
+	 */
+	async resize({mime, width: scaleBy, options: {quality, sizes}}) {
+		const
+			imageClone = this.image.clone(),
+			{width, height} = await imageClone.metadata();
+
+		if (width == null || height == null) {
+			throw new Error('Unable to receive width and height of the image', this.image);
+		}
+
+		const
+			scaledImage = this.scale(imageClone, width, height, scaleBy, sizes.length),
+			convertedImage = this.convert(scaledImage, mime, quality),
+			{data, info} = await convertedImage.toBuffer({resolveWithObject: true});
+
+		return {data, width: info.width, height: info.height};
+	}
+
+	/**
+	 * Scales the image by the provided amount of its original size
+	 *
+	 * @param {import('sharp').Sharp} image
+	 * @param {number} width
+	 * @param {number} height
+	 * @param {number} scaleBy
+	 * @param {number} maxScaleSize
+	 * @returns {import('sharp').Sharp}
+	 */
+	scale(image, width, height, scaleBy, maxScaleSize) {
+		if (scaleBy === maxScaleSize) {
+			return image;
+		}
+
+		const
+			stepWidth = Math.floor(width / maxScaleSize),
+			stepHeight = Math.floor(height / maxScaleSize);
+
+		return image.resize(
+			stepWidth * scaleBy,
+			stepHeight * scaleBy
+		);
+	}
+
+	/**
+	 * Converts the original image to another format
+	 *
+	 * @param {import('sharp').Sharp} image
+	 * @param {string} mimeType
+	 * @param {number} quality
+	 * @returns {import('sharp').Sharp}
+	 */
+	convert(image, mimeType, quality) {
+		const formatMethods = {
+			'image/png': image.png,
+			'image/jpeg': image.jpeg,
+			'image/jpg': image.jpeg,
+			'image/webp': image.webp,
+			'image/avif': image.avif
+		};
+
+		return formatMethods[mimeType]?.call(image, {quality});
+	}
+}
+
+/**
+ * Adapter for scaling an image by the provided amount of its original size
+ *
+ * @param {string} imagePath
+ * @returns {Adapter}
+ */
+module.exports = (imagePath) => new Adapter(imagePath);