From d92a4b9a5a66d51747eda54f1391cd6ea744d190 Mon Sep 17 00:00:00 2001
From: Natalia Tepluhina <tarya.se@gmail.com>
Date: Sun, 8 Aug 2021 14:09:16 +0300
Subject: [PATCH 1/9] Extended watching multiple sources explanation (#1156)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* feat: added example for watching multiple sources

* feat: added nextTick example

* fix: reverted formatting

* Update src/guide/reactivity-computed-watchers.md

Co-authored-by: Thorsten Lünborg <t.luenborg@googlemail.com>

* Update src/guide/reactivity-computed-watchers.md

Co-authored-by: skirtle <65301168+skirtles-code@users.noreply.github.com>

* Update src/guide/reactivity-computed-watchers.md

Co-authored-by: skirtle <65301168+skirtles-code@users.noreply.github.com>

Co-authored-by: Thorsten Lünborg <t.luenborg@googlemail.com>
Co-authored-by: skirtle <65301168+skirtles-code@users.noreply.github.com>
---
 src/guide/reactivity-computed-watchers.md | 57 ++++++++++++++++++-----
 1 file changed, 46 insertions(+), 11 deletions(-)

diff --git a/src/guide/reactivity-computed-watchers.md b/src/guide/reactivity-computed-watchers.md
index fb68e6c6..0efa04f0 100644
--- a/src/guide/reactivity-computed-watchers.md
+++ b/src/guide/reactivity-computed-watchers.md
@@ -83,8 +83,10 @@ watchEffect(onInvalidate => {
 
 ```js
 const data = ref(null)
-watchEffect(async (onInvalidate) => {
-  onInvalidate(() => {/* ... */}) // Promise の解決前にクリーンアップする関数を登録
+watchEffect(async onInvalidate => {
+  onInvalidate(() => {
+    /* ... */
+  }) // Promise の解決前にクリーンアップする関数を登録
   data.value = await fetchData(props.id)
 })
 ```
@@ -101,19 +103,19 @@ Vue のリアクティブシステムは、無効になった変更をバッフ
 </template>
 
 <script>
-  export default {
-    setup() {
-      const count = ref(0)
+export default {
+  setup() {
+    const count = ref(0)
 
-      watchEffect(() => {
-        console.log(count.value)
-      })
+    watchEffect(() => {
+      console.log(count.value)
+    })
 
-      return {
-        count
-      }
+    return {
+      count
     }
   }
+}
 </script>
 ```
 
@@ -211,6 +213,39 @@ firstName.value = 'John' // logs: ["John", ""] ["", ""]
 lastName.value = 'Smith' // logs: ["John", "Smith"] ["John", ""]
 ```
 
+However, if you are changing both watched sources simultaneously in the same method, the watcher will be executed only once:
+
+```js{9-13}
+setup() {
+  const firstName = ref('')
+  const lastName = ref('')
+
+  watch([firstName, lastName], (newValues, prevValues) => {
+    console.log(newValues, prevValues)
+  })
+
+  const changeValues = () => {
+    firstName.value = 'John'
+    lastName.value = 'Smith'
+    // logs: ["John", "Smith"] ["", ""]
+  }
+
+  return { changeValues }
+}
+```
+
+Note that multiple synchronous changes will only trigger the watcher once.
+
+It is possible to force the watcher to trigger after every change by using the setting `flush: 'sync'`, though that isn't usually recommended. Alternatively, [nextTick](/api/global-api.html#nexttick) can be used to wait for the watcher to run before making further changes. e.g.:
+
+```js
+const changeValues = async () => {
+  firstName.value = 'John' // logs: ["John", ""] ["", ""]
+  await nextTick()
+  lastName.value = 'Smith' // logs: ["John", "Smith"] ["John", ""]
+}
+```
+
 ### リアクティブなオブジェクトの監視
 
 ウォッチャを使って、リアクティブな配列やオブジェクトの値を比較するには、値だけのコピーを作っておく必要があります。

From e4326ec318912c9dab80be802aa0420177245bd4 Mon Sep 17 00:00:00 2001
From: Evan You <yyx990803@gmail.com>
Date: Mon, 9 Aug 2021 15:54:34 -0400
Subject: [PATCH 2/9] 3.2 updates (#1157)

---
 src/.vuepress/config.js                   |  51 +++-
 src/api/computed-watch-api.md             |  35 ++-
 src/api/directives.md                     |  84 +++++--
 src/api/effect-scope.md                   |  59 +++++
 src/api/global-api.md                     |  64 ++++-
 src/api/reactivity-api.md                 |   1 +
 src/api/sfc-script-setup.md               | 292 ++++++++++++++++++++++
 src/api/sfc-spec.md                       | 139 ++++++++++
 src/api/sfc-style.md                      | 205 +++++++++++++++
 src/api/sfc-tooling.md                    |  94 +++++++
 src/guide/introduction.md                 |  12 +-
 src/guide/reactivity-computed-watchers.md |  49 ++--
 src/guide/single-file-component.md        | 196 ++++-----------
 src/guide/typescript-support.md           |   2 +-
 src/guide/web-components.md               | 243 ++++++++++++++++++
 15 files changed, 1327 insertions(+), 199 deletions(-)
 create mode 100644 src/api/effect-scope.md
 create mode 100644 src/api/sfc-script-setup.md
 create mode 100644 src/api/sfc-spec.md
 create mode 100644 src/api/sfc-style.md
 create mode 100644 src/api/sfc-tooling.md
 create mode 100644 src/guide/web-components.md

diff --git a/src/.vuepress/config.js b/src/.vuepress/config.js
index 2a756af2..67e2b171 100644
--- a/src/.vuepress/config.js
+++ b/src/.vuepress/config.js
@@ -80,6 +80,7 @@ const sidebar = {
       title: '高度な使い方',
       collapsable: false,
       children: [
+        '/guide/web-components',
         {
           title: 'リアクティビティ',
           children: [
@@ -106,7 +107,12 @@ const sidebar = {
     {
       title: 'スケールアップ',
       collapsable: false,
-      children: ['/guide/routing', '/guide/state-management', '/guide/ssr', '/guide/security']
+      children: [
+        '/guide/routing',
+        '/guide/state-management',
+        '/guide/ssr',
+        '/guide/security'
+      ]
     },
     {
       title: 'アクセシビリティ',
@@ -148,10 +154,33 @@ const sidebar = {
       children: [
         '/api/basic-reactivity',
         '/api/refs-api',
-        '/api/computed-watch-api'
+        '/api/computed-watch-api',
+        '/api/effect-scope',
       ]
     },
-    '/api/composition-api'
+    '/api/composition-api',
+    {
+      title: 'Single File Components',
+      collapsable: false,
+      children: [
+        {
+          title: 'Spec',
+          path: '/api/sfc-spec'
+        },
+        {
+          title: 'Tooling',
+          path: '/api/sfc-tooling'
+        },
+        {
+          title: '<script setup>',
+          path: '/api/sfc-script-setup'
+        },
+        {
+          title: '<style> Features',
+          path: '/api/sfc-style'
+        }
+      ]
+    }
   ],
   examples: [
     {
@@ -379,8 +408,7 @@ module.exports = {
               },
               {
                 text: 'Vue Test Utils',
-                link:
-                  'https://next.vue-test-utils.vuejs.org/guide/'
+                link: 'https://next.vue-test-utils.vuejs.org/guide/'
               },
               {
                 text: 'Devtools',
@@ -491,11 +519,18 @@ module.exports = {
           const date = new Date(timestamp)
 
           const digits = [
-            date.getUTCFullYear(), date.getUTCMonth() + 1, date.getUTCDate(),
-            date.getUTCHours(), date.getUTCMinutes(), date.getUTCSeconds()
+            date.getUTCFullYear(),
+            date.getUTCMonth() + 1,
+            date.getUTCDate(),
+            date.getUTCHours(),
+            date.getUTCMinutes(),
+            date.getUTCSeconds()
           ].map(num => String(num).padStart(2, '0'))
 
-          return '{0}-{1}-{2}, {3}:{4}:{5} UTC'.replace(/{(\d)}/g, (_, num) => digits[num])
+          return '{0}-{1}-{2}, {3}:{4}:{5} UTC'.replace(
+            /{(\d)}/g,
+            (_, num) => digits[num]
+          )
         }
       }
     ],
diff --git a/src/api/computed-watch-api.md b/src/api/computed-watch-api.md
index f691c730..29baa3d3 100644
--- a/src/api/computed-watch-api.md
+++ b/src/api/computed-watch-api.md
@@ -34,10 +34,31 @@ console.log(count.value) // 0
 
 ```ts
 // read-only
-function computed<T>(getter: () => T): Readonly<Ref<Readonly<T>>>
+function computed<T>(
+  getter: () => T,
+  debuggerOptions?: DebuggerOptions
+): Readonly<Ref<Readonly<T>>>
 
 // writable
-function computed<T>(options: { get: () => T; set: (value: T) => void }): Ref<T>
+function computed<T>(
+  options: {
+    get: () => T
+    set: (value: T) => void
+  },
+  debuggerOptions?: DebuggerOptions
+): Ref<T>
+
+interface DebuggerOptions {
+  onTrack?: (event: DebuggerEvent) => void
+  onTrigger?: (event: DebuggerEvent) => void
+}
+
+interface DebuggerEvent {
+  effect: ReactiveEffect
+  target: any
+  type: OperationTypes
+  key: string | symbol | undefined
+}
 ```
 
 ## `watchEffect`
@@ -84,9 +105,17 @@ type StopHandle = () => void
 
 **See also**: [`watchEffect` guide](../guide/reactivity-computed-watchers.html#watcheffect)
 
+## `watchPostEffect` <Badge text="3.2+" />
+
+Alias of `watchEffect` with `flush: 'post'` option.
+
+## `watchSyncEffect` <Badge text="3.2+" />
+
+Alias of `watchEffect` with `flush: 'sync'` option.
+
 ## `watch`
 
-The `watch` API is the exact equivalent of the Options API [this.$watch](./instance-methods.html#watch) (and the corresponding [watch](./options-data.html#watch) option). `watch` requires watching a specific data source and applies side effects in a separate callback function. It also is lazy by default - i.e. the callback is only called when the watched source has changed.
+The `watch` API is the exact equivalent of the Options API [this.\$watch](./instance-methods.html#watch) (and the corresponding [watch](./options-data.html#watch) option). `watch` requires watching a specific data source and applies side effects in a separate callback function. It also is lazy by default - i.e. the callback is only called when the watched source has changed.
 
 - Compared to [watchEffect](#watcheffect), `watch` allows us to:
 
diff --git a/src/api/directives.md b/src/api/directives.md
index 0bff3b91..8116c019 100644
--- a/src/api/directives.md
+++ b/src/api/directives.md
@@ -237,7 +237,7 @@
 
 ## v-bind
 
-- **Shorthand:** `:`
+- **Shorthand:** `:` or `.` (when using `.prop` modifier)
 
 - **Expects:** `any (with argument) | Object (without argument)`
 
@@ -246,6 +246,8 @@
 - **Modifiers:**
 
   - `.camel` - transform the kebab-case attribute name into camelCase.
+  - `.prop` - force a binding to be set as a DOM property. <Badge text="3.2+"/>
+  - `.attr` - force a binding to be set as a DOM attribute. <Badge text="3.2+"/>
 
 - **Usage:**
 
@@ -278,23 +280,34 @@
   <!-- class binding -->
   <div :class="{ red: isRed }"></div>
   <div :class="[classA, classB]"></div>
-  <div :class="[classA, { classB: isB, classC: isC }]">
-    <!-- style binding -->
-    <div :style="{ fontSize: size + 'px' }"></div>
-    <div :style="[styleObjectA, styleObjectB]"></div>
+  <div :class="[classA, { classB: isB, classC: isC }]"></div>
 
-    <!-- binding an object of attributes -->
-    <div v-bind="{ id: someProp, 'other-attr': otherProp }"></div>
+  <!-- style binding -->
+  <div :style="{ fontSize: size + 'px' }"></div>
+  <div :style="[styleObjectA, styleObjectB]"></div>
 
-    <!-- prop binding. "prop" must be declared in my-component. -->
-    <my-component :prop="someThing"></my-component>
+  <!-- binding an object of attributes -->
+  <div v-bind="{ id: someProp, 'other-attr': otherProp }"></div>
 
-    <!-- pass down parent props in common with a child component -->
-    <child-component v-bind="$props"></child-component>
+  <!-- prop binding. "prop" must be declared in my-component. -->
+  <my-component :prop="someThing"></my-component>
 
-    <!-- XLink -->
-    <svg><a :xlink:special="foo"></a></svg>
-  </div>
+  <!-- pass down parent props in common with a child component -->
+  <child-component v-bind="$props"></child-component>
+
+  <!-- XLink -->
+  <svg><a :xlink:special="foo"></a></svg>
+  ```
+
+  When setting a binding on an element, Vue by default checks whether the element has the key defined as a property using an `in` operator check. If the property is defined, Vue will set the value as a DOM property instead of an attribute. This should work in most cases, but you can override this behavior by explicitly using `.prop` or `.attr` modifiers. This is sometimes necessary, especially when [working with custom elements](/guide/web-components.html#passing-dom-properties).
+
+  The `.prop` modifier also has a dedicated shorthand, `.`:
+
+  ```html
+  <div :someProperty.prop="someObject"></div>
+
+  <!-- equivalent to -->
+  <div .someProperty="someObject"></div>
   ```
 
   The `.camel` modifier allows camelizing a `v-bind` attribute name when using in-DOM templates, e.g. the SVG `viewBox` attribute:
@@ -451,8 +464,51 @@
   </ul>
   ```
 
+  Since 3.2, you can also memoize part of the template with invalidation conditions using [`v-memo`](#v-memo).
+
 - **See also:**
   - [Data Binding Syntax - interpolations](../guide/template-syntax.html#text)
+  - [v-memo](#v-memo)
+
+## v-memo <Badge text="3.2+" />
+
+- **Expects:** `Array`
+
+- **Details:**
+
+  Memoize a sub-tree of the template. Can be used on both elements and components. The directive expects a fixed-length array of dependency values to compare for the memoization. If every value in the array was the same as last render, then updates for the entire sub-tree will be skipped. For example:
+
+  ```html
+  <div v-memo="[valueA, valueB]">
+    ...
+  </div>
+  ```
+
+  When the component re-renders, if both `valueA` and `valueB` remain the same, all updates for this `<div>` and its children will be skipped. In fact, even the Virtual DOM VNode creation will also be skipped since the memoized copy of the sub-tree can be reused.
+
+  It is important to specify the memoization array correctly, otherwise we may skip updates that should indeed be applied. `v-memo` with an empty dependency array (`v-memo="[]"`) would be functionally equivalent to `v-once`.
+
+  **Usage with `v-for`**
+
+  `v-memo` is provided solely for micro optimizations in performance-critical scenarios and should be rarely needed. The most common case where this may prove helpful is when rendering large `v-for` lists (where `length > 1000`):
+
+  ```html
+  <div v-for="item in list" :key="item.id" v-memo="[item.id === selected]">
+    <p>ID: {{ item.id }} - selected: {{ item.id === selected }}</p>
+    <p>...more child nodes</p>
+  </div>
+  ```
+
+  When the component's `selected` state changes, a large amount of VNodes will be created even though most of the items remained exactly the same. The `v-memo` usage here is essentially saying "only update this item if it went from non-selected to selected, or the other way around". This allows every unaffected item to reuse its previous VNode and skip diffing entirely. Note we don't need to include `item.id` in the memo dependency array here since Vue automatically infers it from the item's `:key`.
+
+  :::warning
+  When using `v-memo` with `v-for`, make sure they are used on the same element. **`v-memo` does not work inside `v-for`.**
+  :::
+
+  `v-memo` can also be used on components to manually prevent unwanted updates in certain edge cases where the child component update check has been de-optimized. But again, it is the developer's responsibility to specify correct dependency arrays to avoid skipping necessary updates.
+
+- **See also:**
+  - [v-once](#v-once)
 
 ## v-is <Badge text="deprecated" type="warning" />
 
diff --git a/src/api/effect-scope.md b/src/api/effect-scope.md
new file mode 100644
index 00000000..f154162e
--- /dev/null
+++ b/src/api/effect-scope.md
@@ -0,0 +1,59 @@
+# Effect Scope API <Badge text="3.2+" />
+
+:::info
+Effect scope is an advanced API primarily intended for library authors. For details on how to leverage this API, please consult its corresponding [RFC](https://github.com/vuejs/rfcs/blob/master/active-rfcs/0041-reactivity-effect-scope.md).
+:::
+
+## `effectScope`
+
+Creates an effect scope object which can capture the reactive effects (e.g. computed and watchers) created within it so that these effects can be disposed together.
+
+**Typing:**
+
+```ts
+function effectScope(detached?: boolean): EffectScope
+
+interface EffectScope {
+  run<T>(fn: () => T): T | undefined // undefined if scope is inactive
+  stop(): void
+}
+```
+
+**Example:**
+
+```js
+const scope = effectScope()
+
+scope.run(() => {
+  const doubled = computed(() => counter.value * 2)
+
+  watch(doubled, () => console.log(doubled.value))
+
+  watchEffect(() => console.log('Count: ', doubled.value))
+})
+
+// to dispose all effects in the scope
+scope.stop()
+```
+
+## `getCurrentScope`
+
+Returns the current active [effect scope](#effectscope) if there is one.
+
+**Typing:**
+
+```ts
+function getCurrentScope(): EffectScope | undefined
+```
+
+## `onScopeDispose`
+
+Registers a dispose callback on the current active [effect scope](#effectscope). The callback will be invoked when the associated effect scope is stopped.
+
+This method can be used as a non-component-coupled replacement of `onUnmounted` in reusable composition functions, since each Vue component's `setup()` function is also invoked in an effect scope.
+
+**Typing:**
+
+```ts
+function onScopeDispose(fn: () => void): void
+```
diff --git a/src/api/global-api.md b/src/api/global-api.md
index 6297d9e4..ce87a7a4 100644
--- a/src/api/global-api.md
+++ b/src/api/global-api.md
@@ -236,6 +236,44 @@ const AsyncComp = defineAsyncComponent({
 
 **参照**: [動的 & 非同期コンポーネント](../guide/component-dynamic-async.html)
 
+## defineCustomElement <Badge text="3.2+" />
+
+This method accepts the same argument as [`defineComponent`](#definecomponent), but instead returns a native [Custom Element](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_custom_elements) that can be used within any framework, or with no frameworks at all.
+
+Usage example:
+
+```html
+<my-vue-element></my-vue-element>
+```
+
+```js
+import { defineCustomElement } from 'vue'
+
+const MyVueElement = defineCustomElement({
+  // normal Vue component options here
+  props: {},
+  emits: {},
+  template: `...`,
+
+  // defineCustomElement only: CSS to be injected into shadow root
+  styles: [`/* inlined css */`]
+})
+
+// Register the custom element.
+// After registration, all `<my-vue-element>` tags on the page will be upgraded.
+customElements.define('my-vue-element', MyVueElement)
+
+// You can also programmatically instantiate the element:
+// (can only be done after registration)
+document.body.appendChild(
+  new MyVueElement({
+    // initial props (optional)
+  })
+)
+```
+
+For more details on building Web Components with Vue, especially with Single File Components, see [Vue and Web Components](/guide/web-components.html#building-custom-elements-with-vue).
+
 ## resolveComponent
 
 :::warning
@@ -481,10 +519,13 @@ export default {
   inheritAttrs: false,
 
   render() {
-    const props = mergeProps({
-      // class は $attrs の class とマージされます
-      class: 'active'
-    }, this.$attrs)
+    const props = mergeProps(
+      {
+        // class は $attrs の class とマージされます
+        class: 'active'
+      },
+      this.$attrs
+    )
 
     return h('div', props)
   }
@@ -504,12 +545,17 @@ export default {
 import { h, useCssModule } from 'vue'
 
 export default {
-  setup () {
+  setup() {
     const style = useCssModule()
 
-    return () => h('div', {
-      class: style.success
-    }, 'Task complete!')
+    return () =>
+      h(
+        'div',
+        {
+          class: style.success
+        },
+        'Task complete!'
+      )
   }
 }
 </script>
@@ -521,7 +567,7 @@ export default {
 </style>
 ```
 
-CSS モジュールの使い方について詳しくは、 [Vue Loader - CSS Modules](https://vue-loader.vuejs.org/guide/css-modules.html) を参照してください。
+CSS モジュールの使い方について詳しくは、[SFC Style Features: `<style module>`](/api/sfc-style.html#style-module) を参照してください。
 
 ### 引数
 
diff --git a/src/api/reactivity-api.md b/src/api/reactivity-api.md
index e73a34a3..56c453e8 100644
--- a/src/api/reactivity-api.md
+++ b/src/api/reactivity-api.md
@@ -5,3 +5,4 @@
 - [Basic Reactivity APIs](/api/basic-reactivity.html)
 - [Refs](/api/refs-api.html)
 - [Computed and watch](/api/computed-watch-api.html)
+- [Effect Scope API](/api/effect-scope.html)
\ No newline at end of file
diff --git a/src/api/sfc-script-setup.md b/src/api/sfc-script-setup.md
new file mode 100644
index 00000000..a775ebf4
--- /dev/null
+++ b/src/api/sfc-script-setup.md
@@ -0,0 +1,292 @@
+---
+sidebarDepth: 1
+---
+
+# SFC `<script setup>`
+
+`<script setup>` is a compile-time syntactic sugar for using [Composition API](/api/composition-api.html) inside Single File Components (SFCs). It is the recommended syntax if you are using both SFCs and Composition API. It provides a number of advantages over the normal `<script>` syntax:
+
+- More succinct code with less boilerplate
+- Ability to declare props and emitted events using pure TypeScript
+- Better runtime performance (the template is compiled into a render function in the same scope, without an intermediate proxy)
+- Better IDE type-inference performance (less work for the language server to extract types from code)
+
+## Basic Syntax
+
+To opt-in to the syntax, add the `setup` attribute to the `<script>` block:
+
+```vue
+<script setup>
+console.log('hello script setup')
+</script>
+```
+
+The code inside is compiled as the content of the component's `setup()` function. This means that unlike normal `<script>`, which only executes once when the component is first imported, code inside `<script setup>` will **execute every time an instance of the component is created**.
+
+### Top-level bindings are exposed to template
+
+When using `<script setup>`, any top-level bindings (including variables, function declarations, and imports) declared inside `<script setup>` are directly usable in the template:
+
+```vue
+<script setup>
+// variable
+const msg = 'Hello!'
+
+// functions
+function log() {
+  console.log(msg)
+}
+</script>
+
+<template>
+  <div @click="log">{{ msg }}</div>
+</template>
+```
+
+Imports are exposed in the same fashion. This means you can directly use an imported helper function in template expressions without having to expose it via the `methods` option:
+
+```vue
+<script setup>
+import { capitalize } from './helpers'
+</script>
+
+<template>
+  <div>{{ capitalize('hello') }}</div>
+</template>
+```
+
+## Reactivity
+
+Reactive state needs to be explicitly created using [Reactivity APIs](/api/basic-reactivity.html). Similar to values returned from a `setup()` function, refs are automatically unwrapped when referenced in templates:
+
+```vue
+<script setup>
+import { ref } from 'vue'
+
+const count = ref(0)
+</script>
+
+<template>
+  <button @click="count++">{{ count }}</button>
+</template>
+```
+
+## Using Components
+
+Values in the scope of `<script setup>` can also be used directly as custom component tag names:
+
+```vue
+<script setup>
+import MyComponent from './MyComponent.vue'
+</script>
+
+<template>
+  <MyComponent />
+</template>
+```
+
+Think of `MyComponent` as being referenced as a variable. If you have used JSX, the mental model is similar here. The kebab-case equivalent `<my-component>` also works in the template - however PascalCase component tags are strongly recommended for consistency. It also helps differentiating from native custom elements.
+
+### Dynamic Components
+
+Since components are referenced as variables instead of registered under string keys, we should use dynamic `:is` binding when using dynamic components inside `<script setup>`:
+
+```vue
+<script setup>
+import Foo from './Foo.vue'
+import Bar from './Bar.vue'
+</script>
+
+<template>
+  <component :is="Foo" />
+  <component :is="someCondition ? Foo : Bar" />
+</template>
+```
+
+Note how the components can be used as variables in a ternary expression.
+
+### Recursive Components
+
+An SFC can implicitly refer to itself via its filename. E.g. a file named `FooBar.vue` can refer to itself as `<FooBar/>` in its template.
+
+Note this has lower priority than imported components. If you have a named import that conflicts with the component's inferred name, you can alias the import:
+
+```js
+import { FooBar as FooBarChild } from './components'
+```
+
+### Namespaced Components
+
+You can use component tags with dots like `<Foo.Bar>` to refer to components nested under object properties. This is useful when you import multiple components from a single file:
+
+```vue
+<script setup>
+import * as Form from './form-components'
+</script>
+
+<template>
+  <Form.Input>
+    <Form.Label>label</Form.Label>
+  </Form.Input>
+</template>
+```
+
+## `defineProps` and `defineEmits`
+
+To declare options like `props` and `emits` with full type inference support, we can use the `defineProps` and `defineEmits` APIs, which are automatically available inside `<script setup>`:
+
+```vue
+<script setup>
+const props = defineProps({
+  foo: String
+})
+
+const emit = defineEmits(['change', 'delete'])
+// setup code
+</script>
+```
+
+- `defineProps` and `defineEmits` are **compiler macros** only usable inside `<script setup>`. They do not need to be imported, and are compiled away when `<script setup>` is processed.
+
+- `defineProps` accepts the same value as the `props` option, while `defineEmits` accepts the same value as the `emits` option.
+
+- `defineProps` and `defineEmits` provide proper type inference based on the options passed.
+
+- The options passed to `defineProps` and `defineEmits` will be hoisted out of setup into module scope. Therefore, the options cannot reference local variables declared in setup scope. Doing so will result in a compile error. However, it _can_ reference imported bindings since they are in the module scope as well.
+
+If you are using TypeScript, it is also possible to [declare props and emits using pure type annotations](#typescript-only-features).
+
+## `defineExpose`
+
+Components using `<script setup>` are **closed by default** - i.e. the public instance of the component, which is retrieved via template refs or `$parent` chains, will **not** expose any of the bindings declared inside `<script setup>`.
+
+To explicitly expose properties in a `<script setup>` component, use the `defineExpose` compiler macro:
+
+```vue
+<script setup>
+import { ref } from 'vue'
+
+const a = 1
+const b = ref(2)
+
+defineExpose({
+  a,
+  b
+})
+</script>
+```
+
+When a parent gets an instance of this component via template refs, the retrieved instance will be of the shape `{ a: number, b: number }` (refs are automatically unwrapped just like on normal instances).
+
+## `useSlots` and `useAttrs`
+
+Usage of `slots` and `attrs` inside `<script setup>` should be relatively rare, since you can access them directly as `$slots` and `$attrs` in the template. In the rare case where you do need them, use the `useSlots` and `useAttrs` helpers respectively:
+
+```vue
+<script setup>
+import { useSlots, useAttrs } from 'vue'
+
+const slots = useSlots()
+const attrs = useAttrs()
+</script>
+```
+
+`useSlots` and `useAttrs` are actual runtime functions that return the equivalent of `setupContext.slots` and `setupContext.attrs`. They can be used in normal composition API functions as well.
+
+## Usage alongside normal `<script>`
+
+`<script setup>` can be used alongside normal `<script>`. A normal `<script>` may be needed in cases where we need to:
+
+- Declare options that cannot be expressed in `<script setup>`, for example `inheritAttrs` or custom options enabled via plugins.
+- Declaring named exports.
+- Run side effects or create objects that should only execute once.
+
+```vue
+<script>
+// normal <script>, executed in module scope (only once)
+runSideEffectOnce()
+
+// declare additional options
+export default {
+  inheritAttrs: false,
+  customOptions: {}
+}
+</script>
+
+<script setup>
+// executed in setup() scope (for each instance)
+</script>
+```
+
+## Top-level `await`
+
+Top-level `await` can be used inside `<script setup>`. The resulting code will be compiled as `async setup()`:
+
+```vue
+<script setup>
+const post = await fetch(`/api/post/1`).then(r => r.json())
+</script>
+```
+
+In addition, the awaited expression will be automatically compiled in a format that preserves the current component instance context after the `await`.
+
+:::warning Note
+`async setup()` must be used in combination with `Suspense`, which is currently still an experimental feature. We plan to finalize and document it in a future release - but if you are curious now, you can refer to its [tests](https://github.com/vuejs/vue-next/blob/master/packages/runtime-core/__tests__/components/Suspense.spec.ts) to see how it works.
+:::
+
+## TypeScript-only Features
+
+### Type-only props/emit declarations
+
+Props and emits can also be declared using pure-type syntax by passing a literal type argument to `defineProps` or `defineEmits`:
+
+```ts
+const props = defineProps<{
+  foo: string
+  bar?: number
+}>()
+
+const emit = defineEmits<{
+  (e: 'change', id: number): void
+  (e: 'update', value: string): void
+}>()
+```
+
+- `defineProps` or `defineEmits` can only use either runtime declaration OR type declaration. Using both at the same time will result in a compile error.
+
+- When using type declaration, the equivalent runtime declaration is automatically generated from static analysis to remove the need for double declaration and still ensure correct runtime behavior.
+
+  - In dev mode, the compiler will try to infer corresponding runtime validation from the types. For example here `foo: String` is inferred from the `foo: string` type. If the type is a reference to an imported type, the inferred result will be `foo: null` (equal to `any` type) since the compiler does not have information of external files.
+
+  - In prod mode, the compiler will generate the array format declaration to reduce bundle size (the props here will be compiled into `['foo', 'bar']`)
+
+  - The emitted code is still TypeScript with valid typing, which can be further processed by other tools.
+
+- As of now, the type declaration argument must be one of the following to ensure correct static analysis:
+
+  - A type literal
+  - A reference to an interface or a type literal in the same file
+
+  Currently complex types and type imports from other files are not supported. It is theoretically possible to support type imports in the future.
+
+### Default props values when using type declaration
+
+One drawback of the type-only `defineProps` declaration is that it doesn't have a way to provide default values for the props. To resolve this problem, a `withDefaults` compiler macro is also provided:
+
+```ts
+interface Props {
+  msg?: string
+  labels?: string[]
+}
+
+const props = withDefaults(defineProps<Props>(), {
+  msg: 'hello',
+  labels: () => ['one', 'two']
+})
+```
+
+This will be compiled to equivalent runtime props `default` options. In addition, the `withDefaults` helper provides type checks for the default values, and ensures the returned `props` type has the optional flags removed for properties that do have default values declared.
+
+## Restriction: No Src Imports
+
+Due to the difference in module execution semantics, code inside `<script setup>` relies on the context of an SFC. When moved into external `.js` or `.ts` files, it may lead to confusion for both developers and tools. Therefore, **`<script setup>`** cannot be used with the `src` attribute.
diff --git a/src/api/sfc-spec.md b/src/api/sfc-spec.md
new file mode 100644
index 00000000..bf198be6
--- /dev/null
+++ b/src/api/sfc-spec.md
@@ -0,0 +1,139 @@
+# SFC Syntax Specification
+
+## Intro
+
+A `*.vue` file is a custom file format that uses HTML-like syntax to describe a Vue component. Each `*.vue` file consists of three types of top-level language blocks: `<template>`, `<script>`, and `<style>`, and optionally additional custom blocks:
+
+```vue
+<template>
+  <div class="example">{{ msg }}</div>
+</template>
+
+<script>
+export default {
+  data() {
+    return {
+      msg: 'Hello world!'
+    }
+  }
+}
+</script>
+
+<style>
+.example {
+  color: red;
+}
+</style>
+
+<custom1>
+  This could be e.g. documentation for the component.
+</custom1>
+```
+
+## Language Blocks
+
+### `<template>`
+
+- Each `*.vue` file can contain at most one `<template>` block at a time.
+
+- Contents will be extracted and passed on to `@vue/compiler-dom`, pre-compiled into JavaScript render functions, and attached to the exported component as its `render` option.
+
+### `<script>`
+
+- Each `*.vue` file can contain at most one `<script>` block at a time (excluding [`<script setup>`](/api/sfc-script-setup.html)).
+
+- The script is executed as an ES Module.
+
+- The **default export** should be a Vue component options object, either as a plain object or as the return value of [defineComponent](/api/global-api.html#definecomponent).
+
+### `<script setup>`
+
+- Each `*.vue` file can contain at most one `<script setup>` block at a time (excluding normal `<script>`).
+
+- The script is pre-processed and used as the component's `setup()` function, which means it will be executed **for each instance of the component**. Top-level bindings in `<script setup>` are automatically exposed to the template. For more details, see [dedicated documentation on `<script setup>`](/api/sfc-script-setup).
+
+### `<style>`
+
+- A single `*.vue` file can contain multiple `<style>` tags.
+
+- A `<style>` tag can have `scoped` or `module` attributes (see [SFC Style Features](/api/sfc-style) for more details) to help encapsulate the styles to the current component. Multiple `<style>` tags with different encapsulation modes can be mixed in the same component.
+
+### Custom Blocks
+
+Additional custom blocks can be included in a `*.vue` file for any project-specific needs, for example a `<docs>` block. Some real-world examples of custom blocks include:
+
+- [Gridsome: `<page-query>`](https://gridsome.org/docs/querying-data/)
+- [vite-plugin-vue-gql: `<gql>`](https://github.com/wheatjs/vite-plugin-vue-gql)
+- [vue-i18n: `<i18n>`](https://github.com/intlify/bundle-tools/tree/main/packages/vite-plugin-vue-i18n#i18n-custom-block)
+
+Handling of Custom Blocks will depend on tooling - if you want to build your own custom block integrations, see [SFC Tooling](/api/sfc-tooling.html#custom-blocks-integration) for more details.
+
+## Automatic `name` Inference
+
+An SFC automatically infers the component's name from its **filename** in the following cases:
+
+- Dev warning formatting
+- DevTools inspection
+- Recursive self-reference. E.g. a file named `FooBar.vue` can refer to itself as `<FooBar/>` in its template. This has lower priority than explicity registered/imported components.
+
+## Pre-Processors
+
+Blocks can declare pre-processor languages using the `lang` attribute. The most common case is using TypeScript for the `<script>` block:
+
+```html
+<script lang="ts">
+  // use TypeScript
+</script>
+```
+
+`lang` can be applied to any block - for example we can use `<style>` with [SASS](https://sass-lang.com/) and `<template>` with [Pug](https://pugjs.org/api/getting-started.html):
+
+```html
+<template lang="pug">
+p {{ msg }}
+</template>
+
+<style lang="scss">
+  $primary-color: #333;
+  body {
+    color: $primary-color;
+  }
+</style>
+```
+
+Note the intergration with pre-processors may differ based on the toolchain. Check out the respective documentations for examples:
+
+- [Vite](https://vitejs.dev/guide/features.html#css-pre-processors)
+- [Vue CLI](https://cli.vuejs.org/guide/css.html#pre-processors)
+- [webpack + vue-loader](https://vue-loader.vuejs.org/guide/pre-processors.html#using-pre-processors)
+
+## Src Imports
+
+If you prefer splitting up your `*.vue` components into multiple files, you can use the `src` attribute to import an external file for a language block:
+
+```vue
+<template src="./template.html"></template>
+<style src="./style.css"></style>
+<script src="./script.js"></script>
+```
+
+Beware that `src` imports follow the same path resolution rules as webpack module requests, which means:
+
+- Relative paths need to start with `./`
+- You can import resources from npm dependencies:
+
+```vue
+<!-- import a file from the installed "todomvc-app-css" npm package -->
+<style src="todomvc-app-css/index.css">
+```
+
+`src` imports also work with custom blocks, e.g.:
+
+```vue
+<unit-test src="./unit-test.js">
+</unit-test>
+```
+
+## Comments
+
+Inside each block you shall use the comment syntax of the language being used (HTML, CSS, JavaScript, Pug, etc.). For top-level comments, use HTML comment syntax: `<!-- comment contents here -->`
diff --git a/src/api/sfc-style.md b/src/api/sfc-style.md
new file mode 100644
index 00000000..ceb26c37
--- /dev/null
+++ b/src/api/sfc-style.md
@@ -0,0 +1,205 @@
+---
+sidebarDepth: 1
+---
+
+# SFC Style Features
+
+## `<style scoped>`
+
+When a `<style>` tag has the `scoped` attribute, its CSS will apply to elements of the current component only. This is similar to the style encapsulation found in Shadow DOM. It comes with some caveats, but doesn't require any polyfills. It is achieved by using PostCSS to transform the following:
+
+```vue
+<style scoped>
+.example {
+  color: red;
+}
+</style>
+
+<template>
+  <div class="example">hi</div>
+</template>
+```
+
+Into the following:
+
+```vue
+<style>
+.example[data-v-f3f3eg9] {
+  color: red;
+}
+</style>
+
+<template>
+  <div class="example" data-v-f3f3eg9>hi</div>
+</template>
+```
+
+### Child Component Root Elements
+
+With `scoped`, the parent component's styles will not leak into child components. However, a child component's root node will be affected by both the parent's scoped CSS and the child's scoped CSS. This is by design so that the parent can style the child root element for layout purposes.
+
+### Deep Selectors
+
+If you want a selector in `scoped` styles to be "deep", i.e. affecting child components, you can use the `:deep()` pseudo-class:
+
+```vue
+<style scoped>
+.a :deep(.b) {
+  /* ... */
+}
+</style>
+```
+
+The above will be compiled into:
+
+```css
+.a[data-v-f3f3eg9] .b {
+  /* ... */
+}
+```
+
+:::tip
+DOM content created with `v-html` are not affected by scoped styles, but you can still style them using deep selectors.
+:::
+
+### Slotted Selectors
+
+By default, scoped styles do not affect contents rendered by `<slot/>`, as they are considered to be owned by the parent component passing them in. To explicitly target slot content, use the `:slotted` pseudo-class:
+
+```vue
+<style scoped>
+:slotted(div) {
+  color: red;
+}
+</style>
+```
+
+### Global Selectors
+
+If you want just one rule to apply globally, you can use the `:global` pseudo-class rather than creating another `<style>` (see below):
+
+```vue
+<style scoped>
+:global(.red) {
+  color: red;
+}
+</style>
+```
+
+### Mixing Local and Global Styles
+
+You can also include both scoped and non-scoped styles in the same component:
+
+```vue
+<style>
+/* global styles */
+</style>
+
+<style scoped>
+/* local styles */
+</style>
+```
+
+### Scoped Style Tips
+
+- **Scoped styles do not eliminate the need for classes**. Due to the way browsers render various CSS selectors, `p { color: red }` will be many times slower when scoped (i.e. when combined with an attribute selector). If you use classes or ids instead, such as in `.example { color: red }`, then you virtually eliminate that performance hit.
+
+- **Be careful with descendant selectors in recursive components!** For a CSS rule with the selector `.a .b`, if the element that matches `.a` contains a recursive child component, then all `.b` in that child component will be matched by the rule.
+
+## `<style module>`
+
+A `<style module>` tag is compiled as [CSS Modules](https://github.com/css-modules/css-modules) and exposes the resulting CSS classes to the component as an object under the key of `$style`:
+
+```vue
+<template>
+  <p :class="$style.red">
+    This should be red
+  </p>
+</template>
+
+<style module>
+.red {
+  color: red;
+}
+</style>
+```
+
+The resulting classes are hashed to avoid collision, achieving the same effect of scoping the CSS to the current component only.
+
+Refer to the [CSS Modules spec](https://github.com/css-modules/css-modules) for mode details such as [global exceptions](https://github.com/css-modules/css-modules#exceptions) and [composition](https://github.com/css-modules/css-modules#composition).
+
+### Custom Inject Name
+
+You can customize the property key of the injected classes object by giving the `module` attribute a value:
+
+```vue
+<template>
+  <p :class="classes.red">red</p>
+</template>
+
+<style module="classes">
+.red {
+  color: red;
+}
+</style>
+```
+
+### Usage with Composition API
+
+The injected classes can be accessed in `setup()` and `<script setup>` via the [`useCssModule`](/api/global-api.html#usecssmodule) API. For `<style module>` blocks with custom injection names, `useCssModule` accepts the matching `module` attribute value as the first argument:
+
+```js
+// default, returns classes for <style module>
+useCssModule()
+
+// named, returns classes for <style module="classes">
+useCssModule('classes')
+```
+
+## State-Driven Dynamic CSS
+
+SFC `<style>` tags support linking CSS values to dynamic component state using the `v-bind` CSS function:
+
+```vue
+<template>
+  <div class="text">hello</div>
+</template>
+
+<script>
+export default {
+  data() {
+    return {
+      color: 'red'
+    }
+  }
+}
+</script>
+
+<style>
+.text {
+  color: v-bind(color);
+}
+</style>
+```
+
+The syntax works with [`<script setup>`](./sfc-script-setup), and supports JavaScript expressions (must be wrapped in quotes):
+
+```vue
+<script setup>
+const theme = {
+  color: 'red'
+}
+</script>
+
+<template>
+  <p>hello</p>
+</template>
+
+<style scoped>
+p {
+  color: v-bind('theme.color');
+}
+</style>
+```
+
+The actual value will be compiled into a hashed CSS custom property, so the CSS is still static. The custom property will be applied to the component's root element via inline styles and reactively updated if the source value changes.
diff --git a/src/api/sfc-tooling.md b/src/api/sfc-tooling.md
new file mode 100644
index 00000000..f38bc592
--- /dev/null
+++ b/src/api/sfc-tooling.md
@@ -0,0 +1,94 @@
+# SFC Tooling
+
+## Online Playgrounds
+
+You don't need to install anything on your machine to try out Vue SFCs - there are many online playgrounds that allow you to do so right in the browser:
+
+- [Vue SFC Playground](https://sfc.vuejs.org) (official, deployed from latest commit)
+- [VueUse Playground](https://play.vueuse.org)
+- [Vue on CodeSandbox](https://codesandbox.io/s/vue-3)
+- [Vue on Repl.it](https://replit.com/@templates/VueJS-with-Vite)
+- [Vue on Codepen](https://codepen.io/pen/editor/vue)
+- [Vue on StackBlitz](https://stackblitz.com/fork/vue)
+
+It is also recommended to use these online playgrounds to provide reproductions when reporting bugs.
+
+## Project Scaffolding
+
+### Vite
+
+[Vite](https://vitejs.dev/) is a lightweight and fast build tool with first-class Vue SFC support. It is created by Evan You, who is also the author of Vue itself! To get started with Vite + Vue, simply run:
+
+```sh
+npm init vite@latest
+```
+
+Then select the Vue template and follow the instructions.
+
+- To learn more about Vite, check out the [Vite docs](https://vitejs.dev/guide/).
+- To configure Vue-specific behavior in a Vite project, for example passing options to the Vue compiler, check out the docs for [@vitejs/plugin-vue](https://github.com/vitejs/vite/tree/main/packages/plugin-vue#readme).
+
+The [SFC Playground](https://sfc.vuejs.org/) also supports downloading the files as a Vite project.
+
+### Vue CLI
+
+[Vue CLI](https://cli.vuejs.org/) is the official webpack-based build tool for Vue projects. To get started with Vue CLI:
+
+```sh
+npm install -g @vue/cli
+vue create hello-vue
+```
+
+- To learn more about Vue CLI, check out [Vue CLI docs](https://cli.vuejs.org/guide/installation.html).
+
+### Vite or Vue CLI?
+
+We recommend starting new projects with Vite as it offers significantly better development experience in terms of dev server startup and HMR update performance ([details](https://vitejs.dev/guide/why.html)). Only go with Vue CLI if you rely on specific webpack features (e.g. Module Federation).
+
+If you are a [Rollup](https://rollupjs.org/) user, you can safely adopt Vite as it uses Rollup for production builds and supports a Rollup-compatible plugin system. [Even Rollup's maintainer recommends Vite as THE web development wrapper for Rollup](https://twitter.com/lukastaegert/status/1412119729431584774).
+
+## IDE Support
+
+The recommended IDE setup is [VSCode](https://code.visualstudio.com/) + the [Volar](https://github.com/johnsoncodehk/volar) extension. Volar provides syntax highlighting and advanced IntelliSense for template expressions, component props and even slots validation. We strongly recommend this setup if you want to get the best possible experience with Vue SFCs, especially if you are also using TypeScript.
+
+[WebStorm](https://www.jetbrains.com/webstorm/) also provides decent support for Vue SFCs. However, do note as of now its support for `<script setup>` is still [in progress](https://youtrack.jetbrains.com/issue/WEB-49000).
+
+Most other editors have community-created syntax highlighting support for Vue, but lack the same level of code IntelliSense. In the long run, we do hope we can extend the range of editor support by leveraging the [Language Service Protocol](https://microsoft.github.io/language-server-protocol/) as Volar's core logic is implemented as a standard language server.
+
+## Testing Support
+
+- If using Vite, we recommend [Cypress](https://www.cypress.io/) as the test runner for both unit and e2e tests. Unit tests for Vue SFCs can be done with the [Cypress Component Test Runner](https://www.cypress.io/blog/2021/04/06/introducing-the-cypress-component-test-runner/).
+
+- Vue CLI comes with [Jest](https://jestjs.io/) and [Mocha](https://mochajs.org/) integrations.
+
+- If you are manually configuring Jest to work with Vue SFCs, check out [vue-jest](https://github.com/vuejs/vue-jest) which is the official Jest transform for Vue SFCs.
+
+## Custom Blocks Integration
+
+Custom blocks are compiled into imports to the same Vue file with different request queries. It is up to the underlying build tool to handle these import requests.
+
+- If using Vite, a custom Vite plugin should be used to transform matched custom blocks into executable JavaScript. [[Example](https://github.com/vitejs/vite/tree/main/packages/plugin-vue#example-for-transforming-custom-blocks)]
+
+- If using Vue CLI or plain webpack, a webpack loader should be configured to transform the matched blocks. [[Example](https://vue-loader.vuejs.org/guide/custom-blocks.html#custom-blocks)]
+
+## Lower-Level Tools
+
+### `@vue/compiler-sfc`
+
+- [Docs](https://github.com/vuejs/vue-next/tree/master/packages/compiler-sfc)
+
+This package is part of the Vue core monorepo and is always published with the same version as the main `vue` package. Typically, it will be listed as a peer dependency of `vue` in a project. To ensure correct behavior, its version should always be kept in-sync with `vue` - i.e. whenever you upgrade the version of `vue`, you should also upgrade `@vue/compiler-sfc` to match it.
+
+The package itself provides lower-level utilities for processing Vue SFCs and is only meant for tooling authors that need to support Vue SFCs in custom tools.
+
+### `@vitejs/plugin-vue`
+
+- [Docs](https://github.com/vitejs/vite/tree/main/packages/plugin-vue)
+
+Official plugin that provides Vue SFC support in Vite.
+
+### `vue-loader`
+
+- [Docs](https://vue-loader.vuejs.org/)
+
+The official loader that provides Vue SFC support in webpack. If you are using Vue CLI, also see [docs on modifying `vue-loader` options in Vue CLI](https://cli.vuejs.org/guide/webpack.html#modifying-options-of-a-loader).
diff --git a/src/guide/introduction.md b/src/guide/introduction.md
index da924200..2350c86e 100644
--- a/src/guide/introduction.md
+++ b/src/guide/introduction.md
@@ -300,7 +300,7 @@ app.mount('#todo-list-app')
 
 このサンプルは不自然ではありますが、アプリケーションをより小さな単位に分割することに成功し、またプロパティのインターフェイスによって子コンポーネントは適切に疎結合な状態になりました。ここからさらに `<todo-item>` コンポーネントを、より複雑なテンプレートやロジックを使って、親コンポーネントに影響を与えることなく改良することができます。
 
-大規模なアプリケーションでは、開発をおこないやすくするために、アプリケーション全体をコンポーネントに分割することが必要です。コンポーネントについては[ガイドの後半](component-basics.md)でより詳しく述べますが、コンポーネントを使ったアプリケーションのテンプレートがどういうものになるか、(架空の)例をここに載せておきます:
+大規模なアプリケーションでは、開発をおこないやすくするために、アプリケーション全体をコンポーネントに分割することが必要です。コンポーネントについては[ガイドの後半](component-basics.html)でより詳しく述べますが、コンポーネントを使ったアプリケーションのテンプレートがどういうものになるか、(架空の)例をここに載せておきます:
 
 ```html
 <div id="app">
@@ -314,15 +314,11 @@ app.mount('#todo-list-app')
 
 ### カスタム要素との関係
 
-Vue のコンポーネントが [Web Components 仕様](https://www.w3.org/wiki/WebComponents/) の一部である **カスタム要素 (Custom Elements)** によく似ていることに気付いたかもしれません。これは Vue のコンポーネント構文はその仕様を手本にしているためです。例えば、Vue コンポーネントは [Slot API](https://github.com/w3c/webcomponents/blob/gh-pages/proposals/Slots-Proposal.md) と `is` という特別な属性を実装しています。しかしながら、いくつか重要な違いがあります:
+Vue のコンポーネントが [Web Components 仕様](https://www.w3.org/wiki/WebComponents/) の一部である **カスタム要素 (Custom Elements)** に似ていることに気付いたかもしれません。実際、Vue のコンポーネント設計の一部（例えばスロット API）は、ブラウザにネイティブ実装される前の仕様に影響を受けています。
 
-1. Web Components の仕様は確定しましたが、全てのブラウザにネイティブ実装されているわけではありません。Safari 10.1 以上、Chrome 54 以上、Firefox 63 以上が Web Components をネイティブでサポートしています。一方、Vue コンポーネントは、サポートされる全てのブラウザ（Internet Explorer 11 を除く - 詳細は [こちら](https://github.com/vuejs/rfcs/blob/master/active-rfcs/0038-vue3-ie11-support.md) を確認してください）で同じ動作をします。必要があれば、Vue コンポーネントはネイティブなカスタム要素内に含めることもできます。
+主な違いは、Vue のコンポーネントモデルが小さくはないアプリケーションを構築するために必要な多くの追加機能を提供する一貫したフレームワークの一部として設計されていることです。例えば、リアクティブなテンプレート作成や状態管理など、どちらも仕様書では取り扱われていません。
 
-[//]: # 'TODO: link to compatibility build'
-
-2. Vue コンポーネントは、通常のカスタム要素では利用できない重要な機能、中でもクロスコンポーネントデータフロー、カスタムイベント通信やビルドツールとの統合といったものを提供します。
-
-Vue は内部的にはカスタム要素を使っていませんが、カスタム要素として使用または配布する場合に [優れた相互運用性](https://custom-elements-everywhere.com/#vue) があります。Vue CLI では、それ自身をネイティブのカスタム要素として登録するような Vue コンポーネントの構築もサポートしています。
+また、Vue はカスタム要素の実行と作成の両方に優れたサポートを提供しています。詳細については、[Vue and Web Components](/guide/web-components.html) のセクションをご覧ください。
 
 ## 準備ができましたか？
 
diff --git a/src/guide/reactivity-computed-watchers.md b/src/guide/reactivity-computed-watchers.md
index 0efa04f0..d620a772 100644
--- a/src/guide/reactivity-computed-watchers.md
+++ b/src/guide/reactivity-computed-watchers.md
@@ -30,6 +30,36 @@ plusOne.value = 1
 console.log(count.value) // 0
 ```
 
+### Computed Debugging <Badge text="3.2+" />
+
+`computed` accepts a second argument with `onTrack` and `onTrigger` options:
+
+- `onTrack` will be called when a reactive property or ref is tracked as a dependency.
+- `onTrigger` will be called when the watcher callback is triggered by the mutation of a dependency.
+
+Both callbacks will receive a debugger event which contains information on the dependency in question. It is recommended to place a `debugger` statement in these callbacks to interactively inspect the dependency:
+
+```js
+const plusOne = computed(() => count.value + 1, {
+  onTrack(e) {
+    // triggered when count.value is tracked as a dependency
+    debugger
+  },
+  onTrigger(e) {
+    // triggered when count.value is mutated
+    debugger
+  }
+})
+
+// access plusOne, should trigger onTrack
+console.log(plusOne.value)
+
+// mutate count.value, should trigger onTrigger
+count.value++
+```
+
+`onTrack` and `onTrigger` only work in development mode.
+
 ## `watchEffect`
 
 リアクティブの状態に応じて、作用を *自動的に適用しなおす* ために、`watchEffect` を利用できます。これは依存関係をリアクティブにトラッキングし、変更されるたびに即座に関数を再実行します。
@@ -142,6 +172,8 @@ watchEffect(
 
 `flush` オプションは `'sync'` も指定できます。これは作用をいつも同期的に発火することを強制します。しかし、これは非効率的であって、ほとんど必要ないでしょう。
 
+In Vue >= 3.2.0, `watchPostEffect` and `watchSyncEffect` aliases can also be used to make the code intention more obvious.
+
 ### Watcher のデバッグ
 
 `onTrack` および `onTrigger` オプションは、ウォッチャの振る舞いのデバッグに利用できます。
@@ -276,22 +308,14 @@ const state = reactive({
 watch(
   () => state,
   (state, prevState) => {
-    console.log(
-      'not deep',
-      state.attributes.name,
-      prevState.attributes.name
-    )
+    console.log('not deep', state.attributes.name, prevState.attributes.name)
   }
 )
 
 watch(
   () => state,
   (state, prevState) => {
-    console.log(
-      'deep',
-      state.attributes.name,
-      prevState.attributes.name
-    )
+    console.log('deep', state.attributes.name, prevState.attributes.name)
   },
   { deep: true }
 )
@@ -314,10 +338,7 @@ const state = reactive({
 watch(
   () => _.cloneDeep(state),
   (state, prevState) => {
-    console.log(
-      state.attributes.name,
-      prevState.attributes.name
-    )
+    console.log(state.attributes.name, prevState.attributes.name)
   }
 )
 
diff --git a/src/guide/single-file-component.md b/src/guide/single-file-component.md
index 6877aa27..2382a5f2 100644
--- a/src/guide/single-file-component.md
+++ b/src/guide/single-file-component.md
@@ -2,173 +2,85 @@
 
 ## 前書き
 
-多くの Vue プロジェクトでは、グローバルコンポーネントは  `app.mount('#app')` の後に各ページの body においてコンテナ要素のターゲットすることに続いて、`app.component()` を使用して定義されています。
+Vue Single File Components (aka `*.vue` files, abbreviated as **SFC**) is a special file format that allows us to encapsulate the template, logic, **and** styling of a Vue component in a single file. Here's an example SFC:
 
-これはある view を拡張するためだけに JavaScript が利用された中小規模のプロジェクトにおいてはとても有効です。しかしながら、あなたのフロントエンドで JavaScript 全体を操作するようなもっと複雑なプロジェクトでは、これらの点において不利益になります。:
-
-- **グローバル宣言**は全てのコンポーネントに一意な名前を強制すること
-- シンタックスハイライトがない**文字列テンプレート**と複数行 HTML の時の醜いスラッシュが強要されること
-- **CSS サポート無し**だと HTML と JavaScript がコンポーネントにモジュール化されている間、これ見よがしに無視されること
-- **ビルド処理がない**と Pug(前 Jade)と Babel のようなプリプロセッサよりむしろ、HTML や ES5 JavaScript を制限されること
-
-これらは全ては Webpack や Browserify のビルドツールにより実現された `.vue` 拡張子の**単一ファイルコンポーネント**によって解決されます。
-
-こちらが `Hello.vue` と呼ばれたファイルの例です:
-
-<div style="padding: 10px 0 30px"><a href="https://codepen.io/team/Vue/pen/3de13b5cd0133df4ecf307b6cf2c5f94" target="_blank" rel="noopener noreferrer" title="Click for code as text"><img src="/images/sfc.png" width="292" alt="Single-file component example (click for code as text)" style="border-radius: 5px; box-shadow: 0 13px 20px rgb(0 0 0 / 50%); margin: 0 auto; display: block;"></a></div>
-
-さて次にこちらに入ります:
-
-- [完全版シンタックスハイライト](https://github.com/vuejs/awesome-vue#source-code-editing)
-- [CommonJS モジュール](https://webpack.js.org/concepts/modules/#what-is-a-webpack-module)
-- [コンポーネントスコープ CSS](https://vue-loader.vuejs.org/en/features/scoped-css.html)
-
-約束した通り、Pug、Babel (ES2015 モジュールと一緒に) や Stylus など綺麗で機能が豊富なコンポーネントもプリプロセッサとして利用することができます。
-
-<div style="padding: 10px 0 30px"><a href="https://codesandbox.io/s/vue-single-file-component-with-pre-processors-mr3ik?file=/src/App.vue" target="_blank" rel="noopener noreferrer" title="Click for code as text"><img src="/images/sfc-with-preprocessors.png" width="452" alt="Single-file component with pre-processors example (click for code as text)" style="border-radius: 5px; box-shadow: 0 13px 20px rgb(0 0 0 / 50%); margin: 0 auto; display: block;"></a></div>
-
-これらの特定の言語は単なる一例です。TypeScript、SCSS、PostCSS などの生産的なプリプロセッサも簡単に使うことができます。もし `vue-loader` で Webpack を使用しているならば、CSS Modules 向けに素晴らしいサポートがあります。
-
-### 関心の分離について
-
-注意すべき重要な点の 1 つは、**関心の分離がファイルタイプの分離とは等しくないことです。** 現代の UI 開発では、私たちはコードベースを互いに織りなす 3 つの巨大なレイヤーに分割するのではなく、それらを疎結合なコンポーネントに分割して構成する方がはるかに理にかなっていることを発見しました。コンポーネントの内部では、そのテンプレート、ロジック、スタイルが本質的に結合しており、実際にそれらを配置することでコンポーネントの一貫性と保守性が高くなります。
-
-単一ファイルコンポーネントのアイディアが好きではなくても、JavaScript と CSS を別々ファイルに分けることによってホットリロードとプリコンパイル機能を活用することができます:
+```vue
+<script>
+export default {
+  data() {
+    return {
+      greeting: 'Hello World!'
+    }
+  }
+}
+</script>
 
-```html
-<!-- my-component.vue -->
 <template>
-  <div>This will be pre-compiled</div>
+  <p class="greeting">{{ greeting }}</p>
 </template>
-<script src="./my-component.js"></script>
-<style src="./my-component.css"></style>
-```
-
-## はじめる
-
-### サンドボックスの例
-
-すぐに触ってそして単一ファイルコンポーネントを試したい方は、CodeSandBox 上の [この単純な todo アプリケーション](https://codesandbox.io/s/vue-todo-list-app-with-single-file-component-vzkl3?file=/src/App.vue) をチェックしてみてください。
-
-### JavaScript でモジュールビルドシステムが初めてなユーザ向け
 
-`.vue` コンポーネントにより、高度な JavaScript アプリケーションの分野へ入っていきます。 これはあなたがまだ使ったことのない、いくつかの追加のツールの使い方を学ぶことを意味します:
-
-- **Node Package Manager (npm)**: レジストリからパッケージを取得する方法については[Getting Started guide](https://docs.npmjs.com/packages-and-modules/getting-packages-from-the-registry) のセクションを読んでください。
-
-- **ES2015/16 を使ったモダンな JavaScript**: Babel の [Learn ES2015 guide](https://babeljs.io/docs/en/learn)を読んでみてください。今すぐには全ての機能を暗記する必要はないですが、参考として戻れるようにしておいてください。
-
-これらのリソースに没頭した後は、[Vue CLI](https://cli.vuejs.org/)を確認することをお勧めします。 指示に従うことであっという間に `.vue` コンポーネントと ES2015、Webpack、ホットリローティングを備えた Vue プロジェクトを手に入れられるはずです！
-
-### 上級ユーザ向け
-
-CLI はツールの設定の大部分の面倒を見てくれますが、[設定オプション](https://cli.vuejs.org/config/)を通してよりきめ細かいカスタマイズをすることもできます。
-
-あなたが独自のビルドセットアップをゼロから作ることを好む場合、webpack と [vue-loader](https://vue-loader.vuejs.org)を手動で設定する必要があるでしょう。webpack についてもっと学びたいときは、[公式ドキュメント](https://webpack.js.org/configuration/)や [webpack learning academy](https://webpack.academy/p/the-core-concepts)を参照してください。
-
-### Rollup でビルド
-
-ほとんどの場合、サードパーティのライブラリを開発するときは、そのライブラリの利用者が [Tree Shaking](https://webpack.js.org/guides/tree-shaking/) できるような方法でビルドしたいと考えています。Tree Shaking を有効にするためには、`esm` モジュールをビルドする必要があります。 Webpack や Vue CLI は `esm` モジュールのビルドをサポートしていないため、[Rollup](https://rollupjs.org/) の依存が必要です。
-
-#### Rollup のインストール
-
-Rollup といくつかの依存関係をインストールする必要があります:
-
-```bash
-npm install --save-dev rollup @rollup/plugin-commonjs rollup-plugin-vue
+<style>
+.greeting {
+  color: red;
+  font-weight: bold;
+}
+</style>
 ```
 
-これらは `esm` モジュールのコードをコンパイルするために必要な最小限の Rollup プラグインです。コードをコンパイルするために [rollup-plugin-babel](https://github.com/rollup/plugins/tree/master/packages/babel) を、ライブラリにバンドルしたい依存関係を使うならば [node-resolve](https://github.com/rollup/plugins/tree/master/packages/node-resolve) を追加できます。
+As we can see, Vue SFC is a natural extension of the classic trio of HTML, CSS and JavaScript. Each `*.vue` file consists of three types of top-level language blocks: `<template>`, `<script>`, and `<style>`:
 
-#### Rollup の設定
+- The `<script>` section is a standard JavaScript module. It should export a Vue component definition as its default export.
+- The `<template>` section defines the component's template.
+- The `<style>` section defines CSS associated with the component.
 
-Rollup でビルドを設定するには、プロジェクトのルートに `rollup.config.js` ファイルを作成する必要があります:
+Check out more details in the [SFC Syntax Specification](/api/sfc-spec).
 
-```bash
-touch rollup.config.js
-```
+## How It Works
 
-ファイルを作成したら、お好きなエディタで開き、以下のコードを追加します。
+Vue SFC is a framework-specific file format and must be pre-compiled by [@vue/compiler-sfc](https://github.com/vuejs/vue-next/tree/master/packages/compiler-sfc) into standard JavaScript and CSS. A compiled SFC is a standard JavaScript (ES) module - which means with proper build setup you can import an SFC like a module:
 
 ```js
-// サードパーティのプラグインをインポート
-import commonjs from '@rollup/plugin-commonjs'
-import VuePlugin from 'rollup-plugin-vue'
-import pkg from './package.json' // 名前を再利用するために package.json ファイルをインポート
+import MyComponent from './MyComponent.vue'
 
 export default {
-  // エクスポートされたすべてのコンポーネントや関数を含むファイル
-  input: 'src/index.js',
-  // 出力されるフォーマットの配列
-  output: [
-    {
-      file: pkg.module, // esm ライブラリの名前
-      format: 'esm', // フォーマットの選択
-      sourcemap: true, // ソースマップを含めるか
-    }
-  ],
-  // 含めるプラグインの配列
-  plugins: [
-    commonjs(),
-    VuePlugin()
-  ],
-  // ライブラリに Vue をバンドルしないように
-  external: ['vue']
+  components: {
+    MyComponent
+  }
 }
 ```
 
-#### package.json の設定
+`<style>` tags inside SFCs are typically injected as native `<style>` tags during development to support hot updates. For production they can be extracted and merged into a single CSS file.
 
-新しく作成した `esm` モジュールを利用するためには、`package.json` ファイルにいくつかのフィールドを追加する必要があります:
+You can play with SFCs and explore how they are compiled in the [Vue SFC Playground](https://sfc.vuejs.org/).
 
-```json
- "scripts": {
-   ...
-   "build": "rollup -c rollup.config.js",
-   ...
- },
- "module": "dist/my-library-name.esm.js",
- "files": [
-   "dist/",
- ],
- ```
+In actual projects, we typically integrate the SFC compiler with a build tool such as [Vite](https://vitejs.dev/) or [Vue CLI](http://cli.vuejs.org/) (which is based on [webpack](https://webpack.js.org/)), and Vue provides official scaffolding tools to get you started with SFCs as fast as possible. Check out more details in the [SFC Tooling](/api/sfc-tooling) section.
 
-ここでは、以下の内容を指定しています:
+## Why SFC
 
-- パッケージのビルド方法
-- パッケージにバンドルするファイル
-- `esm` モジュールを示すファイル
+While SFCs require a build step, there are numerous benefits in return:
 
-#### `umd` と `cjs` のバンドル
+- Author modularized components using familiar HTML, CSS and JavaScript syntax
+- Pre-compiled templates
+- [Component-scoped CSS](/api/sfc-style)
+- [More ergonomic syntax when working with Composition API](/api/sfc-script-setup)
+- More compile-time optimizations by cross-analyzing template and script
+- [IDE support](/api/sfc-tooling.html#ide-support) with auto-completion and type-checking for template expressions
+- Out-of-the-box Hot-Module Replacement (HMR) support
 
-`umd` と `cjs` モジュールを一緒にビルドするには、`rollup.config.js` と `package.json` に数行の設定を追加するだけです。
+SFC is a defining feature of Vue as a framework, and is the recommended approach for using Vue in the following scenarios:
 
-##### rollup.config.js
+- Single-Page Applications (SPA)
+- Static Site Generation (SSG)
+- Any non-trivial frontends where a build step can be justified for better development experience (DX).
 
-```js
-output: [
-  ...
-   {
-      file: pkg.main,
-      format: 'cjs',
-      sourcemap: true,
-    },
-    {
-      file: pkg.unpkg,
-      format: 'umd',
-      name: 'MyLibraryName',
-      sourcemap: true,
-      globals: {
-        vue: 'Vue',
-      },
-    },
-]
-```
+That said, we do realize there are scenarios where SFCs can feel like overkill. This is why Vue can still be used via plain JavaScript without a build step. If you are just looking for enhancing largely static HTML with light interactions, you can also check out [petite-vue](https://github.com/vuejs/petite-vue), a 5kb subset of Vue optimized for progressive enhancement.
 
-##### package.json
+## What About Separation of Concerns?
 
-```json
-"module": "dist/my-library-name.esm.js",
-"main": "dist/my-library-name.cjs.js",
-"unpkg": "dist/my-library-name.global.js",
-```
+Some users coming from a traditional web development background may have the concern that SFCs are mixing different concerns in the same place - which HTML/CSS/JS were supposed to separate!
+
+To answer this question, it is important for us to agree that **separation of concerns is not equal to separation of file types.** The ultimate goal of engineering principles is to improve maintainability of codebases. Separation of concerns, when applied dogmatically as separation of file types, does not help us reach that goal in the context of increasingly complex frontend applications.
+
+In modern UI development, we have found that instead of dividing the codebase into three huge layers that interweave with one another, it makes much more sense to divide them into loosely-coupled components and compose them. Inside a component, its template, logic, and styles are inherently coupled, and collocating them actually makes the component more cohesive and maintainable.
+
+Note even if you don't like the idea of Single-File Components, you can still leverage its hot-reloading and pre-compilation features by separating your JavaScript and CSS into separate files using [Src Imports](/api/sfc-spec.html#src-imports).
diff --git a/src/guide/typescript-support.md b/src/guide/typescript-support.md
index 5b1107f8..f694ff9e 100644
--- a/src/guide/typescript-support.md
+++ b/src/guide/typescript-support.md
@@ -86,7 +86,7 @@ vue add typescript
 
 ### エディタによるサポート
 
-TypeScript による Vue アプリケーションの開発のために、すぐに利用できる TypeScript サポートを提供している [Visual Studio Code](https://code.visualstudio.com/) を強く推奨します。[単一ファイルコンポーネント](./single-file-component.html) (SFCs) を使用している場合、SFC 内部での TypeScript の推論やその他の優れた機能を提供している、素晴らしい [Vetur エクステンション](https://github.com/vuejs/vetur) を入手してください。
+TypeScript による Vue アプリケーションの開発のために、すぐに利用できる TypeScript サポートを提供している [Visual Studio Code](https://code.visualstudio.com/) を強く推奨します。[単一ファイルコンポーネント](./single-file-component.html) (SFCs) を使用している場合、SFC 内部での TypeScript の推論やその他の優れた機能を提供している、素晴らしい [Volar 拡張機能](https://github.com/johnsoncodehk/volar) を入手してください。
 
 [WebStorm](https://www.jetbrains.com/webstorm/) もすぐに利用できる TypeScript と Vue のサポートを提供しています。
 
diff --git a/src/guide/web-components.md b/src/guide/web-components.md
new file mode 100644
index 00000000..35735c92
--- /dev/null
+++ b/src/guide/web-components.md
@@ -0,0 +1,243 @@
+# Vue and Web Components
+
+[Web Components](https://developer.mozilla.org/en-US/docs/Web/Web_Components) is an umbrella term for a set of web native APIs that allows developers to create reusable custom elements.
+
+We consider Vue and Web Components to be primarily complementary technologies. Vue has excellent support for both consuming and creating custom elements. Whether you are integrating custom elements into an existing Vue application, or using Vue to build and distribute custom elements, you are in good company.
+
+## Using Custom Elements in Vue
+
+Vue [scores a perfect 100% in the Custom Elements Everywhere tests](https://custom-elements-everywhere.com/libraries/vue/results/results.html). Consuming custom elements inside a Vue application largely works the same as using native HTML elements, with a few things to keep in mind:
+
+### Skipping Component Resolution
+
+By default, Vue will attempt to resolve a non-native HTML tag as a registered Vue component before falling back to rendering it as a custom element. This will cause Vue to emit a "failed to resolve component" warning during development. To let Vue know that certain elements should be treated as custom elements and skip component resolution, we can specify the [`compilerOptions.isCustomElement` option](/api/application-config.html#compileroptions).
+
+If you are using Vue with a build setup, the option should be passed via build configs since it is a compile-time option.
+
+#### Example Vite Config
+
+```js
+// vite.config.js
+import vue from '@vitejs/plugin-vue'
+
+export default {
+  plugins: [
+    vue({
+      template: {
+        compilerOptions: {
+          // treat all tags with a dash as custom elements
+          isCustomElement: tag => tag.includes('-')
+        }
+      }
+    })
+  ]
+}
+```
+
+#### Example Vue CLI Config
+
+```js
+// vue.config.js
+module.exports = {
+  chainWebpack: config => {
+    config.module
+      .rule('vue')
+      .use('vue-loader')
+      .tap(options => ({
+        ...options
+        compilerOptions: {
+          // treat any tag that starts with ion- as custom elements
+          isCustomElement: tag => tag.startsWith('ion-')
+        }
+      }))
+  }
+}
+```
+
+### Passing DOM Properties
+
+Since DOM attributes can only be strings, we need to pass complex data to custom elements as DOM properties. When setting props on a custom element, Vue 3 automatically checks DOM-property presence using the `in` operator and will prefer setting the value as a DOM property if the key is present. This means that, in most cases, you won't need to think about this if the custom element follows the [recommended best practices](https://developers.google.com/web/fundamentals/web-components/best-practices#aim-to-keep-primitive-data-attributes-and-properties-in-sync,-reflecting-from-property-to-attribute,-and-vice-versa.).
+
+However, there could be rare cases where the data must be passed as a DOM property, but the custom element does not properly define/reflect the property (causing the `in` check to fail). In this case, you can force a `v-bind` binding to be set as a DOM property using the `.prop` modifier:
+
+```html
+<my-element :user.prop="{ name: 'jack' }"></my-element>
+
+<!-- shorthand equivalent -->
+<my-element .user="{ name: 'jack' }"></my-element>
+```
+
+## Building Custom Elements with Vue
+
+The primary benefit of custom elements is that they can be used with any framework, or even without a framework. This makes them ideal for distributing components where the end consumer may not be using the same frontend stack, or when you want to insulate the end application from the implementation details of the components it uses.
+
+### defineCustomElement
+
+Vue supports creating custom elements using exactly the same Vue component APIs via the [`defineCustomElment`](/api/global-api.html#definecustomelement) method. The method accepts the same argument as [`defineComponent`](/api/global-api.html#definecomponent), but instead returns a custom element constructor that extends `HTMLElement`:
+
+```html
+<my-vue-element></my-vue-element>
+```
+
+```js
+import { defineCustomElement } from 'vue'
+
+const MyVueElement = defineCustomElement({
+  // normal Vue component options here
+  props: {},
+  emits: {},
+  template: `...`,
+
+  // defineCustomElement only: CSS to be injected into shadow root
+  styles: [`/* inlined css */`]
+})
+
+// Register the custom element.
+// After registration, all `<my-vue-element>` tags
+// on the page will be upgraded.
+customElements.define('my-vue-element', MyVueElement)
+
+// You can also programmatically instantiate the element:
+// (can only be done after registration)
+document.body.appendChild(
+  new MyVueElement({
+    // initial props (optional)
+  })
+)
+```
+
+#### Lifecycle
+
+- A Vue custom element will mount an internal Vue component instance inside its shadow root when the element's [`connectedCallback`](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_custom_elements#using_the_lifecycle_callbacks) is called for the first time.
+
+- When the element's `disconnectedCallback` is invoked, Vue will check whether the element is detached from the document after a microtask tick.
+
+  - If the element is still in the document, it's a move and the component instance will be perserved;
+
+  - If the element is detached from the document, it's a removal and the component instance will be unmounted.
+
+#### Props
+
+- All props declared using the `props` option will be defined on the custom element as properties. Vue will automatically handle the reflection between attributes / properties where appropriate.
+
+  - Attributes are always reflected to corresponding properties.
+
+  - Properties with primitive values (`string`, `boolean` or `number`) are reflected as attributes.
+
+- Vue also automatically casts props declared with `Boolean` or `Number` types into the desired type when they are set as attributes (which are always strings). For example given the following props declaration:
+
+  ```js
+  props: {
+    selected: Boolean,
+    index: Number
+  }
+  ```
+
+  And the custom element usage:
+
+  ```html
+  <my-element selected index="1"></my-element>
+  ```
+
+  In the component, `selected` will be cast to `true` (boolean) and `index` will be cast to `1` (number).
+
+#### Events
+
+Events emitted via `this.$emit` or setup `emit` are dispatched as native [CustomEvents](https://developer.mozilla.org/en-US/docs/Web/Events/Creating_and_triggering_events#adding_custom_data_%E2%80%93_customevent) on the custom element. Additional event arguments (payload) will be exposed as an array on the CustomEvent object as its `details` property.
+
+#### Slots
+
+Inside the component, slots can be rendered using the `<slot/>` element as usual. However when consuming the resulting element, it only accepts [native slots syntax](https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_templates_and_slots):
+
+- [Scoped slots](/guide/component-slots.html#scoped-slots) are not supported.
+
+- When passing named slots, use the `slot` attribute instead of the `v-slot` directive:
+
+  ```html
+  <my-element>
+    <div slot="named">hello</div>
+  </my-element>
+  ```
+
+#### Provide / Inject
+
+The [Provide / Inject API](/guide/component-provide-inject.html#provide-inject) and its [Composition API equivalent](/api/composition-api.html#provide-inject) also work between Vue-defined custom elements. However, note that this works **only between custom elements**. i.e. a Vue-defined custom element won't be able to inject properties provided by a non-custom-element Vue component.
+
+### SFC as Custom Element
+
+`defineCustomElement` also works with Vue Single File Components (SFCs). However, with the default tooling setup, the `<style>` inside the SFCs will still be extracted and merged into a single CSS file during production build. When using an SFC as a custom element, it is often desirable to inject the `<style>` tags into the custom element's shadow root instead.
+
+The official SFC toolings support importing SFCs in "custom element mode" (requires `@vitejs/plugin-vue@^1.4.0` or `vue-loader@^16.5.0`). An SFC loaded in custom element mode inlines its `<style>` tags as strings of CSS and exposes them under the component's `styles` option. This will be picked up by `defineCustomElement` and injected into the element's shadow root when instantiated.
+
+To opt-in to this mode, simply end your component file name with `.ce.vue`:
+
+```js
+import { defineCustomElement } from 'vue'
+import Example from './Example.ce.vue'
+
+console.log(Example.styles) // ["/* inlined css */"]
+
+// convert into custom element constructor
+const ExampleElement = defineCustomElement(Example)
+
+// register
+customElements.define('my-example', ExampleElement)
+```
+
+If you wish to customize what files should be imported in custom element mode (for example treating _all_ SFCs as custom elements), you can pass the `customElement` option to the respective build plugins:
+
+- [@vitejs/plugin-vue](https://github.com/vitejs/vite/tree/main/packages/plugin-vue#using-vue-sfcs-as-custom-elements)
+- [vue-loader](https://github.com/vuejs/vue-loader/tree/next#v16-only-options)
+
+### Tips for a Vue Custom Elements Library
+
+When building custom elements with Vue, the elements will rely on Vue's runtime. There is a ~16kb baseline size cost depending on how many features are being used. This means it is not ideal to use Vue if you are shipping a single custom element - you may want to use vanilla JavaScript, [petite-vue](https://github.com/vuejs/petite-vue), or frameworks that specialize in small runtime size. However, the base size is more than justifiable if you are shipping a collection of custom elements with complex logic, as Vue will allow each component to be authored with much less code. The more elements you are shipping together, the better the trade-off.
+
+If the custom elements will be used in an application that is also using Vue, you can choose to externalize Vue from the built bundle so that the elements will be using the same copy of Vue from the host application.
+
+It is recommended to export the individual element constructors to give your users the flexibility to import them on-demand and register them with desired tag names. You can also export a convenience function to automatically register all elements. Here's an example entry point of a Vue custom element library:
+
+```js
+import { defineCustomElement } from 'vue'
+import Foo from './MyFoo.ce.vue'
+import Bar from './MyBar.ce.bar'
+
+const MyFoo = defineCustomElement(Foo)
+const MyBar = defineCustomElement(Bar)
+
+// export individual elements
+export { MyFoo, MyBar }
+
+export function register() {
+  customElements.register('my-foo', MyFoo)
+  customElements.register('my-bar', MyBar)
+}
+```
+
+If you have many components, you can also leverage build tool features such as Vite's [glob import](https://vitejs.dev/guide/features.html#glob-import) or webpack's [`require.context`](https://webpack.js.org/guides/dependency-management/#requirecontext) to load all components from a directory.
+
+## Web Components vs. Vue Components
+
+Some developers believe that framework-proprietary component models should be avoided, and that exclusively using Custom Elements makes an application "future-proof". Here we will try to explain why we believe that this is an overly simplistic take on the problem.
+
+There is indeed a certain level of feature overlap between Custom Elements and Vue Components: they both allow us to define reusable components with data passing, event emitting, and lifecycle management. However, Web Components APIs are relatively low-level and bare-bones. To build an actual application, we need quite a few additional capabilities which the platform does not cover:
+
+- A declarative and efficient templating system;
+
+- A reactive state management system that facilitates cross-component logic extraction and reuse;
+
+- A performant way to render the components on the server and hydrate them on the client (SSR), which is important for SEO and [Web Vitals metrics such as LCP](https://web.dev/vitals/). Native custom elements SSR typically involves simulating the DOM in Node.js and then serializing the mutated DOM, while Vue SSR compiles into string concatenation whenever possible, which is much more efficient.
+
+Vue's component model is designed with these needs in mind as a coherent system.
+
+With a competent engineering team, you could probably build the equivalent on top of native Custom Elements - but this also means you are taking on the long-term maintenance burden of an in-house framework, while losing out on the ecosystem and community benefits of a mature framework like Vue.
+
+There are also frameworks built using Custom Elements as the basis of their component model, but they all inevitably have to introduce their proprietary solutions to the problems listed above. Using these frameworks entails buying into their technical decisions on how to solve these problems - which, despite what may be advertised, doesn't automatically insulate you from potential future churns.
+
+There are also some areas where we find custom elements to be limiting:
+
+- Eager slot evaluation hinders component composition. Vue's [scoped slots](/guide/component-slots.html#scoped-slots) are a powerful mechanism for component composition, which can't be supported by custom elements due to native slots' eager nature. Eager slots also mean the receiving component cannot control when or whether to render a piece of slot content.
+
+- Shipping custom elements with shadow DOM scoped CSS today requires embedding the CSS inside JavaScript so that they can be injected into shadow roots at runtime. They also result in duplicated styles in markup in SSR scenarios. There are [platform features](https://github.com/whatwg/html/pull/4898/) being worked on in this area - but as of now they are not yet universally supported, and there are still production performance / SSR concerns to be addressed. In the meanwhile, Vue SFCs provide [CSS scoping mechanisms](/api/sfc-style.html) that support extracting the styles into plain CSS files.
+
+Vue will always be staying up to date with the latest standards in the web platform, and we will happily leverage whatever the platform provides if it makes our job easier. However, our goal is to provide solutions that work well and work today. That means we have to incorporate new platform features with a critical mindset - and that involves filling the gaps where the standards fall short while that is still the case.

From 09679ca71cfbabea625b3f60d74f24c921ddcc9f Mon Sep 17 00:00:00 2001
From: skirtle <65301168+skirtles-code@users.noreply.github.com>
Date: Wed, 11 Aug 2021 09:38:49 +0100
Subject: [PATCH 3/9] docs: link to the style guide entry for keyed v-for
 (#1164)

---
 src/guide/list.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/guide/list.md b/src/guide/list.md
index f0750bd0..8f3d447c 100644
--- a/src/guide/list.md
+++ b/src/guide/list.md
@@ -127,7 +127,7 @@ Vue が各ノードの識別情報を追跡できるヒントを与えるため
 </div>
 ```
 
-繰り返される DOM の内容が単純な場合や、性能向上のためにデフォルトの動作に意図的に頼る場合を除いて、可能なときはいつでも `v-for` に `key` 属性を与えることが推奨されます。
+繰り返される DOM の内容が単純な場合や、性能向上のためにデフォルトの動作を意図的に頼る場合を除いて、可能なときはいつでも `v-for` に `key` 属性を与えることが[推奨されます](/style-guide/#keyed-v-for-essential)。
 
 これは Vue がノードを識別する汎用的な仕組みなので、`key` はガイドの後半でわかるように `v-for` に縛られない他の用途もあります。
 

From 9094f8611805b65b3a68554da7b5134620977463 Mon Sep 17 00:00:00 2001
From: tkalmar <971164+tkalmar@users.noreply.github.com>
Date: Wed, 11 Aug 2021 23:56:32 +0200
Subject: [PATCH 4/9] Update web-components.md (#1166)

Correct typo
---
 src/guide/web-components.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/guide/web-components.md b/src/guide/web-components.md
index 35735c92..47ae2a6a 100644
--- a/src/guide/web-components.md
+++ b/src/guide/web-components.md
@@ -73,7 +73,7 @@ The primary benefit of custom elements is that they can be used with any framewo
 
 ### defineCustomElement
 
-Vue supports creating custom elements using exactly the same Vue component APIs via the [`defineCustomElment`](/api/global-api.html#definecustomelement) method. The method accepts the same argument as [`defineComponent`](/api/global-api.html#definecomponent), but instead returns a custom element constructor that extends `HTMLElement`:
+Vue supports creating custom elements using exactly the same Vue component APIs via the [`defineCustomElement`](/api/global-api.html#definecustomelement) method. The method accepts the same argument as [`defineComponent`](/api/global-api.html#definecomponent), but instead returns a custom element constructor that extends `HTMLElement`:
 
 ```html
 <my-vue-element></my-vue-element>

From cbbb44aca8598163cdde4e7bcd70fa600ad2dc0f Mon Sep 17 00:00:00 2001
From: Naoki Endoh <naoki.endoh@gmail.com>
Date: Sun, 15 Aug 2021 10:16:56 +0900
Subject: [PATCH 5/9] fix: remove unnecessary particles

close #469
---
 src/guide/component-provide-inject.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/guide/component-provide-inject.md b/src/guide/component-provide-inject.md
index da9a4679..bdb90bb1 100644
--- a/src/guide/component-provide-inject.md
+++ b/src/guide/component-provide-inject.md
@@ -96,7 +96,7 @@ app.component('todo-list', {
 
 ## リアクティブと連携する
 
-前述の例では、リスト `todos` を変更しても、その変更は注入された `todoLength` には反映されません。これは、`provide/inject` の束縛（binding）がデフォルトでリアクティブ _でない_ ことが原因です。`ref` で定義されたプロパティや `reactive` で作成されたオブジェクトを `provide` に渡すことにより、この振る舞いを変更することができます。この場合、祖先コンポーネントをリアクティブにするためには、Composition API の `computed` で定義したプロパティを `todoLength` を割り当てる必要があります。
+前述の例では、リスト `todos` を変更しても、その変更は注入された `todoLength` には反映されません。これは、`provide/inject` の束縛（binding）がデフォルトでリアクティブ _でない_ ことが原因です。`ref` で定義されたプロパティや `reactive` で作成されたオブジェクトを `provide` に渡すことにより、この振る舞いを変更することができます。この場合、祖先コンポーネントをリアクティブにするためには、Composition API の `computed` で定義したプロパティ `todoLength` を割り当てる必要があります。
 
 ```js
 app.component('todo-list', {

From 879d62952a6552697192a7986ceb0e5ceb2d1774 Mon Sep 17 00:00:00 2001
From: wxsm <wxsms@foxmail.com>
Date: Fri, 13 Aug 2021 12:38:46 +0800
Subject: [PATCH 6/9] feat: enable editLinks (close #1168) (#1172)

---
 src/.vuepress/config.js | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/.vuepress/config.js b/src/.vuepress/config.js
index 67e2b171..5d2ffdd1 100644
--- a/src/.vuepress/config.js
+++ b/src/.vuepress/config.js
@@ -482,7 +482,7 @@ module.exports = {
       }
     ],
     repo: 'vuejs-jp/ja.vuejs.org',
-    editLinks: false,
+    editLinks: true,
     editLinkText: 'GitHub でこのページを編集！',
     lastUpdated: '最終更新日',
     docsDir: 'src',

From 5e1f14b6f6f2a6ee5a6414fe6f6a6ee8b0e7cfd2 Mon Sep 17 00:00:00 2001
From: Darek <mastrodaro@gmail.com>
Date: Fri, 13 Aug 2021 06:37:45 +0200
Subject: [PATCH 7/9] no filters in vue 3 (#1171)

---
 src/guide/plugins.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/guide/plugins.md b/src/guide/plugins.md
index b9b31ed1..eab35f15 100644
--- a/src/guide/plugins.md
+++ b/src/guide/plugins.md
@@ -6,7 +6,7 @@
 
 1. グローバルメソッドまたはグローパルプロパティの追加　例）[vue-custom-element](https://github.com/karol-f/vue-custom-element).
 
-2. ディレクティブ / フィルタ / トランジションのような 1 つ以上のグローバルアセットの追加　例) [vue-touch](https://github.com/vuejs/vue-touch).
+2. ディレクティブやトランジションのような 1 つ以上のグローバルアセットの追加　例) [vue-touch](https://github.com/vuejs/vue-touch).
 
 3. グローバル mixin によるコンポーネントオプションの追加　例) [vue-router](https://github.com/vuejs/vue-router).
 

From 7043225995980092c54a3725012f37cdd5d57ede Mon Sep 17 00:00:00 2001
From: skirtle <65301168+skirtles-code@users.noreply.github.com>
Date: Fri, 13 Aug 2021 05:35:29 +0100
Subject: [PATCH 8/9] fix: avoid redirects by including .html on links (#1163)

---
 src/guide/conditional.md      | 2 +-
 src/guide/transitions-list.md | 2 +-
 2 files changed, 2 insertions(+), 2 deletions(-)

diff --git a/src/guide/conditional.md b/src/guide/conditional.md
index df23a950..fb56fa92 100644
--- a/src/guide/conditional.md
+++ b/src/guide/conditional.md
@@ -93,4 +93,4 @@
 `v-if` と `v-for` を同時に利用することは **推奨されません**。 詳細については [スタイルガイド](../style-guide/#avoid-v-if-with-v-for-essential) を参照ください。
 :::
 
-`v-if` と `v-for` が同じ要素に両方つかわれる場合、 `v-if` が先に評価されます。詳細については [リストレンダリングのガイド](list#v-for-with-v-if) を参照してください。
+`v-if` と `v-for` が同じ要素に両方つかわれる場合、 `v-if` が先に評価されます。詳細については [リストレンダリングのガイド](list.html#v-for-with-v-if) を参照してください。
diff --git a/src/guide/transitions-list.md b/src/guide/transitions-list.md
index 3c529b86..c7a42f66 100644
--- a/src/guide/transitions-list.md
+++ b/src/guide/transitions-list.md
@@ -8,7 +8,7 @@
 その上で、例えば `v-for` のように、全てをまとめてレンダリングしたいリスト全体がある場合はどうしましょうか？このような場合では、 `<transition-group>` コンポーネントを利用します。ですが具体的な例を見る前に、コンポーネントについていくつかの重要なことを知っておく必要があります:
 
 - デフォルトでは、ラッパー要素はレンダリングされませんが、 `tag` 属性でレンダリングする要素を指定することができます。
-- 2 つの排他の要素が切り替わっているわけではないため、[トランジションモード](/guide/transitions-enterleave#トランジションモード) は利用できません。
+- 2 つの排他の要素が切り替わっているわけではないため、[トランジションモード](/guide/transitions-enterleave.html#トランジションモード) は利用できません。
 - 要素の内部では、 **常に** 固有の `key` 属性を **持つ必要** があります。
 - CSS トランジションクラスは内部の要素に適用され、グループやコンテナには適用されません。
 

From eac66b16f6b62eca66f16a518a5c9415199120f3 Mon Sep 17 00:00:00 2001
From: Naoki Endoh <naoki.endoh@gmail.com>
Date: Sun, 15 Aug 2021 10:27:27 +0900
Subject: [PATCH 9/9] docs: translate parts of introduction

---
 src/guide/reactivity-computed-watchers.md | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/src/guide/reactivity-computed-watchers.md b/src/guide/reactivity-computed-watchers.md
index d620a772..08e39beb 100644
--- a/src/guide/reactivity-computed-watchers.md
+++ b/src/guide/reactivity-computed-watchers.md
@@ -172,7 +172,7 @@ watchEffect(
 
 `flush` オプションは `'sync'` も指定できます。これは作用をいつも同期的に発火することを強制します。しかし、これは非効率的であって、ほとんど必要ないでしょう。
 
-In Vue >= 3.2.0, `watchPostEffect` and `watchSyncEffect` aliases can also be used to make the code intention more obvious.
+Vue >= 3.2.0 では、`watchPostEffect` と `watchSyncEffect` のエイリアスを使って、コードの意図をより明確にすることもできます。
 
 ### Watcher のデバッグ