feat(material/icon): add support for registry resolver function (#21431)

Currently all of the ways to register icons (e.g. via URL or literal) require the developer to
know the list of icons ahead of time or to fetch more icons than the user needs. These
changes aim to address this issue by adding the ability to register an icon resolver
function which will construct the URL at runtime, depending on the requested icon.

Fixes #18607.

Author: crisbeto

src/material/icon/icon-registry.ts

@@ -74,6 +74,19 @@ export interface IconOptions {
   withCredentials?: boolean;
 }
 
+/**
+ * Function that will be invoked by the icon registry when trying to resolve the
+ * URL from which to fetch an icon. The returned URL will be used to make a request for the icon.
+ */
+export type IconResolver = (name: string, namespace: string) =>
+    (SafeResourceUrl | SafeResourceUrlWithIconOptions | null);
+
+/** Object that specifies a URL from which to fetch an icon and the options to use for it. */
+export interface SafeResourceUrlWithIconOptions {
+  url: SafeResourceUrl;
+  options: IconOptions;
+}
+
 /**
  * Configuration for an icon, including the URL and possibly the cached SVG element.
  * @docs-private
@@ -121,6 +134,9 @@ export class MatIconRegistry implements OnDestroy {
   /** Map from font identifiers to their CSS class names. Used for icon fonts. */
   private _fontCssClassesByAlias = new Map<string, string>();
 
+  /** Registered icon resolver functions. */
+  private _resolvers: IconResolver[] = [];
+
   /**
    * The CSS class to apply when an `<mat-icon>` component has no icon name, url, or font specified.
    * The default 'material-icons' value assumes that the material icon font has been loaded as
@@ -165,6 +181,19 @@ export class MatIconRegistry implements OnDestroy {
     return this._addSvgIconConfig(namespace, iconName, new SvgIconConfig(url, null, options));
   }
 
+  /**
+   * Registers an icon resolver function with the registry. The function will be invoked with the
+   * name and namespace of an icon when the registry tries to resolve the URL from which to fetch
+   * the icon. The resolver is expected to return a `SafeResourceUrl` that points to the icon,
+   * an object with the icon URL and icon options, or `null` if the icon is not supported. Resolvers
+   * will be invoked in the order in which they have been registered.
+   * @param resolver Resolver function to be registered.
+   */
+  addSvgIconResolver(resolver: IconResolver): this {
+    this._resolvers.push(resolver);
+    return this;
+  }
+
   /**
    * Registers an icon using an HTML string in the specified namespace.
    * @param namespace Namespace in which the icon should be registered.
@@ -301,11 +330,19 @@ export class MatIconRegistry implements OnDestroy {
    * @param namespace Namespace in which to look for the icon.
    */
   getNamedSvgIcon(name: string, namespace: string = ''): Observable<SVGElement> {
-    // Return (copy of) cached icon if possible.
     const key = iconKey(namespace, name);
-    const config = this._svgIconConfigs.get(key);
+    let config = this._svgIconConfigs.get(key);
+
+    // Return (copy of) cached icon if possible.
+    if (config) {
+      return this._getSvgFromConfig(config);
+    }
+
+    // Otherwise try to resolve the config from one of the resolver functions.
+    config = this._getIconConfigFromResolvers(namespace, name);
 
     if (config) {
+      this._svgIconConfigs.set(key, config);
       return this._getSvgFromConfig(config);
     }
 
@@ -320,9 +357,10 @@ export class MatIconRegistry implements OnDestroy {
   }
 
   ngOnDestroy() {
-   this._svgIconConfigs.clear();
-   this._iconSetConfigs.clear();
-   this._cachedIconsByUrl.clear();
+    this._resolvers = [];
+    this._svgIconConfigs.clear();
+    this._iconSetConfigs.clear();
+    this._cachedIconsByUrl.clear();
   }
 
   /**
@@ -623,6 +661,21 @@ export class MatIconRegistry implements OnDestroy {
 
     return config.svgElement;
   }
+
+  /** Tries to create an icon config through the registered resolver functions. */
+  private _getIconConfigFromResolvers(namespace: string, name: string): SvgIconConfig | undefined {
+    for (let i = 0; i < this._resolvers.length; i++) {
+      const result = this._resolvers[i](name, namespace);
+
+      if (result) {
+        return isSafeUrlWithOptions(result) ?
+          new SvgIconConfig(result.url, null, result.options) :
+          new SvgIconConfig(result, null);
+      }
+    }
+
+    return undefined;
+  }
 }
 
 /** @docs-private */
@@ -658,3 +711,7 @@ function cloneSvg(svg: SVGElement): SVGElement {
 function iconKey(namespace: string, name: string) {
   return namespace + ':' + name;
 }
+
+function isSafeUrlWithOptions(value: any): value is SafeResourceUrlWithIconOptions {
+  return !!(value.url && value.options);
+}

src/material/icon/icon.spec.ts

@@ -1001,6 +1001,118 @@ describe('MatIcon', () => {
 
   });
 
+  describe('Icons resolved through a resolver function', () => {
+    it('should resolve icons through a resolver function', fakeAsync(() => {
+      iconRegistry.addSvgIconResolver(name => {
+        if (name === 'fluffy') {
+          return trustUrl('cat.svg');
+        } else if (name === 'fido') {
+          return trustUrl('dog.svg');
+        } else if (name === 'felix') {
+          return {url: trustUrl('auth-cat.svg'), options: {withCredentials: true}};
+        }
+        return null;
+      });
+
+      const fixture = TestBed.createComponent(IconFromSvgName);
+      let svgElement: SVGElement;
+      let testRequest: TestRequest;
+      const testComponent = fixture.componentInstance;
+      const iconElement = fixture.debugElement.nativeElement.querySelector('mat-icon');
+
+      testComponent.iconName = 'fido';
+      fixture.detectChanges();
+      http.expectOne('dog.svg').flush(FAKE_SVGS.dog);
+      svgElement = verifyAndGetSingleSvgChild(iconElement);
+      verifyPathChildElement(svgElement, 'woof');
+
+      // Change the icon, and the SVG element should be replaced.
+      testComponent.iconName = 'fluffy';
+      fixture.detectChanges();
+      http.expectOne('cat.svg').flush(FAKE_SVGS.cat);
+      svgElement = verifyAndGetSingleSvgChild(iconElement);
+      verifyPathChildElement(svgElement, 'meow');
+
+      // Using an icon from a previously loaded URL should not cause another HTTP request.
+      testComponent.iconName = 'fido';
+      fixture.detectChanges();
+      http.expectNone('dog.svg');
+      svgElement = verifyAndGetSingleSvgChild(iconElement);
+      verifyPathChildElement(svgElement, 'woof');
+
+      // Change icon to one that needs credentials during fetch.
+      testComponent.iconName = 'felix';
+      fixture.detectChanges();
+      testRequest = http.expectOne('auth-cat.svg');
+      expect(testRequest.request.withCredentials).toBeTrue();
+      testRequest.flush(FAKE_SVGS.cat);
+      svgElement = verifyAndGetSingleSvgChild(iconElement);
+      verifyPathChildElement(svgElement, 'meow');
+
+      // Assert that a registered icon can be looked-up by url.
+      iconRegistry.getSvgIconFromUrl(trustUrl('cat.svg')).subscribe(element => {
+        verifyPathChildElement(element, 'meow');
+      });
+
+      tick();
+    }));
+
+    it('should fall back to second resolver if the first one returned null', fakeAsync(() => {
+      iconRegistry
+        .addSvgIconResolver(() => null)
+        .addSvgIconResolver(name => name === 'fido' ? trustUrl('dog.svg') : null);
+
+      const fixture = TestBed.createComponent(IconFromSvgName);
+      const iconElement = fixture.debugElement.nativeElement.querySelector('mat-icon');
+
+      fixture.componentInstance.iconName = 'fido';
+      fixture.detectChanges();
+      http.expectOne('dog.svg').flush(FAKE_SVGS.dog);
+      verifyPathChildElement(verifyAndGetSingleSvgChild(iconElement), 'woof');
+      tick();
+    }));
+
+    it('should be able to set the viewBox when resolving an icon with a function', fakeAsync(() => {
+      iconRegistry.addSvgIconResolver(name => {
+        if (name === 'fluffy') {
+          return {url: trustUrl('cat.svg'), options: {viewBox: '0 0 27 27'}};
+        } else if (name === 'fido') {
+          return {url: trustUrl('dog.svg'), options: {viewBox: '0 0 43 43'}};
+        }
+        return null;
+      });
+
+      const fixture = TestBed.createComponent(IconFromSvgName);
+      let svgElement: SVGElement;
+      const testComponent = fixture.componentInstance;
+      const iconElement = fixture.debugElement.nativeElement.querySelector('mat-icon');
+
+      testComponent.iconName = 'fido';
+      fixture.detectChanges();
+      http.expectOne('dog.svg').flush(FAKE_SVGS.dog);
+      svgElement = verifyAndGetSingleSvgChild(iconElement);
+      expect(svgElement.getAttribute('viewBox')).toBe('0 0 43 43');
+
+      // Change the icon, and the SVG element should be replaced.
+      testComponent.iconName = 'fluffy';
+      fixture.detectChanges();
+      http.expectOne('cat.svg').flush(FAKE_SVGS.cat);
+      svgElement = verifyAndGetSingleSvgChild(iconElement);
+      expect(svgElement.getAttribute('viewBox')).toBe('0 0 27 27');
+    }));
+
+    it('should throw an error when the resolver returns an untrusted URL', () => {
+      iconRegistry.addSvgIconResolver(() => 'not-trusted.svg');
+
+      expect(() => {
+        const fixture = TestBed.createComponent(IconFromSvgName);
+        fixture.componentInstance.iconName = 'fluffy';
+        fixture.detectChanges();
+      }).toThrowError(/unsafe value used in a resource URL context/);
+    });
+
+  });
+
   it('should handle assigning an icon through the setter', fakeAsync(() => {
     iconRegistry.addSvgIconLiteral('fido', trustHtml(FAKE_SVGS.dog));
 

src/material/icon/testing/fake-icon-registry.ts

@@ -10,11 +10,9 @@ import {Injectable, NgModule, OnDestroy} from '@angular/core';
 import {MatIconRegistry} from '@angular/material/icon';
 import {Observable, of as observableOf} from 'rxjs';
 
-// tslint:disable:no-any Impossible to tell param types.
 type PublicApi<T> = {
   [K in keyof T]: T[K] extends (...x: any[]) => T ? (...x: any[]) => PublicApi<T> : T[K]
 };
-// tslint:enable:no-any
 
 /**
  * A null icon registry that must be imported to allow disabling of custom
@@ -78,6 +76,10 @@ export class FakeMatIconRegistry implements PublicApi<MatIconRegistry>, OnDestro
     return this;
   }
 
+  addSvgIconResolver(): this {
+    return this;
+  }
+
   ngOnDestroy() { }
 
   private _generateEmptySvg(): SVGElement {

tools/public_api_guard/material/icon.d.ts

@@ -19,6 +19,8 @@ export interface IconOptions {
     withCredentials?: boolean;
 }
 
+export declare type IconResolver = (name: string, namespace: string) => (SafeResourceUrl | SafeResourceUrlWithIconOptions | null);
+
 export declare const MAT_ICON_LOCATION: InjectionToken<MatIconLocation>;
 
 export declare function MAT_ICON_LOCATION_FACTORY(): MatIconLocation;
@@ -59,6 +61,7 @@ export declare class MatIconRegistry implements OnDestroy {
     addSvgIconInNamespace(namespace: string, iconName: string, url: SafeResourceUrl, options?: IconOptions): this;
     addSvgIconLiteral(iconName: string, literal: SafeHtml, options?: IconOptions): this;
     addSvgIconLiteralInNamespace(namespace: string, iconName: string, literal: SafeHtml, options?: IconOptions): this;
+    addSvgIconResolver(resolver: IconResolver): this;
     addSvgIconSet(url: SafeResourceUrl, options?: IconOptions): this;
     addSvgIconSetInNamespace(namespace: string, url: SafeResourceUrl, options?: IconOptions): this;
     addSvgIconSetLiteral(literal: SafeHtml, options?: IconOptions): this;
@@ -73,3 +76,8 @@ export declare class MatIconRegistry implements OnDestroy {
     static ɵfac: i0.ɵɵFactoryDef<MatIconRegistry, [{ optional: true; }, null, { optional: true; }, null]>;
     static ɵprov: i0.ɵɵInjectableDef<MatIconRegistry>;
 }
+
+export interface SafeResourceUrlWithIconOptions {
+    options: IconOptions;
+    url: SafeResourceUrl;
+}

tools/public_api_guard/material/icon/testing.d.ts

@@ -3,6 +3,7 @@ export declare class FakeMatIconRegistry implements PublicApi<MatIconRegistry>,
     addSvgIconInNamespace(): this;
     addSvgIconLiteral(): this;
     addSvgIconLiteralInNamespace(): this;
+    addSvgIconResolver(): this;
     addSvgIconSet(): this;
     addSvgIconSetInNamespace(): this;
     addSvgIconSetLiteral(): this;