diff --git a/text/0000-angle-bracket-invocation.md b/text/0000-angle-bracket-invocation.md new file mode 100644 index 0000000000..d5220b4b93 --- /dev/null +++ b/text/0000-angle-bracket-invocation.md @@ -0,0 +1,367 @@ +- Start Date: 2018-03-09 +- RFC PR: (leave this empty) +- Ember Issue: (leave this empty) + +# Angle Bracket Invocation + +## Summary + +This RFC introduces an alternative syntax to invoke components in templates. + +Examples using the classic invocation syntax: + +```hbs +{{site-header user=this.user class=(if this.user.isAdmin "admin")}} + +{{#super-select selected=this.user.country as |s|}} + {{#each this.availableCountries as |country|}} + {{#s.option value=country}}{{country.name}}{{/s.option}} + {{/each}} +{{/super-select}} +``` + +Examples using the angle bracket invocation syntax: + +```hbs + + + + {{#each this.availableCountries as |country|}} + + {{/each}} + +``` + +## Motivation + +The original [angle bracket components](https://github.com/emberjs/rfcs/pull/60) +RFC focused on capitalizing on the opportunity of switching to the new syntax +as an opt-in to the "new-world" components programming model. + +Since then, we have switched to a more iterative approach, favoring smaller +RFCs focusing on one area of improvment at a time. Collectively, these RFCs +have largely accomplished the goals in the original RFC without the angle +bracket opt-in. + +Still, separate from other programming model improvements, there is still a +strong desire from the Ember community for the previously proposed angle +bracket invocation syntax. + +The main advantage of the angle bracket syntax is clarity. Because component +invocation are often encapsulating important pieces of UI, a dedicated syntax +would help visually distinguish them from other handlebars constructs, such as +control flow and dynamic values. This can be seen in the example shown above – +the angle bracket syntax made it very easy to see the component invocations as +well as the `{{#each}}` loop, especially with syntax highlight: + +```hbs + + {{#each this.availableCountries as |country|}} + + {{/each}} + +``` + +This RFC proposes that we adopt the angle bracket invocation syntax to Ember as +an alternative to the classic ("curlies") invocation syntax. + +Unlike the original RFC, the angle bracket invocation syntax proposed here is +purely syntatical and does not affect the semantics. The invocation style is +largely transparent to the invokee and can be used to invoke both classic +components as well as [custom components](https://github.com/emberjs/rfcs/pull/213). + +Since the original angle bracket RFC, we have worked on a few experimental +implementation of the feature, both and in Ember and Glimmer. These experiments +allowed us to attempt using the feature in real apps, and we have learned some +valuable insights throught these usage. + +The original RFC proposed using the `` syntax, which is the same +syntax used by web components (custom elements). While Ember components and web +components share a few similarities, in practice, we find that there are enough +differences that causes the overload to be quite confusing for developers. + +In addition, the code needed to render Ember components is quite different +from what is needed to render web components. If they share the same syntax, +the Glimmer template compiler will not be able to differentiate between the two +at build time, thus requiring a lot of extra runtime code to support the +"fallback" scenario. + +In conclusion, the ideal syntax should be similar to HTML syntax so it doesn't +feel out of place, but different enough that developers and the compiler can +easier tell that they are not just regular HTML elements at a glance. + +## Detailed design + +### Tag Name + +The first part of the angle bracket invocation syntax is the tag name. While +web components use the "dash rule" to distinguish from regular HTML elements, +we propose to use capital letters to distinguish Ember components from regular +HTML elements and web components. + +The invocation `` is equivalent to `{{foo-bar}}`. The tag name will +be normalized using the `dasherize` function, which is the same rules used by +existing use cases, such as service injections. This allows existing components +to be invoked by the new syntax. + +Another benefit of the capital letter rule is that we can now support component +names with a single word, such as `