Correct and improve docs on type definitions for Custom Elements.

The doc was incorrect for two reasons:

- For Vue-based custom elements, the type passed into `GlobalComponents` needs to be the Vue component type, not the custom element type, or the custom elements will not be type checked in any Vue templates.
- The name of the elements need to have at least two words and a hyphen, otherwise with single words the custom elements will not be type checked in any Vue templates.

Author: trusktr

src/guide/extras/web-components.md

@@ -242,25 +242,73 @@ If you have many components, you can also leverage build tool features such as V
 
 If you are developing an application or a library, you may want to [type check](/guide/scaling-up/tooling.html#typescript) your Vue components, including those that are defined as custom elements.
 
-Custom elements are registered globally using native APIs, so by default they won't have type inference when used in Vue templates. To provide type support for Vue components registered as custom elements, we can register global component typings using the the [`GlobalComponents` interface](https://github.com/vuejs/language-tools/blob/master/packages/vscode-vue/README.md#usage) in Vue templates and/or in [JSX](https://www.typescriptlang.org/docs/handbook/jsx.html#intrinsic-elements):
+Custom elements are registered globally using native APIs, so by default they won't have type inference when used in Vue templates. To provide type support for Vue components registered as custom elements, we can register global component typings by augmenting the [`GlobalComponents` interface](https://github.com/vuejs/language-tools/blob/master/packages/vscode-vue/README.md#usage) for type checking in Vue templates (JSX users can augment the [JSX.IntrinsicElements](https://www.typescriptlang.org/docs/handbook/jsx.html#intrinsic-elements) type, which is not shown here).
+
+Here is how to define the type for a custom element made with Vue:
 
 ```typescript
 import { defineCustomElement } from 'vue'
 
-// vue SFC
-import CounterSFC from './src/components/counter.ce.vue'
+// Import the Vue component.
+import SomeComponent from './src/components/SomeComponent.ce.vue'
+
+// Turn the Vue component into a Custom Element class.
+export const SomeElement = defineCustomElement(SomeComponent)
+
+// Remember define the element with the browser, or the element will not be instantiated.
+window.customElements.define('some-element', SomeElement)
+
+// Augment Vue's GlobalComponents type with the new element type.
+declare module 'vue' {
+  interface GlobalComponents {
+    // Be sure to pass in the Vue component type here (SomeComponent, not SomeElement).
+    // Custom Elements require a hyphen in their name, so best to use the element name here.
+    'some-element': typeof SomeComponent 
+  }
+}
+```
+
+Here is how to define the type for any other custom element not made with Vue, assuming that such elements have type definitions:
+
+```ts
+import {SomeElement} from 'some-lib'
+import type {Component} from 'vue'
+
+// Some Custom Element libraries pre-define their elements. But if they require you to do it instead, remember to do that:
+// window.customElements.define('some-element', SomeElement)
 
-// turn component into web components
-export const Counter = defineCustomElement(CounterSFC)
+// List the properties of the SomeElement class that should be exposed to Vue templates for type checking.
+type SomeElementAttributes = 'foo' | 'bar'
 
-// register global typings
+// Add the new element type to Vue's GlobalComponents type.
 declare module 'vue' {
-  export interface GlobalComponents {
-    Counter: typeof Counter
+  interface GlobalComponents {
+    'some-element': Component<Partial<Pick<SomeElement, SomeElementAttributes>>>
   }
 }
 ```
 
+A current limitation of this approach for non-Vue custom elements is that event types are not included, for example props like `@some-event="..."` are currently all typed as `(event: Event) => void` without more specific even types. An `Event` can be downcasted into a more specific type as needed.
+
+If an element does not have type definitions (for example when they are plain JS and the types are not inferrable by TypeScript), the types of the properties can be defined manually:
+
+```ts
+import {SomeElement} from 'some-lib'
+import type {Component} from 'vue'
+
+// Some Custom Element libraries pre-define their elements. But if they require you to do it instead, remember to do that:
+// window.customElements.define('some-element', SomeElement)
+
+// Add the new element type to Vue's GlobalComponents type.
+declare module 'vue' {
+  interface GlobalComponents {
+    'some-element': Component<{foo?: number, bar?: string}>
+  }
+}
+```
+
+Custom Element library authors can include one or more `.d.ts` files that their users can import, which contain the augmentation so that users don't have to do it themselves. For example, the previous sample could be in a file named `SomeElement.vue-types.d.ts` which is sibling to the other files that the library ships, for Vue users to import in addition to the main file that defines the custom element class.
+
 ## Web Components vs. Vue Components {#web-components-vs-vue-components}
 
 Some developers believe that framework-proprietary component models should be avoided, and that exclusively using Custom Elements makes an application "future-proof". Here we will try to explain why we believe that this is an overly simplistic take on the problem.