feat(common): Add custom transformations for Cloudflare and Cloudinary image loaders

Adds support for custom transformations to Cloudinary and Cloudflare image loaders via a `transform` parameter.

Fixes #65191 and  #64639

Author: SkyZeroZx

packages/common/src/directives/ng_optimized_image/image_loaders/cloudflare_loader.ts

@@ -9,6 +9,7 @@
 import {Provider} from '@angular/core';
 import {PLACEHOLDER_QUALITY} from './constants';
 import {createImageLoader, ImageLoaderConfig} from './image_loader';
+import {normalizeLoaderTransform} from './normalized_options';
 
 /**
  * Function that generates an ImageLoader for [Cloudflare Image
@@ -37,6 +38,12 @@ function createCloudflareUrl(path: string, config: ImageLoaderConfig) {
     params += `,quality=${PLACEHOLDER_QUALITY}`;
   }
 
+  // Support custom transformation parameters
+  if (config.loaderParams?.['transform']) {
+    const transformStr = normalizeLoaderTransform(config.loaderParams['transform'], '=');
+    params += `,${transformStr}`;
+  }
+
   // Cloudflare image URLs format:
   // https://developers.cloudflare.com/images/image-resizing/url-format/
   return `${path}/cdn-cgi/image/${params}/${config.src}`;

packages/common/src/directives/ng_optimized_image/image_loaders/cloudinary_loader.ts

@@ -8,6 +8,7 @@
 
 import {Provider} from '@angular/core';
 import {createImageLoader, ImageLoaderConfig, ImageLoaderInfo} from './image_loader';
+import {normalizeLoaderTransform} from './normalized_options';
 
 /**
  * Name and URL tester for Cloudinary.
@@ -67,5 +68,11 @@ function createCloudinaryUrl(path: string, config: ImageLoaderConfig) {
     params += `,r_max`;
   }
 
+  // Allows users to add any Cloudinary transformation parameters as a string or object
+  if (config.loaderParams?.['transform']) {
+    const transformStr = normalizeLoaderTransform(config.loaderParams['transform'], '_');
+    params += `,${transformStr}`;
+  }
+
   return `${path}/image/upload/${params}/${config.src}`;
 }

packages/common/src/directives/ng_optimized_image/image_loaders/normalized_options.ts

@@ -0,0 +1,25 @@
+/**
+ * @license
+ * Copyright Google LLC All Rights Reserved.
+ *
+ * Use of this source code is governed by an MIT-style license that can be
+ * found in the LICENSE file at https://angular.dev/license
+ */
+
+/**
+ * Converts transform parameter to URL parameter string.
+ * @param transform The transform parameter as string or object
+ * @param separator The separator between key and value ('_' for Cloudinary, '=' for Cloudflare)
+ */
+export function normalizeLoaderTransform(
+  transform: string | Record<string, string>,
+  separator: string,
+): string {
+  if (typeof transform === 'string') {
+    return transform;
+  }
+
+  return Object.entries(transform)
+    .map(([key, value]) => `${key}${separator}${value}`)
+    .join(',');
+}

packages/common/test/image_loaders/image_loader_spec.ts

@@ -151,6 +151,45 @@ describe('Built-in image directive loaders', () => {
           `${path}/image/upload/f_auto,q_auto,r_max/img.png`,
         );
       });
+
+      it('should apply custom transformations when transform is provided as a string', () => {
+        const path = 'https://res.cloudinary.com/mysite';
+        const loader = createCloudinaryLoader(path);
+        expect(loader({src: '/img.png', loaderParams: {transform: 'e_grayscale,r_10'}})).toBe(
+          `${path}/image/upload/f_auto,q_auto,e_grayscale,r_10/img.png`,
+        );
+      });
+
+      it('should apply custom transformations when transform is provided as an object', () => {
+        const path = 'https://res.cloudinary.com/mysite';
+        const loader = createCloudinaryLoader(path);
+        expect(
+          loader({src: '/img.png', loaderParams: {transform: {e: 'grayscale', r: 10, f: 'webp'}}}),
+        ).toBe(`${path}/image/upload/f_auto,q_auto,e_grayscale,r_10,f_webp/img.png`);
+      });
+
+      it('should combine rounded and transform parameters', () => {
+        const path = 'https://res.cloudinary.com/mysite';
+        const loader = createCloudinaryLoader(path);
+        expect(
+          loader({
+            src: '/img.png',
+            loaderParams: {rounded: true, transform: 'e_blur:300'},
+          }),
+        ).toBe(`${path}/image/upload/f_auto,q_auto,r_max,e_blur:300/img.png`);
+      });
+
+      it('should apply width and transform parameters together', () => {
+        const path = 'https://res.cloudinary.com/mysite';
+        const loader = createCloudinaryLoader(path);
+        expect(
+          loader({
+            src: '/img.png',
+            width: 500,
+            loaderParams: {transform: {q: 80, e: 'sharpen'}},
+          }),
+        ).toBe(`${path}/image/upload/f_auto,q_auto,w_500,q_80,e_sharpen/img.png`);
+      });
     });
   });
 
@@ -255,6 +294,54 @@ describe('Built-in image directive loaders', () => {
         'https://mysite.com/cdn-cgi/image/format=auto,quality=20/img.png',
       );
     });
+
+    it('should apply custom transformations when transform is provided as a string', () => {
+      const path = 'https://mysite.com';
+      const loader = createCloudflareLoader(path);
+      expect(
+        loader({src: 'img.png', loaderParams: {transform: 'fit=cover,gravity=face,height=300'}}),
+      ).toBe(
+        'https://mysite.com/cdn-cgi/image/format=auto,fit=cover,gravity=face,height=300/img.png',
+      );
+    });
+
+    it('should apply custom transformations when transform is provided as an object', () => {
+      const path = 'https://mysite.com';
+      const loader = createCloudflareLoader(path);
+      expect(
+        loader({
+          src: 'img.png',
+          loaderParams: {transform: {fit: 'cover', gravity: 'auto', height: 300}},
+        }),
+      ).toBe(
+        'https://mysite.com/cdn-cgi/image/format=auto,fit=cover,gravity=auto,height=300/img.png',
+      );
+    });
+
+    it('should combine width and transform parameters', () => {
+      const path = 'https://mysite.com';
+      const loader = createCloudflareLoader(path);
+      expect(
+        loader({
+          src: 'img.png',
+          width: 400,
+          loaderParams: {transform: {fit: 'crop', gravity: 'face'}},
+        }),
+      ).toBe(
+        'https://mysite.com/cdn-cgi/image/format=auto,width=400,fit=crop,gravity=face/img.png',
+      );
+    });
+
+    it('should support additional transformation options via transform object', () => {
+      const path = 'https://mysite.com';
+      const loader = createCloudflareLoader(path);
+      expect(
+        loader({
+          src: 'img.png',
+          loaderParams: {transform: {blur: 50, rotate: 90, quality: 85}},
+        }),
+      ).toBe('https://mysite.com/cdn-cgi/image/format=auto,blur=50,rotate=90,quality=85/img.png');
+    });
   });
 
   describe('Netlify loader', () => {