First-Class Component Templates #779

chriskrycho · 2021-12-03T17:54:56Z

Summary

Adopt <template> tags as a format for making component templates first-class participants in JavaScript and TypeScript with strict mode template semantics. In support of the new syntax, adopt new custom JavaScript and TypeScript files with the extensions .gjs and .gts respectively.

First-class component templates address a number of pain points in today’s component authoring world, and provide a number of new capabilities to Ember and Glimmer users:

accessing local JavaScript values with no ceremony and no backing class, enabling much easier use of existing JavaScript ecosystem tools, including especially styling libraries—standard CSS Modules will “just work,” for example
authoring more than one component in a single file, where colocation makes sense—and thereby providing more control over a component’s public API
likewise authoring locally-scoped helpers, modifiers, and other JavaScript functionality

First-class component templates offer these new capabilities while not only maintaining but improving Ember’s long-standing commitment to integrated testing, in that it allows app and test code to share a single authoring paradigm—substantially simplifying our teaching story. Similarly, it preserves Ember’s long-standing commitment to treating JavaScript and HTML (and CSS!) as distinctive concerns which, however closely related, are not the same.

Full-fledged example showing how this might work in practice

Two notes:

For this and all the examples in the RFC, I assume RFC #0757: Default Modifier Manager for simplicity, but it does not meaningfully change this proposal.
The syntax highlighting here is a mess… but that's because GitHub still doesn't have good highlighting for decorators. Samples which have <template> but not @tracked actually already highlight decently well.

import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';

const Greet = <template>
  <p>Hello, {{@name}}!</p>
</template>

class SetUsername extends Component {
  @tracked name = '';

  updateName = ({ target: { value } }) => {
    this.name = value;
  }

  saveName = (submitEvent) => {
    submitEvent.preventDefault();
    this.args.onSaveName(this.name);
  };

  <template>
    <form {{on "submit" this.saveName}}>
      <label for='name'>Set username:</label>
      <input
        id='name'
        value={{this.value}}
        {{on "input" this.updateName}}
      />
      <button type='submit' disabled={{eq this.value.length 0}}>
        Generate
      </button>
    </form>
  </template>
}

function replaceLocation(el, { with: newUrl }) {
  el.contentWindow.location.replace(newUrl);
}

export default class GenerateAvatar extends Component {
  @tracked name = "";

  get previewUrl() {
    return `http://www.example.com/avatars/${name}`;
  }

  updateName = (newName) => {
    this.name = newName;
  };

  <template>
    <Greet @name={{this.name}} />
    <SetUsername
      @name={{this.name}}
      @onSaveName={{this.updateName}}
    />
    
    {{#if (gt 0 this.name.length)}}
      <iframe
        title='Preview'
        {{replaceLocation with=this.previewUrl}}
      >
    {{/if}}
  </template>
}

A note on the discussion

Before arguing for an alternative syntax, please take the time to read the ~16,000 words of careful, detailed analysis I provided about the tradeoffs of the alternatives designs in this space: Ember Template Imports. I spent an enormous amount of time working through that so that we can have a useful discussion here; please show me the respect of doing the same! If it seems to me from your comments that you have not read or understood those posts, I will direct you to them so that the conversation can be profitable!

Thanks

The words in this RFC are mine, and therefore so are any typos, infelicitous wording, or mistakes—but the best parts of this are the result of years of conversation (and occasional friendly argument!) with @pzuraq, @dfreeman, @jamescdavis, and @rwjblue. Special credit is due to @pzuraq for proving out the tooling considerations and building ember-template-imports, and for continually discussing this with me and many others over the past few years.

gabrielcsapo · 2021-12-03T23:56:11Z