JetBrains / web-types

JSON standard for documenting web component libraries for IDEs, documentation generators and other tools
Apache License 2.0
285 stars 25 forks source link

Web-types on npm for vue 3.2.0 #62

Closed TechAkayy closed 1 year ago

TechAkayy commented 1 year ago

Hi there,

Looking here (https://github.com/JetBrains/web-types/tree/master/packages/vue), I can see web-types for vue until v3.0.0 and this is the version used when installing @web-types/vue from npm

My project currently uses vue 3.2.0 and I would like to install @web-types for this particular version, and I don't find it on npm, rather I could see it under examples here - https://github.com/JetBrains/web-types/tree/master/examples

Assuming web-types is open-source & universal and not tied to jetbrains and can be used in other tools, how can we use web-types when it's not distributed by the framework as part of their periodic releases? I wonder how jetbrains IDE handle this, say if my package.json has vue 3.2.0, then does it automatically download web-types for this version? If so, where is it downloading it from?

I haven't really published any serious npm packages, so I'm not sure if one dependency (@web-types/vue) can always be tied to another dependency (vue) and auto-upgrade/downgrade the npm packages to make sure the two are always in sync, guess this is beyond what peer dependencies could handle?

This raises a question about the schema enforcing a version. Should the schema be flexible where a base version could be set, say 3.0.0, and an override can be specified at an entity level? This can make the single json quite complex over time.

For eg, if there is a new directive, say drv in v3.2.0, then specify the version via semver range, like below?

{
          "name": "drv",
          "version": ">3.2.0",
          "priority": "low",
          "proximity": 10,
          "description": "`drv` is used to register a reference to an element or a child component. The reference will be registered under the parent component's `$refs` object. If used on a plain DOM element, the reference will be that element; if used on a child component, the reference will be component instance.",
          "doc-url": "https://v3.vuejs.org/api/special-attributes.html#ref"
}

Other option is having the web-types (json files) for various versions, say 1.0.0, ...3.0.0, 3.1.0, 3.2.0 etc in a single npm package @web-types/vue and specify the folder containing these different versions in package.json (for web-types attribute), and let the IDE pick the right version from this folder depending on which version of vue (in above example, v3.2.0) is found in the same package.json? But, if package.json contains vue like this "vue": "latest", then the version is really not there...

Please share your thoughts. Thank you!

piotrtomiak commented 1 year ago

@TechAkayy Web Types for Vue framework are so far consumed only by JB IDEs and are tied to how the integration is written for the IDE. The problem here is that you cannot really provide complete list of components or directives without analyzing project source code. Current versions of Web Types for Vue used by WebStorm are available here: https://github.com/JetBrains/intellij-plugins/tree/master/vuejs/resources/web-types. The @web-types NPM packages for Vue are outdated and kept for compatibility with older versions of WebStorm only.

Having said that, we are in a process of open sourcing Web Types code, it's already available in Kotlin, but we need to provide TypeScript version as well. Once that is done, other tools, like ESLint will be able to work with Web Types, however, in case of Vue, they will still need to analyze source code, to build the source code originating part of the model.