From 2216eece66323f8cf1e909870dd9e68826f321fb Mon Sep 17 00:00:00 2001
From: Godfrey Chan <godfreykfc@gmail.com>
Date: Tue, 5 Mar 2019 19:49:55 -0800
Subject: [PATCH 1/7] Angle Bracket Invocations For Built-in Components

---
 .../0459-angle-bracket-built-in-components.md | 257 ++++++++++++++++++
 1 file changed, 257 insertions(+)
 create mode 100644 text/0459-angle-bracket-built-in-components.md

diff --git a/text/0459-angle-bracket-built-in-components.md b/text/0459-angle-bracket-built-in-components.md
new file mode 100644
index 0000000000..0514a13d76
--- /dev/null
+++ b/text/0459-angle-bracket-built-in-components.md
@@ -0,0 +1,257 @@
+- Start Date: 2019-03-05
+- Relevant Team(s): Ember.js
+- RFC PR: https://github.com/emberjs/rfcs/pull/459
+- Tracking: (leave this empty)
+
+# Angle Bracket Invocations For Built-in Components
+
+## Summary
+
+[RFC #311](./0311-angle-bracket-invocation.md) introduced the angle bracket
+component invocation syntax. Many developers in the Ember community has since
+adopted this feature with very positive feedback. This style of component
+invocation will beomce the default style in the Octane edition and become the
+primary way component invocations are taught.
+
+However, Ember ships with three built-in components – `{{link-to}}`, `{{input}}`
+and `{{textarea}}`. To date, it is not possible to invoke them with the angle
+bracket syntax due to various API mismatches and implementation details.
+
+This RFC proposes some small admenments to these APIs and their implementations
+to allow them to be invoked with the angle bracket syntax, i.e. `<LinkTo>`,
+`<Input>` and `<TextArea>`.
+
+## Motivation
+
+As mentioned above, this will allow Ember developers to invoke components with
+a consistent syntax, which should make it easier to teach.
+
+This RFC _does not_ aim to "fix" issues or quirks with the existing APIs – it
+merely attempts to provide a way to do the equivilant invocation in angle
+bracket syntax.
+
+## Detailed design
+
+### `<LinkTo>`
+
+There are two main problem with `{{link-to}}`:
+
+* It uses positional arguments as the main API.
+* It supports an "inline" form (i.e. without a block).
+
+In the new world, components are expected to work with named arguments. This is
+both to improve clarity and to match the HTML tags model (which angle bracket
+invocations are loosely modelled after). Positional arguments are reserved for
+"control-flow-like" components (e.g. `liquid-if`) and to be paired with the
+curly bracket invocation style. Since links are not that, it is not appropiate
+for this component to use positional params.
+
+When invoked with a block, the first argument is the route to navigate to. We
+propose to name this argument explicitly, with `@route`:
+
+```hbs
+{{#link-to "about"}}About Us{{/link-to}}
+
+...becomes...
+
+<LinkTo @route="about">About Us</LinkTo>
+```
+
+The second argument can be used to provide a model to the route. We propose to
+name this argument explicitly, with `@model`:
+
+```hbs
+{{#let this.model.posts.firstObject as |post|}}
+
+  {{#link-to "post" post}}Read {{post.title}}...{{/link-to}}
+
+  ...becomes...
+
+  <LinkTo @route="post" @model={{post}}>Read {{post.title}}...</LinkTo>
+
+{{/let}}
+```
+
+In fact, it is possible to pass multiple models to deeply nested routes with
+additional positional arguments. For this use case, we propose the `@models`
+named argument which accepts an array:
+
+```hbs
+{{#let this.model.posts.firstObject as |post|}}
+  {{#each post.comments as |comment|}}
+
+    {{#link-to "post.comment" post comment}}
+      Comment by {{comment.author.name}} on {{comment.date}}
+    {{/link-to}}
+
+    ...becomes...
+
+    <LinkTo @route="post.comment" @models={{array post comment}}>
+      Comment by {{comment.author.name}} on {{comment.date}}
+    </LinkTo>
+
+  {{/each}}
+{{/let}}
+```
+
+The singular `@model` argument is a special case of `@models`, provided as a
+convenience for the common case. Passing both `@model` and `@models` will be an
+error. (So would passing insufficient amount of models for the given route, as
+it already is today.)
+
+It is also possible to pass query params to the `{{link-to}}` component with
+the somewhat awkward `(query-params)` API. We propose to replace it with a
+`@query` named argument that simply take a regular hash (or POJO):
+
+```hbs
+{{#link-to "posts" (query-params direction="desc" showArchived=false)}}
+  Recent Posts
+{{/link-to}}
+
+...becomes...
+
+<LinkTo @route="posts" @query={{hash direction="desc" showArchived=false}}>
+  Recent Posts
+</LinkTo>
+```
+
+Finally, as mentioned above, `{{link-to}}` supports an "inline" form without a
+block. This form doesn't bring much value and used to cause confusion around
+the ordering of the arguments. We propose to simply not support this for the
+angle bracket invocation style:
+
+```hbs
+{{link-to "About Us" "about"}}
+
+...becomes...
+
+<LinkTo @route="about">About Us</LinkTo>
+```
+
+Other APIs of this compoment are already based on named arguments.
+
+#### Migration Path
+
+We would provide a codemod to convert the old invocation style into the new
+style.
+
+#### Deprecations
+
+Even though the angle bracket invocation style is recommended going forward
+(and should be enforced via a template lint), components can generally be
+invoked using the either the curly or angle bracket syntax. Therefore, while
+not recommended, `{{link-to}}` would still work and invoke the same component.
+
+In the case that the curly invocation style is used, we propose to issue the
+following deprecation warnings:
+
+* Passing positional arguments to `{{link-to}}` (pass named arguments instead)
+* Using the inline form of `{{link-to}}` (use the block form instead)
+* The `query-params` helper (pass a hash/POJO to the `query` argument instead)
+
+### `<Input>`
+
+Today, the `{{input}}` component is internally implemented as several internal
+components that are selected based on the `type` argument. This is intended as
+an internal implmentation detail, but as a result, it is not possible to invoke
+the component with `<Input>` since it does not exist as a "real" component.
+
+We propose to change this internal implementation strategry to make it possible
+to invoke this with angle brackets just like any other components.
+
+For example:
+
+```hbs
+{{input type="text" value=this.model.name}}
+
+...becomes...
+
+<Input @type="text" @value={{this.model.name}} />
+```
+
+Another example:
+
+```hbs
+{{input type="checkbox" name="email-opt-in" checked=this.model.emailPreference}}
+
+...becomes...
+
+<Input @type="checkbox" @name="email-opt-in" @checked={{this.model.emailPreference}} />
+```
+
+#### Migration Path
+
+We would provide a codemod to convert the old invocation style into the new
+style.
+
+#### Deprecations
+
+None.
+
+### `<TextArea>`
+
+Due to a similar implementation issue, it is also not possible to invoke the
+`{{textarea}}` component with angle bracket invocation style.
+
+We propose to change this internal implementation strategry to make it possible
+to invoke this with angle brackets just like any other components. However, to
+align with the name used in [RFC #176](./0176-javascript-module-api.md), we
+propose to take this opportunity to rename the component into `<TextArea>` (as
+opposed to `<Textarea>`).
+
+For example:
+
+```hbs
+{{textarea value=this.model.body}}
+
+...becomes...
+
+<TextArea @value={{this.model.body}} />
+```
+
+#### Migration Path
+
+We would provide a codemod to convert the old invocation style into the new
+style.
+
+#### Deprecations
+
+To prevent surprises, `<Textarea>` will also invoke the same component but with
+a deprecation warning (use `<TextArea>` instead).
+
+## How we teach this
+
+Going forward, we will focus on teaching the angle bracket invocation style as
+the main (only?) way of invoking components. In that world, there wouldn't be
+anything extra to teach, as the invocation style proposed in this RFC is not
+different from any other components, which is the purpose of this proposal. Of
+course, the APIs of these components will still need to be taught, but that is
+not a new change.
+
+The only caveat is that, since the advanced `<LinkTo>` APIs require passing
+arrays and hashes, the `{{array}}` and `{{hash}}` helper would have to be
+taught before those advanced features can be introduced. However, since the
+basic usage (linking to top-level routes) does not require either of those
+helpers, it doesn't really affect things from a getting started perspective.
+
+It should also be mentioned that, other built-ins, such as `{{yield}}`,
+`{{outlet}}`, `{{mount}}`, etc are considered "keywords" not components, they
+are also "control-flow-like", so it wouldn't be appropiate to invoke them with
+angle brackets.
+
+## Drawbacks
+
+None.
+
+## Alternatives
+
+* `<LinkTo>` could only support `@models` without special casing `@model` as a
+  convenience.
+
+* `<LinkTo>` could support a `@text` argument for inline usage.
+
+* `<TextArea>` could just be named `<Textarea>`.
+
+## Unresolved questions
+
+None.

From f3b245329e8d4c6c0d96c637602128905199963a Mon Sep 17 00:00:00 2001
From: Robert Jackson <me@rwjblue.com>
Date: Wed, 6 Mar 2019 12:46:02 -0800
Subject: [PATCH 2/7] Update text/0459-angle-bracket-built-in-components.md

Co-Authored-By: chancancode <godfreykfc@gmail.com>
---
 text/0459-angle-bracket-built-in-components.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/text/0459-angle-bracket-built-in-components.md b/text/0459-angle-bracket-built-in-components.md
index 0514a13d76..6d80dc3042 100644
--- a/text/0459-angle-bracket-built-in-components.md
+++ b/text/0459-angle-bracket-built-in-components.md
@@ -17,7 +17,7 @@ However, Ember ships with three built-in components – `{{link-to}}`, `{{input}
 and `{{textarea}}`. To date, it is not possible to invoke them with the angle
 bracket syntax due to various API mismatches and implementation details.
 
-This RFC proposes some small admenments to these APIs and their implementations
+This RFC proposes some small amendments to these APIs and their implementations
 to allow them to be invoked with the angle bracket syntax, i.e. `<LinkTo>`,
 `<Input>` and `<TextArea>`.
 

From d60495f6e6d9a3711af624f9c575d94f265658eb Mon Sep 17 00:00:00 2001
From: Robert Jackson <me@rwjblue.com>
Date: Wed, 6 Mar 2019 12:46:08 -0800
Subject: [PATCH 3/7] Update text/0459-angle-bracket-built-in-components.md

Co-Authored-By: chancancode <godfreykfc@gmail.com>
---
 text/0459-angle-bracket-built-in-components.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/text/0459-angle-bracket-built-in-components.md b/text/0459-angle-bracket-built-in-components.md
index 6d80dc3042..55080f08ef 100644
--- a/text/0459-angle-bracket-built-in-components.md
+++ b/text/0459-angle-bracket-built-in-components.md
@@ -156,7 +156,7 @@ components that are selected based on the `type` argument. This is intended as
 an internal implmentation detail, but as a result, it is not possible to invoke
 the component with `<Input>` since it does not exist as a "real" component.
 
-We propose to change this internal implementation strategry to make it possible
+We propose to change this internal implementation strategy to make it possible
 to invoke this with angle brackets just like any other components.
 
 For example:

From d3a0e4d4ca21aa7742771a9483c26fbf6503b083 Mon Sep 17 00:00:00 2001
From: Godfrey Chan <godfreykfc@gmail.com>
Date: Wed, 6 Mar 2019 13:58:34 -0800
Subject: [PATCH 4/7] typo

---
 text/0459-angle-bracket-built-in-components.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/text/0459-angle-bracket-built-in-components.md b/text/0459-angle-bracket-built-in-components.md
index 55080f08ef..1d42b5ef08 100644
--- a/text/0459-angle-bracket-built-in-components.md
+++ b/text/0459-angle-bracket-built-in-components.md
@@ -193,7 +193,7 @@ None.
 Due to a similar implementation issue, it is also not possible to invoke the
 `{{textarea}}` component with angle bracket invocation style.
 
-We propose to change this internal implementation strategry to make it possible
+We propose to change this internal implementation strategy to make it possible
 to invoke this with angle brackets just like any other components. However, to
 align with the name used in [RFC #176](./0176-javascript-module-api.md), we
 propose to take this opportunity to rename the component into `<TextArea>` (as

From 9abd68dd9c0d6195991890f91d7261b3fc54dae0 Mon Sep 17 00:00:00 2001
From: Godfrey Chan <godfreykfc@gmail.com>
Date: Fri, 8 Mar 2019 16:11:36 -0800
Subject: [PATCH 5/7] framework core team feedback

---
 .../0459-angle-bracket-built-in-components.md | 57 +++++++++++--------
 1 file changed, 33 insertions(+), 24 deletions(-)

diff --git a/text/0459-angle-bracket-built-in-components.md b/text/0459-angle-bracket-built-in-components.md
index 1d42b5ef08..b1afa68bed 100644
--- a/text/0459-angle-bracket-built-in-components.md
+++ b/text/0459-angle-bracket-built-in-components.md
@@ -19,7 +19,7 @@ bracket syntax due to various API mismatches and implementation details.
 
 This RFC proposes some small amendments to these APIs and their implementations
 to allow them to be invoked with the angle bracket syntax, i.e. `<LinkTo>`,
-`<Input>` and `<TextArea>`.
+`<Input>` and `<Textarea>`.
 
 ## Motivation
 
@@ -135,19 +135,15 @@ Other APIs of this compoment are already based on named arguments.
 We would provide a codemod to convert the old invocation style into the new
 style.
 
-#### Deprecations
+#### Template Lints
 
-Even though the angle bracket invocation style is recommended going forward
-(and should be enforced via a template lint), components can generally be
-invoked using the either the curly or angle bracket syntax. Therefore, while
-not recommended, `{{link-to}}` would still work and invoke the same component.
+Even though the angle bracket invocation style is recommended going forward,
+components can generally be invoked using the either the curly or angle bracket
+syntax. Therefore, while not recommended, `{{link-to}}` would still work and
+invoke the same component.
 
-In the case that the curly invocation style is used, we propose to issue the
-following deprecation warnings:
-
-* Passing positional arguments to `{{link-to}}` (pass named arguments instead)
-* Using the inline form of `{{link-to}}` (use the block form instead)
-* The `query-params` helper (pass a hash/POJO to the `query` argument instead)
+We propose to add template lint rules to using this component with the curly
+invocation style.
 
 ### `<Input>`
 
@@ -184,20 +180,23 @@ Another example:
 We would provide a codemod to convert the old invocation style into the new
 style.
 
-#### Deprecations
+#### Template Lints
 
-None.
+Even though the angle bracket invocation style is recommended going forward,
+components can generally be invoked using the either the curly or angle bracket
+syntax. Therefore, while not recommended, `{{input}}` would still work and
+invoke the same component.
+
+We propose to add template lint rules to using this component with the curly
+invocation style.
 
-### `<TextArea>`
+### `<Textarea>`
 
 Due to a similar implementation issue, it is also not possible to invoke the
 `{{textarea}}` component with angle bracket invocation style.
 
 We propose to change this internal implementation strategy to make it possible
-to invoke this with angle brackets just like any other components. However, to
-align with the name used in [RFC #176](./0176-javascript-module-api.md), we
-propose to take this opportunity to rename the component into `<TextArea>` (as
-opposed to `<Textarea>`).
+to invoke this with angle brackets just like any other components.
 
 For example:
 
@@ -206,7 +205,7 @@ For example:
 
 ...becomes...
 
-<TextArea @value={{this.model.body}} />
+<Textarea @value={{this.model.body}} />
 ```
 
 #### Migration Path
@@ -214,10 +213,20 @@ For example:
 We would provide a codemod to convert the old invocation style into the new
 style.
 
-#### Deprecations
+[RFC #176](./0176-javascript-module-api.md) picked `text-area`/`TextArea` for
+this component. To prevent confusion, we will add a helpful hint to the error
+message ("did you mean `<Textarea>`?") when a user mistakenly typed
+`{{text-area}}` or `<TextArea>` in development mode.
+
+#### Template Lints
+
+Even though the angle bracket invocation style is recommended going forward,
+components can generally be invoked using the either the curly or angle bracket
+syntax. Therefore, while not recommended, `{{textarea}}` would still work and
+invoke the same component.
 
-To prevent surprises, `<Textarea>` will also invoke the same component but with
-a deprecation warning (use `<TextArea>` instead).
+We propose to add template lint rules to using this component with the curly
+invocation style.
 
 ## How we teach this
 
@@ -250,7 +259,7 @@ None.
 
 * `<LinkTo>` could support a `@text` argument for inline usage.
 
-* `<TextArea>` could just be named `<Textarea>`.
+* `<Textarea>` could be named `<TextArea>`.
 
 ## Unresolved questions
 

From 0ebfbb3f070f48398063c6d6c9636b9bd050b50f Mon Sep 17 00:00:00 2001
From: Ricardo Mendes <rokusu@gmail.com>
Date: Sat, 9 Mar 2019 10:35:43 +0000
Subject: [PATCH 6/7] Update 0459-angle-bracket-built-in-components.md

---
 text/0459-angle-bracket-built-in-components.md | 16 ++++++++--------
 1 file changed, 8 insertions(+), 8 deletions(-)

diff --git a/text/0459-angle-bracket-built-in-components.md b/text/0459-angle-bracket-built-in-components.md
index b1afa68bed..46dfad86e1 100644
--- a/text/0459-angle-bracket-built-in-components.md
+++ b/text/0459-angle-bracket-built-in-components.md
@@ -8,9 +8,9 @@
 ## Summary
 
 [RFC #311](./0311-angle-bracket-invocation.md) introduced the angle bracket
-component invocation syntax. Many developers in the Ember community has since
+component invocation syntax. Many developers in the Ember community have since
 adopted this feature with very positive feedback. This style of component
-invocation will beomce the default style in the Octane edition and become the
+invocation will become the default style in the Octane edition and become the
 primary way component invocations are taught.
 
 However, Ember ships with three built-in components – `{{link-to}}`, `{{input}}`
@@ -27,7 +27,7 @@ As mentioned above, this will allow Ember developers to invoke components with
 a consistent syntax, which should make it easier to teach.
 
 This RFC _does not_ aim to "fix" issues or quirks with the existing APIs – it
-merely attempts to provide a way to do the equivilant invocation in angle
+merely attempts to provide a way to do the equivalent invocation in angle
 bracket syntax.
 
 ## Detailed design
@@ -96,8 +96,8 @@ named argument which accepts an array:
 
 The singular `@model` argument is a special case of `@models`, provided as a
 convenience for the common case. Passing both `@model` and `@models` will be an
-error. (So would passing insufficient amount of models for the given route, as
-it already is today.)
+error. Passing insufficient amount of models for the given route, will continue
+to be an error.
 
 It is also possible to pass query params to the `{{link-to}}` component with
 the somewhat awkward `(query-params)` API. We propose to replace it with a
@@ -116,7 +116,7 @@ the somewhat awkward `(query-params)` API. We propose to replace it with a
 ```
 
 Finally, as mentioned above, `{{link-to}}` supports an "inline" form without a
-block. This form doesn't bring much value and used to cause confusion around
+block. This form doesn't bring much value and causes confusion around
 the ordering of the arguments. We propose to simply not support this for the
 angle bracket invocation style:
 
@@ -149,11 +149,11 @@ invocation style.
 
 Today, the `{{input}}` component is internally implemented as several internal
 components that are selected based on the `type` argument. This is intended as
-an internal implmentation detail, but as a result, it is not possible to invoke
+an internal implementation detail, but as a result, it is not possible to invoke
 the component with `<Input>` since it does not exist as a "real" component.
 
 We propose to change this internal implementation strategy to make it possible
-to invoke this with angle brackets just like any other components.
+to invoke it with angle brackets just like any other components.
 
 For example:
 

From 32a25b31d67d67bc7581dd0bead559063b06f076 Mon Sep 17 00:00:00 2001
From: Jen Weber <weberj10@gmail.com>
Date: Tue, 12 Mar 2019 14:52:37 -0700
Subject: [PATCH 7/7] Update text/0459-angle-bracket-built-in-components.md

Co-Authored-By: chancancode <godfreykfc@gmail.com>
---
 text/0459-angle-bracket-built-in-components.md | 3 +++
 1 file changed, 3 insertions(+)

diff --git a/text/0459-angle-bracket-built-in-components.md b/text/0459-angle-bracket-built-in-components.md
index 46dfad86e1..2d5969f6af 100644
--- a/text/0459-angle-bracket-built-in-components.md
+++ b/text/0459-angle-bracket-built-in-components.md
@@ -248,6 +248,9 @@ It should also be mentioned that, other built-ins, such as `{{yield}}`,
 are also "control-flow-like", so it wouldn't be appropiate to invoke them with
 angle brackets.
 
+The technical implementation of this RFC will need to be accompanied by changes to the API docs for the built-in template helpers, [link-to](https://emberjs.com/api/ember/3.8/classes/Ember.Templates.helpers/methods/link-to?anchor=link-to) and [input](https://emberjs.com/api/ember/3.8/classes/Ember.Templates.helpers/methods/input?anchor=input). In keeping with past decisions for Angle Brackets, the API docs should show both curly and Angle Bracket invocations of these helpers. The API docs are expected to show the full supported API surface of Ember.
+
+`link-to` and `input` are used liberally throughout the Ember.js Guides, Tutorial, and `super-rentals` [sample app](https://github.com/ember-learn/super-rentals), so those examples will need to be updated. In the Guides, we want to show solely Angle Brackets invocation. The [syntax conversion guide](https://guides.emberjs.com/release/reference/syntax-conversion-guide/) should be revised to include these helpers.
 ## Drawbacks
 
 None.