Merge pull request #432 from naokie/update-api

Author: naokie

src/api/basic-reactivity.md

@@ -18,6 +18,44 @@ The reactive conversion is "deep"—it affects all nested properties. In the [ES
 function reactive<T extends object>(target: T): UnwrapNestedRefs<T>
 ```
 
+::: tip Note
+`reactive` will unwrap all the deep [refs](./refs-api.html#ref), while maintaining the ref reactivity
+
+```ts
+const count = ref(1)
+const obj = reactive({ count })
+
+// ref will be unwrapped
+console.log(obj.count === count.value) // true
+
+// it will update `obj.count`
+count.value++
+console.log(count.value) // 2
+console.log(obj.count) // 2
+
+// it will also update `count` ref
+obj.count++
+console.log(obj.count) // 3
+console.log(count.value) // 3
+```
+
+:::
+
+::: warning Important
+When assigning a [ref](./refs-api.html#ref) to a `reactive` property, that ref will be automatically unwrapped.
+
+```ts
+const count = ref(1)
+const obj = reactive({})
+
+obj.count = count
+
+console.log(obj.count) // 1
+console.log(obj.count === count.value) // true
+```
+
+:::
+
 ## `readonly`
 
 Takes an object (reactive or plain) or a [ref](./refs-api.html#ref) and returns a readonly proxy to the original. A readonly proxy is deep: any nested property accessed will be readonly as well.
@@ -39,6 +77,19 @@ original.count++
 copy.count++ // warning!
 ```
 
+As with [`reactive`](#reactive), if any property uses a `ref` it will be automatically unwrapped when it is accessed via the proxy:
+
+```js
+const raw = {
+  count: ref(123)
+}
+
+const copy = readonly(raw)
+
+console.log(raw.count.value) // 123
+console.log(copy.count) // 123
+```
+
 ## `isProxy`
 
 Checks if an object is a proxy created by [`reactive`](#reactive) or [`readonly`](#readonly).
@@ -153,6 +204,8 @@ isReactive(state.nested) // false
 state.nested.bar++ // non-reactive
 ```
 
+Unlike [`reactive`](#reactive), any property that uses a [`ref`](/api/refs-api.html#ref) will **not** be automatically unwrapped by the proxy.
+
 ## `shallowReadonly`
 
 Creates a proxy that makes its own properties readonly, but does not perform deep readonly conversion of nested objects (exposes raw values).
@@ -171,3 +224,5 @@ state.foo++
 isReadonly(state.nested) // false
 state.nested.bar++ // works
 ```
+
+Unlike [`readonly`](#readonly), any property that uses a [`ref`](/api/refs-api.html#ref) will **not** be automatically unwrapped by the proxy.

src/api/computed-watch-api.md

@@ -65,7 +65,7 @@ function watchEffect(
 ): StopHandle
 
 interface WatchEffectOptions {
-  flush?: 'pre' | 'post' | 'sync'
+  flush?: 'pre' | 'post' | 'sync' // default: 'pre'
   onTrack?: (event: DebuggerEvent) => void
   onTrigger?: (event: DebuggerEvent) => void
 }
@@ -132,7 +132,7 @@ watch([fooRef, barRef], ([foo, bar], [prevFoo, prevBar]) => {
 **Typing:**
 
 ```ts
-// wacthing single source
+// watching single source
 function watch<T>(
   source: WatcherSource<T>,
   callback: (

src/api/instance-methods.md

@@ -9,17 +9,18 @@
   - `{Object} options (optional)`
     - `{boolean} deep`
     - `{boolean} immediate`
+    - `{string} flush`
 
 - **Returns:** `{Function} unwatch`
 
 - **Usage:**
 
-  Watch a reactive property or a computed function on the component instance for changes. The callback gets called with the new value and the old value for the given property. We can only pass top-level `data`, `prop`, or `computed` property name as a string. For more complex expressions or nested properties, use a function instead.
+  Watch a reactive property or a computed function on the component instance for changes. The callback gets called with the new value and the old value for the given property. We can only pass top-level `data`, `props`, or `computed` property name as a string. For more complex expressions or nested properties, use a function instead.
 
 - **Example:**
 
   ```js
-  const app = Vue.createApp({
+  const app = createApp({
     data() {
       return {
         a: 1,
@@ -58,10 +59,10 @@
   })
   ```
 
-  When watched value is an Object or Array, any changes to its properties or elements won't trigger the watcher because they reference the same Object/Array:
+  When watched value is an object or array, any changes to its properties or elements won't trigger the watcher because they reference the same object/array:
 
   ```js
-  const app = Vue.createApp({
+  const app = createApp({
     data() {
       return {
         article: {
@@ -80,16 +81,16 @@
       })
     },
     methods: {
-      // These methods won't trigger a watcher because we changed only a property of Object/Array,
-      // not the Object/Array itself
+      // These methods won't trigger a watcher because we changed only a property of object/array,
+      // not the object/array itself
       changeArticleText() {
         this.article.text = 'Vue 3 is awesome'
       },
       addComment() {
         this.comments.push('New comment')
       },
 
-      // These methods will trigger a watcher because we replaced Object/Array completely
+      // These methods will trigger a watcher because we replaced object/array completely
       changeWholeArticle() {
         this.article = { text: 'Vue 3 is awesome' }
       },
@@ -103,7 +104,7 @@
   `$watch` returns an unwatch function that stops firing the callback:
 
   ```js
-  const app = Vue.createApp({
+  const app = createApp({
     data() {
       return {
         a: 1
@@ -120,7 +121,9 @@
 
 - **Option: deep**
 
-  To also detect nested value changes inside Objects, you need to pass in `deep: true` in the options argument. Note that you don't need to do so to listen for Array mutations.
+  To also detect nested value changes inside Objects, you need to pass in `deep: true` in the options argument. This option also can be used to watch array mutations.
+
+  > Note: when mutating (rather than replacing) an Object or an Array and watch with deep option, the old value will be the same as new value because they reference the same Object/Array. Vue doesn't keep a copy of the pre-mutate value.
 
   ```js
   vm.$watch('someObject', callback, {
@@ -158,7 +161,9 @@
   If you still want to call an unwatch function inside the callback, you should check its availability first:
 
   ```js
-  const unwatch = vm.$watch(
+  let unwatch = null
+
+  unwatch = vm.$watch(
     'value',
     function() {
       doSomething()
@@ -170,6 +175,24 @@
   )
   ```
 
+- **Option: flush**
+
+  The `flush` option allows for greater control over the timing of the callback. It can be set to `'pre'`, `'post'` or `'sync'`.
+
+  The default value is `'pre'`, which specifies that the callback should be invoked before rendering. This allows the callback to update other values before the template runs.
+
+  The value `'post'` can be used to defer the callback until after rendering. This should be used if the callback needs access to the updated DOM or child components via `$refs`.
+
+  If `flush` is set to `'sync'`, the callback will be called synchronously, as soon as the value changes.
+
+  For both `'pre'` and `'post'`, the callback is buffered using a queue. The callback will only be added to the queue once, even if the watched value changes multiple times. The interim values will be skipped and won't be passed to the callback.
+
+  Buffering the callback not only improves performance but also helps to ensure data consistency. The watchers won't be triggered until the code performing the data updates has finished.
+
+  `'sync'` watchers should be used sparingly, as they don't have these benefits.
+
+  For more information about `flush` see [Effect Flush Timing](../guide/reactivity-computed-watchers.html#effect-flush-timing).
+
 - **See also:** [Watchers](../guide/computed.html#watchers)
 
 ## $emit
@@ -272,7 +295,7 @@
 - **Example:**
 
   ```js
-  Vue.createApp({
+  createApp({
     // ...
     methods: {
       // ...

src/api/instance-properties.md

@@ -28,6 +28,8 @@
 
   The root DOM element that the component instance is managing.
 
+  For components using [fragments](../guide/migration/fragments), `$el` will be the placeholder DOM node that Vue uses to keep track of the component's position in the DOM. It is recommended to use [template refs](../guide/component-template-refs.html) for direct access to DOM elements instead of relying on `$el`.
+
 ## $options
 
 - **Type:** `Object`
@@ -39,7 +41,7 @@
   The instantiation options used for the current component instance. This is useful when you want to include custom properties in the options:
 
   ```js
-  const app = Vue.createApp({
+  const app = createApp({
     customOption: 'foo',
     created() {
       console.log(this.$options.customOption) // => 'foo'
@@ -100,14 +102,15 @@
   ```
 
   ```js
-  const app = Vue.createApp({})
+  const { createApp, h } = Vue
+  const app = createApp({})
 
   app.component('blog-post', {
     render() {
-      return Vue.h('div', [
-        Vue.h('header', this.$slots.header()),
-        Vue.h('main', this.$slots.default()),
-        Vue.h('footer', this.$slots.footer())
+      return h('div', [
+        h('header', this.$slots.header()),
+        h('main', this.$slots.default()),
+        h('footer', this.$slots.footer())
       ])
     }
   })
@@ -144,3 +147,4 @@ Contains parent-scope attribute bindings and events that are not recognized (and
 
 - **See also:**
   - [Non-Prop Attributes](../guide/component-attrs.html)
+  - [Options / Misc - inheritAttrs](./options-misc.html#inheritattrs)

src/api/options-api.md

@@ -1,10 +1,10 @@
-# オプション
+# オプション API
 
-オプションには、次のようなセクションがあります:
+オプション API には、次のようなセクションがあります:
 
 - [Data](/api/options-data.html)
 - [DOM](/api/options-dom.html)
 - [Lifecycle Hooks](/api/options-lifecycle-hooks.html)
 - [Assets](/api/options-assets.html)
 - [Composition](/api/options-composition.html)
-- [Misc](/api/options-misc.html)
+- [Miscellaneous](/api/options-misc.html)

src/api/options-assets.md

@@ -8,6 +8,23 @@
 
   A hash of directives to be made available to the component instance.
 
+- **Usage:**
+
+  ```js
+  const app = createApp({})
+
+  app.component('focused-input', {
+    directives: {
+      focus: {
+        mounted(el) {
+          el.focus()
+        }
+      }
+    },
+    template: `<input v-focus>`
+  })
+  ```
+
 - **See also:** [Custom Directives](../guide/custom-directive.html)
 
 ## components
@@ -18,4 +35,19 @@
 
   A hash of components to be made available to the component instance.
 
+- **Usage:**
+
+  ```js
+  const Foo = {
+    template: `<div>Foo</div>`
+  }
+
+  const app = createApp({
+    components: {
+      Foo
+    },
+    template: `<Foo />`
+  })
+  ```
+
 - **See also:** [Components](../guide/component-basics.html)

src/api/options-composition.md

@@ -19,7 +19,7 @@
     }
   }
 
-  Vue.createApp({
+  createApp({
     created() {
       console.log(2)
     },
@@ -299,7 +299,7 @@ The `setup` function is a new component option. It serves as the entry point for
   }
   ```
 
-  `attrs` and `slots` are proxies to the corresponding values on the internal component instance. This ensures they always expose the latest values even after updates so that we can destructure them without worrying accessing a stale reference:
+  `attrs` and `slots` are proxies to the corresponding values on the internal component instance. This ensures they always expose the latest values even after updates so that we can destructure them without worrying about accessing a stale reference:
 
   ```js
   const MyComponent = {