@angular/common 13.3.12 → 13.4.0

package/common.d.ts

@@ -1,5 +1,5 @@
 /**
- * @license Angular v13.3.12
+ * @license Angular v13.4.0
  * (c) 2010-2022 Google LLC. https://angular.io/
  * License: MIT
  */
@@ -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';
@@ -1095,6 +1097,68 @@ declare namespace i9 {
     }
 }
 
+/**
+ * Injection token that configures the image optimized image functionality.
+ *
+ * @see `NgOptimizedImage`
+ * @publicApi
+ */
+export declare const IMAGE_CONFIG: InjectionToken<ImageConfig>;
+
+/**
+ * Injection token that configures the image loader function.
+ *
+ * @see `ImageLoader`
+ * @see `NgOptimizedImage`
+ * @publicApi
+ */
+export declare const IMAGE_LOADER: InjectionToken<ImageLoader>;
+
+/**
+ * A configuration object for the NgOptimizedImage directive. Contains:
+ * - breakpoints: An array of integer breakpoints used to generate
+ *      srcsets for responsive images.
+ *
+ * Learn more about the responsive image configuration in [the NgOptimizedImage
+ * guide](guide/image-directive).
+ * @publicApi
+ */
+export declare type ImageConfig = {
+    breakpoints?: number[];
+};
+
+/**
+ * Represents an image loader function. Image loader functions are used by the
+ * NgOptimizedImage directive to produce full image URL based on the image name and its width.
+ *
+ * @publicApi
+ */
+export declare type ImageLoader = (config: ImageLoaderConfig) => string;
+
+/**
+ * Config options recognized by the image loader function.
+ *
+ * @see `ImageLoader`
+ * @see `NgOptimizedImage`
+ * @publicApi
+ */
+export declare interface ImageLoaderConfig {
+    /**
+     * Image file name to be added to the image request URL.
+     */
+    src: string;
+    /**
+     * Width of the requested image (to be used when generating srcset).
+     */
+    width?: number;
+    /**
+     * Additional user-provided parameters for use by the ImageLoader.
+     */
+    loaderParams?: {
+        [key: string]: any;
+    };
+}
+
 /**
  * Returns whether a platform id represents a browser platform.
  * @publicApi
@@ -1955,6 +2019,222 @@ export declare abstract class NgLocalization {
     static ɵprov: i0.ɵɵInjectableDeclaration<NgLocalization>;
 }
 
+/**
+ * @ngModule NgOptimizedImageModule
+ *
+ * @description
+ *
+ * Directive that improves image loading performance by enforcing best practices.
+ *
+ * `NgOptimizedImage` ensures that the loading of the Largest Contentful Paint (LCP) image is
+ * prioritized by:
+ * - Automatically setting the `fetchpriority` attribute on the `<img>` tag
+ * - Lazy loading non-priority images by default
+ * - Asserting that there is a corresponding preconnect link tag in the document head
+ *
+ * In addition, the directive:
+ * - Generates appropriate asset URLs if a corresponding `ImageLoader` function is provided
+ * - Automatically generates a srcset
+ * - Requires that `width` and `height` are set
+ * - Warns if `width` or `height` have been set incorrectly
+ * - Warns if the image will be visually distorted when rendered
+ *
+ * @usageNotes
+ *
+ * Follow the steps below to enable and use the directive:
+ * 1. Import it into the necessary NgModule Component.
+ * 2. Optionally provide an `ImageLoader` if you use an image hosting service.
+ * 3. Update the necessary `<img>` tags in templates and replace `src` attributes with `ngSrc`.
+ * Using a `ngSrc` allows the directive to control when the `src` gets set, which triggers an image
+ * download.
+ *
+ * Step 1: import the `NgOptimizedImage` directive.
+ *
+ * ```typescript
+ * import { NgOptimizedImageModule } from '@angular/common';
+ *
+ * // Include it into the necessary NgModule
+ * @NgModule({
+ *   imports: [NgOptimizedImageModule],
+ * })
+ * class AppModule {}
+ *
+ *
+ * Step 2: configure a loader.
+ *
+ * To use the **default loader**: no additional code changes are necessary. The URL returned by the
+ * generic loader will always match the value of "src". In other words, this loader applies no
+ * transformations to the resource URL and the value of the `ngSrc` attribute will be used as is.
+ *
+ * To use an existing loader for a **third-party image service**: add the provider factory for your
+ * chosen service to the `providers` array. In the example below, the Imgix loader is used:
+ *
+ * ```typescript
+ * import {provideImgixLoader} from '@angular/common';
+ *
+ * // Call the function and add the result to the `providers` array:
+ * providers: [
+ *   provideImgixLoader("https://my.base.url/"),
+ * ],
+ * ```
+ *
+ * The `NgOptimizedImage` directive provides the following functions:
+ * - `provideCloudflareLoader`
+ * - `provideCloudinaryLoader`
+ * - `provideImageKitLoader`
+ * - `provideImgixLoader`
+ *
+ * If you use a different image provider, you can create a custom loader function as described
+ * below.
+ *
+ * To use a **custom loader**: provide your loader function as a value for the `IMAGE_LOADER` DI
+ * token.
+ *
+ * ```typescript
+ * import {IMAGE_LOADER, ImageLoaderConfig} from '@angular/common';
+ *
+ * // Configure the loader using the `IMAGE_LOADER` token.
+ * providers: [
+ *   {
+ *      provide: IMAGE_LOADER,
+ *      useValue: (config: ImageLoaderConfig) => {
+ *        return `https://example.com/${config.src}-${config.width}.jpg}`;
+ *      }
+ *   },
+ * ],
+ * ```
+ *
+ * Step 3: update `<img>` tags in templates to use `ngSrc` instead of `src`.
+ *
+ * ```
+ * <img ngSrc="logo.png" width="200" height="100">
+ * ```
+ *
+ * @publicApi
+ */
+export declare class NgOptimizedImage implements OnInit, OnChanges, OnDestroy {
+    private imageLoader;
+    private config;
+    private renderer;
+    private elementRef;
+    private injector;
+    private platformId;
+    private preloadLinkChecker;
+    /**
+     * Calculate the rewritten `src` once and store it.
+     * This is needed to avoid repetitive calculations and make sure the directive cleanup in the
+     * `ngOnDestroy` does not rely on the `IMAGE_LOADER` logic (which in turn can rely on some other
+     * instance that might be already destroyed).
+     */
+    private _renderedSrc;
+    /**
+     * Name of the source image.
+     * Image name will be processed by the image loader and the final URL will be applied as the `src`
+     * property of the image.
+     */
+    ngSrc: string;
+    /**
+     * A comma separated list of width or density descriptors.
+     * The image name will be taken from `ngSrc` and combined with the list of width or density
+     * descriptors to generate the final `srcset` property of the image.
+     *
+     * Example:
+     * ```
+     * <img ngSrc="hello.jpg" ngSrcset="100w, 200w" />  =>
+     * <img src="path/hello.jpg" srcset="path/hello.jpg?w=100 100w, path/hello.jpg?w=200 200w" />
+     * ```
+     */
+    ngSrcset: string;
+    /**
+     * The base `sizes` attribute passed through to the `<img>` element.
+     * Providing sizes causes the image to create an automatic responsive srcset.
+     */
+    sizes?: string;
+    /**
+     * For responsive images: the intrinsic width of the image in pixels.
+     * For fixed size images: the desired rendered width of the image in pixels.
+     */
+    set width(value: string | number | undefined);
+    get width(): number | undefined;
+    private _width?;
+    /**
+     * For responsive images: the intrinsic height of the image in pixels.
+     * For fixed size images: the desired rendered height of the image in pixels.* The intrinsic
+     * height of the image in pixels.
+     */
+    set height(value: string | number | undefined);
+    get height(): number | undefined;
+    private _height?;
+    /**
+     * The desired loading behavior (lazy, eager, or auto).
+     *
+     * Setting images as loading='eager' or loading='auto' marks them
+     * as non-priority images. Avoid changing this input for priority images.
+     */
+    loading?: 'lazy' | 'eager' | 'auto';
+    /**
+     * Indicates whether this image should have a high priority.
+     */
+    set priority(value: string | boolean | undefined);
+    get priority(): boolean;
+    private _priority;
+    /**
+     * Data to pass through to custom loaders.
+     */
+    loaderParams?: {
+        [key: string]: any;
+    };
+    /**
+     * Disables automatic srcset generation for this image.
+     */
+    set disableOptimizedSrcset(value: string | boolean | undefined);
+    get disableOptimizedSrcset(): boolean;
+    private _disableOptimizedSrcset;
+    /**
+     * Sets the image to "fill mode", which eliminates the height/width requirement and adds
+     * styles such that the image fills its containing element.
+     */
+    set fill(value: string | boolean | undefined);
+    get fill(): boolean;
+    private _fill;
+    private lcpObserver;
+    private imgElement;
+    constructor(imageLoader: ImageLoader, config: ImageConfig, renderer: Renderer2, elementRef: ElementRef, injector: Injector, platformId: string, preloadLinkChecker: PreloadLinkCreator);
+    /** @nodoc */
+    ngOnInit(): void;
+    private setHostAttributes;
+    /** @nodoc */
+    ngOnChanges(changes: SimpleChanges): void;
+    private callImageLoader;
+    private getLoadingBehavior;
+    private getFetchPriority;
+    private getRewrittenSrc;
+    private getRewrittenSrcset;
+    private getAutomaticSrcset;
+    private getResponsiveSrcset;
+    private getFixedSrcset;
+    private shouldGenerateAutomaticSrcset;
+    /** @nodoc */
+    ngOnDestroy(): void;
+    private setHostAttribute;
+    static ɵfac: i0.ɵɵFactoryDeclaration<NgOptimizedImage, never>;
+    static ɵdir: i0.ɵɵDirectiveDeclaration<NgOptimizedImage, "img[ngSrc]", never, { "ngSrc": "ngSrc"; "ngSrcset": "ngSrcset"; "sizes": "sizes"; "width": "width"; "height": "height"; "loading": "loading"; "priority": "priority"; "loaderParams": "loaderParams"; "disableOptimizedSrcset": "disableOptimizedSrcset"; "fill": "fill"; "src": "src"; "srcset": "srcset"; }, {}, never>;
+}
+
+/**
+ * This NgModule exports the `NgOptimizedImage` directive.
+ * Import this module to enable the optimized image directive in your application.
+ *
+ * @publicApi
+ * @deprecated In Angular v15, this NgModule is removed in favor of the NgOptimizedImage directive,
+ *       which is annotated as standalone.
+ */
+export declare class NgOptimizedImageModule {
+    static ɵfac: i0.ɵɵFactoryDeclaration<NgOptimizedImageModule, never>;
+    static ɵmod: i0.ɵɵNgModuleDeclaration<NgOptimizedImageModule, [typeof NgOptimizedImage], never, [typeof NgOptimizedImage]>;
+    static ɵinj: i0.ɵɵInjectorDeclaration<NgOptimizedImageModule>;
+}
+
 /**
  * @ngModule CommonModule
  *
@@ -2531,6 +2811,110 @@ declare interface PopStateEvent_2 {
 }
 export { PopStateEvent_2 as PopStateEvent }
 
+/**
+ * Injection token to configure which origins should be excluded
+ * from the preconnect checks. It can either be a single string or an array of strings
+ * to represent a group of origins, for example:
+ *
+ * ```typescript
+ *  {provide: PRECONNECT_CHECK_BLOCKLIST, useValue: 'https://your-domain.com'}
+ * ```
+ *
+ * or:
+ *
+ * ```typescript
+ *  {provide: PRECONNECT_CHECK_BLOCKLIST,
+ *   useValue: ['https://your-domain-1.com', 'https://your-domain-2.com']}
+ * ```
+ *
+ * @publicApi
+ */
+export declare const PRECONNECT_CHECK_BLOCKLIST: InjectionToken<(string | string[])[]>;
+
+/**
+ * @description Contains the logic needed to track and add preload link tags to the `<head>` tag. It
+ * will also track what images have already had preload link tags added so as to not duplicate link
+ * tags.
+ *
+ * In dev mode this service will validate that the number of preloaded images does not exceed the
+ * configured default preloaded images limit: {@link DEFAULT_PRELOADED_IMAGES_LIMIT}.
+ */
+declare class PreloadLinkCreator {
+    private readonly preloadedImages;
+    private readonly document;
+    constructor();
+    /**
+     * @description Add a preload `<link>` to the `<head>` of the `index.html` that is served from the
+     * server while using Angular Universal and SSR to kick off image loads for high priority images.
+     *
+     * The `sizes` (passed in from the user) and `srcset` (parsed and formatted from `ngSrcset`)
+     * properties used to set the corresponding attributes, `imagesizes` and `imagesrcset`
+     * respectively, on the preload `<link>` tag so that the correctly sized image is preloaded from
+     * the CDN.
+     *
+     * {@link https://web.dev/preload-responsive-images/#imagesrcset-and-imagesizes}
+     *
+     * @param renderer The `Renderer2` passed in from the directive
+     * @param src The original src of the image that is set on the `ngSrc` input.
+     * @param srcset The parsed and formatted srcset created from the `ngSrcset` input
+     * @param sizes The value of the `sizes` attribute passed in to the `<img>` tag
+     */
+    createPreloadLinkTag(renderer: Renderer2, src: string, srcset?: string, sizes?: string): void;
+    static ɵfac: i0.ɵɵFactoryDeclaration<PreloadLinkCreator, never>;
+    static ɵprov: i0.ɵɵInjectableDeclaration<PreloadLinkCreator>;
+}
+
+/**
+ * Function that generates an ImageLoader for [Cloudflare Image
+ * Resizing](https://developers.cloudflare.com/images/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
+ */
+export declare const provideCloudflareLoader: (path: string) => Provider[];
+
+/**
+ * Function that generates an 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
+ * @returns Set of providers to configure the Cloudinary loader.
+ *
+ * @publicApi
+ */
+export declare const provideCloudinaryLoader: (path: string) => Provider[];
+
+/**
+ * Function that generates an 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
+ * @returns Set of providers to configure the ImageKit loader.
+ *
+ * @publicApi
+ */
+export declare const provideImageKitLoader: (path: string) => Provider[];
+
+/**
+ * Function that generates an ImageLoader for Imgix and turns it into an Angular provider.
+ *
+ * @param path path to the desired Imgix origin,
+ * e.g. https://somepath.imgix.net or https://images.mysite.com
+ * @returns Set of providers to configure the Imgix loader.
+ *
+ * @publicApi
+ */
+export declare const provideImgixLoader: (path: string) => Provider[];
+
 
 /**
  * Register global data to be used internally by Angular. See the