Merge remote-tracking branch 'upstream/main' into main

Author: narusas

src/about/team/members-partner.json

@@ -16,6 +16,28 @@
       "twitter": "MariaLamardo"
     }
   },
+  {
+    "name": "Daniel Roe",
+    "title": "Framework Architect",
+    "company": "Nuxt",
+    "projects": [
+      {
+        "label": "nuxt",
+        "url": "https://github.com/nuxt"
+      },
+      {
+        "label": "typed-vuex",
+        "url": "https://github.com/danielroe/typed-vuex"
+      }
+    ],
+    "location": "United Kingdom",
+    "languages": ["English"],
+    "socials": {
+      "github": "danielroe",
+      "twitter": "danielcroe",
+      "linkedin": "daniel-roe"
+    }
+  },
   {
     "name": "Pratik Patel",
     "avatarPic": "https://pbs.twimg.com/profile_images/1541624512/profile-pic-09-11-2011_400x400.png",

src/api/ApiIndex.vue

@@ -31,7 +31,9 @@ const filtered = computed(() => {
             return item
           }
           // filter headers
-          const matchedHeaders = item.headers.filter(matches)
+          const matchedHeaders = item.headers.filter(
+            ({ text, anchor }) => matches(text) || matches(anchor)
+          )
           return matchedHeaders.length
             ? { text: item.text, link: item.link, headers: matchedHeaders }
             : null
@@ -92,8 +94,8 @@ function slugify(text: string): string {
         >
           <h3>{{ item.text }}</h3>
           <ul>
-            <li v-for="h of item.headers" :key="h">
-              <a :href="item.link + '.html#' + slugify(h)">{{ h }}</a>
+            <li v-for="h of item.headers" :key="h.anchor">
+              <a :href="item.link + '.html#' + slugify(h.anchor)">{{ h.anchor }}</a>
             </li>
           </ul>
         </div>

src/api/api.data.ts

@@ -4,12 +4,17 @@ import fs from 'fs'
 import path from 'path'
 import { sidebar } from '../../.vitepress/config'
 
+interface APIHeader {
+  anchor: string
+  text: string
+}
+
 export interface APIGroup {
   text: string
   items: {
     text: string
     link: string
-    headers: string[]
+    headers: APIHeader[]
   }[]
 }
 
@@ -34,7 +39,7 @@ export default {
 const headersCache = new Map<
   string,
   {
-    headers: string[]
+    headers: APIHeader[]
     timestamp: number
   }
 >()
@@ -50,15 +55,19 @@ function parsePageHeaders(link: string) {
 
   const src = fs.readFileSync(fullPath, 'utf-8')
   const h2s = src.match(/^## [^\n]+/gm)
-  let headers: string[] = []
+  let headers: APIHeader[] = []
   if (h2s) {
-    headers = h2s.map((h) =>
-      h
-        .slice(2)
-        .replace(/<sup class=.*/, '')
-        .replace(/\\</g, '<')
-        .replace(/`([^`]+)`/g, '$1')
-        .trim()
+    headers = h2s.map((h) => {
+        const text = h
+          .slice(2)
+          .replace(/<sup class=.*/, '')
+          .replace(/\\</g, '<')
+          .replace(/`([^`]+)`/g, '$1')
+          .replace(/\{#([a-zA-Z0-9-]+)\}/g, '') // hidden anchor tag
+          .trim()
+        const anchor = h.match(/\{#([a-zA-Z0-9-]+)\}/)?.[1] ?? text
+        return { text, anchor }
+      }
     )
   }
   headersCache.set(fullPath, {

src/api/general.md

@@ -122,6 +122,18 @@ A type helper for defining a Vue component with type inference.
   type FooInstance = InstanceType<typeof Foo>
   ```
 
+  ### Note on webpack Treeshaking
+
+  Because `defineComponent()` is a function call, it could look like that it would produce side-effects to some build tools, e.g. webpack. This will prevent the component from being tree-shaken even when the component is never used.
+
+  To tell webpack that this function call is safe to be tree-shaken, you can add a `/*#__PURE__*/` comment notation before the function call:
+
+  ```js
+  export default /*#__PURE__*/ defineComponent(/* ... */)
+  ```
+
+  Note this is not necessary if you are using Vite, because Rollup (the underlying production bundler used by Vite) is smart enough to determine that `defineComponent()` is in fact side-effect-free without the need for manual annotations.
+
 - **See also:** [Guide - Using Vue with TypeScript](/guide/typescript/overview.html#general-usage-notes)
 
 ## defineAsyncComponent()

src/ecosystem/themes/themes.json

@@ -165,6 +165,20 @@
         "url": "https://www.primefaces.org/layouts/diamond-vue?af_id=4218",
         "image": "https://www.primefaces.org/vue-templates/diamond.jpg"
       },
+      {
+        "name": "Poseidon",
+        "price": 59,
+        "description": "PrimeOne Design Admin Template",
+        "url": "https://www.primefaces.org/layouts/poseidon-vue?af_id=4218",
+        "image": "https://www.primefaces.org/vue-templates/poseidon.jpg"
+      },
+      {
+        "name": "Verona",
+        "price": 49,
+        "description": "PrimeOne Design Admin Template",
+        "url": "https://www.primefaces.org/layouts/verona-vue?af_id=4218",
+        "image": "https://www.primefaces.org/vue-templates/verona.jpg"
+      },
       {
         "name": "Sapphire",
         "price": 49,

src/guide/essentials/computed.md

@@ -263,7 +263,7 @@ Now when you run `fullName.value = 'John Doe'`, the setter will be invoked and `
 
 ### Getters should be side-effect free
 
-It is important to remember that computed getter functions should only perform pure computation and be free of side effects. For example, don't make async requests or mutate the DOM inside a computed getter! Think of a computed property as declaratively describing how to derive a value based on other values - its only responsibility should be computing and returning that value. Later in the guide we will discuss how we can perform side effects in reaction to state changes with [watchers](./watchers).
+It is important to remember that computed getter functions should only perform pure computation and be free of side effects. For example, **don't make async requests or mutate the DOM inside a computed getter!** Think of a computed property as declaratively describing how to derive a value based on other values - its only responsibility should be computing and returning that value. Later in the guide we will discuss how we can perform side effects in reaction to state changes with [watchers](./watchers).
 
 ### Avoid mutating computed value
 

src/guide/extras/web-components.md

@@ -64,7 +64,7 @@ module.exports = {
 
 ### 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://web.dev/index.md/).
+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://web.dev/custom-elements-best-practices/).
 
 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:
 

src/guide/scaling-up/sfc.md

@@ -2,7 +2,7 @@
 
 ## Introduction
 
-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:
+Vue Single-File Components (a.k.a. `*.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:
 
 ```vue
 <script>
@@ -27,14 +27,14 @@ export default {
 </style>
 ```
 
-As we can see, Vue SFC is a natural extension of the classic trio of HTML, CSS and JavaScript. The `<template>`, `<script>`, and `<style>` blocks encapsulates and collocates the view, logic and styling of a component in the same file. The full syntax is defined in the [SFC Syntax Specification](/api/sfc-spec).
+As we can see, Vue SFC is a natural extension of the classic trio of HTML, CSS and JavaScript. The `<template>`, `<script>`, and `<style>` blocks encapsulate and colocate the view, logic and styling of a component in the same file. The full syntax is defined in the [SFC Syntax Specification](/api/sfc-spec).
 
 ## Why SFC
 
 While SFCs require a build step, there are numerous benefits in return:
 
 - Author modularized components using familiar HTML, CSS and JavaScript syntax
-- [Collocation of inherently coupled concerns](#what-about-separation-of-concerns)
+- [Colocation of inherently coupled concerns](#what-about-separation-of-concerns)
 - Pre-compiled templates
 - [Component-scoped CSS](/api/sfc-css-features)
 - [More ergonomic syntax when working with Composition API](/api/sfc-script-setup)
@@ -48,7 +48,7 @@ SFC is a defining feature of Vue as a framework, and is the recommended approach
 - Static Site Generation (SSG)
 - Any non-trivial frontend where a build step can be justified for better development experience (DX).
 
-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 6kb subset of Vue optimized for progressive enhancement.
+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 6 kB subset of Vue optimized for progressive enhancement.
 
 ## How It Works
 
@@ -74,8 +74,8 @@ In actual projects, we typically integrate the SFC compiler with a build tool su
 
 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 the separation of file types.** The ultimate goal of engineering principles is to improve the 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.
+To answer this question, it is important for us to agree that **separation of concerns is not equal to the separation of file types**. The ultimate goal of engineering principles is to improve the 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.
+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 colocating 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).

src/guide/typescript/overview.md

@@ -129,7 +129,10 @@ export default defineComponent({
 })
 ```
 
-See also: [type tests for `defineComponent`](https://github.com/vuejs/core/blob/main/test-dts/defineComponent.test-d.tsx)
+See also:
+
+- [Note on webpack Treeshaking](/api/general.html#note-on-webpack-treeshaking)
+- [type tests for `defineComponent`](https://github.com/vuejs/core/blob/main/test-dts/defineComponent.test-d.tsx)
 
 :::tip
 `defineComponent()` also enables type inference for components defined in plain JavaScript.

src/partners/components/PartnerCard.vue

@@ -98,7 +98,7 @@ h3 {
 .partner-card.hero .big {
   display: inline-block;
   margin-left: auto;
-  width: 60%;
+  max-width: 60%;
   max-height: 360px;
   object-fit: cover;
 }
@@ -115,6 +115,7 @@ h3 {
   }
   .partner-card.hero .big {
     width: 100%;
+    max-width: 100%;
   }
 }