Fix docs

Author: NullVoxPopuli

docs/rules/template-attribute-indentation.md

@@ -52,13 +52,13 @@ HTML element (> 80 characters):
 
 Examples of **correct** code for this rule:
 
-Non-block form:
+Non-block form (attributes on separate lines):
 
 ```hbs
 {{employee-details firstName=firstName lastName=lastName age=age avatarUrl=avatarUrl}}
 ```
 
-Block form:
+Block form (attributes on separate lines):
 
 ```hbs
 {{#employee-details
@@ -69,7 +69,7 @@ Block form:
 {{/employee-details}}
 ```
 
-HTML element:
+HTML element (attributes on separate lines):
 
 ```hbs
 <input disabled id='firstName' value={{firstName}} class='input-field first-name' type='text' />

docs/rules/template-block-indentation.md

@@ -38,8 +38,7 @@ Examples of **incorrect** code for this rule:
 
 ```hbs
 <div>
-  <p>{{t 'Stuff here!'}}</p>
-</div>
+  <p>{{t 'Stuff here!'}}</p></div>
 ```
 
 Examples of **correct** code for this rule:

docs/rules/template-modifier-name-case.md

@@ -20,10 +20,6 @@ This rule **forbids** the following:
 <template><div {{onFocus}}></div></template>
 ```
 
-```gjs
-<template><div {{modifier 'didInsert'}}></div></template>
-```
-
 This rule **allows** the following:
 
 ```gjs
@@ -34,10 +30,6 @@ This rule **allows** the following:
 <template><div {{on-focus}}></div></template>
 ```
 
-```gjs
-<template><div {{modifier 'did-insert'}}></div></template>
-```
-
 ## See Also
 
 - [named-functions-in-promises](named-functions-in-promises.md)

docs/rules/template-no-bare-strings.md

@@ -13,8 +13,8 @@ This rule disallows text content in templates that isn't wrapped in a translatio
 The following are allowed:
 
 - Whitespace-only strings
-- Strings containing only numbers and punctuation
-- Strings in an allowlist (configurable)
+- Strings in the default allowlist (punctuation characters like `(`, `)`, `.`, `&`, etc.)
+- Strings in a custom allowlist (configurable)
 
 ## Examples
 
@@ -52,12 +52,6 @@ Examples of **correct** code for this rule:
 </template>
 ```
 
-```gjs
-<template>
-  <div>123</div>
-</template>
-```
-
 ```gjs
 <template>
   <div>   </div>

docs/rules/template-no-empty-headings.md

@@ -11,37 +11,37 @@ Disallow headings (h1, h2, etc.) with no accessible text content.
 This rule **forbids** the following:
 
 ```gjs
-<template><h*></h*></template>
+<template><h1></h1></template>
 ```
 
 ```gjs
 <template><div role='heading' aria-level='1'></div></template>
 ```
 
 ```gjs
-<template><h*><span aria-hidden='true'>Inaccessible text</span></h*></template>
+<template><h2><span aria-hidden='true'>Inaccessible text</span></h2></template>
 ```
 
 This rule **allows** the following:
 
 ```gjs
-<template><h*>Heading Content</h*></template>
+<template><h1>Heading Content</h1></template>
 ```
 
 ```gjs
-<template><h*><span>Text</span><h*></template>
+<template><h2><span>Text</span></h2></template>
 ```
 
 ```gjs
 <template><div role='heading' aria-level='1'>Heading Content</div></template>
 ```
 
 ```gjs
-<template><h* aria-hidden='true'>Heading Content</h*></template>
+<template><h3 aria-hidden='true'>Heading Content</h3></template>
 ```
 
 ```gjs
-<template><h* hidden>Heading Content</h*></template>
+<template><h1 hidden>Heading Content</h1></template>
 ```
 
 ## Migration

docs/rules/template-no-mut-helper.md

@@ -70,7 +70,7 @@ the lint violations.
 ```
 
 ```hbs
-<Input @value={{this.name}} @onChange={{fn (mut this 'name')}} />
+<Input @value={{this.name}} @onChange={{fn this.updateName}} />
 ```
 
 ```hbs

docs/rules/template-no-nested-landmark.md

@@ -2,13 +2,13 @@
 
 <!-- end auto-generated rule header -->
 
-Disallows nested landmark elements.
+Disallows nesting landmark elements of the same type.
 
-Landmark elements should not be nested within other landmarks. This creates confusion for screen reader users navigating by landmarks.
+Landmark elements should not be nested within other landmarks of the same name. This creates confusion for screen reader users navigating by landmarks.
 
 ## Rule Details
 
-This rule disallows nesting landmark elements or roles within other landmark elements or roles.
+This rule disallows nesting landmark elements or roles within other landmark elements or roles of the same type.
 
 Landmark elements include:
 
