Quest: First-Class Component Templates

[chriskrycho]

The path to making RFC emberjs/ember.js#779: First-Class Component Templates stable and recommended for end users.

What even is this?

Background

RFC emberjs/ember.js#779: First-Class Component Templates picked <template> tags as the the ability for Ember (and Glimmer) developers to write components with template tags embedded in their JS, like so:

import Component from '@glimmer/component';

const Button = <template>
  <button
    type='button'
    class="my-button"
    {{on "click" @onClick}}
  >
    {{@label}}
  </button>
</template>

export default class Player extends Component {
  @tracked isPlaying = false;

  play = () => (this.isPlaying = true);
  pause = () => (this.isPlaying = false);

  <template>
    <audio src={{@srcUrl}} {{playWhen this.isPlaying}} />

    <Button @label="Play" @onClick={{this.play}} />
    <Button @label="Pause" @onClick={{this.pause}} />
  </template>
}

This is not only a general win for ease of working with Ember: it is also a key part of our TypeScript story, because it makes things like go-to-definition, documentation hovers, autocomplete, auto-import, etc. all much easier to manage. So: what do we need to do to finish unblocking its adoption?

The Road to Stable

See ember-cli/ember-template-imports#35 for details on each part of this.

• Prettier support
• ESLint support
• ember-template-lint integration

The Road to Recommended

• Finish and publish specification
• Make any spec-driven updates to ember-template-imports
• Integrate ember-template-imports into Glimmer, with Ember being a customer

[chriskrycho]

• Thanks to @ventuno, we have ember-template-lint support!
• Thanks to @gitKrystan, we have Prettier support!
• Thanks to @NullVoxPopuli and @nlfurniss, we have ESLint support!

Thanks as well to @wycats, @bmish, and @rwjblue for helping get those various efforts across the line.

I’ll make sure we follow up on this in one of the next few Framework Core team meetings—this is amazing progress, and represents a huge step toward stabilizing this and eventually making it the recommended way of writing Ember templates.

(Keep your eyes open for code-mods coming soon™!)

[ef4]

A status update here is that

• we merged https://github.com/emberjs/rfcs/blob/master/text/0931-template-compiler-api.md which stabilized the plain-javascript representation of template tag
• the build-time implementation of that RFC shipped in https://github.com/embroider-build/content-tag/ for going from template tag to the low-level format. This implementation fixes many outstanding bugs in the original ember-template-imports implementation, which didn't have the benefit of a full javascript parser.
• and [email protected] shipped with the ability to take the low-level format to runnable code.

[wagenet]

@ef4 Do we have an updated checklist on this?

[ef4]

• publish a version of ember-cli-htmlbars that depends on a minimum babel-plugin-ember-template-compilation version of 2.2.0 and that adds the @babel/plugin-transform-class-static-block plugin whenever adding the other class-feature plugins that are implied by legacy decorators.
• publish a version of embroider that depends on a minimum babel-plugin-ember-template-compilation version of 2.2.0 and that adds the @babel/plugin-transform-class-static-block plugin whenever adding the other class-feature plugins that are implied by legacy decorators.
• publish a new ember-template-imports that uses content-tag to do preprocessing and does nothing on the babel side, documenting that it requires the above mentioned ember-cli-htmlbars or embroider version.
• document clearly how to get full editor support (syntax highlighting, linters, typescript) when using template tag in (at least) VSCode.
• ensure that the blueprints support prettier / eslint / etc of GJS/GTS out of the box.
• update guides to use <template>

[NullVoxPopuli]

couple clarifying questions:

document

where to do this?
linting should be automatic provided new enough eslint-plugin-ember and ember-template-lint.

update guides to use

pre-polaris? if so, this would be a good thing to start soon, given all the implementation stuff is done? (this is a really big given.)
there is a bunch of infra-work for the ember-family-of-sites blocking this, afaik (empress, guide-maker, highlighting, (my prism PRs, etc))

[NullVoxPopuli]

Remaining todos

Untracked / missing-GH-issue

• jscodeshift parser?
• handling moduleName

Features

