refactor(compiler): support external runtime component styles for file-based stylesheets (angular#57613)

The AOT compiler now has the capability to handle component stylesheet files as
external runtime files. External runtime files are stylesheets that are not embedded
within the component code at build time. Instead a URL path is emitted within a component's
metadata. When combined with separate updates to the shared style host and DOM renderer,
this will allow these stylesheet files to be fetched and processed by a development
server on-demand. This behavior is controlled by an internal compiler option `externalRuntimeStyles`.
The Angular CLI development server will also be updated to provide the serving functionality
once this capability is enabled. This capability enables upcoming features such as automatic
component style hot module replacement (HMR) and development server deferred stylesheet processing.
The current implementation does not affect the behavior of inline styles. Only the
behavior of stylesheet files referenced via component properties `styleUrl`/`styleUrls`
and relative template `link` elements are changed by enabling the internal option.

PR Close angular#57613

Author: clydin

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

@@ -77,6 +77,7 @@ import {
   MetaKind,
   NgModuleMeta,
   PipeMeta,
+  Resource,
   ResourceRegistry,
 } from '../../../metadata';
 import {PartialEvaluator} from '../../../partial_evaluator';
@@ -249,6 +250,7 @@ export class ComponentDecoratorHandler
     private readonly forbidOrphanRendering: boolean,
     private readonly enableBlockSyntax: boolean,
     private readonly enableLetSyntax: boolean,
+    private readonly externalRuntimeStyles: boolean,
     private readonly localCompilationExtraImportsTracker: LocalCompilationExtraImportsTracker | null,
     private readonly jitDeclarationRegistry: JitDeclarationRegistry,
     private readonly i18nPreserveSignificantWhitespace: boolean,
@@ -400,6 +402,11 @@ export class ComponentDecoratorHandler
 
       this.preanalyzeStylesCache.set(node, styles);
 
+      if (this.externalRuntimeStyles) {
+        // No preanalysis required for style URLs with external runtime styles
+        return;
+      }
+
       // Wait for both the template and all styleUrl resources to resolve.
       await Promise.all([
         ...componentStyleUrls.map((styleUrl) => resolveStyleUrl(styleUrl.url)),
@@ -686,6 +693,7 @@ export class ComponentDecoratorHandler
     // precede inline styles, and styles defined in the template override styles defined in the
     // component.
     let styles: string[] = [];
+    const externalStyles: string[] = [];
 
     const styleResources = extractInlineStyleResources(component);
     const styleUrls: StyleUrlMeta[] = [
@@ -696,6 +704,11 @@ export class ComponentDecoratorHandler
     for (const styleUrl of styleUrls) {
       try {
         const resourceUrl = this.resourceLoader.resolve(styleUrl.url, containingFile);
+        if (this.externalRuntimeStyles) {
+          // External runtime styles are not considered disk-based and may not actually exist on disk
+          externalStyles.push(resourceUrl);
+          continue;
+        }
         if (
           styleUrl.source === ResourceTypeForDiagnostics.StylesheetFromDecorator &&
           ts.isStringLiteralLike(styleUrl.expression)
@@ -816,7 +829,7 @@ export class ComponentDecoratorHandler
           changeDetection,
           interpolation: template.interpolationConfig ?? DEFAULT_INTERPOLATION_CONFIG,
           styles,
-
+          externalStyles,
           // These will be replaced during the compilation step, after all `NgModule`s have been
           // analyzed and the full compilation scope for the component can be realized.
           animations,

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

@@ -6,7 +6,7 @@
  * found in the LICENSE file at https://angular.dev/license
  */
 
-import {ConstantPool} from '@angular/compiler';
+import {ConstantPool, ViewEncapsulation} from '@angular/compiler';
 import ts from 'typescript';
 
 import {CycleAnalyzer, CycleHandlingStrategy, ImportGraph} from '../../../cycles';
@@ -67,11 +67,17 @@ function setup(
   program: ts.Program,
   options: ts.CompilerOptions,
   host: ts.CompilerHost,
-  opts: {compilationMode: CompilationMode; usePoisonedData?: boolean} = {
-    compilationMode: CompilationMode.FULL,
-  },
+  opts: {
+    compilationMode?: CompilationMode;
+    usePoisonedData?: boolean;
+    externalRuntimeStyles?: boolean;
+  } = {},
 ) {
-  const {compilationMode, usePoisonedData} = opts;
+  const {
+    compilationMode = CompilationMode.FULL,
+    usePoisonedData,
+    externalRuntimeStyles = false,
+  } = opts;
   const checker = program.getTypeChecker();
   const reflectionHost = new TypeScriptReflectionHost(checker);
   const evaluator = new PartialEvaluator(reflectionHost, checker, /* dependencyTracker */ null);
@@ -145,6 +151,7 @@ function setup(
     /* forbidOrphanRenderering */ false,
     /* enableBlockSyntax */ true,
     /* enableLetSyntax */ true,
+    externalRuntimeStyles,
     /* localCompilationExtraImportsTracker */ null,
     jitDeclarationRegistry,
     /* i18nPreserveSignificantWhitespace */ true,
@@ -359,6 +366,187 @@ runInEachFileSystem(() => {
       expect(compileResult).toEqual([]);
     });
 
+    it('should populate externalStyles from styleUrl when externalRuntimeStyles is enabled', () => {
+      const {program, options, host} = makeProgram([
+        {
+          name: _('/node_modules/@angular/core/index.d.ts'),
+          contents: 'export const Component: any;',
+        },
+        {
+          name: _('/myStyle.css'),
+          contents: '<div>hello world</div>',
+        },
+        {
+          name: _('/entry.ts'),
+          contents: `
+          import {Component} from '@angular/core';
+
+          @Component({
+            template: '',
+            styleUrl: '/myStyle.css',
+            styles: ['a { color: red; }', 'b { color: blue; }'],
+          }) 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(2);
+      expect(analysis?.meta.externalStyles).toEqual(['/myStyle.css']);
+    });
+
+    it('should populate externalStyles from styleUrls when externalRuntimeStyles is enabled', () => {
+      const {program, options, host} = makeProgram([
+        {
+          name: _('/node_modules/@angular/core/index.d.ts'),
+          contents: 'export const Component: any;',
+        },
+        {
+          name: _('/myStyle.css'),
+          contents: '<div>hello world</div>',
+        },
+        {
+          name: _('/entry.ts'),
+          contents: `
+          import {Component} from '@angular/core';
+
+          @Component({
+            template: '',
+            styleUrls: ['/myStyle.css', '/myOtherStyle.css'],
+            styles: ['a { color: red; }', 'b { color: blue; }'],
+          }) 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(2);
+      expect(analysis?.meta.externalStyles).toEqual(['/myStyle.css', '/myOtherStyle.css']);
+    });
+
+    it('should keep default emulated view encapsulation with styleUrls when externalRuntimeStyles is enabled', () => {
+      const {program, options, host} = makeProgram([
+        {
+          name: _('/node_modules/@angular/core/index.d.ts'),
+          contents: 'export const Component: any;',
+        },
+        {
+          name: _('/myStyle.css'),
+          contents: '<div>hello world</div>',
+        },
+        {
+          name: _('/entry.ts'),
+          contents: `
+          import {Component} from '@angular/core';
+
+          @Component({
+            template: '',
+            styleUrls: ['/myStyle.css', '/myOtherStyle.css'],
+          }) 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?.meta.encapsulation).toBe(ViewEncapsulation.Emulated);
+    });
+
+    it('should populate externalStyles from template link element when externalRuntimeStyles is enabled', () => {
+      const {program, options, host} = makeProgram([
+        {
+          name: _('/node_modules/@angular/core/index.d.ts'),
+          contents: 'export const Component: any;',
+        },
+        {
+          name: _('/myStyle.css'),
+          contents: '<div>hello world</div>',
+        },
+        {
+          name: _('/entry.ts'),
+          contents: `
+          import {Component} from '@angular/core';
+
+          @Component({
+            template: '<link rel="stylesheet" href="myTemplateStyle.css" />',
+            styles: ['a { color: red; }', 'b { color: blue; }'],
+          }) 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(2);
+      expect(analysis?.meta.externalStyles).toEqual(['myTemplateStyle.css']);
+    });
+
+    it('should populate externalStyles with resolve return values when externalRuntimeStyles is enabled', () => {
+      const {program, options, host} = makeProgram([
+        {
+          name: _('/node_modules/@angular/core/index.d.ts'),
+          contents: 'export const Component: any;',
+        },
+        {
+          name: _('/myStyle.css'),
+          contents: '<div>hello world</div>',
+        },
+        {
+          name: _('/entry.ts'),
+          contents: `
+          import {Component} from '@angular/core';
+
+          @Component({
+            template: '<link rel="stylesheet" href="myTemplateStyle.css" />',
+            styleUrl: '/myStyle.css',
+            styles: ['a { color: red; }', 'b { color: blue; }'],
+          }) class TestCmp {}
+      `,
+        },
+      ]);
+      const {reflectionHost, handler, resourceLoader} = setup(program, options, host, {
+        externalRuntimeStyles: true,
+      });
+      resourceLoader.resolve = (v) => 'abc/' + v;
+      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(2);
+      expect(analysis?.meta.externalStyles).toEqual([
+        'abc//myStyle.css',
+        'abc/myTemplateStyle.css',
+      ]);
+    });
+
     it('should replace inline style content with transformed content', async () => {
       const {program, options, host} = makeProgram([
         {

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

@@ -96,6 +96,16 @@ export interface InternalOptions {
    */
   _enableLetSyntax?: boolean;
 
+  /**
+   * Enables the use of `<link>` elements for component styleUrls instead of inlining the file
+   * content.
+   * This option is intended to be used with a development server that processes and serves
+   * the files on-demand for an application.
+   *
+   * @internal
+   */
+  externalRuntimeStyles?: boolean;
+
   /**
    * Detected version of `@angular/core` in the workspace. Used by the
    * compiler to adjust the output depending on the available symbols.

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

@@ -1392,6 +1392,7 @@ export class NgCompiler {
     const strictCtorDeps = this.options.strictInjectionParameters || false;
     const supportJitMode = this.options['supportJitMode'] ?? true;
     const supportTestBed = this.options['supportTestBed'] ?? true;
+    const externalRuntimeStyles = this.options['externalRuntimeStyles'] ?? false;
 
     // Libraries compiled in partial mode could potentially be used with TestBed within an
     // application. Since this is not known at library compilation time, support is required to
@@ -1457,6 +1458,7 @@ export class NgCompiler {
         !!this.options.forbidOrphanComponents,
         this.enableBlockSyntax,
         this.enableLetSyntax,
+        externalRuntimeStyles,
         localCompilationExtraImportsTracker,
         jitDeclarationRegistry,
         this.options.i18nPreserveWhitespaceForLegacyExtraction ?? true,

packages/compiler/src/render3/r3_identifiers.ts

@@ -553,6 +553,11 @@ export class Identifiers {
     moduleName: CORE,
   };
 
+  static ExternalStylesFeature: o.ExternalReference = {
+    name: 'ɵɵExternalStylesFeature',
+    moduleName: CORE,
+  };
+
   static listener: o.ExternalReference = {name: 'ɵɵlistener', moduleName: CORE};
 
   static getInheritedFactory: o.ExternalReference = {

packages/compiler/src/render3/view/api.ts

@@ -236,6 +236,11 @@ export interface R3ComponentMetadata<DeclarationT extends R3TemplateDependency>
    */
   styles: string[];
 
+  /**
+   * A collection of style paths for external stylesheets that will be applied and scoped to the component.
+   */
+  externalStyles?: string[];
+
   /**
    * An encapsulation policy for the component's styling.
    * Possible values:

packages/compiler/src/render3/view/compiler.ts

@@ -152,6 +152,12 @@ function addFeatures(
   if (meta.hasOwnProperty('template') && meta.isStandalone) {
     features.push(o.importExpr(R3.StandaloneFeature));
   }
+  if ('externalStyles' in meta && meta.externalStyles?.length) {
+    const externalStyleNodes = meta.externalStyles.map((externalStyle) => o.literal(externalStyle));
+    features.push(
+      o.importExpr(R3.ExternalStylesFeature).callFn([o.literalArr(externalStyleNodes)]),
+    );
+  }
   if (features.length) {
     definitionMap.set('features', o.literalArr(features));
   }
@@ -281,8 +287,10 @@ export function compileComponentFromMetadata(
     meta.encapsulation = core.ViewEncapsulation.Emulated;
   }
 
+  let hasStyles = !!meta.externalStyles?.length;
   // e.g. `styles: [str1, str2]`
   if (meta.styles && meta.styles.length) {
+    hasStyles = true;
     const styleValues =
       meta.encapsulation == core.ViewEncapsulation.Emulated
         ? compileStyles(meta.styles, CONTENT_ATTR, HOST_ATTR)
@@ -297,7 +305,9 @@ export function compileComponentFromMetadata(
     if (styleNodes.length > 0) {
       definitionMap.set('styles', o.literalArr(styleNodes));
     }
-  } else if (meta.encapsulation === core.ViewEncapsulation.Emulated) {
+  }
+
+  if (!hasStyles && meta.encapsulation === core.ViewEncapsulation.Emulated) {
     // If there is no style, don't generate css selectors on elements
     meta.encapsulation = core.ViewEncapsulation.None;
   }