Merge branch 'main' of https://github.com/vuejs/docs

Author: danielkellyio

.vitepress/config.ts

@@ -1,10 +1,9 @@
 import fs from 'fs'
 import path from 'path'
 import { defineConfigWithTheme } from 'vitepress'
+import type { Config as ThemeConfig } from '@vue/theme'
 import baseConfig from '@vue/theme/config'
 import { headerPlugin } from './headerMdPlugin'
-import type { Config } from '@vue/theme'
-import { UserConfig } from 'vitepress'
 
 const nav = [
   {
@@ -531,8 +530,8 @@ export const sidebar = {
   ]
 }
 
-export default defineConfigWithTheme<Config>({
-  extends: baseConfig as () => UserConfig<Config>,
+export default defineConfigWithTheme<ThemeConfig>({
+  extends: baseConfig,
 
   lang: 'en-US',
   title: 'Vue.js',
@@ -571,6 +570,7 @@ export default defineConfigWithTheme<Config>({
       {
         src: 'https://cdn.usefathom.com/script.js',
         'data-site': 'XNOLWPLB',
+        'data-spa': 'auto',
         defer: ''
       }
     ]

.vitepress/theme/components/PreferenceSwitch.vue

@@ -1,7 +1,7 @@
 <script setup lang="ts">
 import { VTSwitch, VTIconChevronDown } from '@vue/theme'
 import { useRoute } from 'vitepress'
-import { ref, computed, inject, Ref } from 'vue'
+import { inject, Ref } from 'vue'
 import {
   preferCompositionKey,
   preferComposition,
@@ -10,17 +10,15 @@ import {
 } from './preferences'
 
 const route = useRoute()
-const show = computed(() =>
+const show = $computed(() =>
   /^\/(guide|tutorial|examples)\//.test(route.path)
 )
-const showSFC = computed(() => !/^\/guide/.test(route.path))
-const isOpen = ref(
-  typeof localStorage !== 'undefined' &&
-    !localStorage.getItem(preferCompositionKey)
-)
+const showSFC = $computed(() => !/^\/guide/.test(route.path))
+
+let isOpen = $ref(true)
 
 const toggleOpen = () => {
-  isOpen.value = !isOpen.value
+  isOpen = !isOpen
 }
 
 const removeOutline = (e: Event) => {

src/api/composition-api-lifecycle.md

@@ -115,7 +115,7 @@ Registers a callback to be called after the component has been unmounted.
 
   ```vue
   <script setup>
-  import { onMounted, unUnmounted } from 'vue'
+  import { onMounted, onUnmounted } from 'vue'
 
   let intervalId
   onMounted(() => {

src/api/options-rendering.md

@@ -2,7 +2,7 @@
 
 ## template
 
-A string template for the component instance.
+A string template for the component.
 
 - **Type**
 
@@ -14,13 +14,13 @@ A string template for the component instance.
 
 - **Details**
 
-  Template provided via the `template` option will be compiled on-the-fly, therefore it is only supported when using the full build (i.e. the standalone `vue.js` that can compile templates in the browser).
-
-  The template will **replace** the `innerHTML` of mounted element. Any existing markup inside the mounted element will be ignored.
+  A template provided via the `template` option will be compiled on-the-fly at runtime. It is only supported when using a full build of Vue that includes the template compiler. The builds that include the template compiler have the word `runtime` in their names, e.g. `vue.runtime.esm-bundler.js`. Consult the [dist file guide](https://github.com/vuejs/core/tree/main/packages/vue#which-dist-file-to-use) for more details about the different builds.
 
   If the string starts with `#` it will be used as a `querySelector` and use the selected element's `innerHTML` as the template string. This allows the source template to be authored using native `<template>` elements.
 
-  If the `render` is also present in the same component, `template` will be ignored.
+  If the `render` option is also present in the same component, `template` will be ignored.
+
+  If the root component of your application doesn't have a `template` or `render` option specified, Vue will try to use the `innerHTML` of the mounted element as the template instead.
 
   :::warning Security Note
   Only use template sources that you can trust. Do not use user-provided content as your template. See [Security Guide](/guide/best-practices/security.html#rule-no-1-never-use-non-trusted-templates) for more details.

src/api/options-state.md

@@ -78,7 +78,7 @@ Declare the props of a component.
 
 - **Details**
 
-  In Vue, all component props need to be explicit declared. Component props can be declared in two forms:
+  In Vue, all component props need to be explicitly declared. Component props can be declared in two forms:
 
   - Simple form using an array of strings
   - Full form using an object where each property key is the name of the prop, and the value is the prop's type (a constructor function) or advanced options.

src/api/sfc-script-setup.md

@@ -127,6 +127,31 @@ import * as Form from './form-components'
 </template>
 ```
 
+## Using Custom Directives
+
+Globally registered custom directives just work as normal. Local custom directives don't need to be explicitly registered with `<script setup>`, but they must follow the naming scheme `vNameOfDirective`:
+
+```vue
+<script setup>
+const vMyDirective = {
+  beforeMount: (el) => {
+    // do something with the element
+  }
+}
+</script>
+<template>
+  <h1 v-my-directive>This is a Heading</h1>
+</template>
+```
+
+If you're importing a directive from elsewhere, it can be renamed to fit the required naming scheme:
+
+```vue
+<script setup>
+import { myDirective as vMyDirective } from './MyDirective.js'
+</script>
+```
+
 ## defineProps() & 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>`:

src/examples/src/cells/App/template.html

@@ -8,7 +8,7 @@
   <tbody>
     <tr v-for="i in cells[0].length">
       <th>{{ i - 1 }}</th>
-      <td v-for="c, j in cols">
+      <td v-for="(c, j) in cols">
         <Cell :r="i - 1" :c="j"></Cell>
       </td>
     </tr>

src/guide/best-practices/accessibility.md

@@ -277,6 +277,27 @@ Avoid using placeholders as they can confuse many users.
 
 One of the issues with placeholders is that they don't meet the [color contrast criteria](https://www.w3.org/WAI/WCAG21/Understanding/contrast-minimum.html) by default; fixing the color contrast makes the placeholder look like pre-populated data in the input fields. Looking at the following example, you can see that the Last Name placeholder which meets the color contrast criteria looks like pre-populated data:
 
+```vue-html
+<form
+  class="demo"
+  action="/dataCollectionLocation"
+  method="post"
+  autocomplete="on"
+>
+  <div v-for="item in formItems" :key="item.id" class="form-item">
+    <label :for="item.id">{{ item.label }}: </label>
+    <input
+      type="text"
+      :id="item.id"
+      :name="item.id"
+      v-model="item.value"
+      :placeholder="item.placeholder"
+    />
+  </div>
+  <button type="submit">Submit</button>
+</form>
+```
+
 <!-- <common-codepen-snippet title="Form Placeholder" slug="ExZvvMw" :height="265" tab="js,result" theme="light" :preview="false" :editable="false" /> -->
 
 It is best to provide all the information the user needs to fill out forms outside any inputs.

src/guide/components/images/scoped-slots.svg

@@ -344,6 +344,10 @@ Receiving the slot props is a bit different when using a single default slot vs.
 </MyComponent>
 ```
 
+![scoped slots diagram](./images/scoped-slots.svg)
+
+<!-- https://www.figma.com/file/QRneoj8eIdL1kw3WQaaEyc/scoped-slot -->
+
 <div class="composition-api">
 
 [Try it in the Playground](https://sfc.vuejs.org/#eyJBcHAudnVlIjoiPHNjcmlwdCBzZXR1cD5cbmltcG9ydCBNeUNvbXBvbmVudCBmcm9tICcuL015Q29tcG9uZW50LnZ1ZSdcbjwvc2NyaXB0PlxuXG48dGVtcGxhdGU+XG5cdDxNeUNvbXBvbmVudCB2LXNsb3Q9XCJzbG90UHJvcHNcIj5cbiAgXHR7eyBzbG90UHJvcHMudGV4dCB9fSB7eyBzbG90UHJvcHMuY291bnQgfX1cbiAgPC9NeUNvbXBvbmVudD5cbjwvdGVtcGxhdGU+IiwiaW1wb3J0LW1hcC5qc29uIjoie1xuICBcImltcG9ydHNcIjoge1xuICAgIFwidnVlXCI6IFwiaHR0cHM6Ly9zZmMudnVlanMub3JnL3Z1ZS5ydW50aW1lLmVzbS1icm93c2VyLmpzXCJcbiAgfVxufSIsIk15Q29tcG9uZW50LnZ1ZSI6IjxzY3JpcHQgc2V0dXA+XG5jb25zdCBncmVldGluZ01lc3NhZ2UgPSAnaGVsbG8nXG48L3NjcmlwdD5cblxuPHRlbXBsYXRlPlxuICA8ZGl2PlxuICBcdDxzbG90IDp0ZXh0PVwiZ3JlZXRpbmdNZXNzYWdlXCIgOmNvdW50PVwiMVwiPjwvc2xvdD5cblx0PC9kaXY+XG48L3RlbXBsYXRlPiJ9)
@@ -403,7 +407,7 @@ Named scoped slots work similarly - slot props are accessible as the value of th
   </template>
 
   <template #footer="footerProps">
-    {{ headerProps }}
+    {{ footerProps }}
   </template>
 </MyComponent>
 ```