more noodling

Author: yyx990803

src/guide/essentials/state-and-reactivity.md

@@ -1,64 +1,51 @@
 # State and Reactivity
 
-## Data Properties
+:::tip
+This section contains different content for Options API and Composition API. You can toggle between the API styles using the "API Preference" switches at the top of the left sidebar.
+:::
 
-The `data` option for a component is a function. Vue calls this function as part of creating a new component instance. It should return an object, which Vue will then wrap in its reactivity system and store on the component instance as `$data`. For convenience, any top-level properties of that object are also exposed directly via the component instance:
+## Declaring Reactive State
 
 <div class="options-api">
 
+We use the `data` option to declare reactive state of a component. The option value should be a function that returns an object. Vue will call the function when creating a new component instance, and wrap the returned object in its reactivity system. The wrapped object is stored on the component instance as `$data`. For convenience, any top-level properties of that object are also exposed directly on the component instance (`this` in methods and lifecycle hooks):
+
 ```js
-const app = Vue.createApp({
+export default {
   data() {
-    return { count: 4 }
-  }
-})
-
-const vm = app.mount('#app')
-
-console.log(vm.$data.count) // => 4
-console.log(vm.count) // => 4
-
-// Assigning a value to vm.count will also update $data.count
-vm.count = 5
-console.log(vm.$data.count) // => 5
+    return {
+      count: 1
+    }
+  },
 
-// ... and vice-versa
-vm.$data.count = 6
-console.log(vm.count) // => 6
-```
+  mounted() {
+    console.log(this.$data.count) // => 1
+    console.log(this.count) // => 1
 
-</div>
-<div class="composition-api">
+    // Assigning a value to this.count will also update $data.count
+    this.count = 2
+    console.log(this.$data.count) // => 2
 
-```js
-const app = Vue.createApp({
-  setup() {
-    const count = Vue.ref(4)
-    return { count }
+    // ... and vice-versa
+    this.$data.count = 3
+    console.log(this.count) // => 3
   }
-})
-
-const vm = app.mount('#app')
+}
+```
 
-console.log(vm.$data.count) // => 4
-console.log(vm.count) // => 4
+These instance properties are only added when the instance is first created, so you need to ensure they are all present in the object returned by the `data` function. Where necessary, use `null`, `undefined` or some other placeholder value for properties where the desired value isn't yet available.
 
-// Assigning a value to vm.count will also update $data.count
-vm.count = 5
-console.log(vm.$data.count) // => 5
+It is possible to add a new property directly to the component instance without including it in `data`. However, because this property isn't backed by the reactive `$data` object, it won't automatically be tracked by [Vue's reactivity system](/guide/advanced/reactivity-in-depth.html).
 
-// ... and vice-versa
-vm.$data.count = 6
-console.log(vm.count) // => 6
-```
+Vue uses a `$` prefix when exposing its own built-in APIs via the component instance. It also reserves the prefix `_` for internal properties. You should avoid using names for top-level `data` properties that start with either of these characters.
 
 </div>
 
-These instance properties are only added when the instance is first created, so you need to ensure they are all present in the object returned by the `data` function. Where necessary, use `null`, `undefined` or some other placeholder value for properties where the desired value isn't yet available.
+<div class="composition-api">
 
-It is possible to add a new property directly to the component instance without including it in `data`. However, because this property isn't backed by the reactive `$data` object, it won't automatically be tracked by [Vue's reactivity system](/guide/advanced/reactivity-in-depth.html).
 
-Vue uses a `$` prefix when exposing its own built-in APIs via the component instance. It also reserves the prefix `_` for internal properties. You should avoid using names for top-level `data` properties that start with either of these characters.
+
+</div>
 
 ## Methods
 
@@ -114,18 +101,17 @@ Vue doesn't include built-in support for debouncing or throttling but it can be
 
 In cases where a component is only used once, the debouncing can be applied directly within `methods`:
 
-```vue-html
-<script src="https://unpkg.com/[email protected]/lodash.min.js"></script>
-<script>
-  Vue.createApp({
-    methods: {
-      // Debouncing with Lodash
-      click: _.debounce(function() {
-        // ... respond to click ...
-      }, 500)
-    }
-  }).mount('#app')
-</script>
+```js
+import { debounce } from 'lodash-es'
+
+createApp({
+  methods: {
+    // Debouncing with Lodash
+    click: debounce(function () {
+      // ... respond to click ...
+    }, 500)
+  }
+}).mount('#app')
 ```
 
 However, this approach is potentially problematic for components that are reused because they'll all share the same debounced function. To keep the component instances independent from each other, we can add the debounced function in the `created` lifecycle hook:

src/guide/essentials/template-syntax.md

@@ -60,7 +60,7 @@ Because `v-bind` is so commonly used, it has a dedicated shorthand syntax:
 
 Attributes that start with `:` may look a bit different from normal HTML, but it is in fact a valid character for attribute names and all Vue-supported browsers can parse it correctly. In addition, they do not appear in the final rendered markup. The shorthand syntax is optional, but you will likely appreciate it when you learn more about its usage later.
 
-> From this point on, we will be using the shorthand syntax in code examples, as that's the most common usage for Vue developers.
+> For the rest of the guide, we will be using the shorthand syntax in code examples, as that's the most common usage for Vue developers.
 
 ### Boolean Attributes
 
@@ -96,9 +96,9 @@ So far we've only been binding to simple property keys in our templates. But Vue
 
 These expressions will be evaluated as JavaScript in the data scope of the current component instance.
 
-JavaScript expressions can be used in the following positions:
+In Vue templates, JavaScript expressions can be used in the following positions:
 
-- Inside text interpolation (mustaches)
+- Inside text interpolations (mustaches)
 - In the attribute value of any `v-` directive bindings (including shorthands)
 
 ### Expressions Only
@@ -153,7 +153,7 @@ Another example is the `v-on` directive, which listens to DOM events:
 <a @click="url"> ... </a>
 ```
 
-Here the argument is the event name to listen to. `v-on` is one of the few directives that also have a corresponding shorthand, with its shorthand character being `@`. We will talk about event handling in more detail too.
+Here the argument is the event name to listen to: `click`. `v-on` is one of the few directives that also have a corresponding shorthand, with its shorthand character being `@`. We will talk about event handling in more detail too.
 
 ### Dynamic Arguments
 
@@ -187,7 +187,7 @@ In this example, when `eventName`'s value is `"focus"`, `v-on:[eventName]` will
 
 Dynamic arguments are expected to evaluate to a string, with the exception of `null`. The special value `null` can be used to explicitly remove the binding. Any other non-string value will trigger a warning.
 
-#### Dynamic Argument Expression Constraints
+#### Dynamic Argument Syntax Constraints
 
 Dynamic argument expressions have some syntax constraints because certain characters, such as spaces and quotes, are invalid inside HTML attribute names. For example, the following is invalid:
 

src/guide/quick-start.md

@@ -1,8 +1,12 @@
+---
+aside: deep
+---
+
 # Quick Start
 
 ## Without Build Tools
 
-Vue can be used without a build step in progressive enhancement or relatively simple use cases. Simply copy the following code into an HTML file and open it in your browser:
+To get started with Vue without a build step, simply copy the following code into an HTML file and open it in your browser:
 
 ```html
 <script type="importmap">
@@ -13,6 +17,8 @@ Vue can be used without a build step in progressive enhancement or relatively si
   }
 </script>
 
+<div id="app">{{ message }}</div>
+
 <script type="module">
   import { createApp } from 'vue'
 
@@ -24,19 +30,45 @@ Vue can be used without a build step in progressive enhancement or relatively si
     }
   }).mount('#app')
 </script>