@@ -38,23 +38,23 @@ Examples of **incorrect** code for this rule:
 ```gjs
 <template>
   <nav>
-    <main>Content</main>
+    <nav>Nested navigation</nav>
   </nav>
 </template>
 ```
 
 ```gjs
 <template>
   <main>
-    <nav>Navigation</nav>
+    <main>Nested main</main>
   </main>
 </template>
 ```
 
 ```gjs
 <template>
-  <div role="main">
-    <div role="navigation">Nav</div>
+  <div role="navigation">
+    <nav>Nested nav</nav>
   </div>
 </template>
 ```
@@ -70,10 +70,9 @@ Examples of **correct** code for this rule:
 
 ```gjs
 <template>
-  <div>
-    <nav>Nav 1</nav>
-    <nav>Nav 2</nav>
-  </div>
+  <main>
+    <nav>Navigation inside main</nav>
+  </main>
 </template>
 ```
 

docs/rules/template-no-nested-splattributes.md

@@ -4,42 +4,34 @@
 
 Disallow nested `...attributes` usage.
 
-The `...attributes` syntax is used to pass HTML attributes to components. It should only be used on the top-level element of a component template, not on nested elements. Using it on nested elements can lead to unexpected behavior and makes it unclear which element receives the attributes.
+Having `...attributes` on multiple elements nested within each other in a component can cause unintended results. This rule prevents `...attributes` on an element if any of its parent elements already has `...attributes`.
 
 ## Rule Details
 
-This rule disallows using `...attributes` on nested elements within a template.
+This rule disallows `...attributes` on an element when an ancestor element already has `...attributes`.
 
 ## Examples
 
 ### Incorrect ❌
 
 ```gjs
 <template>
-  <div>
+  <div ...attributes>
     <span ...attributes>Text</span>
   </div>
 </template>
 ```
 
 ```gjs
 <template>
-  <section>
+  <section ...attributes>
     <div>
       <button ...attributes>Click</button>
     </div>
   </section>
 </template>
 ```
 
-```gjs
-<template>
-  <div class="wrapper">
-    <input ...attributes />
-  </div>
-</template>
-```
-
 ### Correct ✅
 
 ```gjs
@@ -50,13 +42,16 @@ This rule disallows using `...attributes` on nested elements within a template.
 
 ```gjs
 <template>
-  <button ...attributes>Click</button>
+  <div ...attributes>
+    <span>Text</span>
+  </div>
 </template>
 ```
 
 ```gjs
 <template>
-  <MyComponent ...attributes />
+  <div ...attributes>first</div>
+  <div ...attributes>second</div>
 </template>
 ```
 

docs/rules/template-no-pointer-down-event-binding.md

@@ -2,13 +2,13 @@
 
 <!-- end auto-generated rule header -->
 
-Disallows pointer down event bindings.
+Disallows pointer down and mouse down event bindings.
 
-Pointer down events can cause accessibility issues because they don't work well with keyboard navigation. Use `click` or `keydown` events instead.
+Pointer down and mouse down events can cause accessibility issues because they don't work well with keyboard navigation. Use `click` or `keydown` events instead.
 
 ## Rule Details
 
-This rule disallows the use of `pointerdown` events in templates.
+This rule disallows the use of `pointerdown` and `mousedown` events in templates.
 
 ## Examples
 
@@ -26,23 +26,29 @@ Examples of **incorrect** code for this rule:
 </template>
 ```
 
-Examples of **correct** code for this rule:
+```gjs
+<template>
+  <div {{on "mousedown" this.handleMouseDown}}>Content</div>
+</template>
+```
 
 ```gjs
 <template>
-  <button {{on "click" this.handleClick}}>Click</button>
+  <div onmousedown={{this.handleMouseDown}}>Content</div>
 </template>
 ```
 
+Examples of **correct** code for this rule:
+
 ```gjs
 <template>
-  <button {{on "keydown" this.handleKeyDown}}>Press</button>
+  <button {{on "click" this.handleClick}}>Click</button>
 </template>
 ```
 
 ```gjs
 <template>
-  <div {{on "mousedown" this.handleMouseDown}}>Content</div>
+  <button {{on "keydown" this.handleKeyDown}}>Press</button>
 </template>
 ```
 

docs/rules/template-no-quoteless-attributes.md

@@ -10,7 +10,7 @@ The following two examples are _identical_ from the perspective of the browser:
 
 ```gjs
 <template>
-  <div data-foo="asdf"></div>
+  <div data-foo=asdf></div>
   <div data-foo="asdf"></div>
 </template>
 ```
@@ -32,7 +32,7 @@ This rule attempts to make this situation _slightly_ better by at least ensuring
 This rule **forbids** the following (note that `someValue` could have been intended either as a string or expression):
 
 ```gjs
-<template><div data-foo="someValue"></div></template>
+<template><div data-foo=someValue></div></template>
 ```
 
 This rule **allows** the following: