refactor(compiler): parse options parameter on viewport triggers (angular#64130)

Updates the template parser and AST to capture a second object literal parameter on `viewport` triggers.

PR Close angular#64130

Author: crisbeto

packages/compiler/src/combined_visitor.ts

@@ -70,6 +70,8 @@ export class CombinedRecursiveAstVisitor extends RecursiveAstVisitor implements
   visitDeferredTrigger(trigger: t.DeferredTrigger): void {
     if (trigger instanceof t.BoundDeferredTrigger) {
       this.visit(trigger.value);
+    } else if (trigger instanceof t.ViewportDeferredTrigger && trigger.options !== null) {
+      this.visit(trigger.options);
     }
   }
 

packages/compiler/src/render3/r3_ast.ts

@@ -12,6 +12,7 @@ import {
   ASTWithSource,
   BindingType,
   BoundElementProperty,
+  LiteralMap,
   ParsedEvent,
   ParsedEventType,
 } from '../expression_parser/ast';
@@ -252,7 +253,8 @@ export class InteractionDeferredTrigger extends DeferredTrigger {
 
 export class ViewportDeferredTrigger extends DeferredTrigger {
   constructor(
-    public reference: string | null,
+    readonly reference: string | null,
+    readonly options: LiteralMap | null,
     nameSpan: ParseSourceSpan,
     sourceSpan: ParseSourceSpan,
     prefetchSpan: ParseSourceSpan | null,

packages/compiler/src/render3/r3_deferred_blocks.ts

@@ -279,15 +279,15 @@ function parsePrimaryTriggers(
     if (WHEN_PARAMETER_PATTERN.test(param.expression)) {
       parseWhenTrigger(param, bindingParser, triggers, errors);
     } else if (ON_PARAMETER_PATTERN.test(param.expression)) {
-      parseOnTrigger(param, triggers, errors, placeholder);
+      parseOnTrigger(param, bindingParser, triggers, errors, placeholder);
     } else if (PREFETCH_WHEN_PATTERN.test(param.expression)) {
       parseWhenTrigger(param, bindingParser, prefetchTriggers, errors);
     } else if (PREFETCH_ON_PATTERN.test(param.expression)) {
-      parseOnTrigger(param, prefetchTriggers, errors, placeholder);
+      parseOnTrigger(param, bindingParser, prefetchTriggers, errors, placeholder);
     } else if (HYDRATE_WHEN_PATTERN.test(param.expression)) {
       parseWhenTrigger(param, bindingParser, hydrateTriggers, errors);
     } else if (HYDRATE_ON_PATTERN.test(param.expression)) {
-      parseOnTrigger(param, hydrateTriggers, errors, placeholder);
+      parseOnTrigger(param, bindingParser, hydrateTriggers, errors, placeholder);
     } else if (HYDRATE_NEVER_PATTERN.test(param.expression)) {
       parseNeverTrigger(param, hydrateTriggers, errors);
     } else {

packages/compiler/src/render3/r3_deferred_triggers.ts

@@ -7,6 +7,17 @@
  */
 
 import * as chars from '../chars';
+import {
+  AST,
+  ASTWithSource,
+  ImplicitReceiver,
+  LiteralArray,
+  LiteralMap,
+  LiteralPrimitive,
+  PropertyRead,
+  RecursiveAstVisitor,
+  ThisReceiver,
+} from '../expression_parser/ast';
 import {Lexer, Token, TokenType} from '../expression_parser/lexer';
 import * as html from '../ml_parser/ast';
 import {ParseError, ParseSourceSpan} from '../parse_util';
@@ -117,6 +128,7 @@ export function parseWhenTrigger(
 /** Parses an `on` trigger */
 export function parseOnTrigger(
   {expression, sourceSpan}: html.BlockParameter,
+  bindingParser: BindingParser,
   triggers: t.DeferredBlockTriggers,
   errors: ParseError[],
   placeholder: t.DeferredBlockPlaceholder | null,
@@ -135,16 +147,18 @@ export function parseOnTrigger(
     errors.push(new ParseError(sourceSpan, `Could not find "on" keyword in expression`));
   } else {
     const start = getTriggerParametersStart(expression, onIndex + 1);
+    const isHydrationTrigger = expression.startsWith('hydrate');
     const parser = new OnTriggerParser(
       expression,
+      bindingParser,
       start,
       sourceSpan,
       triggers,
       errors,
-      expression.startsWith('hydrate')
+      isHydrationTrigger
         ? validateHydrateReferenceBasedTrigger
         : validatePlainReferenceBasedTrigger,
-      placeholder,
+      isHydrationTrigger,
       prefetchSpan,
       onSourceSpan,
       hydrateSpan,
@@ -173,12 +187,13 @@ class OnTriggerParser {
 
   constructor(
     private expression: string,
+    private bindingParser: BindingParser,
     private start: number,
     private span: ParseSourceSpan,
     private triggers: t.DeferredBlockTriggers,
     private errors: ParseError[],
     private validator: ReferenceTriggerValidator,
-    private placeholder: t.DeferredBlockPlaceholder | null,
+    private isHydrationTrigger: boolean,
     private prefetchSpan: ParseSourceSpan | null,
     private onSourceSpan: ParseSourceSpan,
     private hydrateSpan: ParseSourceSpan | null,
@@ -333,6 +348,9 @@ class OnTriggerParser {
           this.trackTrigger(
             'viewport',
             createViewportTrigger(
+              this.start,
+              this.isHydrationTrigger,
+              this.bindingParser,
               parameters,
               nameSpan,
               sourceSpan,
@@ -568,6 +586,9 @@ function createInteractionTrigger(
 }
 
 function createViewportTrigger(
+  start: number,
+  isHydrationTrigger: boolean,
+  bindingParser: BindingParser,
   parameters: ParsedParameter[],
   nameSpan: ParseSourceSpan,
   sourceSpan: ParseSourceSpan,
@@ -577,8 +598,74 @@ function createViewportTrigger(
   validator: ReferenceTriggerValidator,
 ): t.ViewportDeferredTrigger {
   validator(OnTriggerType.VIEWPORT, parameters);
+
+  let reference: string | null;
+  let options: LiteralMap | null;
+
+  if (parameters.length === 0) {
+    reference = options = null;
+  } else if (!parameters[0].expression.startsWith('{')) {
+    reference = parameters[0].expression;
+    options = null;
+  } else {
+    const parsed = bindingParser.parseBinding(
+      parameters[0].expression,
+      false,
+      sourceSpan,
+      sourceSpan.start.offset + start + parameters[0].start,
+    );
+
+    if (!(parsed.ast instanceof LiteralMap)) {
+      throw new Error('Options parameter of the "viewport" trigger must be an object literal');
+    } else if (parsed.ast.keys.some((key) => key.key === 'root')) {
+      throw new Error(
+        'The "root" option is not supported in the options parameter of the "viewport" trigger',
+      );
+    }
+
+    const triggerIndex = parsed.ast.keys.findIndex((key) => key.key === 'trigger');
+
+    if (triggerIndex === -1) {
+      reference = null;
+      options = parsed.ast;
+    } else {
+      const value = parsed.ast.values[triggerIndex];
+      const triggerFilter = (_: unknown, index: number) => index !== triggerIndex;
+
+      if (
+        !(value instanceof PropertyRead) ||
+        !(value.receiver instanceof ImplicitReceiver) ||
+        value.receiver instanceof ThisReceiver
+      ) {
+        throw new Error(`"trigger" option of the "viewport" trigger must be an identifier`);
+      }
+
+      reference = (value as PropertyRead).name;
+      options = new LiteralMap(
+        parsed.ast.span,
+        parsed.ast.sourceSpan,
+        parsed.ast.keys.filter(triggerFilter),
+        parsed.ast.values.filter(triggerFilter),
+      );
+    }
+  }
+
+  if (isHydrationTrigger && reference !== null) {
+    throw new Error(`"viewport" hydration trigger cannot have a "trigger"`);
+  } else if (options) {
+    const dynamicNode = DynamicAstValidator.findDynamicNode(options);
+
+    if (dynamicNode !== null) {
+      throw new Error(
+        `Options of the "viewport" trigger must be an object ` +
+          `literal containing only literal values, but "${dynamicNode.constructor.name}" was found`,
+      );
+    }
+  }
+
   return new t.ViewportDeferredTrigger(
-    parameters[0]?.expression ?? null,
+    reference,
+    options,
     nameSpan,
     sourceSpan,
     prefetchSpan,
@@ -604,6 +691,13 @@ function validatePlainReferenceBasedTrigger(type: OnTriggerType, parameters: Par
  * @param parameters Parameters of the trigger.
  */
 function validateHydrateReferenceBasedTrigger(type: OnTriggerType, parameters: ParsedParameter[]) {
+  if (type === OnTriggerType.VIEWPORT) {
+    if (parameters.length > 1) {
+      throw new Error(`Hydration trigger "${type}" cannot have more than one parameter`);
+    }
+    return;
+  }
+
   if (parameters.length > 0) {
     throw new Error(`Hydration trigger "${type}" cannot have parameters`);
   }
@@ -638,3 +732,26 @@ export function parseDeferredTime(value: string): number | null {
   const [time, units] = match;
   return parseFloat(time) * (units === 's' ? 1000 : 1);
 }
+
+class DynamicAstValidator extends RecursiveAstVisitor {
+  private dynamicNode: AST | null = null;
+
+  static findDynamicNode(ast: AST): AST | null {
+    const visitor = new DynamicAstValidator();
+    visitor.visit(ast);
+    return visitor.dynamicNode;
+  }
+
+  override visit(ast: AST): void {
+    if (
+      !(ast instanceof ASTWithSource) &&
+      !(ast instanceof LiteralPrimitive) &&
+      !(ast instanceof LiteralArray) &&
+      !(ast instanceof LiteralMap)
+    ) {
+      this.dynamicNode = ast;
+    } else {
+      super.visit(ast);
+    }
+  }
+}

packages/compiler/test/render3/r3_template_transform_spec.ts

@@ -150,7 +150,13 @@ class R3AstHumanizer implements t.Visitor<void> {
     } else if (trigger instanceof t.InteractionDeferredTrigger) {
       this.result.push(['InteractionDeferredTrigger', trigger.reference]);
     } else if (trigger instanceof t.ViewportDeferredTrigger) {
-      this.result.push(['ViewportDeferredTrigger', trigger.reference]);
+      const result = ['ViewportDeferredTrigger', trigger.reference];
+
+      if (trigger.options !== null) {
+        result.push(unparse(trigger.options));
+      }
+
+      this.result.push(result);
     } else if (trigger instanceof t.NeverDeferredTrigger) {
       this.result.push(['NeverDeferredTrigger']);
     } else {
@@ -1325,6 +1331,29 @@ describe('R3 template transform', () => {
       ]);
     });
 
+    it('should parse a viewport trigger with an options parameter', () => {
+      expectFromHtml(
+        '@defer (on viewport({trigger: foo, rootMargin: "123px", threshold: [1, 2, 3]})){hello}',
+      ).toEqual([
+        ['DeferredBlock'],
+        ['ViewportDeferredTrigger', 'foo', '{rootMargin: "123px", threshold: [1, 2, 3]}'],
+        ['Text', 'hello'],
+      ]);
+    });
+
+    it('should parse a viewport trigger with an options parameter, but without a trigger', () => {
+      expectFromHtml('@defer (on viewport({rootMargin: "123px"})){hello}').toEqual([
+        ['DeferredBlock'],
+        ['ViewportDeferredTrigger', null, '{rootMargin: "123px"}'],
+        ['Text', 'hello'],
+      ]);
+      expectFromHtml('@defer (on viewport({rootMargin: "123px"})){hello}').toEqual([
+        ['DeferredBlock'],
+        ['ViewportDeferredTrigger', null, '{rootMargin: "123px"}'],
+        ['Text', 'hello'],
+      ]);
+    });
+
     describe('block validations', () => {
       it('should report syntax error in `when` trigger', () => {
         expect(() => parse('@defer (when isVisible#){hello}')).toThrowError(
@@ -1498,6 +1527,26 @@ describe('R3 template transform', () => {
         );
       });
 
+      it('should report if `viewport` trigger with an object literal parameter has a "trigger" that is not an identifier', () => {
+        expect(() => parse('@defer (on viewport({trigger: "str"})) {hello}')).toThrowError(
+          /"trigger" option of the "viewport" trigger must be an identifier/,
+        );
+      });
+
+      it('should report if `viewport` trigger has a variable options parameter', () => {
+        expect(() =>
+          parse('@defer (on viewport({threshold: [1, someVar, 3]})) {hello}'),
+        ).toThrowError(
+          /Options of the "viewport" trigger must be an object literal containing only literal values/,
+        );
+      });
+
+      it('should report if `viewport` trigger options parameter contains the `root` property', () => {
+        expect(() => parse('@defer (on viewport({root: foo})) {hello}')).toThrowError(
+          /The "root" option is not supported in the options parameter of the "viewport" trigger/,
+        );
+      });
+
       it('should report duplicate when triggers', () => {
         expect(() => parse('@defer (when isVisible(); when somethingElse()) {hello}')).toThrowError(
           /Duplicate "when" trigger is not allowed/,

packages/compiler/test/render3/util/expression.ts

@@ -179,6 +179,8 @@ class ExpressionSourceHumanizer extends e.RecursiveAstVisitor implements t.Visit
   visitDeferredTrigger(trigger: t.DeferredTrigger): void {
     if (trigger instanceof t.BoundDeferredTrigger) {
       this.recordAst(trigger.value);
+    } else if (trigger instanceof t.ViewportDeferredTrigger && trigger.options !== null) {
+      this.recordAst(trigger.options);
     }
   }
 

packages/language-service/src/template_target.ts

@@ -46,6 +46,7 @@ import {
   TmplAstTextAttribute,
   TmplAstUnknownBlock,
   TmplAstVariable,
+  TmplAstViewportDeferredTrigger,
   tmplAstVisitAll,
   TmplAstVisitor,
 } from '@angular/compiler';
@@ -650,6 +651,8 @@ class TemplateTargetVisitor implements TmplAstVisitor {
   visitDeferredTrigger(trigger: TmplAstDeferredTrigger) {
     if (trigger instanceof TmplAstBoundDeferredTrigger) {
       this.visitBinding(trigger.value);
+    } else if (trigger instanceof TmplAstViewportDeferredTrigger && trigger.options !== null) {
+      this.visitBinding(trigger.options);
     }
   }