chore: improve useValidAnchor doc (biomejs#1955)

crates/biome_js_analyze/src/analyzers/a11y/use_valid_anchor.rs

@@ -23,10 +23,13 @@ declare_rule! {
     ///
     /// There are **many reasons** why an anchor should not have a logic with an incorrect `href` attribute:
     /// - it can disrupt the correct flow of the user navigation e.g. a user that wants to open the link
-    /// in another tab, but the default "click" behaviour is prevented
-    /// - it can source of invalid links, and crawlers can't navigate the website, risking to penalise
+    /// in another tab, but the default "click" behavior is prevented
+    /// - it can source of invalid links, and crawlers can't navigate the website, risking to penalize
     /// SEO ranking
     ///
+    ///
+    /// For a detailed explanation, check out https://marcysutton.com/links-vs-buttons-in-modern-web-applications
+    ///
     /// ## Examples
     ///
     /// ### Invalid
@@ -43,7 +46,9 @@ declare_rule! {
     /// ```jsx,expect_diagnostic
     /// <a href="javascript:void(0)">navigate here</a>
     /// ```
-
+    /// ```jsx,expect_diagnostic
+    /// <a onClick={something}>navigate here</a>
+    /// ```
     /// ### Valid
     ///
     /// ```jsx

website/src/content/docs/linter/rules/use-valid-anchor.md

@@ -29,10 +29,12 @@ used for user interaction.
 There are **many reasons** why an anchor should not have a logic with an incorrect `href` attribute:
 
 - it can disrupt the correct flow of the user navigation e.g. a user that wants to open the link
-in another tab, but the default "click" behaviour is prevented
-- it can source of invalid links, and crawlers can't navigate the website, risking to penalise
+in another tab, but the default "click" behavior is prevented
+- it can source of invalid links, and crawlers can't navigate the website, risking to penalize
 SEO ranking
 
+For a detailed explanation, check out https://marcysutton.com/links-vs-buttons-in-modern-web-applications
+
 ## Examples
 
 ### Invalid
@@ -109,6 +111,24 @@ SEO ranking
 
 </code></pre>
 
+```jsx
+<a onClick={something}>navigate here</a>
+```
+
+<pre class="language-text"><code class="language-text">a11y/useValidAnchor.js:1:4 <a href="https://biomejs.dev/linter/rules/use-valid-anchor">lint/a11y/useValidAnchor</a> ━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
+
+<strong><span style="color: Tomato;">  </span></strong><strong><span style="color: Tomato;">✖</span></strong> <span style="color: Tomato;">Use a </span><span style="color: Tomato;"><strong>button</strong></span><span style="color: Tomato;"> element instead of an </span><span style="color: Tomato;"><strong>a</strong></span><span style="color: Tomato;"> element.</span>
+
+<strong><span style="color: Tomato;">  </span></strong><strong><span style="color: Tomato;">&gt;</span></strong> <strong>1 │ </strong>&lt;a onClick={something}&gt;navigate here&lt;/a&gt;
+   <strong>   │ </strong>   <strong><span style="color: Tomato;">^</span></strong><strong><span style="color: Tomato;">^</span></strong><strong><span style="color: Tomato;">^</span></strong><strong><span style="color: Tomato;">^</span></strong><strong><span style="color: Tomato;">^</span></strong><strong><span style="color: Tomato;">^</span></strong><strong><span style="color: Tomato;">^</span></strong><strong><span style="color: Tomato;">^</span></strong><strong><span style="color: Tomato;">^</span></strong><strong><span style="color: Tomato;">^</span></strong><strong><span style="color: Tomato;">^</span></strong><strong><span style="color: Tomato;">^</span></strong><strong><span style="color: Tomato;">^</span></strong><strong><span style="color: Tomato;">^</span></strong><strong><span style="color: Tomato;">^</span></strong><strong><span style="color: Tomato;">^</span></strong><strong><span style="color: Tomato;">^</span></strong><strong><span style="color: Tomato;">^</span></strong><strong><span style="color: Tomato;">^</span></strong>
+    <strong>2 │ </strong>
+
+<strong><span style="color: lightgreen;">  </span></strong><strong><span style="color: lightgreen;">ℹ</span></strong> <span style="color: lightgreen;">Anchor elements should only be used for default sections or page navigation</span>
+
+<strong><span style="color: lightgreen;">  </span></strong><strong><span style="color: lightgreen;">ℹ</span></strong> <span style="color: lightgreen;">Check </span><span style="color: lightgreen;"><a href="https://marcysutton.com/links-vs-buttons-in-modern-web-applications">this thorough explanation</a></span><span style="color: lightgreen;"> to better understand the context.</span>
+
+</code></pre>
+
 ### Valid
 
 ```jsx