More docs

Author: NullVoxPopuli

docs/rules/template-no-action.md

@@ -47,6 +47,12 @@ Examples of **correct** code for this rule:
 - Replace `(action "methodName")` with method references or `(fn this.methodName)`
 - Replace `<button onclick={{action ...}}>` with `<button {{on "click" ...}}>`
 
+## Related Rules
+
+* [no-action-modifiers](template-no-action-modifiers.md)
+* [no-element-event-actions](template-no-element-event-actions.md)
+* [no-mut-helper](template-no-mut-helper.md)
+
 ## References
 
 - [eslint-plugin-ember template-no-action](https://github.com/ember-cli/eslint-plugin-ember/blob/master/docs/rules/template-no-action.md)

docs/rules/template-no-at-ember-render-modifiers.md

@@ -38,6 +38,31 @@ Examples of **correct** code for this rule:
 </template>
 ```
 
+## Migration
+
+The migration path typically depends on what the render-modifier was used for, but if you need a custom modifier, the [`ember-modifier` README](https://github.com/ember-modifier/ember-modifier) covers everything you need to know for making custom modifiers.
+
+For example, if render modifiers were used for setup/teardown, the migration to `ember-modifier` could be the following:
+
+```js
+import Component from '@glimmer/component';
+import { modifier } from 'ember-modifier';
+
+export default class MyComponent extends Component {
+  myModifier = modifier((element) => {
+    let handleEvent = () => {};
+
+    element.addEventListener('eventName', handleEvent);
+
+    return () => element.removeEventListener('eventName', handelEvent);
+  });
+}
+```
+
+```hbs
+<div {{this.myModifier}}>
+```
+
 ## References
 
 - [eslint-plugin-ember template-no-at-ember-render-modifiers](https://github.com/ember-cli/eslint-plugin-ember/blob/master/docs/rules/template-no-at-ember-render-modifiers.md)

docs/rules/template-no-block-params-for-html-elements.md

@@ -62,6 +62,10 @@ This rule disallows using block params on HTML elements. Use components if you n
 </template>
 ```
 
+## Migration
+
+- Remove the unused block parameters or fix the tag name to refer to a component
+
 ## Related Rules
 
 - [template-no-arguments-for-html-elements](./template-no-arguments-for-html-elements.md)

docs/rules/template-no-builtin-form-components.md

@@ -26,6 +26,67 @@ This rule **allows** the following:
 <template><textarea {{on "input" this.handleInput}}>{{this.body}}</textarea></template>
 ```
 
+## Migration
+
+Many forms may be simplified by switching to a light one-way data approach.
+
+For example – vanilla JavaScript has everything we need to handle form data, de-sync it from our source data and collect all user input in a single object.
+
+```js
+import Component from '@glimmer/component';
+import { tracked } from '@glimmer/tracking';
+import { action } from '@ember/object';
+
+export default class MyComponent extends Component {
+  @tracked userInput = {};
+
+  @action
+  handleInput(event) {
+    const formData = new FormData(event.currentTarget);
+    this.userInput = Object.fromEntries(formData.entries());
+  }
+}
+```
+
+```hbs
+<form {{on "input" this.handleInput}}>
+  <label> Name
+    <input name="name">
+  </label>
+</form>
+```
+
+Another option would is to "control" the field's value by 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}}
+/>
+```
+
+## Related Rules
+
+* [no-mut-helper](template-no-mut-helper.md)
+
 ## References
 
 - [Ember Built-in Components](https://guides.emberjs.com/release/components/built-in-components/)

docs/rules/template-no-chained-this.md

@@ -12,6 +12,16 @@ Using `this.this.*` in templates is almost always a typo or copy/paste mistake.
 
 This rule disallows `this.this.*` patterns in templates (e.g., `{{this.this.foo}}` or `<this.this.Bar />`).
 
+## Motivation
+
+Templates are meant to clearly reference local properties, arguments (`@arg`), or component state via `this`. When you see `this.this.foo`, it's either:
+
+- A typo (e.g., copy/paste or incorrect refactor)
+- A misunderstanding of Glimmer component boundaries
+- A misuse of dynamic component invocation (e.g., `<this.this.foo />`)
+
+These patterns often go unnoticed but produce confusing or broken runtime behavior.
+
 ## Examples
 
 ### Incorrect ❌

docs/rules/template-no-class-bindings.md

@@ -30,6 +30,10 @@ This rule **allows** the following:
 <template><SomeThing /></template>
 ```
 
+## Migration
+
+- find in templates and remove `classBinding` and/or `classNameBindings`.
+
 ## References
 
 - [ember-template-lint no-class-bindings](https://github.com/ember-template-lint/ember-template-lint/blob/master/docs/rule/no-class-bindings.md)

docs/rules/template-no-curly-component-invocation.md

@@ -46,6 +46,10 @@ This rule **allows** the following:
 <template><Nested::Component /></template>
 ```
 
+## Migration
+
+- use <https://github.com/ember-codemods/ember-angle-brackets-codemod>
+
 ## Configuration
 
 This rule accepts an options object with the following properties:

docs/rules/template-no-element-event-actions.md

@@ -44,6 +44,11 @@ Examples of **correct** code for this rule:
 | --------------------- | --------- | ------- | ----------------------------------------------------------------------------------------------------------------- |
 | `requireActionHelper` | `boolean` | `false` | When `true`, only flags events using `{{action ...}}`; when `false`, flags any dynamic value on event attributes. |
 
+## Related Rules
+
+* [no-action](template-no-action.md)
+* [no-action-modifiers](template-no-action-modifiers.md)
+
 ## References
 
 - [Ember Octane migration guide](https://guides.emberjs.com/release/upgrading/current-edition/action-on-and-fn/)

docs/rules/template-no-html-comments.md

@@ -34,3 +34,8 @@ Examples of **correct** code for this rule:
   <div>Content</div>
 </template>
 ```
+
+## References
+
+* [Ember guides/template features](https://guides.emberjs.com/release/components/#toc_supported-features)
+* [Handlebars docs/comments](https://handlebarsjs.com/guide/#template-comments)

docs/rules/template-no-implicit-this.md

@@ -8,6 +8,17 @@ Require explicit `this` for property access in templates to avoid ambiguity.
 
 This rule requires explicitly using `this.` prefix for component properties and `@` prefix for named arguments in templates, avoiding ambiguous property references.
 
+## Motivation
+
+Currently, the way to access properties on a components class is `{{greeting}}`
+from a template. This works because the component class is one of the objects
+we resolve against during the evaluation of the expression.
+
+The first problem with this approach is that the `{{greeting}}` syntax is
+ambiguous, as it could be referring to a local variable (block param), a helper
+with no arguments, a closed over component, or a property on the component
+class.
+
 ## Examples
 
 Examples of **incorrect** code for this rule:
@@ -42,6 +53,12 @@ Examples of **correct** code for this rule:
 </template>
 ```
 
+## Migration
+
+* use [ember-no-implicit-this-codemod](https://github.com/ember-codemods/ember-no-implicit-this-codemod)
+* [upgrade to Glimmer components](https://guides.emberjs.com/release/upgrading/current-edition/glimmer-components/), which don't allow ambiguous access
+  * classic components have [auto-reflection](https://github.com/emberjs/rfcs/blob/master/text/0276-named-args.md#motivation), and can use `this.myArgName` or `this.args.myArgNme` or `@myArgName` interchangeably
+
 ## References
 
 - [Ember Octane Guide - Templates](https://guides.emberjs.com/release/components/component-state-and-actions/)