Add vue/v-on-handler-style rule and deprecate `vue/v-on-function-ca…

…ll` rule (#2009) * Add `vue/v-on-handler-style` rule and deprecated `vue/v-on-function-call` rule * Update docs/rules/v-on-handler-style.md Co-authored-by: Flo Edelmann <[email protected]> * Update docs/rules/v-on-handler-style.md Co-authored-by: Flo Edelmann <[email protected]> * simplify element in doc * add related rules to doc * add ignored examples to doc * change to report morev * fix doc * change v-on-handler-style * refactor * Apply suggestions from code review Co-authored-by: Flo Edelmann <[email protected]> * update docs * fix error message * refactor * Update docs/rules/v-on-handler-style.md Co-authored-by: Flo Edelmann <[email protected]> Co-authored-by: Flo Edelmann <[email protected]>
vuejs · Oct 30, 2022 · f5d700c · f5d700c
1 parent 2c1ba8c
commit f5d700c
Show file tree

Hide file tree

Showing 10 changed files with 1,951 additions and 8 deletions.
diff --git a/docs/rules/README.md b/docs/rules/README.md
@@ -264,7 +264,7 @@ For example:
 | [vue/sort-keys](./sort-keys.md) | enforce sort-keys in a manner that is compatible with order-in-components |  | :hammer: |
 | [vue/static-class-names-order](./static-class-names-order.md) | enforce static class names order | :wrench: | :hammer: |
 | [vue/v-for-delimiter-style](./v-for-delimiter-style.md) | enforce `v-for` directive's delimiter style | :wrench: | :lipstick: |
-| [vue/v-on-function-call](./v-on-function-call.md) | enforce or forbid parentheses after method calls without arguments in `v-on` directives | :wrench: | :hammer: |
+| [vue/v-on-handler-style](./v-on-handler-style.md) | enforce writing style for handlers in `v-on` directives | :wrench: | :hammer: |
 
 </rules-table>
 
@@ -324,6 +324,7 @@ The following rules extend the rules provided by ESLint itself and apply them to
 |:--------|:------------|
 | [vue/no-invalid-model-keys](./no-invalid-model-keys.md) | [vue/valid-model-definition](./valid-model-definition.md) |
 | [vue/script-setup-uses-vars](./script-setup-uses-vars.md) | (no replacement) |
+| [vue/v-on-function-call](./v-on-function-call.md) | [vue/v-on-handler-style](./v-on-handler-style.md) |
 
 ## Removed
 

diff --git a/docs/rules/v-on-event-hyphenation.md b/docs/rules/v-on-event-hyphenation.md
@@ -107,6 +107,7 @@ Don't use hyphenated name but allow custom event names
 
 - [vue/custom-event-name-casing](./custom-event-name-casing.md)
 - [vue/attribute-hyphenation](./attribute-hyphenation.md)
+- [vue/v-on-handler-style](./v-on-handler-style.md)
 
 ## :books: Further Reading
 

diff --git a/docs/rules/v-on-function-call.md b/docs/rules/v-on-function-call.md
@@ -9,6 +9,7 @@ since: v5.2.0
 
 > enforce or forbid parentheses after method calls without arguments in `v-on` directives
 
+- :warning: This rule was **deprecated** and replaced by [vue/v-on-handler-style](v-on-handler-style.md) rule.
 - :wrench: The `--fix` option on the [command line](https://eslint.org/docs/user-guide/command-line-interface#fixing-problems) can automatically fix some of the problems reported by this rule.
 
 ## :book: Rule Details

diff --git a/docs/rules/v-on-handler-style.md b/docs/rules/v-on-handler-style.md
@@ -0,0 +1,219 @@
+---
+pageClass: rule-details
+sidebarDepth: 0
+title: vue/v-on-handler-style
+description: enforce writing style for handlers in `v-on` directives
+---
+# vue/v-on-handler-style
+
+> enforce writing style for handlers in `v-on` directives
+
+- :exclamation: <badge text="This rule has not been released yet." vertical="middle" type="error"> ***This rule has not been released yet.*** </badge>
+- :wrench: The `--fix` option on the [command line](https://eslint.org/docs/user-guide/command-line-interface#fixing-problems) can automatically fix some of the problems reported by this rule.
+
+## :book: Rule Details
+
+This rule aims to enforce a consistent style in `v-on` event handlers:
+
+```vue
+<!-- Method handler: -->
+<button v-on:click="handler" />
+
+<!-- Inline handler: -->
+<button v-on:click="handler()" />
+
+<!-- Inline function: -->
+<button v-on:click="() => handler()" />
+```
+
+<eslint-code-block fix :rules="{'vue/v-on-handler-style': ['error']}">
+
+```vue
+<template>
+  <!-- ✓ GOOD -->
+  <button v-on:click="handler" />
+
+  <!-- ✗ BAD -->
+  <button v-on:click="handler()" />
+  <button v-on:click="() => handler()" />
+</template>
+```
+
+</eslint-code-block>
+
+## :wrench: Options
+
+```json
+{
+  "vue/v-on-handler-style": ["error",
+    ["method", "inline-function"], // ["method", "inline-function"] | ["method", "inline"] | "inline-function" | "inline"
+    {
+      "ignoreIncludesComment": false
+    }
+  ]
+}
+```
+
+- First option ... Specifies the name of an allowed style. Default is `["method", "inline-function"]`.
+  - `["method", "inline-function"]` ... Allow handlers by method binding. e.g. `v-on:click="handler"`. Allow inline functions where method handlers cannot be used. e.g. `v-on:click="() => handler(listItem)"`.
+  - `["method", "inline"]` ... Allow handlers by method binding. e.g. `v-on:click="handler"`. Allow inline handlers where method handlers cannot be used. e.g. `v-on:click="handler(listItem)"`.
+  - `"inline-function"` ... Allow inline functions. e.g. `v-on:click="() => handler()"`
+  - `"inline"` ... Allow inline handlers. e.g. `v-on:click="handler()"`
+- Second option
+  - `ignoreIncludesComment` ... If `true`, do not report inline handlers or inline functions containing comments, even if the preferred style is `"method"`. Default is `false`.
+
+### `["method", "inline-function"]` (Default)
+
+<eslint-code-block fix :rules="{'vue/v-on-handler-style': ['error', ['method', 'inline-function']]}">
+
+```vue
+<template>
+  <!-- ✓ GOOD -->
+  <button v-on:click="handler" />
+  <template v-for="e in list">
+    <button v-on:click="e" />
+    <button v-on:click="() => handler(e)" />
+  </template>
+
+  <!-- ✗ BAD -->
+  <button v-on:click="handler()" />
+  <button v-on:click="count++" />
+  <button v-on:click="() => handler()" />
+  <button v-on:click="() => count++" />
+  <button v-on:click="(a, b) => handler(a, b)" />
+  <template v-for="e in list">
+    <button v-on:click="e()" />
+    <button v-on:click="() => e()" />
+    <button v-on:click="handler(e)" />
+  </template>
+</template>
+```
+
+</eslint-code-block>
+
+### `["method", "inline"]`
+
+<eslint-code-block fix :rules="{'vue/v-on-handler-style': ['error', ['method', 'inline']]}">
+
+```vue
+<template>
+  <!-- ✓ GOOD -->
+  <button v-on:click="handler" />
+  <template v-for="e in list">
+    <button v-on:click="e" />
+    <button v-on:click="handler(e)" />
+  </template>
+
+  <!-- ✗ BAD -->
+  <button v-on:click="handler()" />
+  <button v-on:click="count++" />
+  <button v-on:click="() => handler()" />
+  <button v-on:click="() => count++" />
+  <button v-on:click="(a, b) => handler(a, b)" />
+  <template v-for="e in list">
+    <button v-on:click="e()" />
+    <button v-on:click="() => e()" />
+    <button v-on:click="() => handler(e)" />
+  </template>
+</template>
+```
+
+</eslint-code-block>
+
+### `["inline-function"]`
+
+<eslint-code-block fix :rules="{'vue/v-on-handler-style': ['error', ['inline-function']]}">
+
+```vue
+<template>
+  <!-- ✓ GOOD -->
+  <button v-on:click="() => handler()" />
+  <button v-on:click="() => count++" />
+
+  <!-- ✗ BAD -->
+  <button v-on:click="handler" />
+  <button v-on:click="handler()" />
+  <button v-on:click="handler($event)" />
+  <button v-on:click="count++" />
+</template>
+```
+
+</eslint-code-block>
+
+### `["inline"]`
+
+<eslint-code-block fix :rules="{'vue/v-on-handler-style': ['error', ['inline']]}">
+
+```vue
+<template>
+  <!-- ✓ GOOD -->
+  <button v-on:click="handler()" />
+  <button v-on:click="handler($event)" />
+  <button v-on:click="count++" />
+
+  <!-- ✗ BAD -->
+  <button v-on:click="handler" />
+  <button v-on:click="() => handler()" />
+  <button v-on:click="(foo) => handler(foo)" />
+  <button v-on:click="(foo, bar) => handler(foo, bar)" />
+  <button v-on:click="() => count++" />
+</template>
+```
+
+</eslint-code-block>
+
+### `["method", "inline-function"], { "ignoreIncludesComment": true }`
+
+<eslint-code-block fix :rules="{'vue/v-on-handler-style': ['error', ['method', 'inline-function'], {ignoreIncludesComment: true}]}">
+
+```vue
+<template>
+  <!-- ✓ GOOD -->
+  <button v-on:click="handler" />
+  <button v-on:click="() => handler() /* comment */" />
+
+  <!-- ✗ BAD -->
+  <button v-on:click="handler()" />
+  <button v-on:click="() => handler()" />
+  <button v-on:click="handler() /* comment */" />
+</template>
+```
+
+</eslint-code-block>
+
+### `["method", "inline"], { "ignoreIncludesComment": true }`
+
+<eslint-code-block fix :rules="{'vue/v-on-handler-style': ['error', ['method', 'inline'], {ignoreIncludesComment: true}]}">
+
+```vue
+<template>
+  <!-- ✓ GOOD -->
+  <button v-on:click="handler" />
+  <button v-on:click="handler() /* comment */" />
+
+  <!-- ✗ BAD -->
+  <button v-on:click="handler()" />
+  <button v-on:click="() => handler()" />
+  <button v-on:click="() => handler() /* comment */" />
+</template>
+```
+
+</eslint-code-block>
+
+## :couple: Related Rules
+
+- [vue/v-on-style](./v-on-style.md)
+- [vue/v-on-event-hyphenation](./v-on-event-hyphenation.md)
+
+## :books: Further Reading
+
+- [Guide - Inline Handlers]
+- [Guide - Method Handlers]
+
+[Guide - Inline Handlers]: https://vuejs.org/guide/essentials/event-handling.html#inline-handlers
+[Guide - Method Handlers]: https://vuejs.org/guide/essentials/event-handling.html#method-handlers
+
+## :mag: Implementation
+
+- [Rule source](https://github.com/vuejs/eslint-plugin-vue/blob/master/lib/rules/v-on-handler-style.js)
+- [Test source](https://github.com/vuejs/eslint-plugin-vue/blob/master/tests/lib/rules/v-on-handler-style.js)
diff --git a/docs/rules/v-on-style.md b/docs/rules/v-on-style.md
@@ -59,6 +59,10 @@ Default is set to `shorthand`.
 
 </eslint-code-block>
 
+## :couple: Related Rules
+
+- [vue/v-on-handler-style](./v-on-handler-style.md)
+
 ## :books: Further Reading
 
 - [Style guide - Directive shorthands](https://vuejs.org/style-guide/rules-strongly-recommended.html#directive-shorthands)

diff --git a/lib/index.js b/lib/index.js
@@ -200,6 +200,7 @@ module.exports = {
     'v-for-delimiter-style': require('./rules/v-for-delimiter-style'),
     'v-on-event-hyphenation': require('./rules/v-on-event-hyphenation'),
     'v-on-function-call': require('./rules/v-on-function-call'),
+    'v-on-handler-style': require('./rules/v-on-handler-style'),
     'v-on-style': require('./rules/v-on-style'),
     'v-slot-style': require('./rules/v-slot-style'),
     'valid-attribute-name': require('./rules/valid-attribute-name'),

diff --git a/lib/rules/v-on-function-call.js b/lib/rules/v-on-function-call.js
@@ -82,7 +82,9 @@ module.exports = {
         },
         additionalProperties: false
       }
-    ]
+    ],
+    deprecated: true,
+    replacedBy: ['v-on-handler-style']
   },
   /** @param {RuleContext} context */
   create(context) {