jetbrains / web-types

JSON standard for documenting web component libraries for IDEs, documentation generators and other tools

Web-Types

Welcome to Web-Types, a JSON format for documenting web component libraries.

Web-Types is a framework-agnostic format aimed at providing IDEs and other tools with the metadata information about the contents of a component library. Its powerful name patterns allow encoding information about web framework syntax or customizing code completion suggestions for large icon libraries in the IDEs that support Web-Types.

Version 2.0 of the format

Web-Types started as a format to support Vue libraries, but we've always wanted to provide a more generic solution. Finally, version 2.0 of Web-Types format works seamlessly for any kind of web framework, Web Components library, or CSS icons pack.

A detailed documentation of the format is available here

Starting with version 2021.3.1 of WebStorm (and other JetBrains IDEs), a full support for the new Web-Types format is supported (the new format has been partially supported since 2021.2). You can now add custom HTML elements and attributes, custom CSS classes, properties, functions, pseudo-classes, and pseudo-elements. Vue and Angular support integrates fully with the format, so you can easily mix Web Components in Angular or Vue templates.

Example Web-Types files are available in examples folder. Web-Types for Angular and Vue frameworks are available in the examples/references directory. They require dynamic contributions based on project source from IDE plugins to work properly.

A webinar recording with Piotr Tomiak explaining the new version of the format and how pattern processing works is available on YouTube.

The new version of Web-Types is backward compatible with the Vue-only Web-Types.

Local development with Web-Types

To enable your Web-Types file in the project, link it through the web-types property of your local project package.json file. You can specify multiple Web-Types files by providing an array of paths.

Distribution

Library providers are welcome to include detailed Web-Types JSONs and link them through web-types property in package.json. E.g.:

{
  ...
  "web-types": "./web-types.json"
  ...
}

Many libraries are providing this feature, for instance:

