refactor(compiler-cli): add inline stylesheet external runtime style transformation support (angular#57613)

To provide support for HMR of inline component styles (`styles` decorator field), the AOT
compiler will now use the resource host transformation API with the Angular CLI to provide
external runtime stylesheet URLs when the `externalRuntimeStyles` compiler option is enabled.
This allows both a component's file-based and inline styles to be available for HMR when used
with a compatible development server such as with the Angular CLI. No behavioral change is
present if the `externalRuntimeStyles` option is not enabled or the resource host transformation
API is not used.
An `order` numeric field is also added to the transformation API which allows consumers such as
the Angular CLI to create identifiers for each inline style in a specific containing file.

PR Close angular#57613

Author: clydin

packages/compiler-cli/src/ngtsc/annotations/common/src/api.ts

@@ -87,4 +87,20 @@ export interface ResourceLoaderContext {
    * The absolute path to the file that contains the resource or reference to the resource.
    */
   containingFile: string;
+
+  /**
+   * For style resources, the placement of the style within the containing file with lower numbers
+   * being before higher numbers.
+   * The value is primarily used by the Angular CLI to create a deterministic identifier for each
+   * style in HMR scenarios.
+   * This is undefined for templates.
+   */
+  order?: number;
+
+  /**
+   * The name of the class that defines the component using the resource.
+   * This allows identifying the source usage of a resource in cases where multiple components are
+   * contained in a single source file.
+   */
+  className: string;
 }

packages/compiler-cli/src/ngtsc/annotations/component/src/handler.ts

@@ -332,7 +332,11 @@ export class ComponentDecoratorHandler
     const resolveStyleUrl = (styleUrl: string): Promise<void> | undefined => {
       try {
         const resourceUrl = this.resourceLoader.resolve(styleUrl, containingFile);
-        return this.resourceLoader.preload(resourceUrl, {type: 'style', containingFile});
+        return this.resourceLoader.preload(resourceUrl, {
+          type: 'style',
+          containingFile,
+          className: node.name.text,
+        });
       } catch {
         // Don't worry about failures to preload. We can handle this problem during analysis by
         // producing a diagnostic.
@@ -378,11 +382,18 @@ export class ComponentDecoratorHandler
     return templateAndTemplateStyleResources.then(async (templateInfo) => {
       // Extract inline styles, process, and cache for use in synchronous analyze phase
       let styles: string[] | null = null;
+      // Order plus className allows inline styles to be identified per component by a preprocessor
+      let orderOffset = 0;
       const rawStyles = parseDirectiveStyles(component, this.evaluator, this.compilationMode);
       if (rawStyles?.length) {
         styles = await Promise.all(
           rawStyles.map((style) =>
-            this.resourceLoader.preprocessInline(style, {type: 'style', containingFile}),
+            this.resourceLoader.preprocessInline(style, {
+              type: 'style',
+              containingFile,
+              order: orderOffset++,
+              className: node.name.text,
+            }),
           ),
         );
       }
@@ -394,6 +405,8 @@ export class ComponentDecoratorHandler
               this.resourceLoader.preprocessInline(style, {
                 type: 'style',
                 containingFile: templateInfo.templateUrl ?? containingFile,
+                order: orderOffset++,
+                className: node.name.text,
               }),
             ),
           )),
@@ -766,8 +779,13 @@ export class ComponentDecoratorHandler
     if (this.preanalyzeStylesCache.has(node)) {
       inlineStyles = this.preanalyzeStylesCache.get(node)!;
       this.preanalyzeStylesCache.delete(node);
-      if (inlineStyles !== null) {
-        styles.push(...inlineStyles);
+      if (inlineStyles?.length) {
+        if (this.externalRuntimeStyles) {
+          // When external runtime styles is enabled, a list of URLs is provided
+          externalStyles.push(...inlineStyles);
+        } else {
+          styles.push(...inlineStyles);
+        }
       }
     } else {
       // Preprocessing is only supported asynchronously

packages/compiler-cli/src/ngtsc/annotations/component/src/resources.ts

@@ -429,6 +429,7 @@ export function preloadAndParseTemplate(
       const templatePromise = resourceLoader.preload(resourceUrl, {
         type: 'template',
         containingFile,
+        className: node.name.text,
       });
 
       // If the preload worked, then actually load and parse the template, and wait for any

packages/compiler-cli/src/ngtsc/annotations/component/test/component_spec.ts

@@ -547,6 +547,122 @@ runInEachFileSystem(() => {
       ]);
     });
 
+    it('should populate externalStyles from inline style transform when externalRuntimeStyles is enabled', async () => {
+      const {program, options, host} = makeProgram([
+        {
+          name: _('/node_modules/@angular/core/index.d.ts'),
+          contents: 'export const Component: any;',
+        },
+        {
+          name: _('/entry.ts'),
+          contents: `
+          import {Component} from '@angular/core';
+
+          @Component({
+            template: '',
+            styles: ['.abc {}']
+          }) class TestCmp {}
+      `,
+        },
+      ]);
+      const {reflectionHost, handler, resourceLoader} = setup(program, options, host, {
+        externalRuntimeStyles: true,
+      });
+      resourceLoader.canPreload = true;
+      resourceLoader.canPreprocess = true;
+      resourceLoader.preprocessInline = async function (data, context) {
+        expect(data).toBe('.abc {}');
+        expect(context.containingFile).toBe(_('/entry.ts').toLowerCase());
+        expect(context.type).toBe('style');
+        expect(context.order).toBe(0);
+
+        return 'abc/myInlineStyle.css';
+      };
+
+      const TestCmp = getDeclaration(program, _('/entry.ts'), 'TestCmp', isNamedClassDeclaration);
+      const detected = handler.detect(TestCmp, reflectionHost.getDecoratorsOfDeclaration(TestCmp));
+      if (detected === undefined) {
+        return fail('Failed to recognize @Component');
+      }
+
+      await handler.preanalyze(TestCmp, detected.metadata);
+
+      const {analysis} = handler.analyze(TestCmp, detected.metadata);
+      expect(analysis?.resources.styles.size).toBe(1);
+      expect(analysis?.meta.externalStyles).toEqual(['abc/myInlineStyle.css']);
+      expect(analysis?.meta.styles).toEqual([]);
+    });
+
+    it('should not populate externalStyles from inline style when externalRuntimeStyles is enabled and no transform', async () => {
+      const {program, options, host} = makeProgram([
+        {
+          name: _('/node_modules/@angular/core/index.d.ts'),
+          contents: 'export const Component: any;',
+        },
+        {
+          name: _('/entry.ts'),
+          contents: `
+          import {Component} from '@angular/core';
+
+          @Component({
+            template: '',
+            styles: ['.abc {}']
+          }) class TestCmp {}
+      `,
+        },
+      ]);
+      const {reflectionHost, handler} = setup(program, options, host, {
+        externalRuntimeStyles: true,
+      });
+
+      const TestCmp = getDeclaration(program, _('/entry.ts'), 'TestCmp', isNamedClassDeclaration);
+      const detected = handler.detect(TestCmp, reflectionHost.getDecoratorsOfDeclaration(TestCmp));
+      if (detected === undefined) {
+        return fail('Failed to recognize @Component');
+      }
+
+      await handler.preanalyze(TestCmp, detected.metadata);
+
+      const {analysis} = handler.analyze(TestCmp, detected.metadata);
+      expect(analysis?.resources.styles.size).toBe(1);
+      expect(analysis?.meta.externalStyles).toEqual([]);
+      expect(analysis?.meta.styles).toEqual(['.abc {}']);
+    });
+
+    it('should not populate externalStyles from inline style when externalRuntimeStyles is enabled and no preanalyze', async () => {
+      const {program, options, host} = makeProgram([
+        {
+          name: _('/node_modules/@angular/core/index.d.ts'),
+          contents: 'export const Component: any;',
+        },
+        {
+          name: _('/entry.ts'),
+          contents: `
+          import {Component} from '@angular/core';
+
+          @Component({
+            template: '',
+            styles: ['.abc {}']
+          }) class TestCmp {}
+      `,
+        },
+      ]);
+      const {reflectionHost, handler} = setup(program, options, host, {
+        externalRuntimeStyles: true,
+      });
+
+      const TestCmp = getDeclaration(program, _('/entry.ts'), 'TestCmp', isNamedClassDeclaration);
+      const detected = handler.detect(TestCmp, reflectionHost.getDecoratorsOfDeclaration(TestCmp));
+      if (detected === undefined) {
+        return fail('Failed to recognize @Component');
+      }
+
+      const {analysis} = handler.analyze(TestCmp, detected.metadata);
+      expect(analysis?.resources.styles.size).toBe(1);
+      expect(analysis?.meta.externalStyles).toEqual([]);
+      expect(analysis?.meta.styles).toEqual(['.abc {}']);
+    });
+
     it('should replace inline style content with transformed content', async () => {
       const {program, options, host} = makeProgram([
         {

packages/compiler-cli/src/ngtsc/core/api/src/interfaces.ts

@@ -92,6 +92,22 @@ export interface ResourceHostContext {
    * The absolute path to the file that contains the resource or reference to the resource.
    */
   readonly containingFile: string;
+
+  /**
+   * For style resources, the placement of the style within the containing file with lower numbers
+   * being before higher numbers.
+   * The value is primarily used by the Angular CLI to create a deterministic identifier for each
+   * style in HMR scenarios.
+   * This is undefined for templates.
+   */
+  readonly order?: number;
+
+  /**
+   * The name of the class that defines the component using the resource.
+   * This allows identifying the source usage of a resource in cases where multiple components are
+   * contained in a single source file.
+   */
+  className: string;
 }
 
 /**

packages/compiler-cli/src/ngtsc/resource/src/loader.ts

@@ -98,6 +98,7 @@ export class AdapterResourceLoader implements ResourceLoader {
         type: 'style',
         containingFile: context.containingFile,
         resourceFile: resolvedUrl,
+        className: context.className,
       };
       result = Promise.resolve(result).then(async (str) => {
         const transformResult = await this.adapter.transformResource!(str, resourceContext);
@@ -135,6 +136,8 @@ export class AdapterResourceLoader implements ResourceLoader {
       type: 'style',
       containingFile: context.containingFile,
       resourceFile: null,
+      order: context.order,
+      className: context.className,
     });
     if (transformResult === null) {
       return data;