docs(rules): updated rules docs

Author: AndreaPontrandolfo

README.md

@@ -4,5 +4,5 @@
 
 This ESLint plugin currently contains 2 rules:
 
-- prefer-destructured-optionals
-- ensure-matching-remove-event-listener
+- [prefer-destructured-optionals](./docs/rules/prefer-destructured-optionals.md)
+- [valid-event-listener](./docs/rules/valid-event-listener.md)

docs/rules/prefer-destructured-optionals.md

@@ -0,0 +1,25 @@
+# Enforces a specific style for the anatomy of a function signature
+
+This rule enforce that required parameters should always be placed at the start of the function signature and optional parameters should always be placed at the end of the function signature, in the form of a destructured object.
+
+## Fail
+
+```js
+const myFn = (param1, optionalParam = "x") => {
+  console.log(param1, optionalParam);
+};
+```
+
+```js
+const myFn = (param1, { optionalParam1 = "default" }, param2) => {
+  console.log(param1, optionalParam1, param2);
+};
+```
+
+## Pass
+
+```js
+const myFn = (param1, param2, { optionalParam = "x" }) => {
+  console.log(param1, param2, optionalParam);
+};
+```

docs/rules/valid-event-listener.md

@@ -0,0 +1,148 @@
+# Enforces best practices around addEventListener method
+
+This rule enforces 3 things:
+
+- enforces the use of a useEventListener hook from a hooks library instead of manually adding and removing event listeners (_optional_. `true` by default)
+- every addEventListener should have a cleanup function
+- every addEventListener should have a matching removeEventListener in the returned cleanup function of same useEffect block
+- addEventListener methods should not be called conditionally
+
+## Options
+
+### requireUseEventListenerHook
+
+Type: `boolean`\
+Default: `true`
+
+A lot of react-hooks libraries provide a `useEventListener` hook that simplifies event-listeners management. This rule can enforce the use of such a hook instead of manually adding and removing event listeners.
+
+This option is set to `true` by default. Setting this to false will disable this check but the other checks around addEventListener usage correctness will still be enforced.
+
+## Fail
+
+```js
+// eslint fsecond/valid-event-listener: [2, {"requireUseEventListenerHook": false}]
+useEffect(() => {
+  doThis();
+  if (x) window.document.addEventListener("keydown", handleUserKeyPress);
+}, []);
+```
+
+```js
+// eslint fsecond/valid-event-listener: [2, {"requireUseEventListenerHook": false}]
+useEffect(() => {
+  doThis();
+  x && window.document.addEventListener("keydown", handleUserKeyPress);
+}, []);
+```
+
+```js
+// eslint fsecond/valid-event-listener: [2, {"requireUseEventListenerHook": false}]
+useEffect(() => {
+  doThis();
+  if (x) {
+    window.document.addEventListener("keydown", handleUserKeyPress);
+  }
+}, []);
+```
+
+```js
+// eslint fsecond/valid-event-listener: [2, {"requireUseEventListenerHook": false}]
+useEffect(() => {
+  doThis();
+  if (x) {
+    x();
+  } else {
+    window.document.addEventListener("keydown", handleUserKeyPress);
+  }
+}, []);
+```
+
+```js
+// eslint fsecond/valid-event-listener: [2, {"requireUseEventListenerHook": false}]
+useEffect(() => {
+  doThis();
+  if (x) {
+    doThisMore();
+  }
+  window.document.addEventListener("keydown", handleUserKeyPress);
+}, []);
+```
+
+```js
+// eslint fsecond/valid-event-listener: [2, {"requireUseEventListenerHook": false}]
+useEffect(() => {
+  doThis();
+  if (x) {
+    doThisMore();
+  }
+  window.document.addEventListener("keydown", handleUserKeyPress);
+  doMoreOfThis();
+  return () => {
+    if (x) {
+      doThisMore();
+    }
+    doThatAfter();
+  };
+}, []);
+```
+
+```js
+// eslint fsecond/valid-event-listener: 2
+// eslint fsecond/valid-event-listener: [2, {"requireUseEventListenerHook": true}]
+useEffect(() => {
+  window.addEventListener("keydown", handleUserKeyPress);
+  return () => {
+    window.removeEventListener("keydown", handleUserKeyPress);
+  };
+}, []);
+```
+
+## Pass
+
+```js
+// eslint fsecond/valid-event-listener: 2
+// eslint fsecond/valid-event-listener: [2, {"requireUseEventListenerHook": true}]
+useEventListener("scroll", onScroll);
+```
+
+```js
+// eslint fsecond/valid-event-listener: 2
+// eslint fsecond/valid-event-listener: [2, {"requireUseEventListenerHook": true}]
+useEventListener("visibilitychange", onVisibilityChange, documentRef);
+```
+
+```js
+// eslint fsecond/valid-event-listener: 2
+// eslint fsecond/valid-event-listener: [2, {"requireUseEventListenerHook": true}]
+useEventListener("click", onClick, buttonRef);
+```
+
+```js
+// eslint fsecond/valid-event-listener: 2
+// eslint fsecond/valid-event-listener: [2, {"requireUseEventListenerHook": true}]
+useEffect(() => {
+  return () => {
+    window.removeEventListener("keydown", handleUserKeyPress);
+  };
+}, []);
+```
+
+```js
+// eslint fsecond/valid-event-listener: 2
+// eslint fsecond/valid-event-listener: [2, {"requireUseEventListenerHook": true}]
+// eslint fsecond/valid-event-listener: [2, {"requireUseEventListenerHook": false}]
+useEffect(() => {
+  refcurrent = value;
+}, [value]);
+```
+
+```js
+// eslint fsecond/valid-event-listener: [2, {"requireUseEventListenerHook": false}]
+useEffect(() => {
+  window.document.addEventListener("keydown", handleUserKeyPress);
+  return () => {
+    window.document.removeEventListener("keydown", handleUserKeyPress);
+  };
+}, []);
+```

src/rules/prefer-destructured-optionals.ts

@@ -11,7 +11,6 @@ export default createEslintRule<Options, MessageIds>({
     docs: {
       description:
         "enforce placing optional parameters on a destructured object instead of the function signature itself",
-      recommended: "stylistic",
     },
     schema: [],
     messages: {

src/rules/valid-event-listener.test.ts

@@ -1,6 +1,7 @@
 import { RuleTester } from "@typescript-eslint/utils/ts-eslint";
 import { test } from "vitest";
 import rule, { RULE_NAME } from "./valid-event-listener";
+
 const casesWithRequireUseEventListenerHookOption = {
   valids: [
     {

src/rules/valid-event-listener.ts

@@ -14,7 +14,6 @@ export default createEslintRule<Options, MessageIds>({
     type: "problem",
     docs: {
       description: "Enforces best practices around addEventListener method.",
-      recommended: "recommended",
     },
     schema: [
       {