Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Add new rule no-builtin-form-components #2990

Merged
merged 3 commits into from
Nov 21, 2023
Merged

Add new rule no-builtin-form-components #2990

Changes from 1 commit
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
4610195
Add rule no-builtin-form-components
gilest Nov 8, 2023
9edf1d6
Improve rule docs
gilest Nov 9, 2023
0f68434
Favour light one-way example in rule docs
gilest Nov 11, 2023
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Jump to
Jump to file
Failed to load files.
Diff view
Diff view
8 changes: 7 additions & 1 deletion docs/rule/no-builtin-form-components.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# no-builtin-form-components

Ember's built-in form components use two-way data binding, where the property as `@value` or `@checked` is mutated by user interaction. This goes against the Data Down Actions Up principle, goes against Glimmer Components’ intention to have immutable arguments, and is [discouraged by the Ember Core team](https://www.pzuraq.com/on-mut-and-2-way-binding/).
Ember's built-in form components use two-way data binding, where the property passed as `@value` or `@checked` is mutated by user interaction. This goes against the Data Down Actions Up principle, goes against Glimmer Components’ intention to have immutable arguments, and is [discouraged by the Ember Core team](https://www.pzuraq.com/on-mut-and-2-way-binding/).

## Examples

Expand All @@ -18,6 +18,8 @@ This rule **forbids** the following:

The migration path typically involves replacing the built-in form component with a native HTML element and binding an event listener to handle user input.

In the following example the initial value of a field is controlled by a local tracked property, which is updated by an event listener.

```js
import Component from '@glimmer/component';
import { tracked } from '@glimmer/tracking';
Expand Down Expand Up @@ -51,6 +53,8 @@ You may consider composing the [set helper](https://github.com/pzuraq/ember-set-
/>
```

Depending on your requirements, consider using form management patterns like the "light" [Form component from ember-primitives](https://ember-primitives.pages.dev/7-forms/1-intro) or the "controlled" [ember-headless-form](https://ember-headless-form.pages.dev/).
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

this isn't quite what I meant about adding. 😅

This is docs, for example -- also in the tutorial

I think we should show an "uncontrolled" example before the controlled example. I think it's important that folks see how to not write JavaScript before they reach for javascript.

I linked to ember-primitives as an example of the pattern, rather than intending for it to be directly linked. Apologies for not being more clear!

Copy link
Contributor Author

@gilest gilest Nov 11, 2023 •
edited

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Ahh yes. That makes a lot more sense 😅

FWIW I appreciate the resources you're creating and the modern improvements.

But we should have empathy for the frustrated engineer who is on the receiving end of lint errors, and try to give them a very clear explanation of the problem and how to solve it. Ideally without overloading them with other new ideas.

That's why I'm not using cell or the new component authoring format in the examples.

Anyway I had another run at it. Let me know your thoughts

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

FWIW I appreciate the resources you're creating and the modern improvements.

<3

other new ideas.

controlling every aspect of a form is actually the new idea -- the uncontrolled way is the very old way to do forms, it builds on the foundation of the platform and allows the developer to do less work.

Additionally, React has been trying to teach uncontrolled vs controlled forms for 5+ years! 💪

That's why I'm not using cell or the new component authoring format in the examples.

that's totally fine! the details are a means to the concept, and not actually important to the concept -- I think that's probably one thing people get too hung up on when learning new things. It's important to be able to adapt a concept in to your existing code, as not all documentation can match what your existing code is doing.

Anyway I had another run at it. Let me know your thoughts

will do, thanks a ton for working on this and being willing to have the back and forth!!

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

a means to the concept, and not actually important to the concept
can match what your existing code is doing.

which you've don't exactly! yay!


## Related Rules

* [no-mut-helper](no-mut-helper.md)
Expand All @@ -63,3 +67,5 @@ You may consider composing the [set helper](https://github.com/pzuraq/ember-set-
* [Native HTML `input`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/input)
* [Native HTML `textarea`](https://developer.mozilla.org/en-US/docs/Web/HTML/Element/textarea)
* [The `on` modifier](https://guides.emberjs.com/release/components/component-state-and-actions/#toc_html-modifiers-and-actions)
* [Form component – ember-primitives](https://ember-primitives.pages.dev/7-forms/1-intro)
* [ember-headless-form](https://ember-headless-form.pages.dev/)