-
Notifications
You must be signed in to change notification settings - Fork 235
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.
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
Add new rule no-builtin-form-components
#2990
Changes from 2 commits
File filter
Filter by extension
Conversations
Jump to
Diff view
Diff view
There are no files selected for viewing
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,71 @@ | ||
# no-builtin-form-components | ||
|
||
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 | ||
|
||
This rule **forbids** the following: | ||
|
||
```hbs | ||
<Input /> | ||
``` | ||
|
||
```hbs | ||
<Textarea></Textarea> | ||
``` | ||
|
||
## Migration | ||
|
||
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'; | ||
import { action } from '@ember/object'; | ||
|
||
export default class MyComponent extends Component { | ||
@tracked name; | ||
|
||
@action | ||
updateName(event) { | ||
this.name = event.target.value; | ||
} | ||
} | ||
``` | ||
|
||
```hbs | ||
<input | ||
type="text" | ||
value={{this.name}} | ||
{{on "input" this.updateName}} | ||
/> | ||
``` | ||
|
||
You may consider composing the [set helper](https://github.com/pzuraq/ember-set-helper) with the [pick helper](https://github.com/DockYard/ember-composable-helpers#pick) to avoid creating an action within a component class. | ||
|
||
```hbs | ||
<input | ||
type="text" | ||
value={{this.name}} | ||
{{on "input" (pick "target.value" (set this "name"))}} | ||
/> | ||
``` | ||
|
||
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/). | ||
There was a problem hiding this comment. Choose a reason for hiding this commentThe 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! There was a problem hiding this comment. Choose a reason for hiding this commentThe 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 Anyway I had another run at it. Let me know your thoughts There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
<3
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 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.
will do, thanks a ton for working on this and being willing to have the back and forth!! There was a problem hiding this comment. Choose a reason for hiding this commentThe reason will be displayed to describe this comment to others. Learn more.
which you've don't exactly! yay! |
||
|
||
## Related Rules | ||
|
||
* [no-mut-helper](no-mut-helper.md) | ||
|
||
## References | ||
|
||
* [Built-in components guides](https://guides.emberjs.com/release/components/built-in-components/) | ||
* [Built-in `Input` component API](https://api.emberjs.com/ember/release/classes/Ember.Templates.components/methods/Input?anchor=Input) | ||
* [Built-in `Textarea` component API](https://api.emberjs.com/ember/release/classes/Ember.Templates.components/methods/Textarea?anchor=Textarea) | ||
* [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/) |
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,25 @@ | ||
import Rule from './_base.js'; | ||
|
||
const WHY = 'Built-in form components use two-way binding to mutate values.'; | ||
const ACTION = 'Instead, refactor to use a native HTML element.'; | ||
export const MESSAGES = { | ||
Input: `Do not use the \`Input\` component. ${WHY} ${ACTION}`, | ||
Textarea: `Do not use the \`Textarea\` component. ${WHY} ${ACTION}`, | ||
}; | ||
|
||
const COMPONENTS = new Set(['Input', 'Textarea']); | ||
|
||
export default class NoBuiltinFormComponents extends Rule { | ||
visitor() { | ||
return { | ||
ElementNode(node) { | ||
if (COMPONENTS.has(node.tag)) { | ||
this.log({ | ||
message: MESSAGES[node.tag], | ||
node, | ||
}); | ||
} | ||
}, | ||
}; | ||
} | ||
} |
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -0,0 +1,61 @@ | ||
import generateRuleTests from '../../helpers/rule-test-harness.js'; | ||
|
||
generateRuleTests({ | ||
name: 'no-builtin-form-components', | ||
|
||
config: true, | ||
|
||
good: [ | ||
'<input type="text" />', | ||
'<input type="checkbox" />', | ||
'<input type="radio" />', | ||
'<textarea></textarea>', | ||
], | ||
|
||
bad: [ | ||
{ | ||
template: '<Input />', | ||
verifyResults(results) { | ||
expect({ results }).toMatchInlineSnapshot(` | ||
{ | ||
"results": [ | ||
{ | ||
"column": 0, | ||
"endColumn": 9, | ||
"endLine": 1, | ||
"filePath": "layout.hbs", | ||
"line": 1, | ||
"message": "Do not use the \`Input\` component. Built-in form components use two-way binding to mutate values. Instead, refactor to use a native HTML element.", | ||
"rule": "no-builtin-form-components", | ||
"severity": 2, | ||
"source": "<Input />", | ||
}, | ||
], | ||
} | ||
`); | ||
}, | ||
}, | ||
{ | ||
template: '<Textarea></Textarea>', | ||
verifyResults(results) { | ||
expect({ results }).toMatchInlineSnapshot(` | ||
{ | ||
"results": [ | ||
{ | ||
"column": 0, | ||
"endColumn": 21, | ||
"endLine": 1, | ||
"filePath": "layout.hbs", | ||
"line": 1, | ||
"message": "Do not use the \`Textarea\` component. Built-in form components use two-way binding to mutate values. Instead, refactor to use a native HTML element.", | ||
"rule": "no-builtin-form-components", | ||
"severity": 2, | ||
"source": "<Textarea></Textarea>", | ||
}, | ||
], | ||
} | ||
`); | ||
}, | ||
}, | ||
], | ||
}); |
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Both of these migration paths are for 'controlled inputs'
There is another migration path, too.
Which is faster, and involves less binding.
See:
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
True. I've seen some of this before but never used these patterns exactly. Not sure I understand them well enough make a concise recommendation.
How would you suggest the rule doc is structured?
We might:
Ideally the simplest explanation of how to fix this issue is early in this doc.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
Option 2 would be my preference.
You can copy from the above links 🎉
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
I've made minor changes to incorporate your recommendations.
To be frank the docs on the ember primitives page are not easy to follow and don't clearly explain the light/controlled concepts so I don't really want to copy that over to this rule doc.
I'd welcome specific suggestions from you, but I can't paraphrase what you want because it's a bit conceptual IMO 😅
For many cases they will be the ideal migration but I think keeping an example of a low-level migration without addons is valuable for users to understand the underlying change that is needed.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
can you open an issue on ember-primitives? docs should be easy to understand, and it's a bug that they're not https://github.com/universal-ember/ember-primitives/ thanks!!
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
You got it – universal-ember/ember-primitives#165