-
-<div id="app">
-  <!-- template -->
-  {{ message }}
-</div>
 ```
 
-The above example uses a browser feature called [Import Maps](https://caniuse.com/import-maps) so that we can use the short `'vue'` import specifier across all code samples in the documentation. Import Maps is currently only available in Chromium-based browsers - if your preferred browser does not support it yet, you can polyfill it with [es-module-shims](https://github.com/guybedford/es-module-shims).
+Notice how we can import directly from `'vue'` in our code - this is made possible by the `<script type="importmap">` block, leveraging a browser feature called [Import Maps](https://caniuse.com/import-maps). Import maps are currently only available in Chromium-based browsers, so we recommend using Chrome or Edge during the learning process. If your preferred browser does not support import maps yet, you can polyfill it with [es-module-shims](https://github.com/guybedford/es-module-shims).
+
+You can add entries for other dependencies to the import map - just make sure they point to the ES modules version of the library you intend to use.
 
-:::tip For learning only
+:::tip Not for production
 The import-maps-based setup is meant for learning only - if you intend to use Vue without build tools in in production, make sure to check out the [Production Deployment Guide](/guide/best-practices/production-deployment.html#without-build-tools).
 :::
 
+### Serving over HTTP
+
+As we dive deeper into the guide, we may need to split our code into separate JavaScript files so that they are easier to manage. For example:
+
+```js
+import MyComponent from './my-component.js'
+```
+
+In order for this to work, you need to serve your HTML over the `http://` protocol instead of `file://` protocol. To start a local HTTP server, first install [Node.js](https://nodejs.org/en/), and then run `npx serve` from the command line in the same directory where your HTML file is.
+
+### Using the Global Build
+
+For consistency, we will be exclusively using [ES modules](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Guide/Modules) syntax throughout the documentation. That said, Vue is also available in a more traditional build where it exposes a global `Vue` variable:
+
+```html
+<script src="https://unpkg.com/vue@3"></script>
+
+<div id="app">...</div>
+
+<script>
+  // instead of `import { createApp } from 'vue'`:
+  const { createApp } = Vue
+
+  createApp({
+    // ...
+  }).mount('#app')
+</script>
+```
+
 ## With Build Tools
 
 A build setup allows us to use Vue [Single File Components](/guide/scaling-up/sfc) (SFCs). The official Vue build setup is based on [Vite](https://vitejs.dev), a frontend build tool that is modern, lightweight and extremely fast.
@@ -78,17 +110,11 @@ If you are unsure about an option, simply choose `No` by hitting enter for now.
 
 You should now have your first Vue project running!
 
+- The recommended IDE setup is [Visual Studio Code](https://code.visualstudio.com/) + [Volar extension](https://marketplace.visualstudio.com/items?itemName=johnsoncodehk.volar). [WebStorm](https://www.jetbrains.com/webstorm/) is also viable.
 - More tooling details are discussed in the [Tooling Guide](/guide/scaling-up/tooling.html).
 - To learn more about the underlying build tool Vite, check out the [Vite docs](https://vitejs.dev).
 - If you chose to use TypeScript, check out [Using Vue with TypeScript](scaling-up/typescript.html).
 
-## IDE Setup
-
-If you are using Vue with build tools, it is recommended to use the following IDE setup for get syntax highlighting, type inference and auto-completion support for Single File Components:
-
-- Recommended: [Visual Studio Code](https://code.visualstudio.com/) + [Volar extension](https://marketplace.visualstudio.com/items?itemName=johnsoncodehk.volar)
-- Also viable: [JetBrains WebStorm](https://www.jetbrains.com/webstorm/)
-
 ## Next Steps
 
 If you skipped the [Introduction](/guide/introduction), we strongly recommend reading it before moving on to the rest of the documentation.