Add 'on' keyword support and related tests

sketching some updates

@ef4 -- it doesn't work

Use globalThis

lint:fix

Author: NullVoxPopuli

packages/@ember/template-compiler/lib/compile-options.ts

@@ -1,3 +1,4 @@
+import { on } from '@ember/modifier';
 import { assert } from '@ember/debug';
 import {
   RESOLUTION_MODE_TRANSFORMS,
@@ -14,11 +15,18 @@ function malformedComponentLookup(string: string) {
   return string.indexOf('::') === -1 && string.indexOf(':') > -1;
 }
 
+const RUNTIME_KEYWORDS_NAME = '__ember_keywords__';
+export const keywords = {
+  on,
+};
+
+// Not worth adding a type
+(globalThis as any)[RUNTIME_KEYWORDS_NAME] = keywords;
+
 function buildCompileOptions(_options: EmberPrecompileOptions): EmberPrecompileOptions {
   let moduleName = _options.moduleName;
 
-  let options: EmberPrecompileOptions & Partial<EmberPrecompileOptions> = {
-    meta: {},
+  let options = {
     isProduction: false,
     plugins: { ast: [] },
     ..._options,
@@ -35,8 +43,25 @@ function buildCompileOptions(_options: EmberPrecompileOptions): EmberPrecompileO
     },
   };
 
-  if ('eval' in options) {
-    const localScopeEvaluator = options.eval as (value: string) => unknown;
+  options.meta ||= {};
+  options.meta.emberRuntime ||= {
+    /**
+     * NOTE: when stepping through lexicalScope, or other callbacks here,
+     *       we first detect the keywords as "not in scope",
+     *       and that is what we want, so that we can import them.
+     */
+    lookupKeyword(name: string): string {
+      assert(
+        `${name} is not a known keyword. Available keywords: ${Object.keys(keywords).join(', ')}`,
+        name in keywords
+      );
+
+      return `globalThis.${RUNTIME_KEYWORDS_NAME}.${name}`;
+    },
+  };
+
+  if ('eval' in options && options.eval) {
+    const localScopeEvaluator = options.eval;
     const globalScopeEvaluator = (value: string) => new Function(`return ${value};`)();
 
     options.lexicalScope = (variable: string) => {
@@ -57,9 +82,7 @@ function buildCompileOptions(_options: EmberPrecompileOptions): EmberPrecompileO
   if ('scope' in options) {
     const scope = (options.scope as () => Record<string, unknown>)();
 
-    options.lexicalScope = (variable: string) => {
-      return variable in scope;
-    };
+    options.lexicalScope = (variable: string) => variable in scope || variable in keywords;
 
     delete options.scope;
   }

packages/@ember/template-compiler/lib/plugins/auto-import-builtins.ts

@@ -0,0 +1,44 @@
+import type { AST, ASTPlugin } from '@glimmer/syntax';
+import type { EmberASTPluginEnvironment } from '../types';
+import { isPath, trackLocals } from './utils';
+
+/**
+ @module ember
+*/
+
+/**
+  A Glimmer2 AST transformation that makes importable keywords work
+
+  @private
+  @class TransformActionSyntax
+*/
+
+export default function autoImportBuiltins(env: EmberASTPluginEnvironment): ASTPlugin {
+  let { hasLocal, visitor } = trackLocals(env);
+
+  return {
+    name: 'auto-import-built-ins',
+
+    visitor: {
+      ...visitor,
+      ElementModifierStatement(node: AST.ElementModifierStatement) {
+        if (isOn(node, hasLocal)) {
+          if (env.meta?.jsutils) {
+            node.path.original = env.meta.jsutils.bindImport('@ember/modifier', 'on', node, {
+              name: 'on',
+            });
+          } else if (env.meta?.emberRuntime) {
+            node.path.original = env.meta.emberRuntime.lookupKeyword('on');
+          }
+        }
+      },
+    },
+  };
+}
+
+function isOn(
+  node: AST.ElementModifierStatement | AST.MustacheStatement | AST.SubExpression,
+  hasLocal: (k: string) => boolean
+): node is AST.ElementModifierStatement & { path: AST.PathExpression } {
+  return isPath(node.path) && node.path.original === 'on' && !hasLocal('on');
+}

packages/@ember/template-compiler/lib/plugins/index.ts

@@ -9,8 +9,10 @@ import TransformInElement from './transform-in-element';
 import TransformQuotedBindingsIntoJustBindings from './transform-quoted-bindings-into-just-bindings';
 import TransformResolutions from './transform-resolutions';
 import TransformWrapMountAndOutlet from './transform-wrap-mount-and-outlet';
+import AutoImportBuiltins from './auto-import-builtins';
 
 export const INTERNAL_PLUGINS = {
+  AutoImportBuiltins,
   AssertAgainstAttrs,
   AssertAgainstNamedOutlets,
   AssertInputHelperWithoutBlock,
@@ -40,6 +42,7 @@ export const RESOLUTION_MODE_TRANSFORMS = Object.freeze([
 ]);
 
 export const STRICT_MODE_TRANSFORMS = Object.freeze([
+  AutoImportBuiltins,
   TransformQuotedBindingsIntoJustBindings,
   AssertReservedNamedArguments,
   TransformActionSyntax,

packages/@ember/template-compiler/lib/template.ts

@@ -3,7 +3,7 @@ import { precompile as glimmerPrecompile } from '@glimmer/compiler';
 import type { SerializedTemplateWithLazyBlock } from '@glimmer/interfaces';
 import { setComponentTemplate } from '@glimmer/manager';
 import { templateFactory } from '@glimmer/opcode-compiler';
-import compileOptions from './compile-options';
+import compileOptions, { keywords } from './compile-options';
 import type { EmberPrecompileOptions } from './types';
 
 type ComponentClass = abstract new (...args: any[]) => object;
@@ -237,38 +237,48 @@ export function template(
   templateString: string,
   providedOptions?: BaseTemplateOptions | BaseClassTemplateOptions<any>
 ): object {
-  const options: EmberPrecompileOptions = { strictMode: true, ...providedOptions };
-  const evaluate = buildEvaluator(options);
+  const options = { strictMode: true, ...providedOptions };
 
+  const evaluate = buildEvaluator(options);
   const normalizedOptions = compileOptions(options);
   const component = normalizedOptions.component ?? templateOnly();
 
   const source = glimmerPrecompile(templateString, normalizedOptions);
-  const template = templateFactory(evaluate(`(${source})`) as SerializedTemplateWithLazyBlock);
+  const wire = evaluate(`(${source})`) as SerializedTemplateWithLazyBlock;
+
+  const template = templateFactory(wire);
 
   setComponentTemplate(template, component);
 
   return component;
 }
 
 const evaluator = (source: string) => {
-  return new Function(`return  ${source}`)();
+  return new Function(`return ${source}`)();
 };
 
-function buildEvaluator(options: Partial<EmberPrecompileOptions> | undefined) {
-  if (options === undefined) {
-    return evaluator;
-  }
-
+/**
+ * Builds the source wireformat JSON block
+ *
+ * @param options
+ * @returns
+ */
+function buildEvaluator(options: Partial<EmberPrecompileOptions>) {
   if (options.eval) {
     return options.eval;
   } else {
-    const scope = options.scope?.();
+    /**
+     * This is ran before the template is compiled,
+     * so we cannot use any information gathered during template compilation.
+     */
+    let scope = options.scope?.();
 
     if (!scope) {
       return evaluator;
     }
 
+    scope = Object.assign({}, keywords, scope);
+
     return (source: string) => {
       let hasThis = Object.prototype.hasOwnProperty.call(scope, 'this');
       let thisValue = hasThis ? (scope as { this?: unknown }).this : undefined;

packages/@ember/template-compiler/lib/types.ts

@@ -1,4 +1,5 @@
 import type {
+  ASTPluginBuilder,
   ASTPluginEnvironment,
   builders,
   PrecompileOptions,
@@ -13,21 +14,39 @@ export type Builders = typeof builders;
  * typing. Here export the interface subclass with no modification.
  */
 
-export type PluginFunc = NonNullable<
-  NonNullable<PrecompileOptionsWithLexicalScope['plugins']>['ast']
->[number];
+export type PluginFunc = ASTPluginBuilder<EmberASTPluginEnvironment>;
 
 export type LexicalScope = NonNullable<PrecompileOptionsWithLexicalScope['lexicalScope']>;
 
 interface Plugins {
   ast: PluginFunc[];
 }
 
-export interface EmberPrecompileOptions extends PrecompileOptions {
+export interface EmberPrecompileOptions extends Omit<PrecompileOptions, 'meta'> {
   isProduction?: boolean;
   moduleName?: string;
   plugins?: Plugins;
   lexicalScope?: LexicalScope;
+  meta?: {
+    /**
+     * Exists for historical reasons, should not be in new code, as
+     * the module name does not correspond to anything meaningful at runtime.
+     */
+    moduleName?: string | undefined;
+
+    /**
+     * Not available at runtime
+     */
+    jsutils?: { bindImport: (...args: unknown[]) => string };
+
+    /**
+     * Utils unique to the runtime compiler
+     */
+    emberRuntime?: {
+      lookupKeyword(name: string): string;
+    };
+  };
+
   /**
    * This supports template blocks defined in class bodies.
    *

packages/@ember/template-compiler/package.json

@@ -12,6 +12,8 @@
     "@ember/-internals": "workspace:*",
     "@ember/component": "workspace:*",
     "@ember/debug": "workspace:*",
+    "@ember/modifier": "workspace:*",
+    "@ember/helper": "workspace:*",
     "@glimmer/compiler": "workspace:*",
     "@glimmer/env": "workspace:*",
     "@glimmer/interfaces": "workspace:*",

packages/@glimmer-workspace/integration-tests/test/keywords/on-runtime-test.ts

@@ -0,0 +1,64 @@
+import { castToBrowser } from '@glimmer/debug-util';
+import { jitSuite, RenderTest, test } from '@glimmer-workspace/integration-tests';
+
+import { template } from '@ember/template-compiler/runtime';
+
+class KeywordOn extends RenderTest {
+  static suiteName = 'keyword modifier: on (runtime)';
+
+  @test
+  'explicit scope'(assert: Assert) {
+    let handleClick = () => {
+      assert.step('success');
+    };
+
+    const compiled = template('<button {{on "click" handleClick}}>Click</button>', {
+      strictMode: true,
+      scope: () => ({
+        handleClick,
+      }),
+    });
+
+    this.renderComponent(compiled);
+
+    castToBrowser(this.element, 'div').querySelector('button')!.click();
+    assert.verifySteps(['success']);
+  }
+
+  @test
+  'implicit scope'(assert: Assert) {
+    let handleClick = () => {
+      assert.step('success');
+    };
+
+    hide(handleClick);
+
+    const compiled = template('<button {{on "click" handleClick}}>Click</button>', {
+      strictMode: true,
+      eval() {
+        return eval(arguments[0]);
+      },
+    });
+
+    this.renderComponent(compiled);
+
+    castToBrowser(this.element, 'div').querySelector('button')!.click();
+    assert.verifySteps(['success']);
+  }
+}
+
+jitSuite(KeywordOn);
+
+/**
+ * This function is used to hide a variable from the transpiler, so that it
+ * doesn't get removed as "unused". It does not actually do anything with the
+ * variable, it just makes it be part of an expression that the transpiler
+ * won't remove.
+ *
+ * It's a bit of a hack, but it's necessary for testing.
+ *
+ * @param variable The variable to hide.
+ */
+const hide = (variable: unknown) => {
+  new Function(`return (${JSON.stringify(variable)});`);
+};