Generate web-types for @ionic/vue package

[piotrtomiak]

Feature Request

Ionic version:

[x] @ionic/vue 0.0.x

Feature Request

This is a feature request to include web-types metadata information with @ionic/vue library to provide users of WebStorm (and possibly other IDEs in the future) with precise code completion, inspections and documentation for Ionic components.

Preferred Solution

The best solution would be to generate the file based on existing Ionic documentation JSONs during the build process and ship it with the library. This solution has been implemented in quasar library and are being worked on in vuetify and bootstrap-vue. I've looked at some of the JSONs generated by ionic documentation and it should be relatively straightforward to transform information to a slightly different format.

I can work on the transformation code itself, but it would be pretty difficult for me to hook into the build process in the correct place, so I need some help from your side, before I can create a PR for this.

Alternatives

It's difficult for an IDE to analyze contents of compiled Vue library and the quality of code completion, inspection and documentation is pretty poor. web-types offer excellent opportunity to provide consumers of your library with precise information. It is especially useful for new users of the library as it allows to avoid constant looking into documentation on the web.

Related Code

Here is an example PR from Quasar - quasarframework/quasar#4749

Additional Context

The feature has been requested by one of our users on Twitter: https://twitter.com/leereichardt/status/1165554297225891841

[liamdebeasi]

Thanks for the issue! We recently released an all new Ionic Vue beta that should fix most of the issues reported. Can you try out the latest Ionic Vue beta and let me know if this is still an issue?

Getting Started with the latest Ionic Vue beta

The new Ionic Vue beta is built for Vue 3. Moving forward, we are not going to support Vue 2. For information on how to get started with the latest beta, check out our Ionic Vue Getting Started Guide.

At this time, we do not have a migration path from Ionic Vue built for Vue 2 to Ionic Vue built for Vue 3, but the Ionic Framework differences should be minimal.

Feel free to check out our Ionic Vue Beta Announcement blog post for more details on this release.

Help! The reported issue still happens in the latest Ionic Vue beta.

Please follow up here with the issue reproduced in an Ionic starter application running the latest Ionic Vue beta. Also include any revised steps to reproduce the issue. Issues that do not have a GitHub repo with the issue reproduced in an Ionic starter app will be closed.

My issue is resolved/My issue is no longer relevant.

You can either close the issue yourself, or do nothing. If there is no response within 14 days, this thread will be automatically closed.

I have a new issue.

Please create a new issue. Be sure to reproduce the issue in an Ionic starter application running the latest Ionic Vue beta and include a link to the repo.

Be sure to search for your issue first, as the issue you are running into may have already been reported.

We are excited to get closer to the Ionic Vue release and look forward to welcoming new Vue developers to the Ionic community. Please let me know if there are any questions. Thanks!

[piotrtomiak]

@liamdebeasi It looks like the issue is still valid. Vue 3 doesn't provide good framework for documenting components, directives and filters provided by the library for use in templates.

[liamdebeasi]

Thanks for checking! To clarify, this is just for WebStorm, correct?

[piotrtomiak]

@liamdebeasi At this point yes, but web-types (https://github.com/JetBrains/web-types) are open standard and we hope other editors will also support it. There is FR for VSCode Vetur plugin vuejs/vetur#2090 to support web-types. Vetur is currently using it's own format, which is very limited and doesn't support component slots, directives, filters etc.

I can contribute web-types generation. All I need is for someone familiar with the build system, to show me where to plug-in, so that I can access Ionic documentation and generate the file.

[liamdebeasi]

Thanks! We would love to have a contribution for this. In terms of the build system, @ionic/vue is here: https://github.com/ionic-team/ionic-framework/tree/ionic-vue/packages/vue. During the beta, we are going to be working in the ionic-vue branch.

proxies.ts has all the Ionic components that are auto generated from the core directory.

components/ has additional components that wrap the regular Ionic components to provide additional features (such as router integration)

The build system is fairly straightforward: https://github.com/ionic-team/ionic-framework/blob/ionic-vue/packages/vue/package.json#L5-L12 We aren't really doing anything to fancy here.

Is there any other information that would be helpful?

[ionitron-bot]

This issue has been labeled as help wanted. This label is added to issues that we believe would be good for contributors.

If you'd like to work on this issue, please comment here letting us know that you would like to submit a pull request for it. This helps us to keep track of the pull request and make sure there isn't duplicated effort.

For a guide on how to create a pull request and test this project locally to see your changes, see our contributing documentation.

Thank you!

[piotrtomiak]

@liamdebeasi Thanks for the pointers! What I am missing here is the access to the actual documentation for the elements and attributes, not just the list of them. E.g. docs here https://ionicframework.com/docs/api/back-button have detailed description for color attribute. To generate web-types properly I need to access this documentation.

[liamdebeasi]

Sure thing - so that will all be found in the core directory: https://github.com/ionic-team/ionic-framework/tree/master/core/src

All components have their documentation autogenerated into the following files:

1. This file contains information regarding types: https://github.com/ionic-team/ionic-framework/blob/master/core/src/components.d.ts
2. This file contains the entire API that is then used to automatically generate the component documentation pages you see on our Ionic Docs website. https://github.com/ionic-team/ionic-framework/blob/master/core/api.txt. It is generated via this file: https://github.com/ionic-team/ionic-framework/blob/master/core/scripts/api-spec-generator.js

Taking ion-back-button as an example:

1. The component file is found here: https://github.com/ionic-team/ionic-framework/blob/master/core/src/components/back-button/back-button.tsx. Notice there are special comments which describe properties, shadow parts, etc.
2. The types are generated into component.d.ts: https://github.com/ionic-team/ionic-framework/blob/master/core/src/components.d.ts#L155-L188
3. The API is generated into api.txt: https://github.com/ionic-team/ionic-framework/blob/master/core/api.txt#L82-L125

[piotrtomiak]

Thanks! Looks like I should be able to take it from here :)

[liamdebeasi]

Great! Happy to answer any additional questions if they come up 👍 We appreciate you taking a look at this!

[grgur]

If you like to use Vetur then you can try this simple plugin that adds autocompletion for tags and attributes to your Ionic Vue project: https://www.npmjs.com/package/@modus/ionic-vetur

Just add it to the project and it will work automatically (given that you already have Vetur installed)

npm i modus/ionic-vetur -D

[liamdebeasi]

Hey there @piotrtomiak,

Wanted to check in and see if you were able to make any progress. Now that Ionic Vue has shipped, I have some additional time to help out if you need it.

[piotrtomiak]

@liamdebeasi Sorry, I wasn't able to start it yet, I need to fix various Vue-related bugs for upcoming WebStorm release and I'll be able to work on this afterwards, probably within 2-3 weeks.

[liamdebeasi]

No problem! Let me know if I can help with anything.

[piotrtomiak]

@liamdebeasi I've created a PR with the changes. Please review :) The generation code places web-types.json in dist folder, let me know if it should be a different location. I have decided to use docs/core.json as the source as it contains all of the required information to generate web-types and it's just a matter of translation between two formats.

[liamdebeasi]

Thanks for the issue. This has been resolved via #22428, and a fix will be available in an upcoming release of Ionic Framework.

Thank you for all your help!

[ionitron-bot]

Thanks for the issue! This issue is being locked to prevent comments that are not relevant to the original issue. If this is still an issue with the latest version of Ionic, please create a new issue and ensure the template is fully filled out.