Configurable component definitions for intellisense inside templates

[senritsu]

Inspiration

As highlighted by talks at VueConf by @octref and @masahirotanaka, vetur already has the infrastructure in place to allow the addition of intellisense for component libraries like element-ui (@ElemeFE) and OnsenUI. Having rich intellisense for components is immensely useful, especially for libraries with a lot of components and complex props.

Proposal

I think it would be very useful to expand those capabilities, so that in the future intellisense for project-specific components or libraries can be added without any modifications to vetur itself. In a brief conversation about this with @octref we arrived at one option being the introduction of a vetur-specific config file similar to a .babelrc or .eslintrc. Such a config file could then be used to define components in a JSON format similar to the current support for OnsenUI (link pending) and element (#234).

This would enable authors of bigger projects to add intellisense for external libraries or their own custom components, greatly helping the team as complexity grows.

Caveats and further improvements

One shortcoming of having a simple config file in the style of ESLint or similar tools is that while this would solve the issue for custom components, it would not work very well for external libraries. Manually copypasting component definitions from multiple external libraries together would be quite tedious.

Another issue might be name collisions for cases where components are not globally registered. Maybe it is possible for the vue language server to infer registered components inside a .vue file to resolve ambiguities? It might also be perfectly valid to just ignore this. Prefixing components is helpful for other reasons anyways, already done by most libraries, and prevents collisions from happening in the first place.

Regarding how to provide or bundle the definitions: one solution might be the introduction of a standard component description format for providing intellisense, similar in concept to typescript definition files. These could be bundled with libraries and also be created inside the project for local components. Another solution (especially for preventing the overhead of having to keep the intellisense documentation in sync with component changes) would be a way to have something similar to docstrings inside the components themselves. Using that, or a combination of parsing/reflection on the components (#145), would result in a living documentation that is not outdated as soon as it is published.

A hybrid approach that combines a bit of both might be to provide a tool that does the parsing/processing and generates the documentation. The generated files could then be bundled with the libraries, and the generator could be integrated into the build pipelines of library authors.

Of course, the latter options are at the very least technically challenging and might not be feasible at all, so a simple initial solution would be preferred. Nonetheless, i think a discussion about those edge cases and possible ways to deal with them could help arrive at a more sophisticated and robust solution.

Points of discussion

• How could a vetur config look like and is it desirable to even have one?
• How to best support both library-bundled component definitions and project-specific definitions?
• How would the JSON format to describe components look? Maybe people involved with the currently existing integrations can chime in what they think about this?

Also pinging @HerringtonDarkholme as the apparent champion of the element-ui integration.

[HerringtonDarkholme]

Thank @senritsu for bringing this out.

Some comments:

one solution might be the introduction of a standard component description format for providing intellisense

This is Angular's approach. Angualr's AOT metadata naturally gives rise to component definition. But I wonder how can we introduce this in Vue. We probably need more momentum to introduce this to Vue community as whole, not only vetur users.

a way to have something similar to docstrings inside the components themselves.

I think this will be implemented in vue language server in future. But it will be only available for user's project, not library code. Library author can export Vue component in several different format. It is hard to find component definition in, potentially, arbitrary JavaScript code.

For now, I think the best approach is to hard code venerable library in vetur. And implementing vue file analysis has higher priority. If we can analyze Vue file well enough and make vetur the de-facto editor for Vue. Only then do we have louder voice to push component definition to library authors.

[octref]

The overall idea is to have a description format for Vue SFC that balances between:

• Having all the information necessary for IntelliSense, error checking and other language features
• Having the JSON description automatically generated from Vue SFC file (maybe in the context of a Vue project)

This will probably take very long to develop / adopt, but it can benefit other editors supporting LSP too.

Agree with @HerringtonDarkholme for now, let's limit it to Element and Onsen other highly popular Vue UI libraries. But we can add a configuration point such as vetur.component-description-path or something that let user provide their own version of https://github.com/ElementUI/element-helper-json. This would benefit people working with internal Vue libraries.

@masahirotanaka @Leopoldthecoder

[masahirotanaka]

Catching up. @OnsenUI team is currently implementing a repository similar to element-helper-json. However, the structure will be a bit different since we will also include Web Component/React/Angular related component and attributes and make them distinguishable.

I like the idea Vetur specify the JSON format and make it pluggable. For the moment, we will write our own IHTMLTagProvider.

[brianjorden]

Was just reading up on this a bit and was trying to figure out if I could jam in my own custom generated helper json files instead. I may hack my way through it temporarily, but given this issue hasn't been updated in quite some time, does the vetur.component-description-path type option still seem feasible that you mentioned @octref ?

[octref]

This is already available in Vetur: https://vuejs.github.io/vetur/framework.html#custom-tags-attributes

Quasar already does it: https://github.com/quasarframework/quasar/blob/dev/quasar/package.json#L108-L111

There is no documentation on the format yet, but you can copy it from https://github.com/ElementUI/element-helper-json.

I'll try to standardize the format with https://github.com/octref/vuetypes.