• Add failing test for declarative shadow-dom embroider-build/content-tag#66
• Advance RFC #0931 "JS Representation of Template Tag" to Stage Ready for Release rfcs#933
• Advance RFC #0785 "Introduce new test helpers for rendering (and re-rendering) that obviate the need for get and set" to Stage Recommended rfcs#991
• For linting, we'd need to be able to emit a full AST, including nodes for the template embroider-build/content-tag#39
• [Feature request] source map generation embroider-build/content-tag#61
  • Transform callback embroider-build/content-tag#29
    • Add transform callback to process that is overridable (with the default value being what our transform does today) embroider-build/content-tag#70
  • Add line numbers to js errors embroider-build/content-tag#56
  • Reproduce issue described in #45 - multi-byte characters are counted incorrectly. embroider-build/content-tag#53

Compatibility

• Setting enableTypeScriptTransform to true breaks imports in .gjs tests ember-cli/ember-template-imports#228

Docs

• docs: Add Template Tag format guides ember-learn/guides-source#1978

Readiness Progression

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

Highlighting

• Links break highlighting ember-tooling/tree-sitter-glimmer#119
• Indent module support ember-tooling/tree-sitter-glimmer#60
• auto closing of tags appears to not work on gjs/gts files lifeart/vsc-ember-syntax#44
• feat: add glimmer js/ts markdown language injects lifeart/vsc-ember-syntax#45

Linting

Requires eslint-plugin-ember @ v12+

• new "flat" configs contain invalid parser key ember-cli/eslint-plugin-ember#2061
• @typescript-eslint breaks after update to eslint-plugin-ember v12 ember-cli/eslint-plugin-ember#2062
• Revamped gjs/gts support ember-template-lint/ember-template-lint#3013
  • [gjs]: no-unknown-arguments-for-builtin-components incorrectly assumes an <Input> is the ember <Input> ember-template-lint/ember-template-lint#3014
  • [gjs]: require-input-label incorrectly assumes an <Input> is the ember <Input> ember-template-lint/ember-template-lint#3015

Glint

• Enable Glint by Default rfcs#976 (since tsserver doesn't work on gjs/gts)
  • Needs Fixed/Resolved
  • GJS parsed as JSX typed-ember/glint#694
  • auto-import / import-suggestions only work on gts files typed-ember/glint#692
  • Goto Definition only works in gts files (not gjs) typed-ember/glint#676
  • Glint doesn’t support multiple Typescript extends typed-ember/glint#672
  • provide completions for element tag names typed-ember/glint#667
  • *Like-bug: (ModifierLike, ComponentLike, etc?) When using WithBoundArgs, Type instantiation is excessively deep and possibly infinite (requiring glint-ignore/expect-error to move forward in a project) typed-ember/glint#661
  • --watch reports errors when normal build does not typed-ember/glint#649
  • {{#each-in}} breaks if used with a Map typed-ember/glint#645
  • Activate on gjs files typed-ember/glint#633
  • Import of .gts emits broken declarations typed-ember/glint#628
  • Quest: let's forward _all_ the ServerCapabilities to tsserver typed-ember/glint#626
  • Bug?: "Unclosed element pre, when <pre> is mentioned in test name of gts test file typed-ember/glint#617
  • Syntax error in tsconfig.json causes out-of-memory error typed-ember/glint#614
  • Use content-tag in @glint/environment-ember-template-imports typed-ember/glint#609
  • LSP Suggestions typed-ember/glint#604
  • glint --declaration fails to create declaration files when @glint-ignore, @glint-expect-error, or @glint-nocheck is used typed-ember/glint#599
  • @glint-expect-error cannot suppress errors from MustacheStatement in AttrNode  typed-ember/glint#589
  • Component helper with {{#let}} not playing well with components that accept and yield generics typed-ember/glint#575
  • VSCode completion after disabling the builtin typescript extension typed-ember/glint#506
  • "Go to symbol in editor" in Code does not work if built-in TS disabled typed-ember/glint#271
  • More autocompletion typed-ember/glint#121

Nice to have

• Make fn built-in in strict-mode rfcs#998
• Option to not clear the screen when in watch mode? typed-ember/glint#597
• Allow inline component signatures on first-class, template-only components typed-ember/glint#387

[Windvis]

Adding support for generating .gjs/.gts components is also one of the remaining todos. There is an open PR already: emberjs/ember.js#20511