RFC#389 - {{element}} as keyword

Register element as a built-in keyword so it no longer needs to be
imported in strict-mode (gjs/gts) templates.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: NullVoxPopuli

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

@@ -1,4 +1,4 @@
-import { fn } from '@ember/helper';
+import { element, fn } from '@ember/helper';
 import { on } from '@ember/modifier';
 import { assert } from '@ember/debug';
 import {
@@ -25,6 +25,7 @@ function malformedComponentLookup(string: string) {
 export const RUNTIME_KEYWORDS_NAME = '__ember_keywords__';
 
 export const keywords: Record<string, unknown> = {
+  element,
   fn,
   on,
 };

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

@@ -27,11 +27,17 @@ export default function autoImportBuiltins(env: EmberASTPluginEnvironment): ASTP
         }
       },
       SubExpression(node: AST.SubExpression) {
+        if (isElement(node, hasLocal)) {
+          rewriteKeyword(env, node, 'element', '@ember/helper');
+        }
         if (isFn(node, hasLocal)) {
           rewriteKeyword(env, node, 'fn', '@ember/helper');
         }
       },
       MustacheStatement(node: AST.MustacheStatement) {
+        if (isElement(node, hasLocal)) {
+          rewriteKeyword(env, node, 'element', '@ember/helper');
+        }
         if (isFn(node, hasLocal)) {
           rewriteKeyword(env, node, 'fn', '@ember/helper');
         }
@@ -68,3 +74,10 @@ function isFn(
 ): node is (AST.MustacheStatement | AST.SubExpression) & { path: AST.PathExpression } {
   return isPath(node.path) && node.path.original === 'fn' && !hasLocal('fn');
 }
+
+function isElement(
+  node: AST.MustacheStatement | AST.SubExpression,
+  hasLocal: (k: string) => boolean
+): node is (AST.MustacheStatement | AST.SubExpression) & { path: AST.PathExpression } {
+  return isPath(node.path) && node.path.original === 'element' && !hasLocal('element');
+}

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

@@ -0,0 +1,84 @@
+import { castToBrowser } from '@glimmer/debug-util';
+import {
+  GlimmerishComponent,
+  jitSuite,
+  RenderTest,
+  test,
+} from '@glimmer-workspace/integration-tests';
+
+import { template } from '@ember/template-compiler/runtime';
+
+class KeywordElement extends RenderTest {
+  static suiteName = 'keyword helper: element (runtime)';
+
+  @test
+  'explicit scope'(assert: Assert) {
+    const compiled = template('{{#let (element "h1") as |Tag|}}<Tag>Hello</Tag>{{/let}}', {
+      strictMode: true,
+      scope: () => ({}),
+    });
+
+    this.renderComponent(compiled);
+
+    let h1 = castToBrowser(this.element, 'div').querySelector('h1');
+    assert.ok(h1, 'h1 element exists');
+    assert.strictEqual(h1!.textContent, 'Hello');
+  }
+
+  @test
+  'implicit scope'(assert: Assert) {
+    const compiled = template('{{#let (element "h1") as |Tag|}}<Tag>Hello</Tag>{{/let}}', {
+      strictMode: true,
+      eval() {
+        return eval(arguments[0]);
+      },
+    });
+
+    this.renderComponent(compiled);
+
+    let h1 = castToBrowser(this.element, 'div').querySelector('h1');
+    assert.ok(h1, 'h1 element exists');
+    assert.strictEqual(h1!.textContent, 'Hello');
+  }
+
+  @test
+  'MustacheStatement with explicit scope'(assert: Assert) {
+    const Child = template('{{#let @tag as |Tag|}}<Tag>World</Tag>{{/let}}', {
+      strictMode: true,
+      scope: () => ({}),
+    });
+
+    const compiled = template('<Child @tag={{element "span"}} />', {
+      strictMode: true,
+      scope: () => ({
+        Child,
+      }),
+    });
+
+    this.renderComponent(compiled);
+
+    let span = castToBrowser(this.element, 'div').querySelector('span');
+    assert.ok(span, 'span element exists');
+    assert.strictEqual(span!.textContent, 'World');
+  }
+
+  @test
+  'no eval and no scope'(assert: Assert) {
+    class Foo extends GlimmerishComponent {
+      static {
+        template('{{#let (element "h1") as |Tag|}}<Tag>Hello</Tag>{{/let}}', {
+          strictMode: true,
+          component: this,
+        });
+      }
+    }
+
+    this.renderComponent(Foo);
+
+    let h1 = castToBrowser(this.element, 'div').querySelector('h1');
+    assert.ok(h1, 'h1 element exists');
+    assert.strictEqual(h1!.textContent, 'Hello');
+  }
+}
+
+jitSuite(KeywordElement);

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

@@ -0,0 +1,79 @@
+import { castToBrowser } from '@glimmer/debug-util';
+import { jitSuite, RenderTest, test } from '@glimmer-workspace/integration-tests';
+
+import { template } from '@ember/template-compiler/runtime';
+import { element } from '@ember/helper';
+
+class KeywordElement extends RenderTest {
+  static suiteName = 'keyword helper: element';
+
+  @test
+  'it works as a SubExpression'(assert: Assert) {
+    const compiled = template('{{#let (element "h1") as |Tag|}}<Tag>Hello</Tag>{{/let}}', {
+      strictMode: true,
+      scope: () => ({ element }),
+    });
+
+    this.renderComponent(compiled);
+
+    let h1 = castToBrowser(this.element, 'div').querySelector('h1');
+    assert.ok(h1, 'h1 element exists');
+    assert.strictEqual(h1!.textContent, 'Hello');
+  }
+
+  @test
+  'it works with the runtime compiler'(assert: Assert) {
+    hide(element);
+
+    const compiled = template('{{#let (element "h1") as |Tag|}}<Tag>Hello</Tag>{{/let}}', {
+      strictMode: true,
+      eval() {
+        return eval(arguments[0]);
+      },
+    });
+
+    this.renderComponent(compiled);
+
+    let h1 = castToBrowser(this.element, 'div').querySelector('h1');
+    assert.ok(h1, 'h1 element exists');
+    assert.strictEqual(h1!.textContent, 'Hello');
+  }
+
+  @test
+  'it works as a MustacheStatement'(assert: Assert) {
+    const Child = template('{{#let @tag as |Tag|}}<Tag>World</Tag>{{/let}}', {
+      strictMode: true,
+      scope: () => ({}),
+    });
+
+    const compiled = template('<Child @tag={{element "span"}} />', {
+      strictMode: true,
+      scope: () => ({
+        element,
+        Child,
+      }),
+    });
+
+    this.renderComponent(compiled);
+
+    let span = castToBrowser(this.element, 'div').querySelector('span');
+    assert.ok(span, 'span element exists');
+    assert.strictEqual(span!.textContent, 'World');
+  }
+}
+
+jitSuite(KeywordElement);
+
+/**
+ * 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)});`);
+};

smoke-tests/scenarios/basic-test.ts

@@ -401,6 +401,30 @@ function basicTest(scenarios: Scenarios, appName: string) {
                 });
               });
             `,
+            'element-as-keyword-test.gjs': `
+              import { module, test } from 'qunit';
+              import { setupRenderingTest } from 'ember-qunit';
+              import { render } from '@ember/test-helpers';
+
+              import Component from '@glimmer/component';
+
+              class Demo extends Component {
+                <template>
+                  {{#let (element "h1") as |Tag|}}
+                    <Tag class="greeting">Hello from element keyword</Tag>
+                  {{/let}}
+                </template>
+              }
+
+              module('{{element}} as keyword', function(hooks) {
+                setupRenderingTest(hooks);
+
+                test('it works', async function(assert) {
+                  await render(Demo);
+                  assert.dom('h1.greeting').hasText('Hello from element keyword');
+                });
+              });
+            `,
             'fn-as-keyword-but-its-shadowed-test.gjs': `
               import QUnit, { module, test } from 'qunit';
               import { setupRenderingTest } from 'ember-qunit';