JSON output changes

[mwcz]

Hi @runem! I just discovered wca and have been enjoying experimenting with it.

One thing I'd like to use wca for is to automatically generate JSON schemas for our components (the project is PatternFly Elements). My plan is to ask wca for JSON, then feed that JSON into a schema template, which will then output the final schema.json file.

Before going all-in on that though, I wanted to ask about this output from wca:

!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!
WARNING: The json transformer hasn't been finished yet. You can expect large changes in this output.
!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!!

What sort of JSON changes do you have in mind for wca? For now, I pinned the version of wca so we won't be surprised by any JSON format changes, so we're all good there. I just wanted to get a sense of what you plan to change.

[runem]

Thanks for you interest in this library!

First of all, sorry for my late answer. I have been very busy this week :-)

Right now the JSON format just outputs the internal data structure directly and replaces internal non-serializable types like nodes and types with "{NODE}" and "{TYPE}" (see this file).

I print the warning because I want it to output serialized types with ts-simple-type, locations of nodes and source file names. I want it to include as much information as possible. Therefore I don't think my final format will be missing information that's available right now.

In short, I want the JSON format to contain as much information as possible while being decoupled from my internal data structures.

I'm also very open for suggestions, so do you have any specific requirements in mind for your use case?

I will be focusing on improving the JSON output during the next two weeks. I'll keep you updated here 👍

[mwcz]

Thanks for the reply!

Mostly I just wanted to know what you had planned, which all sounds great to me. There are a few things I would like to have access to in the JSON output. CMS integration of web components is the main driver for them, for example allowing a CMS to present web components in a highly visual authoring view. To do that, the CMS would need to know a few more things, such as:

1. a "default" value for attributes that need them (requires adding syntax to @attr)
2. a list of valid values for an attribute (can be somewhat done already with @attr {value1|value2} foo but isn't a perfect approach since the underlying type is lost)
3. a syntax for what can be put into an element's slots (for instance, <my-tabs> may require contents to be <my-tab> + <my-tab-panel> and a CMS should enforce that)
4. a human-oriented "title" for each attribute, slot, and property (for labeling form fields in the CMS)

I'm happy to open separate issues for each of these with more description and impl proposals. Happy to work up PRs too, if you like the suggestions.

[goatandsheep]

Can it be something like VSCode HTML so that it is recognized by autocomplete?

[mwcz]

That would be awesome, and it would solve item 2 above. I looked through https://github.com/microsoft/vscode-html-languageservice/blob/master/src/htmlLanguageTypes.ts and it looks like my items 1, 3, and 4 would still need to be provided somewhere outside of the VSCode HTML data structure. Still, getting autocompletion would be a great win!

[runem]

@mwcz I have noted your needs and they all seem doable.

1. It seems like this would be the syntax to use when specifying defaults using jsdoc: @attr {string} [attrname="default value"] (https://jsdoc.app/tags-type.html). I don't parse this syntax right now, so we should open an issue on it.
2. I already parse the type from jsdoc if present, so your example should very well work. As mentioned, I plan on outputting these types in the json output, but the types are actually already outputted in the vscode format (see below).
3. We will need to think this into a possible jsdoc format. Now I'm just thinking out loud, but maybe the format @slot {"my-tab"|"my-tab-panel"} myslot would make sense.
4. Same as 3. Maybe jsdoc already has a way to specify 'human oriented' title, but I'm in doubt.

I would be really happy if you open issues for each of these points! :-)

@goatandsheep I already support this format 🎉 (I call the output format vscode). You can generate it by running the following command:

wca analyze my-component.js --format=vscode --outFile=output.json

I just published a couple of fixes to the output, so you should try version 0.1.8 of wca when generating it :-)

@mwcz I agree that right now, all of your needs would probably be better met by the future json format generated by wca. Version 1 of the vscode format is very light weight as of now, but I'm sure it will be able to contain more information in the future.

[goatandsheep]

The recommendation is to put other component information into description.

[runem]

@goatandsheep That would be a great addition to the output! I have created issue #6 to track it.