feat(common): add NgOptimizedImage directive

.circleci/config.yml

@@ -71,6 +71,7 @@ var_11: &only_release_branches
     branches:
       only:
         - main
+        - image-directive
         - /\d+\.\d+\.x/
 
 # CircleCI orbs

goldens/public-api/common/errors.md

@@ -6,12 +6,32 @@
 
 // @public
 export const enum RuntimeErrorCode {
+    // (undocumented)
+    INVALID_INPUT = 2952,
+    // (undocumented)
+    INVALID_LOADER_ARGUMENTS = 2959,
     // (undocumented)
     INVALID_PIPE_ARGUMENT = 2100,
     // (undocumented)
+    INVALID_PRECONNECT_CHECK_BLOCKLIST = 2957,
+    // (undocumented)
+    LCP_IMG_MISSING_PRIORITY = 2955,
+    // (undocumented)
     NG_FOR_MISSING_DIFFER = -2200,
     // (undocumented)
-    PARENT_NG_SWITCH_NOT_FOUND = 2000
+    PARENT_NG_SWITCH_NOT_FOUND = 2000,
+    // (undocumented)
+    PRIORITY_IMG_MISSING_PRECONNECT_TAG = 2956,
+    // (undocumented)
+    REQUIRED_INPUT_MISSING = 2954,
+    // (undocumented)
+    UNEXPECTED_DEV_MODE_CHECK_IN_PROD_MODE = 2958,
+    // (undocumented)
+    UNEXPECTED_INPUT_CHANGE = 2953,
+    // (undocumented)
+    UNEXPECTED_SRC_ATTR = 2950,
+    // (undocumented)
+    UNEXPECTED_SRCSET_ATTR = 2951
 }
 
 // (No @packageDocumentation comment for this package)

goldens/public-api/common/index.md

@@ -17,7 +17,9 @@ import { NgModuleFactory } from '@angular/core';
 import { Observable } from 'rxjs';
 import { OnChanges } from '@angular/core';
 import { OnDestroy } from '@angular/core';
+import { OnInit } from '@angular/core';
 import { PipeTransform } from '@angular/core';
+import { Provider } from '@angular/core';
 import { Renderer2 } from '@angular/core';
 import { SimpleChanges } from '@angular/core';
 import { Subscribable } from 'rxjs';
@@ -256,6 +258,20 @@ export class I18nSelectPipe implements PipeTransform {
     static ɵpipe: i0.ɵɵPipeDeclaration<I18nSelectPipe, "i18nSelect", true>;
 }
 
+// @public
+export const IMAGE_LOADER: InjectionToken<ImageLoader>;
+
+// @public
+export type ImageLoader = (config: ImageLoaderConfig) => string;
+
+// @public
+export interface ImageLoaderConfig {
+    // (undocumented)
+    src: string;
+    // (undocumented)
+    width?: number;
+}
+
 // @public
 export function isPlatformBrowser(platformId: Object): boolean;
 
@@ -517,6 +533,35 @@ export abstract class NgLocalization {
     static ɵprov: i0.ɵɵInjectableDeclaration<NgLocalization>;
 }
 
