cem-plugin-jet-brains-ide-integration
This project has been moved to the Custom Element JetBrains Integration project.
A custom elements manifest analyzer plugin to generate configuration files for web component integration with JetBrains IDEs
This is a plugin automatically generates a web-types.json
file for JetBrains IDEs using the Custom Element Manifest Analyzer.
This config enables JetBrains IDEs to display autocomplete and contextual information about your custom elements.
Usage
Pre-installation
Ensure the following steps have been taken in your component library prior to using this plugin:
Install
npm i -D cem-plugin-jet-brains-ide-integration
Import
import { generateWebTypes } from "cem-plugin-jet-brains-ide-integration";
export default {
plugins: [generateWebTypes()],
};
Implementation
Once the file has been generated, the IDE should automatically pick it up and you should see your information displayed in the IDE!
If you are deploying your library for others to use, it will also be automatically discovered and integrated by the IDE. No user involvement necessary!
Configuration
The configuration has the following optional parameters:
{
export interface Options {
outdir?: string;
webTypesFileName?: string | null;
exclude?: string[];
descriptionSrc?: "description" | "summary";
slotDocs?: boolean;
eventDocs?: boolean;
cssPropertiesDocs?: boolean;
cssPartsDocs?: boolean;
excludeHtml?: boolean;
excludeCss?: boolean;
labels?: {
slots?: string;
events?: string;
cssProperties?: string;
cssParts?: string;
};
}
import { generateWebTypes } from "cem-plugin-jet-brains-ide-integration";
export default {
plugins: [
generateWebTypes({
outdir: 'dist',
webTypesFileName?: string | null;
exclude: ['MyInternalElement'],
descriptionSrc: "description",
slotDocs: true,
eventDocs: true,
cssPropertiesDocs: true,
cssPartsDocs: true,
excludeHtml: false,
excludeCss: true,
labels: {
slots: "Slot Section",
events: "Custom Events",
cssProperties: "CSS Variables",
cssParts: "Style Hooks"
},
}),
],
};
Example
Here is a basic example of a component configuration using jsDoc:
class RadioGroup extends HTMLElement {}
Tag Mapping
Tag | Description |
---|
@summary / description | This provides the description for the custom element when autocomplete is used or the element is hovered. If no summary is provided, it will fall back to the description if it is available. |
@attr / @attribute | This will provide descriptions for each attribute. If you use union types in TypeScript or in the description, these will display as autocomplete options. Values can also be defined in the jsDoc using comma or pipe delimited values |
@reference | This is a custom tag for this plugin. It creates a reference link at the bottom of the information bubble. If multiple references are present, only the first one will be used. |
The @summary
and @attr
/ @attribute
descriptions have limited markdown support and enable you to style text, create links, and add code snippets.
Descriptions
Using the descriptionSrc
configuration, you can determine the source of the text that gets displayed in the editor autocomplete bubble. This is useful if you want to provide alternate descriptions for your React users.
If no value is provided, the plugin will use the summary
property and then fall back to the description
property if a summary is not available.
Note: Descriptions support multiple lines by breaking the comment up into multiple lines whereas summaries do not and will need to be manually added using \n
.
Slot Documentation
Slot information will display with the element description during autocompletion or when hovered over. This section can be hidden by setting slotDocs
to false
in the config.
Event Documentation
Event information will display with the element description during autocompletion or when hovered over. This section can be hidden by setting eventDocs
to false
in the config.
CSS Documentation
Component-specific CSS Properties and CSS Parts are included in the component documentation. These can be hidden using the cssPropertiesDocs
and cssPartsDocs
configuration options respectively.
Documentation Labels
There may be instances where you may want to translate or override the default section headers. Using the labels
configuration you can change one or all of the headers for the component description sections.
export default {
plugins: [
generateWebTypes({
...
labels: {
slots: "Placeholders",
events: "事件",
cssProperties: "Propiedades CSS",
cssParts: "Style Hooks"
},
}),
],
};
CSS Custom Data
Adding the CSS Custom Data file to your config provides you with autocomplete for your component's CSS custom properties.
These values can be added in your component's jsDoc. The var()
wrapper will be added automatically if they are prefixed with --
.
** NOTE: ** CSS custom property values are not supported in web-types yet, but it is an upcoming feature. Values will not be autocompleted, but custom CSS properties will.
CSS Parts
Developers will also receive autocomplete for defined CSS parts.