From 3cda46b9a351970a8a703baf60ace0fcab311751 Mon Sep 17 00:00:00 2001
From: Yosuke Ota <otameshiyo23@gmail.com>
Date: Tue, 6 Jul 2021 19:55:14 +0900
Subject: [PATCH] Update docs related to `<script setup>`. (#1530)

* Update docs related to `<script setup>`.

* update doc

* update

* update doc
---
 docs/README.md                               |  2 +-
 docs/rules/experimental-script-setup-vars.md |  4 +
 docs/user-guide/README.md                    | 83 +++++++++++++++++++-
 3 files changed, 87 insertions(+), 2 deletions(-)

diff --git a/docs/README.md b/docs/README.md
index e19258040..10a5d0d55 100644
--- a/docs/README.md
+++ b/docs/README.md
@@ -15,7 +15,7 @@ This plugin allows us to check the `<template>` and `<script>` of `.vue` files w
 ESLint editor integrations are useful to check your code in real-time.
 
 :::warning Status of Vue.js 3.x supports
-This plugin supports the basic syntax of Vue.js 3.0, but the Vue.js 3.0 experimental features `<script setup>` and `<style vars>` are not yet supported. Follow [#1248](https://github.com/vuejs/eslint-plugin-vue/issues/1248) for more details.
+This plugin supports the basic syntax of Vue.js 3.0 and `<script setup>`, but the Vue.js 3.0 experimental feature CSS variable injection is not yet supported. Follow [#1248](https://github.com/vuejs/eslint-plugin-vue/issues/1248) for more details.
 :::
 
 ## :traffic_light: Versioning policy
diff --git a/docs/rules/experimental-script-setup-vars.md b/docs/rules/experimental-script-setup-vars.md
index bf89fa9a9..14735e5e3 100644
--- a/docs/rules/experimental-script-setup-vars.md
+++ b/docs/rules/experimental-script-setup-vars.md
@@ -19,6 +19,10 @@ This rule will find variables defined in `<script setup="args">` and mark them a
 
 This rule only has an effect when the `no-undef` rule is enabled.
 
+:::warning
+`<script setup="args">` syntax wasn't rejected by Vue's RFC. Check out the [new syntax](https://github.com/vuejs/rfcs/blob/master/active-rfcs/0040-script-setup.md).
+:::
+
 ## :book: Rule Details
 
 Without this rule this code triggers warning:
diff --git a/docs/user-guide/README.md b/docs/user-guide/README.md
index 0b3c3d825..f6dc47456 100644
--- a/docs/user-guide/README.md
+++ b/docs/user-guide/README.md
@@ -72,7 +72,7 @@ By default all rules from **base** and **essential** categories report ESLint er
 :::
 
 :::warning Status of Vue.js 3.x supports
-This plugin supports the basic syntax of Vue.js 3.0, but the Vue.js 3.0 experimental features `<script setup>` and `<style vars>` are not yet supported. Follow [#1248](https://github.com/vuejs/eslint-plugin-vue/issues/1248) for more details.
+This plugin supports the basic syntax of Vue.js 3.0 and `<script setup>`, but the Vue.js 3.0 experimental feature CSS variable injection is not yet supported. Follow [#1248](https://github.com/vuejs/eslint-plugin-vue/issues/1248) for more details.
 :::
 
 ### Running ESLint from the command line
@@ -335,3 +335,84 @@ Note that you cannot use angle-bracket type assertion style (`var x = <foo>bar;`
 You need to turn off Vetur's template validation by adding `vetur.validation.template: false` to your `.vscode/settings.json`.
 
 See also: "[Visual Studio Code](#editor-integrations)" section and [Vetur - Linting](https://vuejs.github.io/vetur/guide/linting-error.html#linting).
+
+### Does not work well with `<script setup>`
+
+#### The variables used in the `<template>` are warned by `no-unused-vars` rule
+
+You must use [vue/script-setup-uses-vars](../rules/script-setup-uses-vars.md) rule.  
+In your configuration, use the rule set provided by `eslint-plugin-vue` or enable it rule.
+
+Example **.eslintrc.js**:
+
+```js
+module.exports = {
+  // Use the rule set.
+  extends: ['plugin:vue/base'],
+  rules: {
+    // Enable vue/script-setup-uses-vars rule
+    'vue/script-setup-uses-vars': 'error',
+  }
+}
+```
+
+#### Compiler macros such as `defineProps` and `defineEmits` are warned by `no-undef` rule
+
+You need to define [global variables](https://eslint.org/docs/user-guide/configuring/language-options#using-configuration-files-1) in your ESLint configuration file.  
+If you don't want to define global variables, use `import { defineProps, defineEmits } from 'vue'`.
+
+Example **.eslintrc.js**:
+
+```js
+module.exports = {
+  globals: {
+    defineProps: "readonly",
+    defineEmits: "readonly",
+    defineExpose: "readonly",
+    withDefaults: "readonly"
+  }
+}
+```
+
+See also [ESLint - Specifying Globals > Using configuration files](https://eslint.org/docs/user-guide/configuring/language-options#using-configuration-files-1).
+
+#### Parsing error with Top Level `await`
+
+##### Using ESLint <= v7.x
+
+The parser `espree` that comes with `ESLint` v7.x doesn't understand the syntax of ES2022, so it can't parse the Top Level `await` either.  
+However, `espree` v8+ can understand the syntax of ES2022 and parse the Top Level `await`.  
+You install `espree` v8+ and specify `"espree"` and ES2022 in your configuration, the parser will be able to parse it.
+
+```js
+module.exports = {
+  parser: 'vue-eslint-parser',
+  parserOptions: {
+    parser: 'espree', // <-
+    ecmaVersion: 2022, // <-
+    sourceType: 'module'
+  },
+}
+```
+
+However, note that the AST generated by `espree` v8+ may not work well with some rules of `ESLint` v7.x.
+
+<!--
+##### Using ESLint >= v8.x
+
+You need to specify `2022` for `parserOptions.ecmaVersion`.
+
+```js
+module.exports = {
+  parserOptions: {
+    ecmaVersion: 2022,
+    sourceType: 'module'
+  },
+}
+```
+-->
+
+#### Other Problems
+
+Try searching for existing issues.
+If it does not exist, you should open a new issue and share your repository to reproduce the issue.