feat(common): define public API surface for NgOptimizedImage directive (#47082)

AndrewKushnir · Pawel Kozlowski · commit d5f7da21207f · 2022-08-16T17:36:54.000Z
This commit annotates a set of symbols exposed by the NgOptimizedImage directive as a public API. PR Close #47082
diff --git a/goldens/public-api/common/index.md b/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;
 
diff --git a/packages/common/src/common.ts b/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';
diff --git a/packages/common/src/directives/ng_optimized_image/image_loaders/cloudflare_loader.ts b/packages/common/src/directives/ng_optimized_image/image_loaders/cloudflare_loader.ts
@@ -17,6 +17,9 @@ import {createImageLoader, ImageLoaderConfig} from './image_loader';
  * @param path Your domain name
  * e.g. https://mysite.com
  * @returns Provider that provides an ImageLoader function
+ *
+ * @publicApi
+ * @developerPreview
  */
 export const provideCloudflareLoader = createImageLoader(
     createCloudflareURL,
diff --git a/packages/common/src/directives/ng_optimized_image/image_loaders/cloudinary_loader.ts b/packages/common/src/directives/ng_optimized_image/image_loaders/cloudinary_loader.ts
@@ -22,6 +22,9 @@ import {createImageLoader, ImageLoaderConfig} from './image_loader';
  *                       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,
diff --git a/packages/common/src/directives/ng_optimized_image/image_loaders/image_loader.ts b/packages/common/src/directives/ng_optimized_image/image_loaders/image_loader.ts
@@ -14,6 +14,9 @@ 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
@@ -24,6 +27,9 @@ export interface ImageLoaderConfig {
 
 /**
  * Represents an image loader function.
+ *
+ * @publicApi
+ * @developerPreview
  */
 export type ImageLoader = (config: ImageLoaderConfig) => string;
 
@@ -36,6 +42,9 @@ 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',
diff --git a/packages/common/src/directives/ng_optimized_image/image_loaders/imagekit_loader.ts b/packages/common/src/directives/ng_optimized_image/image_loaders/imagekit_loader.ts
@@ -21,6 +21,9 @@ import {createImageLoader, ImageLoaderConfig} from './image_loader';
  *                       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,
diff --git a/packages/common/src/directives/ng_optimized_image/image_loaders/imgix_loader.ts b/packages/common/src/directives/ng_optimized_image/image_loaders/imgix_loader.ts
@@ -19,6 +19,9 @@ import {createImageLoader, ImageLoaderConfig} from './image_loader';
  *                       should verify that there is a corresponding `<link rel="preconnect">`
  *                       present in the document's `<head>`.
  * @returns Set of providers to configure the Imgix loader.
+ *
+ * @publicApi
+ * @developerPreview
  */
 export const provideImgixLoader =
     createImageLoader(createImgixURL, ngDevMode ? ['https://somepath.imgix.net/'] : undefined);
diff --git a/packages/common/src/directives/ng_optimized_image/index.ts b/packages/common/src/directives/ng_optimized_image/index.ts
@@ -5,7 +5,12 @@
  * 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
  */
+
+// These exports represent the set of symbols exposed as a public API.
+export {provideCloudflareLoader} from './image_loaders/cloudflare_loader';
+export {provideCloudinaryLoader} from './image_loaders/cloudinary_loader';
 export {IMAGE_LOADER, ImageLoader, ImageLoaderConfig} from './image_loaders/image_loader';
+export {provideImageKitLoader} from './image_loaders/imagekit_loader';
 export {provideImgixLoader} from './image_loaders/imgix_loader';
 export {NgOptimizedImage} from './ng_optimized_image';
 export {PRECONNECT_CHECK_BLOCKLIST} from './preconnect_link_checker';
diff --git a/packages/common/src/directives/ng_optimized_image/ng_optimized_image.ts b/packages/common/src/directives/ng_optimized_image/ng_optimized_image.ts
@@ -61,6 +61,9 @@ const ASPECT_RATIO_TOLERANCE = .1;
  *
  * @usageNotes
  * TODO: add Image directive usage notes.
+ *
+ * @publicApi
+ * @developerPreview
  */
 @Directive({
   standalone: true,
@@ -95,8 +98,10 @@ export class NgOptimizedImage implements OnInit, OnChanges, OnDestroy {
    * descriptors to generate the final `srcset` property of the image.
    *
    * Example:
+   * ```
    * <img rawSrc="hello.jpg" rawSrcset="100w, 200w" />  =>
    * <img src="path/hello.jpg" srcset="path/hello.jpg?w=100 100w, path/hello.jpg?w=200 200w" />
+   * ```
    */
   @Input() rawSrcset!: string;
 
@@ -144,7 +149,7 @@ export class NgOptimizedImage implements OnInit, OnChanges, OnDestroy {
   }
 
   /**
-   * Get a value of the `src` and `srcset` if they're set on a host <img> element.
+   * Get a value of the `src` and `srcset` if they're set on a host `<img>` element.
    * These inputs are needed to verify that there are no conflicting sources provided
    * at the same time (e.g. `src` and `rawSrc` together or `srcset` and `rawSrcset`,
    * thus causing an ambiguity on which src to use) and that images
diff --git a/packages/common/src/directives/ng_optimized_image/preconnect_link_checker.ts b/packages/common/src/directives/ng_optimized_image/preconnect_link_checker.ts
@@ -32,6 +32,9 @@ const INTERNAL_PRECONNECT_CHECK_BLOCKLIST = new Set(['localhost', '127.0.0.1', '
  *  {provide: PRECONNECT_CHECK_BLOCKLIST, multi: true,
  *   useValue: ['https://your-domain-1.com', 'https://your-domain-2.com']}
  * ```
+ *
+ * @publicApi
+ * @developerPreview
  */
 export const PRECONNECT_CHECK_BLOCKLIST =
     new InjectionToken<Array<string|string[]>>('PRECONNECT_CHECK_BLOCKLIST');
