Advance RFC #0779 "First-Class Component Templates" to Stage Ready for Release

[emberjs-rfcs-bot]

Advance emberjs/ember.js#779 to the Ready For Release Stage

Summary

This pull request is advancing the RFC to the Ready For Release Stage.

• PR to Accepted Stage: Submitted for discussion: Transitioning between specific states, and Ember.TransitionState ember.js#779

An FCP is required before merging this PR to advance.

Upon merging this PR, automation will open a draft PR for this RFC to move to the Released Stage.

Ready for Release Stage Description

This stage is complete when the implementation is complete according to plan outlined in the RFC, and is in harmony with any changes in Ember that have occurred since the RFC was first written. This includes any necessary learning materials. At this stage, features or deprecations may be available for use behind a feature flag, or with an optional package, etc.

For codebase changes, there are no open questions that are anticipated to require breaking changes; the Ember team is ready to commit to the stability of any interfaces exposed by the current implementation of the feature.

This stage should include a list of criteria for determining when the proposal can be considered Recommended after being Released.

An FCP is required to move into this stage.

Each Ember core team will be requested as a reviewer on the PR to move into this stage. A representative of each team adds a review. If a team does not respond to the request, and after the conclusion of the FCP, it is assumed that the release may proceed.

Checklist to move to Ready for Release

• Implementation is complete according to plan outlined in the RFC, with any adjustments noted in the RFC
• Any necessary learning materials have been updated
• The Ember team is ready to commit to the stability of any interfaces exposed by the current implementation of the feature
• Criteria for moving to the Recommended Stage has been filled out
• This PR has been converted from a draft to a regular PR and the Final Comment Period label has been added to start the FCP
• Each team has been added as a reviewer to the PR at the start of the FCP
  • Framework @emberjs/framework
  • Data @emberjs/ember-data-core
  • CLI @emberjs/cli
  • Learning @emberjs/learning-core
  • Typescript @emberjs/typescript-core
  • Steering @emberjs/steering

Criteria for moving to Recommended (required)

A set of criteria for moving this RFC to the Recommended Stage, following release:

• ember-cli-code-coverage compatibility
  • Fix unnecessary addition of sourcemaps - Fixes #108 ember-cli/ember-template-imports#110
  • Increase coverage payload limit ember-cli-code-coverage/ember-cli-code-coverage#371
  • Handle coverage annotation in scope function babel-plugin-ember-template-compilation#12
  • Ensure that coverage data for .gjs/.gts files is present.
• typescript-eslint type-aware lints
• eslint auto-fix --fix does not work in gjs/gts files ember-cli/eslint-plugin-ember#1750
• single VSCode add-on
• (Maybe) Implement syntax highlighting for linguist (GitHub).
• Implement syntax highlighting for guides

• Update guides content (docs: Add Template Tag format guides ember-learn/guides-source#1978)
• Ember Inspector should show GJS-based templates in a reasonable way

Track Implementation

• Either:
  • Remove support for non-official syntaxes from ember-template-imports.
  • Or implement a true babel syntax extension and pull all the support into babel-plugin-ember-template-compilation
• Quest: First-Class Component Templates tracking-polaris#33
• Add public import for uniqueId helper ember.js#20165
• make sure appropriate core teams have permissions on all relevant packages (like ember-template-imports).
• make sure the priority between ember keywords and javascript locals is correct. If we get it wrong, we break our future ability to ever introduce a new keyword without a breaking change.

[simonihmig]

Can we add emberjs/ember.js#20165 to the criteria above?

[chriskrycho]

Done! Thanks for flagging that up, @simonihmig!

[ef4]

I added a todo:

make sure the priority between ember keywords and javascript locals is correct. If we get it wrong, we break our future ability to ever introduce a new keyword without a breaking change.

based on discussion with @wycats. We both came away convinced that this is important. In template tag, Javascript locals have to take precedence over ember keywords (and thus get put into the scope bag when template tag is transpiled away). So if somebody has:

let component = something();
<template>
  {{component "stuff"}}
</template>

That should result in scope: () => ({ component }). It does not currently.

The idea is that the scope bag should be the intersection of the upvars in the template (which should include keywords) and the locals in the Javascript scope.

[ef4]

On the implementation side: work is actively progressing to replace the ad-hoc parser based implementation (which has a list of known issues) with the full-swc-based-parser implementation.

[ef4]

We need someone to volunteer to produce the full list of documentation work required for this, including updates to guides & tutorial plus anything about how to setup the language server, syntax highlighting, etc.

[ef4]

• To get this to Ready-for-release we need guides content to exist -- not updating everything to switch over, because that can wait until we switch to Polaris as the default docs, but rather just having some dedicated content explaining how template tag works.
• We're working through TS transform breaks imports in templates babel-plugin-ember-template-compilation#30 which is an implementation blocker for use in typescript projects.

[ef4]

Added criterion to remember: ensure that moduleName handling is doing something sensible. I think right now some builds emit extra information there even in prod builds, including full absolute paths.

[NullVoxPopuli]

If anyone is following along here, there is a big todo list here: emberjs/tracking-polaris#33

[ef4]

Status update:

• our implementation is solid and the key bugs are fixed
• there's still work ongoing on the tooling side to improve DX.
• on the learning side, it's time to start a Template Tag specific branch. The RFC review meeting had consensus that this is important to document because it's already seeing adoption and it aids embroider adoption and it's good for addon authors to start adopting to make their components more portable to embroider.

[ef4]

Status updates by area:

Implementation

• we should fix bad transform of fake this param embroider-build/content-tag#71 before advancing
• ember-template-lint should be updated to use content-tag
• we should probably move prettier outside eslint, because (1) it breaks with template tag and (2) the docs for prettier explicitly tell you they don't recommend running inside eslint
  • this may not really be a blocker, we've seen multiple apps with heavy usage working OK this way.

Tooling

• lots of stuff has just landed in the glint repo to integrate volar and improve DX.

Docs

• learning team has a plan for feature flagging template tag content: https://github.com/emberjs/core-notes/pull/592/files#diff-58bf749bf139760b9fc22b6eb926ee42f3818397da23ffb309b410f1c140e624R22
• POC: feature flags ember-learn/guidemaker-ember-template#191

[ef4]

On docs, the next action is to make a PR with actual infrastructure supporting template tag on/off in the guides.

[ef4]

We think this is actually already working on "Recommended" level support and this should have advanced to Released, so entering FCP.