Web-types Generation for Vue Components

[BeniRupp]

Hey @piotrtomiak,

I want to add web-types generation to some other libraries out there. When writing some generator code for parsing Vue components, I ended up in a similar solution you have implemented here. Then I ask myself if it would be helpful to provide a JavaScript function for extracting web-type information out of a Vue component function or object.

The rough idea of using that function looks like that:

const SomeLibrary = require('some-library')
let webTypes = {
    // ...
   contributions: { html: { tags: [], attributes: []}},
}
const componentNames = Object.keys(SomeLibrary).filter(k => k !== "default")
componentNames.forEach(name => {
    const tagInfo = getTagInfoForVueComponent(SomeLibrary[name], name)
    webTypes.contributions.html.tags.push(tagInfo)
})

What do you think would it be helpful to have such a function? And would this repository be the right place for that?

[piotrtomiak]

@BeniRupp The entry point for logic you're proposing is here: https://github.com/JetBrains/web-types/blob/master/scripts/vue/extract-vue.sh . The problem is that it has it's limitation when it comes to documentation and some things, like events or slots. The best way to generate web-types is to use documented source code. If your library is using JSDoc style documentation, you can generate web-types with vue-docgen-web-types library.

[BeniRupp]

Ah, thank you for that pointer! I'll have a look at the script. 👍

Unfortunately, the library I want to add web-types to (PortalVue) is not using JSDoc.

[piotrtomiak]

@BeniRupp I've had a look at the repository (https://github.com/LinusBorg/portal-vue/). You could actually try to keep documentation in web-types and generate MD files from it, or you might want to parse documentation MD files and generate web-types from them.

[BeniRupp]

Thanks @piotrtomiak for having a look at the repository. I really like the idea of treating the source code as the source of truth, so I would prefer the web-types generation based on the code. Nevertheless, I see some advantages in generating web-types based on documentation, since "a random string" as a default value is hard to generate from the sources.

Apart from that, I've tried the extract-vue.sh script and it works quite well. Now I ask myself how to contribute web-types for a library like PortalVue. Should I add some generation script to the library repository itself or/and publish the web-types under the @web-types scope by adding the web-types JSON file to this repository?

[piotrtomiak]

Apart from that, I've tried the extract-vue.sh script and it works quite well.

I would treat the script is a good starting point for creation of web-types JSON. But with your setup, the first version should be manually crafted (I did that for core Vue library and few others). Once you have that, than you could write auto-generation from MD files.

Now I ask myself how to contribute web-types for a library like PortalVue. Should I add some generation script to the library repository itself or/and publish the web-types under the @web-types scope by adding the web-types JSON file to this repository?

It's best to ship web-types with the library. However, for older versions of libraries you could contribute web-types to the @web-types namespace. Please create a PR for this.

[piotrtomiak]

@BeniRupp Since 2023.2, WebStorm and other IDEs support Custom Elements Manifest - https://youtrack.jetbrains.com/issue/WEB-60580, so if you don't have any need for patterns, you can generate just one file.