wip: application & template syntax

Author: yyx990803

src/public/images/oxford-comma.jpg renamed to .github/contributing/oxford-comma.jpg

@@ -57,7 +57,7 @@ Writing documentation is an exercise in empathy. We're not describing an objecti
 
 - **Avoid abbreviations** in writing and code examples (e.g. `attribute` is better than `attr`, `message` is better than `msg`), unless you are specifically referencing an abbreviation in an API (e.g. `$attrs`). Abbreviation symbols included on standard keyboards (e.g. `@`, `#`, `&`) are OK.
 - **When referencing a directly following example, use a colon (`:`) to end a sentence**, rather than a period (`.`).
-- **Use the Oxford comma** (e.g. "a, b, and c" instead of "a, b and c"). ![Why the Oxford comma is important](/images/oxford-comma.jpg)
+- **Use the Oxford comma** (e.g. "a, b, and c" instead of "a, b and c"). ![Why the Oxford comma is important](./oxford-comma.jpg)
   - Source: [The Serial (Oxford) Comma: When and Why To Use It](https://www.inkonhand.com/2015/10/the-serial-oxford-comma-when-and-why-to-use-it/)
 - **When referencing the name of a project, use the name that project refers to itself as.** For example, "webpack" and "npm" should both use lowercase as that's how their documentation refers to them.
 - **Use Title Case for headings** - at least for now, since it's what we use through the rest of the docs. There's research suggesting that sentence case (only first word of the heading starts with a capital) is actually superior for legibility and also reduces the cognitive overhead for documentation writers, since they don't have to try to remember whether to capitalize words like "and", "with", and "about".

.github/contributing/writing-guide.md

@@ -1,10 +1,10 @@
 ;(() => {
-  const restore = (key, cls) => {
+  const restore = (key, cls, def = false) => {
     const saved = localStorage.getItem(key)
-    if (saved && saved !== 'false') {
+    if (saved ? saved !== 'false' : def) {
       document.documentElement.classList.add(cls)
     }
   }
   restore('vue-docs-prefer-composition', 'prefer-composition')
-  restore('vue-docs-prefer-sfc', 'prefer-sfc')
+  restore('vue-docs-prefer-sfc', 'prefer-sfc', true)
 })()

src/.vitepress/inlined-scripts/restorePreference.js

@@ -1,11 +1,13 @@
 import { ref } from 'vue'
 
 const hasStorage = typeof localStorage !== 'undefined'
-const get = (key: string): boolean =>
-  hasStorage ? JSON.parse(localStorage.getItem(key) || 'false') : false
+const get = (key: string, defaultValue = false): boolean =>
+  hasStorage
+    ? JSON.parse(localStorage.getItem(key) || String(defaultValue))
+    : defaultValue
 
 export const preferCompositionKey = 'vue-docs-prefer-composition'
 export const preferComposition = ref(get(preferCompositionKey))
 
 export const preferSFCKey = 'vue-docs-prefer-sfc'
-export const preferSFC = ref(get(preferSFCKey))
+export const preferSFC = ref(get(preferSFCKey, true))

src/.vitepress/theme/components/preferences.ts

@@ -1,7 +1,13 @@
 .demo {
-  background-color: var(--vt-c-bg-soft);
+  /* background-color: var(--vt-c-bg-soft); */
+  transition: border-color 0.5s;
   padding: 22px 24px;
   border-radius: 8px;
+  border: 1px solid var(--vt-c-divider-light);
+}
+
+.demo p {
+  margin: 0;
 }
 
 .demo button {

src/.vitepress/theme/styles/inline-demo.css

@@ -2,6 +2,9 @@
 
 ## createApp()
 
+// TODO rework this
+// TODO document that you can pass props to the root component
+
 In Vue 3, APIs that globally mutate Vue's behavior are now moved to application instances created by the new `createApp` method. In addition, their effects are now scoped to that specific application's instance:
 
 ```js
@@ -347,7 +350,7 @@ You can modify its properties, listed below, before mounting your application.
 - **Usage:**
 
 ```js
-app.config.errorHandler = (err, vm, info) => {
+app.config.errorHandler = (err, instance, info) => {
   // handle error
   // `info` is a Vue-specific error info, e.g. which lifecycle hook
   // the error was found in
@@ -367,7 +370,7 @@ Assign a handler for uncaught errors during component render function and watche
 - **Usage:**
 
 ```js
-app.config.warnHandler = function (msg, vm, trace) {
+app.config.warnHandler = function (msg, instance, trace) {
   // `trace` is the component hierarchy trace
 }
 ```

src/api/application.md

@@ -259,6 +259,8 @@
 
   When used without an argument, can be used to bind an object containing attribute name-value pairs. Note in this mode `class` and `style` does not support Array or Objects.
 
+  // TODO details on auto prop/attr check
+
 - **Example:**
 
   ```vue-html

src/api/built-in-directives.md

@@ -1,7 +1,6 @@
 <p>
   <span :title="message">
-    Hover your mouse over me for a few seconds to see my dynamically bound
-    title!
+    Hover your mouse over me for a few seconds to see my dynamically bound title!
   </span>
 </p>
 

src/examples/src/attribute-bindings/App/template.html

@@ -2,7 +2,7 @@
 
 ## The App Instance
 
-Every Vue application starts by creating a new **application instance** with the `createApp` function:
+Every Vue application starts by creating a new **application instance** with the [`createApp`](/api/application#createapp) function:
 
 ```js
 import { createApp } from 'vue'
@@ -14,11 +14,48 @@ const app = createApp({
 
 ## The Root Component
 
-## Mounting the App
+The object we are passing into `createApp` is in fact a component. Every app requires a "root component" that can contain other components as its children.
+
+If you are using Single File Components, we typically import the root component from another file:
+
+```js
+import { createApp } from 'vue'
+// import the root component App from a single-file component.
+import App from './App.vue'
+
+const app = createApp(App)
+```
+
+While many examples in this guide only need a single component, most real applications are organized into a tree of nested, reusable components. For example, a Todo application's component tree might look like this:
+
+```
+App (root component)
+├─ TodoList
+│  └─ TodoItem
+│     ├─ DeleteTodoButton
+│     └─ EditTodoButton
+└─ TodoListFooter
+   ├─ ClearTodosButton
+   └─ TodoListStatistics
+```
+
+We will discuss how to define and compose multiple components together in later sections of the guide. Before that, we will focus on what happens inside a single component.
 
-## App-Scoped Assets
+## App Configurations
 
-The application instance is used to register 'globals' that can then be used by components within that application. We'll discuss that in detail later in the guide but as a quick example:
+The app instance exposes a `.config` object that allows us to configure a few app-level options, for example defining an app-level error handler that captures errors from all descendent components:
+
+```js
+app.config.errorHandler = (err) => {
+  /* handle error */
+}
+```
+
+You can browse the full list of `app.config` options in the [API reference](/api/application#app-config).
+
+## Global Assets
+
+The app instance is used to register "global assets" that can then be used by components within that app. We'll discuss them in detail later in the guide but here is a quick example:
 
 ```js
 const app = createApp({})
@@ -36,9 +73,7 @@ app.provide('store', myStore)
 app.use(LocalePlugin)
 ```
 
-### Chaining
-
-Most of the methods exposed by the application instance return that same instance, allowing for chaining:
+Most of the methods exposed by the application instance return that same instance, so we can also use the chaining syntax:
 
 ```js
 const app = createApp({})
@@ -48,6 +83,61 @@ const app = createApp({})
   .use(LocalePlugin)
 ```
 
-You can browse the full application API in the [API reference](/api/application.html).
+You can browse the full list of app instance methods in the [API reference](/api/application).
+
+## Mounting the App
+
+An app instance won't render anything until its `.mount()` method is called.
+It expects a "container" argument, which can either be an actual DOM element or a selector string:
+
+```html
+<div id="app"></div>
+```
+
+```js
+app.mount('#app')
+```
+
+The content of the app's root component will be rendered inside the container element. The container element itself is not considered part of the app.
+
+The `.mount()` method should always be called after all app configurations and asset registrations are done. Also note that its return value, unlike the asset registration methods, is the root component instance instead of the app instance.
+
+### In-DOM Root Component Template
+
+When using Vue without a build step, we can write our root component's template directly inside the mount container:
+
+```html
+<div id="app">
+  <button @click="count++">{{ count }}</button>
+</div>
+```
+
+```js
+import { createApp } from 'vue'
+
+const app = createApp({
+  data() {
+    return {
+      count: 0
+    }
+  }
+})
+
+app.mount('#app')
+```
+
+Vue will automatically use the container's `innerHTML` as the template if the root component does not already have a `template` option.
 
 ## Multiple App Instances
+
+You are not limited to a single app instance on the same page. The `createApp` API allows multiple Vue applications to co-exist on the same page, each with its own scope for configuration and global assets:
+
+```js
+const app1 = createApp({ /* ... */ })
+app1.mount('#container-1')
+
+const app2 = createApp({ /* ... */ })
+app2.mount('#container-2')
+```
+
+If you are using Vue to enhance server-rendered HTML and only need Vue to control specific parts of a large page, avoid mounting a singe Vue app instance on the entire page. Instead, create multiple small app instances and mount them on the elements they are responsible for.