+// @public
+export class NgOptimizedImage implements OnInit, OnChanges, OnDestroy {
+    constructor(imageLoader: ImageLoader, renderer: Renderer2, imgElement: ElementRef, injector: Injector);
+    set height(value: string | number | undefined);
+    // (undocumented)
+    get height(): number | undefined;
+    loading?: string;
+    // (undocumented)
+    ngOnChanges(changes: SimpleChanges): void;
+    // (undocumented)
+    ngOnDestroy(): void;
+    // (undocumented)
+    ngOnInit(): void;
+    set priority(value: string | boolean | undefined);
+    // (undocumented)
+    get priority(): boolean;
+    rawSrc: string;
+    rawSrcset: string;
+    // (undocumented)
+    srcset?: string;
+    set width(value: string | number | undefined);
+    // (undocumented)
+    get width(): number | undefined;
+    // (undocumented)
+    static ɵdir: i0.ɵɵDirectiveDeclaration<NgOptimizedImage, "img[rawSrc]", never, { "rawSrc": "rawSrc"; "rawSrcset": "rawSrcset"; "width": "width"; "height": "height"; "loading": "loading"; "priority": "priority"; "src": "src"; "srcset": "srcset"; }, {}, never, never, true>;
+    // (undocumented)
+    static ɵfac: i0.ɵɵFactoryDeclaration<NgOptimizedImage, never>;
+}
+
 // @public
 export class NgPlural {
     constructor(_localization: NgLocalization);
@@ -743,6 +788,29 @@ interface PopStateEvent_2 {
 }
 export { PopStateEvent_2 as PopStateEvent }
 
+// @public
+export const PRECONNECT_CHECK_BLOCKLIST: InjectionToken<(string | string[])[]>;
+
+// @public
+export const provideCloudflareLoader: (path: string, options?: {
+    ensurePreconnect?: boolean | undefined;
+}) => Provider[];
+
+// @public
+export const provideCloudinaryLoader: (path: string, options?: {
+    ensurePreconnect?: boolean | undefined;
+}) => Provider[];
+
+// @public
+export const provideImageKitLoader: (path: string, options?: {
+    ensurePreconnect?: boolean | undefined;
+}) => Provider[];
+
+// @public
+export const provideImgixLoader: (path: string, options?: {
+    ensurePreconnect?: boolean | undefined;
+}) => Provider[];
+
 // @public
 export function registerLocaleData(data: any, localeId?: string | any, extraData?: any): void;
 

packages/common/src/common.ts

@@ -27,3 +27,4 @@ export {PLATFORM_BROWSER_ID as ɵPLATFORM_BROWSER_ID, PLATFORM_SERVER_ID as ɵPL
 export {VERSION} from './version';
 export {ViewportScroller, NullViewportScroller as ɵNullViewportScroller} from './viewport_scroller';
 export {XhrFactory} from './xhr';
+export * from './directives/ng_optimized_image';

packages/common/src/directives/ng_optimized_image/asserts.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.io/license
+ */
+
+import {ɵRuntimeError as RuntimeError} from '@angular/core';
+
+import {RuntimeErrorCode} from '../../errors';
+
+/**
+ * Asserts whether an ngDevMode is enabled and throws an error if it's not the case.
+ * This assert can be used to make sure that there is no dev-mode code invoked in
+ * the prod mode accidentally.
+ */
+export function assertDevMode(check: string) {
+  if (!ngDevMode) {
+    throw new RuntimeError(
+        RuntimeErrorCode.UNEXPECTED_DEV_MODE_CHECK_IN_PROD_MODE,
+        `Unexpected invocation of the ${check} in the prod mode. ` +
+            `Please make sure that the prod mode is enabled for production builds.`);
+  }
+}

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

@@ -0,0 +1,34 @@
+/**
+ * @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.io/license
+ */
+
+import {createImageLoader, ImageLoaderConfig} from './image_loader';
+
+/**
+ * Function that generates a built-in ImageLoader for Cloudflare Image Resizing
+ * and turns it into an Angular provider. Note: Cloudflare has multiple image
+ * products - this provider is specifically for Cloudflare Image Resizing;
+ * it will not work with Cloudflare Images or Cloudflare Polish.
+ *
+ * @param path Your domain name
+ * e.g. https://mysite.com
+ * @returns Provider that provides an ImageLoader function
+ *
+ * @publicApi
+ * @developerPreview
+ */
+export const provideCloudflareLoader = createImageLoader(
+    createCloudflareURL,
+    ngDevMode ? ['https://<ZONE>/cdn-cgi/image/<OPTIONS>/<SOURCE-IMAGE>'] : undefined);
+
+function createCloudflareURL(path: string, config: ImageLoaderConfig) {
+  let params = `format=auto`;
+  if (config.width) {
+    params += `,width=${config.width}`;
+  }
+  return `${path}/cdn-cgi/image/${params}/${config.src}`;
+}

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

@@ -0,0 +1,46 @@
+/**
+ * @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.io/license
+ */
+
+import {createImageLoader, ImageLoaderConfig} from './image_loader';
+
+/**
+ * Function that generates a built-in ImageLoader for Cloudinary
+ * and turns it into an Angular provider.
+ *
+ * @param path Base URL of your Cloudinary images
+ * This URL should match one of the following formats:
+ * https://res.cloudinary.com/mysite
+ * https://mysite.cloudinary.com
+ * https://subdomain.mysite.com
+ * @param options An object that allows to provide extra configuration:
+ * - `ensurePreconnect`: boolean flag indicating whether the NgOptimizedImage directive
+ *                       should verify that there is a corresponding `<link rel="preconnect">`
+ *                       present in the document's `<head>`.
+ * @returns Set of providers to configure the Cloudinary loader.
+ *
+ * @publicApi
+ * @developerPreview
+ */
+export const provideCloudinaryLoader = createImageLoader(
+    createCloudinaryURL,
+    ngDevMode ?
+        [
+          'https://res.cloudinary.com/mysite', 'https://mysite.cloudinary.com',
+          'https://subdomain.mysite.com'
+        ] :
+        undefined);
+
+function createCloudinaryURL(path: string, config: ImageLoaderConfig) {
+  // Example of a Cloudinary image URL:
+  // https://res.cloudinary.com/mysite/image/upload/c_scale,f_auto,q_auto,w_600/marketing/tile-topics-m.png
+  let params = `f_auto,q_auto`;  // sets image format and quality to "auto"
+  if (config.width) {
+    params += `,w_${config.width}`;
+  }
+  return `${path}/image/upload/${params}/${config.src}`;
+}

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

@@ -0,0 +1,96 @@
+/**
+ * @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.io/license
+ */
+
+import {InjectionToken, Provider, ɵRuntimeError as RuntimeError} from '@angular/core';
+
+import {RuntimeErrorCode} from '../../../errors';
+import {PRECONNECT_CHECK_BLOCKLIST} from '../preconnect_link_checker';
+import {isAbsoluteURL, isValidPath, normalizePath, normalizeSrc} from '../util';
+
+/**
+ * Config options recognized by the image loader function.
+ *
+ * @publicApi
+ * @developerPreview
+ */
+export interface ImageLoaderConfig {
+  // Name of the image to be added to the image request URL
+  src: string;
+  // Width of the requested image (to be used when generating srcset)
+  width?: number;
+}
+
+/**
+ * Represents an image loader function.
+ *
+ * @publicApi
+ * @developerPreview
+ */
+export type ImageLoader = (config: ImageLoaderConfig) => string;
+
+/**
+ * Noop image loader that does no transformation to the original src and just returns it as is.
+ * This loader is used as a default one if more specific logic is not provided in an app config.
+ */
+const noopImageLoader = (config: ImageLoaderConfig) => config.src;
+
+/**
+ * Special token that allows to configure a function that will be used to produce an image URL based
+ * on the specified input.
+ *
+ * @publicApi
+ * @developerPreview
+ */
+export const IMAGE_LOADER = new InjectionToken<ImageLoader>('ImageLoader', {
+  providedIn: 'root',
+  factory: () => noopImageLoader,
+});
+
+export function createImageLoader(
+    buildUrlFn: (path: string, config: ImageLoaderConfig) => string, exampleUrls?: string[]) {
+  return function provideImageLoader(
+      path: string, options: {ensurePreconnect?: boolean} = {ensurePreconnect: true}) {
+    if (ngDevMode && !isValidPath(path)) {
+      throwInvalidPathError(path, exampleUrls || []);
+    }
+    path = normalizePath(path);
+
+    const loaderFn = (config: ImageLoaderConfig) => {
+      if (ngDevMode && isAbsoluteURL(config.src)) {
+        throwUnexpectedAbsoluteUrlError(path, config.src);
+      }
+
+      return buildUrlFn(path, {...config, src: normalizeSrc(config.src)});
+    };
+    const providers: Provider[] = [{provide: IMAGE_LOADER, useValue: loaderFn}];
+
+    if (ngDevMode && options.ensurePreconnect === false) {
+      providers.push({provide: PRECONNECT_CHECK_BLOCKLIST, useValue: [path], multi: true});
+    }
+
+    return providers;
+  };
+}
+
+function throwInvalidPathError(path: unknown, exampleUrls: string[]): never {
+  const exampleUrlsMsg = exampleUrls.join(' or ');
+  throw new RuntimeError(
+      RuntimeErrorCode.INVALID_LOADER_ARGUMENTS,
+      `Image loader has detected an invalid path (\`${path}\`). ` +
+          `To fix this, supply a path using one of the following formats: ${exampleUrlsMsg}`);
+}
+
+function throwUnexpectedAbsoluteUrlError(path: string, url: string): never {
+  throw new RuntimeError(
+      RuntimeErrorCode.INVALID_LOADER_ARGUMENTS,
+      `Image loader has detected a \`<img>\` tag with an invalid \`rawSrc\` attribute: ${url}. ` +
+          `This image loader expects \`rawSrc\` to be a relative URL - ` +
+          `however the provided value is an absolute URL. ` +
+          `To fix this, provide \`rawSrc\` as a path relative to the base URL ` +
+          `configured for this loader (\`${path}\`).`);
+}

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

@@ -0,0 +1,40 @@
+/**
+ * @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.io/license
+ */
+
+import {createImageLoader, ImageLoaderConfig} from './image_loader';
+
+/**
+ * Function that generates a built-in ImageLoader for ImageKit
+ * and turns it into an Angular provider.
+ *
+ * @param path Base URL of your ImageKit images
+ * This URL should match one of the following formats:
+ * https://ik.imagekit.io/myaccount
+ * https://subdomain.mysite.com
+ * @param options An object that allows to provide extra configuration:
+ * - `ensurePreconnect`: boolean flag indicating whether the NgOptimizedImage directive
+ *                       should verify that there is a corresponding `<link rel="preconnect">`
+ *                       present in the document's `<head>`.
+ * @returns Set of providers to configure the ImageKit loader.
+ *
+ * @publicApi
+ * @developerPreview
+ */
+export const provideImageKitLoader = createImageLoader(
+    createImagekitURL,
+    ngDevMode ? ['https://ik.imagekit.io/mysite', 'https://subdomain.mysite.com'] : undefined);
+
+export function createImagekitURL(path: string, config: ImageLoaderConfig) {
+  // Example of an ImageKit image URL:
+  // https://ik.imagekit.io/demo/tr:w-300,h-300/medium_cafe_B1iTdD0C.jpg
+  let params = `tr:q-auto`;  // applies the "auto quality" transformation
+  if (config.width) {
+    params += `,w-${config.width}`;
+  }
+  return `${path}/${params}/${config.src}`;
+}