Custom Elements Manifest is a file format that describes custom elements in your project.
Custom Elements Manifest is a file format that describes custom elements. This format will allow tooling and IDEs to give rich information about the custom elements in a given project. You can find the repository for the specification of the schema here.
✨ Try it out in the online playground! ✨
Currently it only does fields, finish attrs/events as well
Also make sure to not have duplicates, e.g.: if a method is already present in the class's members, it means the class is overriding it
example:
class Foo extends Super {
someMethod(){}
}
class Super extends HTMLElement {
someMethod(){}
}someMethod should only be in the output classdoc for Foo once
import { LitElement } from '@lion/core';
import { ChoiceGroupMixin, FormGroupMixin } from '@lion/form-core';
/**
* A wrapper around multiple radios.
*/
export class LionRadioGroup extends ChoiceGroupMixin(FormGroupMixin(LitElement)) {
connectedCallback() {
super.connectedCallback();
this.setAttribute('role', 'radiogroup');
}
/**
* @override FormGroupMixin, during a reset if the current checked value is behind
* the initial checked value, they both got unchecked
*/
resetGroup() {
let initValue;
this.formElements.forEach(child => {
if (typeof child.resetGroup === 'function') {
child.resetGroup();
} else if (typeof child.reset === 'function') {
child.reset();
// If the value was initially checked save this
if (child.checked) {
initValue = child.value;
}
}
});
this.modelValue = initValue;
this.resetInteractionState();
}
}{
"kind": "javascript-module",
"path": "./src/LionRadioGroup.js",
"declarations": [
{
"kind": "class",
"name": "LionRadioGroup",
"mixins": [
{
"name": "ChoiceGroupMixin",
"package": "@lion/form-core"
},
{
"name": "ChoiceGroupMixin",
"package": "@lion/form-core"
}
],
"superclass": {
"name": "LitElement",
"package": "@lion/core"
},
"members": [
{
"kind": "method",
"name": "resetGroup",
"privacy": "public"
}
],
"tagName": "lion-radio-group"
}
],
"exports": [
{
"kind": "js",
"name": "LionRadioGroup",
"declaration": {
"name": "LionRadioGroup",
"module": "./src/LionRadioGroup.js"
}
}
]
}Should automatically add a customElementsManifest property to the package's package.json with a path to the generated custom elements manifest for easy adoption.
This also makes it easy for tools like snowpack to create a "web components" filter, relevant discussion here: https://twitter.com/passle_/status/1357389975856312322?s=20
/**
* @returns {void}
*/
foo() {}results in: {type: { type: ''}}
/**
* Banner component
*
* @attr type - Determines the style, can be "info", "warning", or "error". Default is "info"
* @attr corner - Determines if banner sets position at upper right corner or not.
*
* @slot header - Primary message of the banner.
* @slot content - Secondary message of the banner. Used to provide a description.
*/
export class Banner extends SpectrumElement {
@property({ reflect: true, type: String })
public type: 'info' | 'warning' | 'error' = 'info';
@property({ reflect: true, type: Boolean })
public corner = false;
}"attributes": [
{
"name": "type",
"type": {
"type": ""
},
"description": "Determines the style, can be \"info\", \"warning\", or \"error\". Default is \"info\""
},
{
"name": "corner",
"type": {
"type": ""
},
"description": "Determines if banner sets position at upper right corner or not."
},
{
"name": "type",
"fieldName": "type"
},
{
"name": "corner",
"fieldName": "corner"
}
],If types are imported they should have a module or package property
import Person from './Person';
const foo: Person = {};e.g.:
export default function() {}
export default () => {}Currently shows up as:
{
"declarations": [
{
"kind": "function",
"name": ""
}
],
"exports": [
{
"kind": "js",
"name": "default",
"declaration": {
"name": "",
"module": "./my-element.js"
}
}
]
}Expected:
{
"declarations": [
{
"kind": "function",
"name": "default"
}
],
"exports": [
{
"kind": "js",
"name": "default",
"declaration": {
"name": "default",
"module": "./my-element.js"
}
}
]
}todo
ts has some helper functions for this:
ts.getJSDocTypeParameterTags
ts.getJSDocReturnTypeadd --dev flag to output custom-elements.json to the console.
Currently everything is hardcoded.
custom-elements.jsonI think this only requires a small change to the static properties getter, since it supports a default value, e.g.:
static get properties() {
return {
mode: {
type: String,
value: 'auto'
},
data: {
type: Object,
notify: true,
value: function() { return {}; }
}
}
}Note that objects and arrays are a function that return an object or array
Schema should be published soon, so we can now actually just have it as a dependency
Currently only customElements.define is picked up as a export of kind "custom-elements-definition". We should also pick up window.customElements.define.
It now naively handles window.customElements.define, but it would be nice to implement the helper code lars mentioned
class MyElement extends HTMLElement {
/**
* @type {string} - description
*/
prop = 'foo';
constructor() {
super();
/** @type {number} - description */ // if duplicate description/type, overwrite the description/type above
this.prop = 'foo';
}
}${import('./module.js').SomeType}. Get type SomeType, add reference to ./module.js /**
* @param {e} Event
* @returns {void}
*/
myMethod(e) {} {
"name": "Event",
"type": {
"type": "e"
}
},
{
"name": "e"
}{import('foo').SomeType}/**
* Size of the text field
* @attr
* @type {"small"|"large"}
*/
size = "large";
constructor() {
super();
/**
* Size of the text field
* @attr
* @type {"small"|"large"}
*/
this.size = "large";
} static get observedAttributes() {
return [
/** some jsdoc */
"placeholder",
/** more jsdoc */
"disabled",
];
}/**
* Dispatched when the enter key is pressed
*/
this.dispatchEvent(new CustomEvent('enter'));class MyElement extends HTMLElement {
/**
* Dispatched when the enter key is pressed
* @fires {Event} some-event - some description for some-event
* @event {SomeCustomEvent} foo-changed - some description for foo-changed
*/
this.dispatchEvent(new CustomEvent('foo-changed'));
}@fires@eventEvent or CustomEvent, add Reference to the event (it should be in imports or in declarations after the analyze phase)@event or @fires overwrites the description on top${import('./module.js').SomeEvent}. Get type SomeEvent, add reference to ./module.jshttps://github.com/webcomponents/custom-elements-manifest/pull/31/files
when adding an event, check if it doesnt already exist
__open(dispatch) {
if (dispatch) {
this.dispatchEvent(
new CustomEvent('opened-changed', {
detail: true,
}),
);
}
this.__button.setAttribute('aria-expanded', 'true');
}
__close() {
this.dispatchEvent(
new CustomEvent('opened-changed', {
detail: false,
}),
);
this.__button.setAttribute('aria-expanded', 'false');
}{
"name": "opened-changed",
"type": {
"type": "CustomEvent"
}
},
{
"name": "opened-changed",
"type": {
"type": "CustomEvent"
}
}In some places there are quite a lot of any types used, just to get something working. It'd be nice to reduce the amount of any throughout the code.
Contributions are welcome here, if anybody is interested in contributing to this: Dont worry about the entire codebase, whatever cleanup here is welcome 🙂
@open-wc/scoped-elements should be package instead of module
"mixins": [
{
"name": "ScopedElementsMixin",
"module": "@open-wc/scoped-elements"
},
{
"name": "LocalizeMixin",
"package": "ing-web"
}
example:
input
class MyElement extends HTMLElement {
/**
* @param {Object} opts
* @param {string} opts.currency
*/
_onCurrencyChanged({ currency }) {}
}output:
"parameters": [
{
"name": "opts",
"type": {
"type": "Object"
}
},
{
"name": "opts.currency",
"type": {
"type": "string"
}
},
{}
]currently readonly is not specified in the schema, and will incorrectly be handled by the analyzer:
private foo: readonly string = '';"type": {
"type": "readonly string"
},/** @type {string} - description */
export const foo = 'bar';example:
class Foo extends HTMLElement {
shadow = this.attachShadow({mode: 'open'});
}For example, if I wanted to separate out certain properties as special ones, maybe even by adding a special jsdoc-like indicator (like @specialProp or something) how might i go about making a custom section in the produced markdown?
The use case I have is that my web components have what I call "Internal Access properties" that give consumers of the components direct access to certain important DOM elements directly rather than them having to crawl the internal shadowRoot with nested querySelectors. It would be awesome if i could specify some tag on those properties and have them get broken out into their own special category section with a name and table columns I could specify add to, etc.
I was testing the analyzer against https://github.com/justinfagnani/chessboard-element and got this error:
/Users/justinfagnani/Projects/Personal/chessboardjs/node_modules/@custom-elements-manifest/analyzer/dist/ast/handleCustomElementsDefine.js:24
elementClass = node.parent.arguments[1].text;
^
TypeError: Cannot read property '1' of undefined
at Object.handleCustomElementsDefine (/Users/justinfagnani/Projects/Personal/chessboardjs/node_modules/@custom-elements-manifest/analyzer/dist/ast/handleCustomElementsDefine.js:24:45)
at visitNode (/Users/justinfagnani/Projects/Personal/chessboardjs/node_modules/@custom-elements-manifest/analyzer/dist/create.js:287:46)
at visitNode (/Users/justinfagnani/Projects/Personal/chessboardjs/node_modules/@custom-elements-manifest/analyzer/node_modules/typescript/lib/typescript.js:27028:24)
at Object.forEachChild (/Users/justinfagnani/Projects/Personal/chessboardjs/node_modules/@custom-elements-manifest/analyzer/node_modules/typescript/lib/typescript.js:27255:21)
at visitNode (/Users/justinfagnani/Projects/Personal/chessboardjs/node_modules/@custom-elements-manifest/analyzer/dist/create.js:308:30)
at visitNode (/Users/justinfagnani/Projects/Personal/chessboardjs/node_modules/@custom-elements-manifest/analyzer/node_modules/typescript/lib/typescript.js:27028:24)
at Object.forEachChild (/Users/justinfagnani/Projects/Personal/chessboardjs/node_modules/@custom-elements-manifest/analyzer/node_modules/typescript/lib/typescript.js:27253:24)
at visitNode (/Users/justinfagnani/Projects/Personal/chessboardjs/node_modules/@custom-elements-manifest/analyzer/dist/create.js:308:30)
at visitNode (/Users/justinfagnani/Projects/Personal/chessboardjs/node_modules/@custom-elements-manifest/analyzer/node_modules/typescript/lib/typescript.js:27028:24)
at Object.forEachChild (/Users/justinfagnani/Projects/Personal/chessboardjs/node_modules/@custom-elements-manifest/analyzer/node_modules/typescript/lib/typescript.js:27253:24)
There are different results between using CLI globbing custom-elements-manifest analyze --globs="src/*.js" and via config file { globs: ["src/*.js"] }.
The values passed into globby differ here, such that when using the CLI, the glob paths are what is defined, plus some node_modules etc. filtering.
[
'src/*.js',
'!node_modules/**/*.*',
'!bower_components/**/*.*',
'!**/*.test.{js,ts}',
'!**/*.suite.{js,ts}',
'!**/*.config.{js,ts}'
]The same defined in a configuration file results in the same set of globs, plus the CLI's default value for globbing:
[
'**/*.{js,ts}', // <- these are CLI defaults
'!**/.*.{js,ts}', // <- these are CLI defaults
'src/*.js',
'!node_modules/**/*.*',
'!bower_components/**/*.*',
'!**/*.test.{js,ts}',
'!**/*.suite.{js,ts}',
'!**/*.config.{js,ts}'
]If globs are specified, I'd expect the same result regardless if they were via CLI or configuration file, and only use the default glob paths if neither specified.
Currently static get observedAttributes only works if an array is provided like so:
static get observedAttributes() {
return ['value', 'max'];
}But sometimes people may add different logic in there, which currently breaks the analyzer, like here:
https://github.com/Matsuuu/twitch-chat/blob/main/src/twitch-chat.js#L65
Currently in handleEvents we go through the entire source program again with a visitor to find a reference to the used event. We should be able to handle this in the link phase instead, since the used event should either be in the imports or in the declarations for a module.
Currently slots, css parts and css properties are only supported through JSDoc.
We could do a check with dom5/parse5 for any innerHTML or html tagged template literals, do a query select for slot, slot[name] and [part], to automatically find slots, parts, and properties.
In the original manifest analyzer, additional properties were supported for type and defaults for tags like @cssprop:
/**
* @cssprop {<length>} [--my-prop=10px] My CSS property.
*/
Is there interest in supporting this in core?
Fixture:
class MyElement extends HTMLElement {
static get observedAttributes() {
return [
/** some jsdoc */ // only description
"placeholder",
/**
* Disabled the component // description goes here, or after the type.
* @type {disabled}
* @type {disabled} - Disables the component // If this is present, override the description above
* @property disabled // adds a `"fieldName": "prop1"` to the attr in the output CE.json
*/
"disabled",
];
}
}static get observedAttributes() {}static observedAttributes = []@property related fieldName doesnt clash with the support for the @property jsdoc@type jsdoc@type's description overwrites the 'top' description${import('./module.js').SomeEvent}. Get type SomeEvent, add reference to ./module.jsHey @thepassle!
First off thanks heaps for the hard work on this library. I'm having some slight issues trying to extend the manifest in the analyzePhase within my custom plugin. All the syntax kinds are messed up for some reason, classes are returning as variable declarations, enums as class declarations, types as functions and so on. All the code is available here, you can also see the plugin and what not inside the cem directory (nothing special).
Another issue closely related is I'm trying to get "inherited" documentation on a property or method from an interface but it currently doesn't work. Sometimes it's preferable to write an interface and implement it across different components. Documenting solely the single interface saves energy in avoiding to have to document multiple component props/methods over and over.
Normally the recommended way to get documentation is to retrieve it on a symbol via the TypeChecker. Something like...
// EXAMPLE
const comment = checker.getSymbolAtLocation(identifier)?.getDocumentationComment(checker);
return normalizeLineBreaks(ts.displayPartsToString(comment) ?? '');This library currently doesn't parse files using createProgram (probably performance reasons to avoid type checks?) and instead uses createSourceFile, unfortunately this loses type information which can be used in the analyzePhase by a custom plugin. In my case this could be used to get better type inference and symbol documentation.
Is this something we can resolve in this library or should I fork?
When checking default values for properties, the assignment is a registered field, and nothing else, to avoid things like:
{
"kind": "method",
"name": "__onKeyDown",
"default": "this.__onKeyDown.bind(this)"
}For fields and variables we can already add the 'simple' TS type by getting the: node.type.getText()
Fixture:
class MyElement extends HTMLElement {
foo: string = ''
}
customElements.define('my-element', MyElement);Click on foo in the left panel of AST explorer, set compiler to typescript, and you'll see a type property in the PropertyDeclaration that you can call .getText() on
via the README, Plugins are defined as functions, including the example:
A plugin is a function that returns an object. There are several hooks you can opt in to:
However, the current implementation defines a Plugin as an object with analyzePhase, and other callbacks. While plugins in npm (and the built in lit and stencil plugins) may expose functions, the plugins array must ultimately be an object.
Happy to send PR with doc changes, but want to confirm the intentions here first.
It would be really nice to have Stencil support as a plugin with the new plugin API.
git clone https://github.com/open-wc/custom-elements-manifest.gitcd custom-elements-manifestyarn installcd packages/custom-elements-manifest-analyzeryarn tsc:watchnpm startFor tests, you can add a new fixture in the fixtures folder, and the tests will automatically run it, and compare the output.json (which is the output generated by the analyzer) to the fixture/custom-elements.json, which is the expected state.
@Component({tag: 'my-foo'}) decorator to add a tagName to a classDoc
kind: custom-elements-definition, and should show up in a modules exports@Prop() decorator
@Prop(), make sure to add it as an attribute as well@Prop({reflect: true}), make sure to add it as an attribute as well@Prop({attribute: 'foo'}), make sure to add it as an attribute as well, with the given attribute name@Prop() isValid: string; make sure the attr name is is-valid (camelcase to kebab)@Prop() foo: ComplexType ignore the attribute; only add attributes if the type is a primitive (num, str, bool, etc)@Event() decorator
@Event() todoCompleted: EventEmitter<Todo>;, it will fire a todoCompleted event, add that to events@Event({eventName: 'todoCompleted'}), it will fire a todoCompleted event, add that to eventsA plugin is a function that returns an object. There are several hooks you can opt in to:
Most (if not all) of the work for the Stencil plugin will happen in the analyzePhase, which is where you'll have access to a modules AST. ASTExplorer is your friend 🙂
import ts from 'typescript';
export default {
plugins: [
function myPlugin() {
return {
// Runs for each module
analyzePhase({node, moduleDoc}){
// You can use this phase to access a module's AST nodes and mutate the custom-elements-manifest
switch (node.kind) {
case ts.SyntaxKind.ClassDeclaration:
// AST magic goes here, and you can mutate the `moduleDoc`
break;
}
},
// Runs for each module, after analyzing, all information about your module should now be available
moduleLinkPhase({node, moduleDoc}){},
// Runs after modules have been parsed and after post-processing
packageLinkPhase(customElementsManifest){},
}
}
]
}Here's a fixture/overview (and ASTExplorer link) of things the plugin should support:
import { Component } from '@stencil/core';
// TodoList should have `todo-list` as `tagName` in the output custom-elements.json
// This is also an export of kind: "custom-elements-definition"
@Component({
tag: 'todo-list'
})
export class TodoList {
// shows up as attr
@Prop() color: string;
// shows up as `is-valid` attr (camelcase to kebab)
@Prop() isValid: boolean;
// doesnt show up as attr! (complex type)
@Prop() controller: MyController;
// shows up as attr `valid`
@Prop({ attribute: 'valid' }) isValid: boolean;
// shows up as attr `message` (probably doesnt even need special handling, but just incase)
@Prop({ reflect: true }) message = 'Hello';
// shows up as event `todoCompleted`
// `todoCompleted` should not be present in the class's members array
@Event() todoCompleted: EventEmitter<Todo>;
// shows up as event `foo`
@Event({
eventName: 'foo',
}) fooEvent: EventEmitter<Todo>;
// these should not show up in custom-elements.json
componentWillLoad(){}
componentDidLoad(){}
componentShouldUpdate(){}
componentWillRender(){}
componentDidRender(){}
componentWillUpdate(){}
componentDidUpdate(){}
}Support @prop and @property jsdoc, e.g.:
/**
* @prop {boolean} bar - description
* @property {boolean} bar - description
*/
class Foo extends HTMLElement {}Hey, I saw this list of supported jsdoc "tags"...
webcomponents/custom-elements-manifest#42 (comment)
would it be possible to allow extraction of custom tags via a simple config or so 🤔
i could imagine somthing like this.
class MyElement extend HTMLElement {
/**
* @type string
* @editvia textarea[rows=2]
*/
message = '';
/**
* @type string
* @editvia select['variation-a', 'variation-b']
*/
variation = '';could be something like this
export default {
extractAdditionalJsDocs: ['editvia']
}so in the end for this class I would have this additional values available in the json and then tools could use it
what do you think?
React
A declarative, efficient, and flexible JavaScript library for building user interfaces.
🖖 Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
Typescript
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
Django
The Web framework for perfectionists with deadlines.
Laravel
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. 📊📈🎉
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
Facebook
We are working to build community through open source technology. NB: members must have two-factor auth.
Microsoft
Open source projects and samples from Microsoft.
Google
Google ❤️ Open Source for everyone.
Alibaba
Alibaba Open Source for everyone
D3
Data-Driven Documents codes.
Tencent
China tencent open source team.