Web Components support in HTML files

[octref]

Related:

• [html] Add support for custom tag providers for HTML #2784
• https://github.com/octref/vuetypes

Problem

WebComponent offers a JavaScript API to define HTML tags / attributes. We want people to get completion, diagnostics and other language features that's already available to the HTML server.

Approach

We plan to:

• Define a JSON schema for tag/attribute definition JSON file (like dts for TS projects)
• Allow user to specify a list of such tag/attribute JSON files as a setting

However, there is currently no way to auto-generate such a JSON file from user-authored JS files. In the short term, these files are most likely to be hand-written. In the long term, we hope we can standardize such a format and find a way to auto-generate these JSON files with the WebComponents community.

Supported Features

Working Out of the box

• DocumentHighlight
• DocumentSymbol
• Folding

Plan to Support

What we'll ship for November iteration:

• Completion: HTML tags.
• 🏃 Completion: HTML attributes. Attribute itself yes, attribute description 👉 HTML attribute completion description #66230
• Hover: Hovering over HTML tags / attributes should show descriptions.
  - [ ] Diagnostics:
  - Required attributes not included
  - Attribute value is not one of attribute's enum value
  - [ ] TextMate Grammar: Color web component tags/attributes differently

Hard to Support

We do want these features, but there is no clear way to implement these features.

• Jump to definition: Jumping to definition on <my-tag> should go to the JS file that defines such a class.
• Find References / Rename: Requires project understanding, but our HTML support is single file.

No plan to Support

• Signature Help: It does not make sense when Completion offers snippets.
• QuickFix: No sensible quick fix that we can offer.

[octref]

Let's take this file for example: https://github.com/mdn/web-components-examples/blob/master/composed-composed-path/main.js

The JSON could look like this:

{
  "components": [
    {
      "name": "open-shadow",
      "description": "Open Shadow DOM Component",
      "attributes": [
        {
          "name": "text",
          "description": "The text inside the component",
          "required": true
        }
      ]
    },
    {
      "name": "closed-shadow",
      "description": "Closed Shadow DOM Component",
      "attributes": [
        {
          "name": "text",
          "description": "The text inside the component",
          "required": true
        }
      ]
    }
  ]
}

[octref]

What we have now:

Here is how it works:

• You specify html.experimental.custom.tags and html.experimental.custom.attributes
• VS Code loads those tag/attribute definitions and offer completion, hover and other common HTML features

I'll open up issues in WebComponent related repos to get more feedback.

[ChenShihao]

The font looks awesome!! Could you please tell me the name of this? Thx!

[bahrus]

Really appreciate this feature. I upgraded to version 1.20, and I had good luck with my first two VSCode projects. However, I've tried on a number of other projects, and am not having luck. The intellisense for web-components.json isn't picking up the schema file, and defining -properties in web-coponents.json seems to have provide no help when editing .html files (contained in demo folder).

Example repo: https://github.com/bahrus/xtal-siema

Hope I'm (not) missing something simple.

Update:

Actually, the "schema support" may have been because I copy and pasted an existing document the first time, so the editor used pattern recognition to provide intellisense -- making me incorrectly jump to the conclusion that it was using schema support.

Also, it doesn't seem any tooltip is provided until attributes are defined.

[octref]

@bahrus It's working for me though:

You would need to reload VS Code after changing the JSON files. They are only loaded during startup.

[bahrus]

It is, I was wrong. It seems until you add the attributes array, tooltip for the tag name might not happen. Not a big issue, and I could be wrong.

[Blackbaud-TommyVernieri]

This is a great feature, thanks for working on it!

As I test it out, the elements I've defined show up only when I have a folder open in VS Code. If I go to New Window, Open File..., choose an HTML file, then I don't see completion for the elements I've defined in my settings.

I'd expect it to work on loose HTML files in addition to working in the context of an open folder.

[octref]

@Blackbaud-TommyVernieri What's your use cases?

