webcomponents

Web Component Custom Data Sample

This sample demonstrates how you can use VS Code's HTML / CSS Custom Data support to enhance your WebComponents HTML editing experience.

The Custom Data format enhances auto-completion and hover information support for HTML. These two features ease the two essential acts of coding: reading and writing code. With its Markdown support, Custom Data allows you to show text documentation, links and code samples, right in the editor when the user is writing or reading the WebComponents HTML.

You can join the discussion at w3c/webcomponents, or open new issues in this repository to discuss about Custom Data.

Demo

Explanation

When you open this folder in VS Code, you should be able to use the auto-completion and hover features as shown in the demo above. You can try these features in index.html.

This is supported through the html.customData setting found in .vscode/settings.json:

{
  "html.customData": [
    "./src/web-components.html-data.json",
    "./node_modules/@github/time-elements/web-components.html-data.json"
  ]
}

The setting points to a list of JSON files that follows the HTML Custom Data schema. VS Code's HTML Language Server will read those JSON during startup and then provide language editing features for the defined HTML tags, attributes and attribute values.

The two demos show two different scenarios:

1. src/web-components.html-data.json. This shows how users who have written components and wish to use them in HTML can take advantage of Custom Data.

   The JSON file src/web-component.html-data.json can either be hand-written or generated by tools such as https://github.com/runem/web-component-analyzer.

2. node_modules/@github/time-elements/web-components.html-data.json. This shows how WebComponents library authors can distribute Custom Data with their components to offer documentation, auto completion and hover information to end users. This is similar to how today JavaScript library authors distribute their packages with TypeScript type definitions. (For example, look at node_modules/@github/time-elements/index.d.ts).

   The Custom Data for @github/time-elements currently is hand-written, but in the future it might be possible to:

• Use an analyzer to examine the JS entry file and generate such Custom Data
• Let frameworks emit such Custom Data as part of their compilation process (just as TypeScript would generate d.ts files from TS files)

Limitations

• VS Code's HTML language server loads these components upon startup. Ideally, as users change the configuration, VS Code's HTML language server should reload the data. microsoft/vscode#67750.
• slot is not being parsed and no <slot> or <slot name=""> completions yet.
• No emmet support yet. Tracked in microsoft/vscode#64032.
• There's no description for events yet.