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

Is the example [web-components.json](https://github.com/microsoft/vscode-custom-data/blob/master/samples/webcomponents/web-components.json) the latest version? it uses "label" instead of "name"? could be that I missed that change 🙈 

imho the minimum to make it useful for more than "just" vscode depends on what it is used for

## Use Case Docs:
What web component users are interested
- custom-element name
- attribute names
- property names
- events names
- slot names
- css variable names
- deprecations, defaults, examples ... (e.g. common info usually part of jsDoc)

and adding a short description for all those "names"/"labels"

basically outline what I can expect from this custom element / web component.

=> [web-component-analyzer](https://github.com/runem/web-component-analyzer) can already output markdown documentation. Right now it's using the "internal" data for it... but it would be nice if `custom-elements.json` as input would be all thats needed.

## Use Web Component Catalog:
Allow searching ala npm search but for web components only.
e.g. npm package that has a `custom-elements.json` will be treated as web component and get's index

info needed is the same as for Docs (e.g. index all the names/labels/descriptions and let the user search through it all)
=> I am currently working on that 👍 

## Use Case Playground:
An example would be storybook with can render a web component and give knobs to modify all the states of it.

It needs 
- custom-element name
- attribute names + Knob type
- property names + Knob type

A description is not needed in that case; A Knob Type can in many cases be derived from the actual type. Still, there will need to be a method of overriding it.

## Suggestion

add a property jsDoc which "just" contains the raw jsDoc from the code if available.
Then examples, default values, Knob Type, type, ... can all be custom parsed if needed. (but still, only `custom-elements.json` is needed as a source of input - no source code parsing is required)
```
"properties": [
  {
    "label": "text",
    "description": "The text inside the component",
    "jsDoc": "/**\n Some longer description\n * @type {string} * @example ... \n * @storybook-knob ColorPicker\n */"
   }
]
```

That way the json format stays simple and tools use cases can still get the information they need. If at some point everyone uses the same jsDoc we can make it a separate property in the json.

### Possible ways forward

*adding minimal:*
- properties (with label, description, jsDoc)

*adding for docs (e.g. above +):*
- events (with label + description)
- slots (with name + description) [use name as slots have names not labels?]
- css variables?

*adding full (e.g. above +):*
- add types
- link properties to attributes (with attribute and reflect)
- extract examples, type, default, for properties

**Example for docs:**
```js
{
  "tags": [
    {
      "label": "open-shadow",
      "description": "Open Shadow DOM Component",
      "properties": [
        {
          "label": "text",
          "description": "The text inside the component",
          "jsDoc": "/**\n Some longer description\n * @type {string} * @example ... \n * @storybook-knob ColorPicker\n */"
        }
      ],
      "events": [
        {
          "label": "colorchange",
          "description": "This event will fire whenever 'color' changes"
        }
      ],
      "slots": [
        {
          "name": "",
          "description": "Main content"
        },
        {
          "name": "left",
          "description": "Left content"
        }
      ]
    }
  ]
}
```




-- 
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-537467042