Re: [w3c/webcomponents] Editor support for WebComponents (#776)

@daKmoR Those were outdated. I should have updated them before I left for vacation so discussion could have continued 😅Sorry.

I just updated the sample for web components using Custom Data V1.1 with better description, please take a look:
- https://github.com/microsoft/vscode-custom-data/tree/master/samples/webcomponents

- https://github.com/microsoft/vscode-custom-data for the Custom Data format overview

I included two samples, one that explains how you might use it to document your components, and one for https://github.com/github/time-elements. 

---

Re https://github.com/JetBrains/web-types: https://github.com/vuejs/vue/issues/7186#issuecomment-531878768


---

For @runem's suggestions, here's my thoughts and questions.

## Describing members

Let me talk from [Custom Data](https://github.com/microsoft/vscode-custom-data)'s perspective ([readme here](https://github.com/microsoft/vscode-custom-data/tree/master/samples/webcomponents)). If you look at this demo:

![demo](https://user-images.githubusercontent.com/4033249/67523979-9c3e4580-f664-11e9-9560-e2768bed5252.gif)

What I tried to do was, making sure there's a clear connection between the data provided (`description` and `references`) and the auto-completion and hover features:

![Rectangle](https://user-images.githubusercontent.com/4033249/67524095-eb847600-f664-11e9-94be-a2e173d5f68e.png)

So from this angle, the 4 proposed addition:

- Attributes: already there
- Properties: how does this relate to any editing features?
- Events fired: how does this relate to any editing features?
- Slots: would be useful, as it puts restrictions on what usage of the custom element is valid. For example, the editor should show an error when a slot is required but not provided, and in the attribute-value completion of `slot=""`, it should provide all `slots` provided by the component.

I feel overall, making the **Custom Data** format closely connected to the editor features is valuable, since **its purpose is to give people an easy way to enhance HTML editor features, not describing every WebComponents**. Here's a list of all the editor features driven by the data: https://github.com/microsoft/vscode-html-languageservice/blob/master/docs/customData.md#language-features.


But if you have an extended format, you can easily transform it to the Custom Data format. For example, if the standardized WebComponent metadata always have `events`, you can put them to the end of `description`. So it could look like:

[Events1]() | [Events2]()

or

- [Events1]()
- [Events2]()

depending on how you generate the `description`. The freedom is left to you, and the Custom Data format is minimal and still closely connected to editor features.

## Relation between property & attribute

I'm not sure if Custom Data itself should involve property at all.

## Describing types

> it seems like boolean attributes are using the valueSet: 'v' even though "v" doesn’t exist as a value set?

They are [here](https://github.com/microsoft/vscode-html-languageservice/blob/bd605d1fbe724daebe442a077c2d9c8357e8b298/src/languageFacts/data/html5.ts#L22-L1142).

> I think this format will need to have some way of specifying more complex types than string enumeration types. This is applicable for both attributes and properties.

I'm still in the progress of making Vue template type-checkable, and you can find latest progress here: https://vuejs.github.io/vetur/interpolation.html


There are already prior art: [Vue Type Checks](https://vuejs.org/v2/guide/components-props.html#Type-Checks), [Vue Prop Types](https://github.com/znck/prop-types), etc. But I think for HTML it's different, and I doubt any HTML Language Server would support such type-checking in templates. Because:

- At the end your are using `this.getAttribute` to get the attributes. It's a `string`, not interpolated JS (Vue's props is interpolated JS, so I'm working on type-checking it). There's not much point in type-checking a string using TypeScript.
- Template type-checking is very specific to each framework, and can't be implemented in a generic way. You can look into https://github.com/microsoft/TypeScript/issues/29432. I doubt TS team would do it anytime soon.

## Default property values

Makes sense. And in auto-completion it can be offered as `color="red"` where `red` is selected, so you can start to type a different value if you want.

## Deprecated

It's better to exist as `deprecated` and `deprecationMessage`, instead of making it either string or boolean. Or just make it `deprecationMessage`, in the case of omission it means no deprecation.

## Examples

They can be compiled into the `description` field. Take a look at https://github.com/microsoft/vscode-custom-data/blob/master/samples/webcomponents/node_modules/%40github/time-elements/web-components.html-data.json.


## Methods

This needs TS support. You should just include `d.ts` files that extends `HTMLElement` and expose them into the global scope. For example, https://github.com/microsoft/vscode-custom-data/blob/master/samples/webcomponents/node_modules/%40github/time-elements/index.d.ts


## Path

This makes sense, and we can implement jump-to-definition on those tags.

## Globals

There's already `globalAttributes`. Others I'm not sure.

---

## Summary & TLDR

- [Custom Data](https://github.com/microsoft/vscode-custom-data) format should connect closely to editor features. For most of the WebComponents fields, if you want to show them in auto-completion & hover, just append them to the `description` field as Markdown.
- A web-components.json schema could (and should) be a superset of Custom Data format. You can use it to generate Custom Data to drive editor features. You can also use that to do other things such as generate documentation.
- As I mentioned in https://github.com/microsoft/vscode-custom-data/tree/master/samples/webcomponents, VS Code can start to look into `package.json` to see if Custom Data is provided, and use that to enhance editor features. Currently you need to manually link to them, such as in

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

- Overall I'd be happy if each WC would have a JSON metadata format published to each component in registry, just as how people publish `d.ts` to each packages. Note, though, that it took [7 years](https://blog.johnnyreilly.com/2019/10/definitely-typed-movie.html) for TS and DefinitelyTyped to get there.

- It'd be great if you open separate issue in https://github.com/microsoft/vscode-custom-data to discuss about the suggestion one by one.

- If you try to talk from an editor support angle, it'd be much easier for me to take the suggestions. For example:
  - 👍Add a `slots` field. It should be used for completing `slots=""` attribute value inside the custom component. Required slots should be included inside the HTML usage of the custom component. 
  - 👍Add a `path` and make jump-to-definition work on HTML custom elements.
  - 🤷‍♂Add a `events` field since it's important for describing a custom component. I have no idea how that relate to any editor features.





-- 
You are receiving this because you are subscribed to this thread.
Reply to this email directly or view it on GitHub:
https://github.com/w3c/webcomponents/issues/776#issuecomment-546117300