The settings are local to each workspace. We also plan to allow extensions to add additional tags/attributes (#64022).

[Blackbaud-TommyVernieri]

Fair question. Honestly I was just testing it out and it wasn't obvious why it wasn't working. I had added the settings to my User Settings so it expected it to work for any HTML file. I ended up opening a workspace and it worked there.

For a more realistic use case: I sometimes author loose HTML files and then copy-paste that content into a web-based editor. I can certainly workaround that limitation by first opening folder or workspace; and I expect that my primary use case will be editing HTML files withing the context of a workspace when working in a cloned repo. So feel free to disregard this request if getting completion working on loose files is not a priority.

Thanks for linking to #64022, that's exactly what I'd like to be able to do next. That would let me distribute a common tags definition among coworkers. I'll keep an eye on how that one progresses. Thanks!

[2silver]

How can I escape colons ":" in attributes-values (label)? As far as I know colons are Json-valid values?
I tried to include TAL-Attributes, but it only shows the text before the colon

Example:

    {
      "attributes": [{
          "label": "tal:define",
          "description": "TAL-Template Define Attribute"
        }
      ]
    }

Only shows tal in Auto-Completion

[octref]

That's actually caused by our bad handling of attribute names. We used to store the data as:

${attribute-name}:${attribute-value-group-name}

So an attribute like spellcheck:b will prompt true | false (defined in b attribute value group) after the attribute completion.

I'll fix it in my PR microsoft/vscode-html-languageservice#45 and start writing updated docs / schemas for the JSON files.

[bkelley13]

Curious about plans for enumerations for attribute values or required? (ie, myattribute = {left|right})

[octref]

@2silver What you were doing was valueSet. Take a look at https://github.com/Microsoft/vscode-html-languageservice/blob/master/docs/customData.md.

@bkelley13 Take a look at https://github.com/Microsoft/vscode-html-languageservice/blob/master/docs/customData.md.

[octref]

Take a look at the new release notes for the custom data support: https://code.visualstudio.com/updates/v1_31#_html-and-css-custom-data-support

[bkelley13]

Many thanks, it's exactly what we are looking for.

[josundt]

The company I work for have for some time been creating a UI library with a broad collection of web components to be used across our company's applications.

We have made our own JSON metadata format for our components with our own JSON schema, and today we use these JSON files as models for our UI library documentation application. Devs use this application as a lookup reference when composing application features with our components.

But since the format was created, we had an intent to use these JSON files to provide intellisense/auto-completion to the VSCode HTML language service some time in the future.

So when the VSCode "Web Components support in HTML files" feature was announced, the time seemed just about right to get started looking in to this:-)

I have tested the feature in VSCode 1.31.0, and I have compared the proposed VSCode JSON format to the one we created. I am quite happy with the feature, but there's still a few limitations to the feature and to the JSON format that I hope you can possibly address.

1. A tag definition in the "tags" section of the current JSON format allow you to specify only one type of child nodes for an element, namely attribute nodes.

In the JSON format created in my company, an element/tag does not only express what attributes it supports, but it also can specify supported child elementNodes and/or textNodes. This way we can express whether a component supports child elements and/or text nodes or not, and we may also express constraints to what child elements are supported by the given element/tag.

Would it be possible to extend your current JSON format so that it can express whether text nodes and/or child elements are supported, and ideally also to express constraints to what child elements are supported, and then feed this info to the HTML language service?

In addition I think it would be very nice if it was possible to somehow give a web component's custom attribute some visual preference (highlight/bold, sort first etc). over all the global HTML element attributes. Today the custom attributes for a component is a bit hard to find in the list of attributes as they disappear among all the others....

[octref]

child elements

We don't do any diagnostic error on HTML yet. I assume you want VS Code to show warning on using <child> not under <parent>? I don't think if we'll do that.

custom attribute some visual preference

@aeschli What do you think about showing a star before custom element's labels?

[josundt]

@octref So if I understood you correctly, VSCode auto-completion does not filter elements based on the parent element context. (Example: between start and end tag of a "select" element, VSCode auto-complete suggests any html element, not only "option" elements).

When it comes to the "visual preference" for attributes, I've had a look at the SVG sample on https://github.com/octref/svg-data/blob/master/data/svg-html-contribution.json since my previous comment.

I noticed the usage of "attributeCategories" in this example, which looked to me like a way to filter global attributes (inherited from base HTMLElement) for the custom element in the auto-completion. I could not find "attributeCategories" defined in the JSON schema though, so I am not really sure what it is used for in the sample, but if the intent was like I assume, this would be a nice way to hide irrelevant and show relevant attributes.

I also like the idea of showing a * before custom element's labels if this also means they get sorted on top!

[octref]

So if I understood you correctly, VSCode auto-completion does not filter elements based on the parent element context.

That's correct, we don't have any logic in HTML completion (it returns the whole list and is filtered down by VS Code's Completion Widget). The problem is the internet if full of invalid HTML, so showing any error or preventing certain completions might backfire.

I've created #68548 to track the * proposal for ranking custom tags/attributes.