• Vue.js
  • vuetify (vuetifyjs/vuetify#9440)
  • quasar (quasarframework/quasar#4749)
  • bootstrap-vue (bootstrap-vue/bootstrap-vue#4110)
  • nuxt.js (nuxt/nuxt#7611)
  • @ionic/vue (ionic-team/ionic-framework#22428)

In case a library is not shipping Web Types, they can be published under the @web-types scope on NPM. Currently, the following frameworks and libraries are supported in such a way:

• Vue.js
  • quasar-framework
• Web Components
  • lit

Published JSONs are checked into this repository under the packages folder. In case of Web-Types published to @web-types scope, IDEs are supposed to download required JSONs without any changes to the user project structure.

Various IDEs perform optimizations when scanning node_modules directory, so to ensure that web-types for your package are always available, make sure it's listed in packages/registry.json.

Schema

Web-Types JSON Schema is available in the schema folder. Use one of the following URLs to reference it in your JSON files:

http://json.schemastore.org/web-types

or

https://raw.githubusercontent.com/JetBrains/web-types/master/schema/web-types.json

Generating Web-Types

From source

Currently, the following component documentation formats are supported:

• JSDoc using styleguidist vue-docgen-api library - add vue-docgen-web-types package to your project and run the vue-docgen-web-types command. You can launch it in a watch mode by passing --watch and you can pass a custom configuration file via --configFile parameter. See config.d.ts for detailed information on supported configuration file options.

If you're not using JSDoc in your project, you can create your own builder for web-types JSON. For examples see vuetify, quasar or bootstrap-vue pull requests from above.

Publishing to @web-types scope

We welcome your PRs with Web-Types for libraries in packages folder. There should be a single file per library in the format:

packages/<pkg-name>/<pkg-name>@<pkg-version>.web-types.json

We are syncing contents of the packages folder using script/publish.sh script which usage syntax is following:

publish.sh <package-name> [--dry-run]

The script scans folder packages/<package-name> for provided Web-Types jsons and synchronizes contents with NPM.

Versioning and naming of @web-types scope

Versioning and naming rules are as follows:

• Web-Types for package pkg-name are available under @web-types/pkg-name
• Web-Types for package @scope/pkg-name are available under @web-types/at-scope-pkg-name
• Web-Types for version 1.2.3 are published as prerelease 1.2.3-n, e.g. 1.2.3-3
• Web-Types for pre-release version 1.2.3-rc.1 are published with additional segment, e.g. 1.2.3-rc.1.3
• to search for appropriate Web-Types package use range <pkg-ver and include prerelease versions, e.g. to find Web-Types for version 1.2.6, query package list with <1.2.6, which can match Web-Types in version 1.2.4-12
• all outdated versions are marked as deprecated and should be ignored by an IDE

Contributions

All contributions are welcome! We need your help to improve the Web-Types format specification, to support other frameworks and to improve quality of generated metadata through scripts.

web-types's Issues

lit support in inline html`` template literal

I'm not seeing support for lit html, despite appearing to have it here: https://github.com/JetBrains/web-types/tree/master/packages/lit/lit%402.0.0. I'm using PHPStorm 2022.3.1.

Specifically I'm expecting to see auto completion for event attributes (@click for instance) within a typical lit render method, but it's not working, e.g.

import {LitElement, html} from 'lit';
import {customElement} from 'lit/decorators.js';

@customElement('my-element')
class MyComponent extends LitElement {
  // ...
  render() {
    return html`
      <button @click="${() => console.log('hello world'); }">Click me</button>
    `;
  }
}

Is there something I need to do to get this support for my project? I noticed that lit is missing from the registry.json file. Could that be the issue? Why is lit one of the only packages in this monorepo not listed there?

Thanks!

custom vue component tag attribute description in intellisense

I generated a web-types.json for locally developed vue components and want to include a description for tag attributes. Intellisense works for component and tags. I tried manually adding a description for tag attributes per schema, however it did not work.

• Would you please inform if attribute descriptions are picked up by intellisense?
• If yes, what is required in component to generate this metadata?

Best regards,

How to define events for components individually using V2

I found that the events defined in the V2 are global and do not support defining a component individually.

"js": {
      "events": [
        {
          "name": "test",
          "description": "test event"
        }
    ]
}

But if defined in a component like V1, it works fine but produces an error.

"html": {
      "elements": [
        {
          "name": "app-demo",
          "events": [ // Property 'events' is deprecated: Contribute events to JS namespace: /js/events
            {
              "name": "load",
              "description": "load more info",
            }
          ]
       }
    ]
}

I would like to ask how to define separate events for components now.

Question about other librairies support

Hello,

I'm working on a lit-element based web-components library and I would like projects that use it to be able to have autocompletion.
I'm use this project web-component-analyzer to extract the documentation of the components.
Do you think it's possible to generate a web-types.json from a custom-elements.json?

Thx,
Guillaume

Docs: How to add css classes to a webtype?

I'm looking to create a tailwind css webtype, and wondering how I can add css classes?
I checked the schema but it wasn't immediately obvious to me.
Thanks!

Vue directive (attribute): missing definition field for directive `:argument`

Directives have the following syntax:

v-name:argument.modifier1.modifier2.modifierN="expression"

In the schema, I see that it is possible to define the directive's name, modifiers and expression (value), but there is no mention of the argument (which follows the :, before any modifiers)

So how does one document the argument?

    "html-attribute": {
      "type": "object",
      "properties": {
        "name": {
          "$ref": "#/definitions/name"
        },
        "description": {
          "$ref": "#/definitions/description"
        },
        "doc-url": {
          "$ref": "#/definitions/doc-url"
        },
        "default": {
          "$ref": "#/definitions/html-attribute-default"
        },
        "required": {
          "$ref": "#/definitions/html-attribute-required"
        },
        "value": {
          "$ref": "#/definitions/html-attribute-value"
        },
        "source": {
          "$ref": "#/definitions/source"
        },
        "vue-modifiers": {
          "type": "array",
          "items": {
            "$ref": "#/definitions/named-entity"
          }
        }
      },
      "required": [
        "name"
      ],
      "additionalProperties": false
    },

Web types vs type definitions in Vue & Nuxt

Hi there,

I have watched few of your videos on youtube and I have a pretty good understanding of what web types are. Though, one thing still is unclear, would be great if you can clarify for me and for anyone reading this thread.

Typescript provides the necessary information for IDEs (for eg, Volar in vs-code is ts-based) and most of the UI libraries like vuetify, quasar etc are already shipping type definitions which helps with autocompletion, highlighting etc when working on vue templates. Does this mean, this overrides the need for web-types in vue-based projects?

For eg, I'm looking at nuxt3 support in Webstorm here - https://youtrack.jetbrains.com/issue/WEB-54200, and there was web-types for nuxt2 previously (nuxt/nuxt#7611), but no web-types for nuxt3. Also, @web-types/vue on npm was never updated in the last 2 years. Where should I look for the latest vue 3.2's web-types?

Of course, I understand the fact that this is an open standard and will be useful for various other frameworks, but does typescript override the use of web-types? Also, with regards to consuming web-types, when both typescript defn & web-types info is available for a tag/attribute, how does webstorm deal with this scenario? Does it does some kinda merging of data, or prefer one over the other?

Context: I'm working on a visual drag & drop tool (to build vue applications), and as we don't deal with typescript/language servers in our tool, web types are very very helpful for us, hence the curiosity about the future of web-types. For now, glad that most of the top vue-based ui libraries are already auto-generating web-types.

Thanks in advance.

Attribute enum autosuggestion

I have prepared my-foo tag with size attribute which is enumeration of values m and s. WebStorm/IntelliJ doesn't suggest those values.

Is my JSON correct or this is missing feature in WebStorm/IntelliJ ?

Having such feature would be veeeeeeery useful for cases like:

• colour palettes
• sizes
• types of buttons
• etc...

{
  "name": "my-foo",
  "attributes": [
    {
      "name": "size",
      "value": {
        "kind": "enum",
        "items": [
          "m",
          "s"
        ]
      },
      "default": "\"m\""
    }
  ]
}

Lit web-types IDE autodetection

I don't get how to have IDE auto loading @web-types/lit webtypes definition.

Here is a simple project:
package.json:

{
  "name": "test",
  "version": "0.0.0",
  "dependencies": {
    "lit": "^2.0.0"
  },
  "web-types": [
    "./component-web-types.json"
  ]
}

Some component definition in file named component-web-types.json:

{
    "$schema": "http://json.schemastore.org/web-types",
    "name": "test",
    "version": "0.0.0",
    "framework": "lit",
    "contributions": {
        "html": {
            "elements": [
                {
                    "name": "test-component",
                    "attributes": [
                        {
                            "name": "test-prop",
                            "required": false,
                            "value": {
                                "type": "string",
                                "required": true
                            }
                        }
                    ]
                }
            ]
        }
    }
}

And simple demo component test-new.js

import {LitElement, html, css} from 'lit';
import {customElement} from 'lit/decorators.js';

@customElement('test-new')
export class TestNew extends LitElement {
  render() {
    return html`
      <test-component></test-component>
    `;
  }
}

I open IDE on that project, run in terminal

npm install

I open test-new.js, I expect to have completion on test-component or test-component attributes while typing it <test-component te...></test-component> (expecting completion when caret is at ...), but get nothing.

When I add @web-types/lit as dev dependency:

npm i -D @web-types/lit

Completion works as expected.

web-types entry in package.json breaks (Vue) syntax highlighting

The "web-types" entry in package.json seems to be breaking syntax highlighting in the editor, specifically with Vue:

Without web-types entry in package.json:

With web-types entry in package.json:

I also notice that IntelliJ is stuck on "Analzying" (but it isn't doing anything)

The "File" menu seems inaccessible too, clicking it does nothing, as if IntelliJ is stuck.

Removing the "web-types" entry in package.json fixes the syntax highlighting issue, and "Analyzing" message disappears.
Happy to provide the web-types json file, and any other IntelliJ debug logs needed :)

IntelliJ debug log: https://gist.github.com/dancarasco/1bcf95efefc9ee12d6bde69b9c106e53

Distributor ID: Ubuntu
Description: Ubuntu 20.04.1 LTS
Release: 20.04
Codename: focal

IntelliJ IDEA Ultimate:

"slots"-property in V2

I am a bit confused with the examples and the provided packages.

I want to document a webcomponent that can be used like this:

<my-panel type="primary">
  <span slot="title">Some Title</span>
  <span>This is some content</span>
</my-panel>

The component is written in Angular Elements.

Currently I got this web-types.json:

{
  "$schema": "https://raw.githubusercontent.com/JetBrains/web-types/master/schema/web-types.json",
  "name": "my-web-types-test",
  "version": "0.0.1",
  "description-markup": "html",
  "contributions": {
    "html": {
      "elements": [
        {
          "name": "my-panel",
          "description": "Panel with a Title",
          "attributes": [
            {
              "name": "type",
              "description": "Some useful information",
              "value": {
                "type": "enum"
              },
              "values": [
                {
                  "name": "primary"
                },
                {
                  "name": "secondary"
                }
              ]
            }
          ],
          "slots": [
            {
              "name": "default"
            },
            {
              "name": "title"
            }
          ]
        }
      ]
    }
  }
}

The Tag and the attribute is working fine. The only Problem I have, is the missing support for the slot-suggestion. IntelliJ 2021.3.2 dont show any suggestions for the slot-attribute. Also I can not find the "slots"-property in the schema.
I found "slots" in the bootstrap-vue package: https://github.com/JetBrains/web-types/blob/master/packages/bootstrap-vue/bootstrap-vue%402.0.0.web-types.json

Is "slots" still the correct way to document slots that are provided by an webcomponent or is there a new way to do this?
Thanks for any help :)

Does Web-Types support React?

Hi :)

I am working on a component library that uses Web Components, so web-types has been very useful to feed good documentation to JetBrains IDEs for Vue consumers :D.
JetBrains IDEs are not working very well with our React Bundle. Therefore I would like to try to also generate web-types metadata for React, but simple tries are not picked up by IntelliJ.

Could you let me know if it currently supports React and if there is some example out there.

Thanks!

How can I use web types for Vue.js?

I just read an article about web-types and their use for Vue.js in WebStorm. However I do not quite understand how I as a developer can have this feature in my IntelliJ IDE. Do I need to download a plugin?

可否添加对 ant-design-vue 的支持？

我目前在使用 antd 的 vue 版本 https://vue.ant.design/，但 IDE 中只有部分标签有提示，而其他的则没有，该功能如果是通过 NPM 库 @web-types 的方式实现的，那么可否将之开放出来便于我们追加最新的标签？

Web-types on npm for vue 3.2.0

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!

Question about support for a web component

Hi,

I'm not sure if I understand how the whole process is working.
My goal is to have a better idea support for a web component.
I would like to try in my side project first:
https://github.com/jcgueriaud1/xof-tree
It's web component based on open-wc starter.
Currently I don't have any support in IntelliJ.

What are the step to do this?

• I should create web-types.json (As a first step I will probably create this manually)
• I should add this in my package.json: "web-types": "dist/json/web-types.json"

I can publish it and I should have a better support in IntelliJ?

Do I need to add this in this repository or as a @web-types package? (I don't like since it's something that should be maintain in my component)
Or it something framework related (my component is using lit-html so the web-types.json should be added in lit-html)?

Thank you :)

Boolean type expect a value

Hi,

I'm trying to generate a web-types.json for a custom Vue framework. I can get autocomplete from PHPStorm but boolean type expects a value.

Did I miss something ?

{
  "$schema": "https://raw.githubusercontent.com/JetBrains/web-types/master/schema/web-types.json",
  "framework": "vue",
  "name": "npm package name",
  "version": "",
  "contributions": {
    "html": {
      "tags": [
        {
          "name": "aa-btn",
          "attributes": [
            {
              "name": "badge",
              "description": "If true, disable hover & active behaviors",
              "value": {
                "kind": "expression",
                "type": "boolean"
              }
            }
          ]
        }
      ]
    }
  }
}

PhpStorm does not see web-types and does not offer hints

Hello!

I want to use web-types locally in my Vue 3 project so that I can use PhpStorm hints in development.

To do this, I did the following:

1. Filled in the web-types property in package.json
2. I created a web-types structure in which I specified the testProp attribute for the HelloWorld component
3. Used the HelloWorld component in App.vue

However, when trying to specify the testProp attribute in the arguments of the component, PhpStorm does not give me a hint about the presence of such an argument. At the same time, PhpStorm gives a hint only about the arguments that I defined in HelloWorld.vue (testPropTwo)

May you tell me, is everything done correctly? If so, how do I make web-types work?

Here is a link to my repository: https://github.com/PurpleTape/phpstorm-web-types-issue

PhpStorm 2022.1.4
macOS 12.4

Thanks!

Missing mkdirp dependency

The mkdirp dependency is not listed in dependencies.

npx vue-docgen-web-types
internal/modules/cjs/loader.js:883
  throw err;
  ^

Error: Cannot find module 'mkdirp'
Require stack:
- /Users/project/node_modules/vue-docgen-web-types/lib/build.js
- /Users/project/node_modules/vue-docgen-web-types/lib/cli.js
    at Function.Module._resolveFilename (internal/modules/cjs/loader.js:880:15)
    at Function.Module._load (internal/modules/cjs/loader.js:725:27)
    at Module.require (internal/modules/cjs/loader.js:952:19)
    at require (internal/modules/cjs/helpers.js:88:18)
    at Object.<anonymous> (/Users/project/node_modules/vue-docgen-web-types/lib/build.js:39:34)
    at Module._compile (internal/modules/cjs/loader.js:1063:30)
    at Object.Module._extensions..js (internal/modules/cjs/loader.js:1092:10)
    at Module.load (internal/modules/cjs/loader.js:928:32)
    at Function.Module._load (internal/modules/cjs/loader.js:769:14)
    at Module.require (internal/modules/cjs/loader.js:952:19) {
  code: 'MODULE_NOT_FOUND',
  requireStack: [
    '/Users/project/node_modules/vue-docgen-web-types/lib/build.js',
    '/Users/project/node_modules/vue-docgen-web-types/lib/cli.js'
  ]
}

Vue directive modifier syntax lacking pattern matching

In our project, we have directives that used modifiers, but are not guaranteed to be an exact string. Some modifiers are words, some could a string of digits (supplied by the user), and others might be a combination of letters and digits:

v-my-directive.click.d100.o1234

Where we allow the user to supply an arbitrary value (say after .d###, to specify a delay value).

There appears to be no way to specify that a modifier could match a regular expression. It only appears that #definitions/name can only be an exact string. Perhaps a new type could be created for directive modifiers?

Also, we allow passing element IDs via modifers. Since we do not know the user's IDs ahead of time, is it possible to define wildcard modifiers?

How should these be used in practice as an end-user?

I can't seem to get IDEA Ultimate (2019.2.3) to recognize web-types. As a testcase:
I created a new Vue.js project and installed bootstrap-vue and @web-types/bootstrap-vue. When editing a Vue template, both b-form and BForm still show "Unknown html tag" as always. Oddly, it will auto-complete Form with no prefix as coming from bootstrap-vue, along with its props. After doing so, jumping to the declaration goes to node_modules/bootstrap-vue/esm/mixins/form.js.

Do I need to somehow register bootstrap-vue (or its types) as a library in my project?

Support for custom events, custom element properties and scoped CSS properties

Hi!

First of all, thank you for putting the time for giving support for library authors to have autocomplete in the IDE.

I work for a company where we have a private library of web components.

We create web applications with this library. For the web applications we use Angular (but this doesn't matter right now).

I was testing the new schema that supports custom elements.

Lets imagine we have the following custom element (made with lit to simplify it):

import { CSSResultGroup, html, HTMLTemplateResult, LitElement } from 'lit';
import { customElement, property } from 'lit/decorators.js';

@customElement('my-element')
export class MyElement extends LitElement {

  static get styles(): CSSResultGroup {
    return css``;
  }

  @property({type: String, attribute: 'foo-attr'}) foo = 'foo';

  fire(): void {
    this.dispatchEvent(new CustomEvent('foo-changed'));
  }

  render(): HTMLTemplateResult {
    return html`
      <div part="bar"></div>
      <slot name="container"></slot>
    `;
  }
}

Basically this custom element, has a property named "foo" and this property gets reflected as an attribute named "foo-attr". Also this custom element fires a custom event named "foo-changed". I have named the attribute different from the property on purpose.

To use this custom element, one can import the JS and then in the HTML add something like this:

<my-element foo-attr="Hello World"></my-element>

<script defer>

  const el = document.querySelector('my-element');
  el.addEventListener('foo-changed', () => {});

</script>

If I try to document this custom element with the new schema of web-types, it looks something like this:

{
    "$schema": "https://raw.githubusercontent.com/JetBrains/web-types/master/v2-preview/web-types.json",
     "name": "Library name",
     "version": "1.0.0",
     "js-types-syntax": "typescript",
     "description-markup": "markdown",

     "contributions": {
         "css": {
             "properties": []
         },
         "html": {
             "elements": [
                 {
                     "name": "my-element",
                     "description": "Some description goes here in markdown format",
                     "doc-url": "https://www.url-that-points-to-the-online-documentation-of-the-element.com",
                     "attributes": [
                         {
                             "name": "foo-attr",
                             "description": "Some descriptions for this attribute",
                             "default": "foo",
                             "required": false,
                             "doc-url": "https://www.url-that-points-to-the-online-documentation-of-this-attribute.com"
                             "value": { 
                               "kind": "plain",
                               "type": "string"
                            }
                         }
                     ]
                 }
             ]
         }
     }
}

I'm pretty sure that more things could be added, but I want to keep it simple.

What are currently my issues?

1. How to document custom events and properties so when a developer writes in the HTML something like this:

<!-- This example uses Angular -->

<my-element
    
   <!-- This woks fine because we have documented the attribute -->
    foo-attr="Hello World"
    
   <!-- 
  IDE tells developer that property "foo" doesn't exist (even if we 
  had defined the property name same as the attribute name) 
   -->
    [foo]="'Hello World'"
    
    <!-- IDE tells the developer that this event is not fired by the custom element -->
    (foo-changed)="doSomething()"
></my-element>

What do I ask?

1. How can I tell the IDE that a custom element fires custom events?

2. How can I tell the IDE that a custom element has a property for frameworks that support setting HTMLElement properties directly in the HTML.

3. When CSS custom properties are supported in the IDE (I know it's supported in the schema but I saw a video where it was said that it's still not enabled in the IDE), how can I tell it which CSS custom properties belong to each custom element? In the schema-v2 I can specify an array of CSS global properties but I don't see how to group them by custom element.

Possible solutions to my problems?

1. Maybe you could add to the html-attribute definition, in the schema, a property named "field-name" or "property-name" to be able to specify that an attribute is also a property and this property has the name provided. This is something similar to what custom-elements-manifest does.

One thing I found confusing, is the fact that the HTML attribute definition let's you specify the type via the html-value-type definition. HTML attributes are always a String, it's the property the one that has a type. I don't know this may be only confusing to me.

Basically the above attribute definition will look like this:

{
     "name": "foo-attr",
     "description": "Some descriptions for this attribute",
     "default": "foo",
     "required": false,
     "doc-url": "https://www.url-that-points-to-the-online-documentation-of-this-attribute.com",
     "property-name": "foo",
      "value": { 
        "kind": "plain",
        "type": "string"
      }
 }

2. Maybe adding to the html-element definition, in the schema, a property named "events". In the above example it will look like this:

// ....
"html": {
   "elements": [
       {
           // ....

          "events": [
               {
                   "description": "Some description for the event",
                   "name": "foo-changed",
                   "type":  "void",
               }
           ]
       }
   ]
}

3. Support for scoping CSS properties by HTML element?

Obviously, it's not easy to define a schema that gives support to so many possible cases (frameworks and libraries).

Thank you for the great work!

Property case conversion

Hi,
I'm trying to apply js property case conversion for PolymerJS web-types definition and generation based on modified version of marcobeierer's web-component-analyzer fork #25 (comment)

I don't get how to make it work
On IntelliJ 2021.3.1 I get that:

On following project, I expect forBaz to be not recognized and foo-baz recognized, I get the opposite.

Here is the full project:
package.json

{
  "name": "web-types-case-test",
  "version": "0.1.0",
  "web-types": [
    "./framework-web-types.json",
    "./component-web-types.json"
  ]
}

Framework generic definition framework-web-types.json

{
  "$schema": "http://json.schemastore.org/web-types",
  "name": "framework-web-types",
  "js-types-syntax": "typescript",
  "version": "0.1.0",
  "framework-config": {
    "canonical-names": {
      "/js/properties": "kebab-case"
    },
    "name-variants": {
      "/js/properties": [
        "kebab-case"
      ]
    }
  },
  "contributions": {
    "html": {
      "attributes": [
        {
          "name": "Properties",
          "description": "Properties expression",
          "value": {
            "kind": "expression",
            "type": "any"
          },
          "pattern": {
            "items": [
              "/js/properties"
            ],
            "template": [
              "#item:property name"
            ]
          }
        }
      ]
    }
  }
}

Generated web-components definitions component-web-types.json

{
    "$schema": "http://json.schemastore.org/web-types",
    "name": "web-components",
    "version": "1.0.0",
    "js-types-syntax": "typescript",
    "contributions": {
        "html": {
            "elements": [
                {
                    "name": "demo-test",
                    "attributes": [
                        {
                            "name": "foo-bar",
                            "value": {
                                "type": "string"
                            }
                        }
                    ],
                    "js": {
                        "properties": [
                            {
                                "name": "fooBaz",
                                "value": {
                                    "type": "string"
                                }
                            }
                        ]
                    }
                }
            ]
        }
    }
}

index.html

<!doctype html>
<html>
  <body>
    <demo-test foo-bar="1" fooBaz="1" foo-baz="2"></demo-test>
  </body>
</html>

Support for locally imported components

In VueJs, component dependencies can be imported locally in each file. They do not have to be registered globally, even for libraries. Since components are exported using the default export, they also have no name. Instead, their tag will match the name of the variable that declared the component. Eg:

<template>
  <my-fancy-component></my-fancy-component>
  <another-name></another-name>
  <foo-bar></foo-bar>
</template>
<script setup>
import MyFancyComponent from '@/components/MyFancyComponent';
import AnotherName from '@/components/MyFancyComponent';
const FooBar = MyFancyComponent;
</script>

In this case, all three names are valid since they reference the same default export.

Thus, it should be possible to declare a "vue-component" contribution not by name or type, but by module/file only. Any tag matching a variable affected from the default export should match the web-type. The import shouldn't appear as "unused" (like right now), even if the web-type is declared with highest priority.

web-types.json not loaded in my WebStorm 2020.2.2

Hey @piotrtomiak ,

as mentioned in the vue global conf amsterdam, I can not get my web-types.json to work on my machine.
Intresting is, it worked on your machine with the exactly same web-types.json file

web-types:
https://gist.github.com/joeherold/c1fd371ad40f706790ace2fda37e11e7

should provide api-key as a suggesetion

Thank you a lot!
Johannes Pichler

Can I use web-types in Goland without package.json?

Does the web-types system have a dependency on NPM?

I don't use npm or package.json but I want to use the HTMX webtype in JetBrains Goland.

Is this possible?

$schema

The example packages have $schema as a relative path, but I'm not sure how this translates when distributing a web-types.json with my own package.
Should I:

• Omit it?
• Copy the web-types.schema.json to my own project?
• Something else?

The schema.json has "$schema": "http://json-schema.org/draft-07/schema#", is there a similar URL we can use to refer to this?

Source pathing is wrong, which prevents navigation

This is what you currently get in the generated web-types.json file:

          "source": {
            "module": "./src\\components\\General\\Page.vue",
            "symbol": "default"
          }

But if you fix the pathing manually to:

          "source": {
            "module": "./src/components/General/Page.vue",
            "symbol": "default"
          }

Then everything works, is this a bug or should this be changed through the configuration?

This is how I did it:

1. Install vue-docgen-web-types in your project: npm i vue-docgen-web-types
2. Add the following to package.json

	"scripts": {
		"update-web-types": "vue-docgen-web-types"
	},
    "web-types": "./web-types.json",

3. Run the update-web-types npm command.
4. Check the ./web-types.json

I also don't have JsDoc installed.

Is there a solution for scenarios where the components are registered by a dedicated file?

Hi, I'm trying to solve an issue where my Vue components' code-completion won't work if they are not registered within the main.ts file.

Here's the gist of it

In this case, the code-completion works 😄

// main.ts

import { createApp } from "vue";

// component
import Button from "primevue/button";

init();

function init() {
  const app = createApp(App);

  app.component("PrimeButton", Button);
}

In this case, the code-completion does not work 😢

// main.ts

import { createApp } from "vue";

import { registerComponents } from "./registerComponents";

init();

function init() {
  const app = createApp(App);

  registerComponents(app);
}

// registerComponents.ts

import type { App } from "vue";

import Button from "primevue/button";

export function registerComponents(app: App): void {
  app.component("PrimeButton", Button);
}

Example for vanilla js web components

Can you please add an example for vanilla web components?

Using a configuration file with --config

Not a bug - just need some help! - Attempting to change/add an array of directories to the 'components' array in WebTypesBuilderConfig, what is the recommended way to pass this into the --config option? Create a new ts file, Implement WebTypesBuilderConfig and all the properties, override them in the constructor and point --config to a new .ts file?

I tend to work mainly with .js and .json files in this project, we don't compile TS so trying to work out the best approach to this. So far I haven't been able to get the doc gen to pick up a --config file.

Thanks!

The vue3 global component setting web-types.json component cannot jump?

Hi, I am using vue3 in my project, I use vue-docgen-web-types to generate global component information in the project, this prevents webstorm from making errors on global component tags, but since I have done this I cannot jump to the corresponding global component file in the vue file by tag. This surprised me, because when there is no web types.json file, although tags are not recognized, tags can jump instead.

Source class for Web Components

I am trying to add a TypeScript class as a source for my custom element, but I can't figure out how to properly configure it.

Here's one of the things I've tried:

"name": "my-element",
"source": {
  "module": "MyModule",
  "symbol": "MyClass"
}

and this is a typescript file containing the class:

export declare module MyModule {
    export class MyClass {
        public Name: string;
        public LastName: string;
    }
}

I have also tried adding path in the "module" option,

Can someone instruct me on how to get a TypeScript class to work as a custom-element's source?
To be able to navigate to it, etc.?

extract.sh script doesn't work with Vue3

extract.sh is using Vue2, any plans on Vue3 version?

Web-types Generation for Vue Components

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?

Use web-types.json localy

WebStorm 2019.2 and PhpStorm 2019.2
Ubuntu 18.04

We are trying to add support for web types to our project as a local file.

About our project:
Typscript, use VueJs for UI.
We have a very unusual use of Vue.
All components wrote on classes with many syntactic sugar.
A component consists of several files: component class, template, styles, and unit test.
Of course, IDE does not understand our component syntax. There are no normal autocomplete in the our template files.

With the introduction of 2019.2 we got the idea to use web types locally. We want to generate a web type file on all our components on the fly. There we want to greatly improve the usability of the development, since there will be a full autocomplete for all components and their properties.

But something went wrong, and the web-types don't work. It feels like the IDE doesn't see them.

Our steps for the test:

1. created a file web-types.json with a description of one of our components - control-progress-line
2. added a line in package.json: "web-types": "./web-types.json"

This does not work. What are we doing wrong?

File web-types.json:

{
  "$schema": "https://raw.githubusercontent.com/JetBrains/web-types/master/schema/web-types.schema.json",
  "framework": "vue",
  "name": "ui",
  "version": "0.0.2",
  "contributions": {
    "html": {
      "types-syntax": "typescript",
      "tags": [
        {
          "name": "control-progress-line",
          "source-file": "./src/ui/components/control-progress-line/index.ts",
          "attributes": [
            {
              "name": "buffer",
              "type": "number",
              "required": true,
              "default": "-1"
            },
            {
              "name": "value",
              "type": "number",
              "required": true,
              "default": "-1"
            },
            {
              "name": "max",
              "type": "number",
              "required": true,
              "default": "0"
            },
            {
              "name": "tooltip",
              "type": "boolean",
              "default": "true"
            },
            {
              "name": "outerWidth",
              "type": "number"
            }
          ],
          "events": [
            {
              "name": "timeClick",
              "arguments": [
                {
                  "name": "value",
                  "type": "number"
                }
              ]
            }
          ]
        }
      ],
      "attributes": [

      ]
    }
  }
}

Part of file package.json:

{
  "name": "***",
  "version": "0.0.2",
  "description": "***",
  "main": "index.js",
  "scripts": {
    ***
  },
  "devDependencies": {
    ....
    "@types/chai": "^4.1.7",
    "@types/copy-webpack-plugin": "^5.0.0",
    "@types/html-webpack-plugin": "^3.2.1",
    "@types/jasmine": "^3.3.16",
    "@types/mocha": "^5.2.7",
    "@types/webpack": "^4.32.1",
    "@web-types/vue": "^2.5.0-1",
    ....
    "clean-webpack-plugin": "^3.0.0",
    "copy-webpack-plugin": "^5.0.4",
    "fork-ts-checker-webpack-plugin": "^1.4.3",
    "html-webpack-plugin": "^3.2.0",
    ...
    "jasmine-core": "^3.4.0",
    "reflect-metadata": "^0.1.13",
    "ts-loader": "^6.0.4",
    "tslint": "^5.18.0",
    "typescript": "^3.5.3",
    "vue": "^2.6.10",
    "vue-class-component": "^7.1.0",
    "vue-loader": "^15.7.1",
    "vue-property-decorator": "^8.2.1",
    "vue-rx-decorators": "^0.0.8",
    "vue-template-compiler": "^2.6.10",
    "vue-template-loader": "^1.0.0",
    "vue-tsx-support": "^2.3.1",
    "vuex": "^3.1.1",
    "webpack": "^4.38.0",
    ....
  },
  "web-types": "web-types.json"
}

Component template file example:

<div>
   <control-progress-line :value="currentTime" :buffer="currentBuffer" :max="duration" @timeClick="onTimeClick"></control-progress-line>
</div>

"Unknown HTML Tag" - IntelliJ 2020.3.2

web-types version:
"vue-docgen-web-types": "^0.1.7",

App:
"vue": "^2.6.12"

IntelliJ is giving the following warning message when trying to use web-types with 2020.3.2 (latest release as of writing):

web-types.json has been generated with no errors:

When rolling back to IntelliJ 2020.3, web-types works fine. Seems to only be an issue with the latest releases.
Happy to provide any logs necessary.

How to generate web-types for local library

I have an internally developed global component library I would like to generate web-types for. I've built a basic web-types.json file and added a single component to it to test functionality and would like to generate docs for all of the components in our library.

I've attempted to run the extract.sh file, but this appears to try and pull the library off NPM, which will not work with our unpublished library.

Is there a script I can interact with directly to call into my local library?

What assumptions are made about the shape of the library? Can I run this system over a vue-cli generated library? Or should I have this library simply look at the index file for the component library?

Thanks!

Better error handling for vue-docgen-web-types

I couldn't find any option to get more verbose error messages if something goes wrong during generation, I just get this:

Building web-types to C:\dev\module-laravel-app\web-types.json
Error building web-types: Error building file C:\dev\module-laravel-app\web-types.json: Unexpected token (312:75)

which is really not helpful at all 😄
One of my vue files is throwing it off, I know as much, but there are plenty and manually trying them one by one would be arduous to say the least.

How to document CSS custom properties (CSS variables) ?

I tried with a web-types file like

{
    "$schema": "http://json.schemastore.org/web-types",
    "name": "test",
    "version": "0.0.0",
    "contributions": {
        "css": {
            "properties": [
                {
                    "name": "--demo-css-var",
                    "description": "Demo CSS var"
                }
            ]
        }
    }
}

But it seems not to be working: I don't have completion in CSS file.
Or it's working with some other conditions I don't get. I have something working in some context, but I'm not sure if this is due to web-types file.

This function seems a bit off

I feel that this library will become meaningless after vue 3 is used on a large scale, because TypeScript will provide code hints, like many React-TS libraries do. . .

Ref: https://vue-composition-api-rfc.netlify.com/#logic-reuse-code-organization

Publish web-types JSON schema

Once web-types schema matures enough, it should be published to e.g. http://schemastore.org/json/

enums working partially for WebStorm 2020.2.2

If you have defined CSS declaration in your project for attribute then Webstorm will show you (ctrl + J) CSS specificity instead of providing autocomplete for web-types enums.

css

foo[bar] { display: block }

html

<foo bar=""></foo>

web-types.json

...
  "contributions": {
    "html": {
      "elements": [
        {
          "name": "foo",
          "attributes": [
            {
              "name": "bar",
              "value": {
                "kind": "plain",
                "type": "enum"
              },
              "values": [
                {
                  "name": "baz"
                },
                {
                  "name": "qux"
                },
              ]
            },
          ]
...

Named component import

Hi! I have a problem when I import vue component with the named export.

I'm making my component library, but let's take a look at bootstrap-vue, because they have the same problem.

When I use global vue components via Vue.component(...) or Vue.use(...) – everything fine. It shows me the description and all available props.

But when I import component in my SFC and register it locally – web-types doesn't work. It shows me only default Vue directives, attributes, etc.

Thanks for helping.

Use web-types from symlinked projects

WebStorm 2019.2 EAP

We try to connect web types to our project as a local file.

1. Created two Vue projects
2. In the first project, we created the types/web-types.json file, and in the package.json we added the line
   "web-types": "types/web-types.json",
3. In the second project, we connected the first project via yarn link

This does not work.
In the second project there are no visible components from the first project.
What are we doing wrong?

File types/web-types.json:

{
  "framework": "vue",
  "name": "ui",
  "version": "0.0.1",
  "contributions": {
    "html": {
      "types-syntax": "typescript",
      "tags": [
        {
          "name": "MyBtn",
          "attributes": [
            {
              "name": "disabled",
              "type": "boolean"
            },
            {
              "name": "title",
              "type": "string"
            }
          ],
          "events": [
            {
              "name": "click"
            }
          ],
          "slots": []
        }
      ],
      "attributes": [
      ]
    }
  }
}

Priority issue with web-types and named import

I have component library writtenin vue3. I have successfully integrated web-types but when i do anamed importthen i loose features such as icon does not show up and props code suggestion does not show up. How can i make sure that code completion works with named import as well ?

Better support for union types

Just found this project in hopes of improving auto completion for my lib, its looking not bad!

Sadly I use union types for many values and I am missing auto completion for those.
e.g:
I define my props using vue3's script setup and typescript:

const props = withDefaults(
  defineProps<{
    disabled?: boolean;
    size?: "small" | "medium" | "large";
    buttonType?: "primary" | "secondary" | "red" | "transparent";
    loading?: boolean;
    to?: string | RouteLocationRaw | object;
  }>(),
  {
    disabled: false,
    size: "small",
    buttonType: "primary",
    loading: false,
    to: undefined,
  }
);

the generator creates this attribute for "buttonType":

            {
              "name": "buttonType",
              "required": false,
              "value": {
                "kind": "expression",
                "type": "union"
              },
              "default": "\"primary\""
            },

loosing all the context of my union :/

How to set the offset in the source property?

I am implementing Web types for my custom web components and I struggle to figure out which value "offset" should be set in order to get the "Go to definitions" working in IntelliJ.

Example:

{
      "elements": [
        {
          "name": "my-component",
          "description": "This is a custom web component",
          "source": {
            "file": "./MyComponent.js",
            "offset": 0
          },
          "pattern": {
            "or": ["my-component"]
          }
}

It is working if the class in MyComponent.js is the first line in the file:

class MyComponent extends LitElement {
...
}

But if it is the second line it does not work, for example:

define(["lit"], function ({LitElement}) {
    class MyComponent extends LitElement  {
    ...
    }
})

I tried setting offset to the following value: -1 0 1 2, without success.

How the offset should be set?

web-types not loading with intellij 2021.1

In my vue 3 component library's package.json i am using "web-types": "./ais-components.web-types.json",. However i am not getting any code suggestion in library consuming app.

Package.json

  "module": "./dist/ais-components.es.js",
  "main": "./dist/ais-components.umd.js",
  "web-types": "./ais-components.web-types.json",
  "exports": {
    ".": {
      "import": "./dist/ais-components.es.js",
      "require": "./dist/ais-components.umd.js"
    },

I also don't see any error in my intellij logs.

How to add web-types to package.json exactly?

I might be missing something but how exactly is one supposed to add web-types to package.json?

The docs only say:

link them through web-types property in package.json

But that's not clear to me. Should the property be an array or an object? Should the value(s) point to the web-type definition folder, its package.json file, its *.web-types.json file? Where?

Please provide an example. Thanks.