Merge branch 'master' into prefer-define-component

Author: thesheppard

docs/rules/define-props-destructuring.md

@@ -0,0 +1,95 @@
+---
+pageClass: rule-details
+sidebarDepth: 0
+title: vue/define-props-destructuring
+description: enforce consistent style for props destructuring
+---
+
+# vue/define-props-destructuring
+
+> enforce consistent style for props destructuring
+
+- :exclamation: <badge text="This rule has not been released yet." vertical="middle" type="error"> _**This rule has not been released yet.**_ </badge>
+
+## :book: Rule Details
+
+This rule enforces a consistent style for handling Vue 3 Composition API props, allowing you to choose between requiring destructuring or prohibiting it.
+
+By default, the rule requires you to use destructuring syntax when using `defineProps` instead of storing props in a variable and warns against combining `withDefaults` with destructuring.
+
+<eslint-code-block :rules="{'vue/define-props-destructuring': ['error']}">
+
+```vue
+<script setup>
+  // ✓ GOOD
+  const { foo } = defineProps(['foo'])
+  const { bar = 'default' } = defineProps(['bar'])
+
+  // ✗ BAD
+  const props = defineProps(['foo'])
+  const propsWithDefaults = withDefaults(defineProps(['foo']), { foo: 'default' })
+
+  // ✗ BAD
+  const { baz } = withDefaults(defineProps(['baz']), { baz: 'default' })
+</script>
+```
+
+</eslint-code-block>
+
+The rule applies to both JavaScript and TypeScript props:
+
+<eslint-code-block :rules="{'vue/define-props-destructuring': ['error']}">
+
+```vue
+<script setup lang="ts">
+  // ✓ GOOD
+  const { foo } = defineProps<{ foo?: string }>()
+  const { bar = 'default' } = defineProps<{ bar?: string }>()
+
+  // ✗ BAD
+  const props = defineProps<{ foo?: string }>()
+  const propsWithDefaults = withDefaults(defineProps<{ foo?: string }>(), { foo: 'default' })
+</script>
+```
+
+</eslint-code-block>
+
+## :wrench: Options
+
+```js
+{
+  "vue/define-props-destructuring": ["error", {
+    "destructure": "always" | "never"
+  }]
+}
+```
+
+- `destructure` - Sets the destructuring preference for props
+  - `"always"` (default) - Requires destructuring when using `defineProps` and warns against using `withDefaults` with destructuring
+  - `"never"` - Requires using a variable to store props and prohibits destructuring
+
+### `"destructure": "never"`
+
+<eslint-code-block :rules="{'vue/define-props-destructuring': ['error', { destructure: 'never' }]}">
+
+```vue
+<script setup>
+  // ✓ GOOD
+  const props = defineProps(['foo'])
+  const propsWithDefaults = withDefaults(defineProps(['foo']), { foo: 'default' })
+
+  // ✗ BAD
+  const { foo } = defineProps(['foo'])
+</script>
+```
+
+</eslint-code-block>
+
+## :books: Further Reading
+
+- [Reactive Props Destructure](https://vuejs.org/guide/components/props.html#reactive-props-destructure)
+
+## :mag: Implementation
+
+- [Rule source](https://github.com/vuejs/eslint-plugin-vue/blob/master/lib/rules/define-props-destructuring.js)
+- [Test source](https://github.com/vuejs/eslint-plugin-vue/blob/master/tests/lib/rules/define-props-destructuring.js)

docs/rules/index.md

@@ -12,7 +12,7 @@ since: v7.0.0
 
 ## :book: Rule Details
 
-This rule disallows the use of bare strings in `<template>`.  
+This rule disallows the use of bare strings in `<template>`.
 In order to be able to internationalize your application, you will need to avoid using plain strings in your templates. Instead, you would need to use a template helper specializing in translation.
 
 This rule was inspired by [no-bare-strings rule in ember-template-lint](https://github.com/ember-template-lint/ember-template-lint/blob/master/docs/rule/no-bare-strings.md).
@@ -50,7 +50,7 @@ This rule was inspired by [no-bare-strings rule in ember-template-lint](https://
 </eslint-code-block>
 
 :::tip
-This rule does not check for string literals, in bindings and mustaches interpolation. This is because it looks like a conscious decision.  
+This rule does not check for string literals, in bindings and mustaches interpolation. This is because it looks like a conscious decision.
 If you want to report these string literals, enable the [vue/no-useless-v-bind] and [vue/no-useless-mustaches] rules and fix the useless string literals.
 :::
 
@@ -72,7 +72,7 @@ If you want to report these string literals, enable the [vue/no-useless-v-bind]
 }
 ```
 
-- `allowlist` ... An array of allowed strings.
+- `allowlist` ... An array of allowed strings or regular expression patterns (e.g. `/\d+/` to allow numbers).
 - `attributes` ... An object whose keys are tag name or patterns and value is an array of attributes to check for that tag name.
 - `directives` ... An array of directive names to check literal value.
 

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

@@ -61,7 +61,32 @@ This rule checks whether template contains single root element valid for Vue 2.
 
 ## :wrench: Options
 
-Nothing.
+```json
+{
+  "vue/no-multiple-template-root": ["error", {
+    "disallowComments": false
+  }]
+}
+```
+
+- "disallowComments" (`boolean`) Enables there should not be any comments in the template root. Default is `false`.
+
+### "disallowComments": true
+
+<eslint-code-block :rules="{'vue/no-multiple-template-root': ['error', {disallowComments: true}]}">
+
+```vue
+/* ✗ BAD */
+<template>
+  <!-- root comment -->
+  <div>
+    vue eslint plugin
+  </div>
+  <!-- root comment -->
+</template>
+```
+
+</eslint-code-block>
 
 ## :rocket: Version
 

docs/rules/no-multiple-template-root.md

@@ -58,6 +58,7 @@ const plugin = {
     'define-emits-declaration': require('./rules/define-emits-declaration'),
     'define-macros-order': require('./rules/define-macros-order'),
     'define-props-declaration': require('./rules/define-props-declaration'),
+    'define-props-destructuring': require('./rules/define-props-destructuring'),
     'dot-location': require('./rules/dot-location'),
     'dot-notation': require('./rules/dot-notation'),
     'enforce-style-attribute': require('./rules/enforce-style-attribute'),

lib/index.js

@@ -0,0 +1,79 @@
+/**
+ * @author Wayne Zhang
+ * See LICENSE file in root directory for full license.
+ */
+'use strict'
+
+const utils = require('../utils')
+
+module.exports = {
+  meta: {
+    type: 'suggestion',
+    docs: {
+      description: 'enforce consistent style for props destructuring',
+      categories: undefined,
+      url: 'https://eslint.vuejs.org/rules/define-props-destructuring.html'
+    },
+    fixable: null,
+    schema: [
+      {
+        type: 'object',
+        properties: {
+          destructure: {
+            enum: ['always', 'never']
+          }
+        },
+        additionalProperties: false
+      }
+    ],
+    messages: {
+      preferDestructuring: 'Prefer destructuring from `defineProps` directly.',
+      avoidDestructuring: 'Avoid destructuring from `defineProps`.',
+      avoidWithDefaults: 'Avoid using `withDefaults` with destructuring.'
+    }
+  },
+  /** @param {RuleContext} context */
+  create(context) {
+    const options = context.options[0] || {}
+    const destructurePreference = options.destructure || 'always'
+
+    return utils.compositingVisitors(
+      utils.defineScriptSetupVisitor(context, {
+        onDefinePropsEnter(node, props) {
+          const hasNoArgs = props.filter((prop) => prop.propName).length === 0
+          if (hasNoArgs) {
+            return
+          }
+
+          const hasDestructure = utils.isUsingPropsDestructure(node)
+          const hasWithDefaults = utils.hasWithDefaults(node)
+
+          if (destructurePreference === 'never') {
+            if (hasDestructure) {
+              context.report({
+                node,
+                messageId: 'avoidDestructuring'
+              })
+            }
+            return
+          }
+
+          if (!hasDestructure) {
+            context.report({
+              node,
+              messageId: 'preferDestructuring'
+            })
+            return
+          }
+
+          if (hasWithDefaults) {
+            context.report({
+              node: node.parent.callee,
+              messageId: 'avoidWithDefaults'
+            })
+          }
+        }
+      })
+    )
+  }
+}

lib/rules/define-props-destructuring.js

@@ -149,17 +149,33 @@ module.exports = {
      */
     const opts = context.options[0] || {}
     /** @type {string[]} */
-    const allowlist = opts.allowlist || DEFAULT_ALLOWLIST
+    const rawAllowlist = opts.allowlist || DEFAULT_ALLOWLIST
     const attributes = parseTargetAttrs(opts.attributes || DEFAULT_ATTRIBUTES)
     const directives = opts.directives || DEFAULT_DIRECTIVES
 
-    const allowlistRe = new RegExp(
-      allowlist
-        .map((w) => regexp.escape(w))
-        .sort((a, b) => b.length - a.length)
-        .join('|'),
-      'gu'
-    )
+    /** @type {string[]} */
+    const stringAllowlist = []
+    /** @type {RegExp[]} */
+    const regexAllowlist = []
+
+    for (const item of rawAllowlist) {
+      if (regexp.isRegExp(item)) {
+        regexAllowlist.push(regexp.toRegExp(item))
+      } else {
+        stringAllowlist.push(item)
+      }
+    }
+
+    const allowlistRe =
+      stringAllowlist.length > 0
+        ? new RegExp(
+            stringAllowlist
+              .map((w) => regexp.escape(w))
+              .sort((a, b) => b.length - a.length)
+              .join('|'),
+            'gu'
+          )
+        : null
 
     /** @type {ElementStack | null} */
     let elementStack = null
@@ -168,7 +184,21 @@ module.exports = {
      * @param {string} str
      */
     function getBareString(str) {
-      return str.trim().replace(allowlistRe, '').trim()
+      let result = str.trim()
+
+      if (allowlistRe) {
+        result = result.replace(allowlistRe, '')
+      }
+
+      for (const regex of regexAllowlist) {
+        const flags = regex.flags.includes('g')
+          ? regex.flags
+          : `${regex.flags}g`
+        const globalRegex = new RegExp(regex.source, flags)
+        result = result.replace(globalRegex, '')
+      }
+
+      return result.trim()
     }
 
     /**

lib/rules/no-bare-strings-in-template.js

@@ -6,6 +6,21 @@
 
 const utils = require('../utils')
 
+/**
+ * Get all comments that need to be reported
+ * @param {(HTMLComment | HTMLBogusComment | Comment)[]} comments
+ * @param {Range[]} elementRanges
+ * @returns {(HTMLComment | HTMLBogusComment | Comment)[]}
+ */
+function getReportComments(comments, elementRanges) {
+  return comments.filter(
+    (comment) =>
+      !elementRanges.some(
+        (range) => range[0] <= comment.range[0] && comment.range[1] <= range[1]
+      )
+  )
+}
+
 module.exports = {
   meta: {
     type: 'problem',
@@ -15,8 +30,19 @@ module.exports = {
       url: 'https://eslint.vuejs.org/rules/no-multiple-template-root.html'
     },
     fixable: null,
-    schema: [],
+    schema: [
+      {
+        type: 'object',
+        properties: {
+          disallowComments: {
+            type: 'boolean'
+          }
+        },
+        additionalProperties: false
+      }
+    ],
     messages: {
+      commentRoot: 'The template root disallows comments.',
       multipleRoot: 'The template root requires exactly one element.',
       textRoot: 'The template root requires an element rather than texts.',
       disallowedElement: "The template root disallows '<{{name}}>' elements.",
@@ -28,6 +54,8 @@ module.exports = {
    * @returns {RuleListener} AST event handlers.
    */
   create(context) {
+    const options = context.options[0] || {}
+    const disallowComments = options.disallowComments
     const sourceCode = context.getSourceCode()
 
     return {
@@ -37,6 +65,18 @@ module.exports = {
           return
         }
 
+        const comments = element.comments
+        const elementRanges = element.children.map((child) => child.range)
+        if (disallowComments && comments.length > 0) {
+          for (const comment of getReportComments(comments, elementRanges)) {
+            context.report({
+              node: comment,
+              loc: comment.loc,
+              messageId: 'commentRoot'
+            })
+          }
+        }
+
         const rootElements = []
         let extraText = null
         let extraElement = null

lib/rules/no-multiple-template-root.js

@@ -1,6 +1,6 @@
 {
   "name": "eslint-plugin-vue",
-  "version": "10.0.0",
+  "version": "10.0.1",
   "description": "Official ESLint plugin for Vue.js",
   "main": "lib/index.js",
   "types": "lib/index.d.ts",