A decorator that transforms a class property to a component internal property.
An internal property is a property that works under the hood. Its role is to be an intrinsic mechanism, so it would be better to avoid sharing and reusing it outside of the class.
For React users, this concept may be familiar as a Component State.
@element('my-component-with-modal', {renderer})
class MyComponentWithModal extends HTMLElement {
@internal private isOpen: boolean = false;
private handleOpen(): void {
this.isOpen = !this.isOpen;
}
private [render](): TemplateResult {
return html`
<button @click=${this.handleOpen}>Open modal</button>
<some-modal ?open=${this.isOpen}></some-modal>
`;
}
}A symbolic name of the ElementGears.internalChangedCallback. Use it to declare the method.
class Foo extends HTMLElement {
[internalChangedCallback](propertyName: PropertyKey, oldValue: unknown, newValue: unknown): void {
// method body
}
}A symbolic name of the ElementGears.propertyChangedCallback. Use it to declare the method.
class Foo extends HTMLElement {
[propertyChangedCallback](propertyName: PropertyKey, oldValue: unknown, newValue: unknown): void {
// method body
}
}A symbolic name of the ElementGears.render. Use it to declare the method.
class Foo extends HTMLElement {
[render](): unknown {
// method body
}
}A symbolic name of the ElementGears.updatedCallback. Use it to declare the method.
class Foo extends HTMLElement {
[updatedCallback](): void {
// method body
}
}A decorator that binds a class property to an appropriate attribute and provides a transformation to the property value to and from the attribute string.
An attribute is the most well-known property type and also the most complex
type to work with. Standard requires that it should only be a string type,
but Corpuscule allows it to have three primitive types: String, Boolean,
and Number.
connectedCallback is
allowed yet also limited, because component users can set these attributes
before connection to DOM and would be upset if default values override ones
made by them. If you consider all these possibilities, you can set defaults
in connectedCallback manually; it will require additional render for your
component though.HTMLElement attributes storage, and
whenever you request them, cast to proper type happens. That's the reason
you cannot save in attribute more than just a primitive type.attributeChangedCallback method with
attribute name, old and new value.<script type="module">
@element('my-button', {renderer})
class MyButton extends HTMLElement {
@attribute('disabled', Boolean) isDisabled;
[render]() {
return html`
<button disabled=${this.isDisabled}><slot></slot></button>
${this.isDisabled ? html`<span>Button disabled</span>` : nothing}
`;
}
}
</script>
<my-button disabled>Don't click me</my-button>a name of the attribute to bind.
a type of the property value that should be converted.
A decorator that transforms a class getter to a computed property. It is an approach that can be used to reduce the number of expensive calculations by remembering the latest result produced by the getter and providing it until all the class properties the getter depends on are changed.
a token produced by a createComputingToken to bind this decorator with @observer.
A decorator that converts a class declaration to a Custom Element and unites all other decorators making a complete working system from them.
a name of the new Custom Element. According to the standard, it should contain a dash symbol.
a list of options that tunes the custom element according to the requirements.
A decorator that makes a class property observed. It works together with the computed property created via @computer decorator to reset the remembered getter result. When a value of one of the observed properties is changed, the remembered result of the computed one is reset, and the next call to the getter will start the recalculation which result will be remembered again.
Each computed property will observe all the observed properties at once and will drop the remembered result on any of their change.
a token produced by a createComputingToken to bind this decorator with @computer.
A decorator that converts a class property to a component regular property.
A regular property of the component is a property that can be set only imperatively by assigning the component instance filed.
@element('my-square-info', {renderer})
class MySquareInfo extends HTMLElement {
@property(v => typeof v === 'object' && v.width && v.height)
public square = {width: 10, height: 10};
protected [render](): TemplateResult {
return html`
<div>Square width: ${this.square.width}</div>
<div>Square height: ${this.square.height}</div>
`;
}
}
customElements.whenDefined('my-component').then(() => {
const mySquareInfo = document.createElement('my-square-info');
mySquareInfo.square = {width: 40, height: 40};
document.body.append(mySquareInfo);
});a function that checks the type of the assigned value; if it
returns false, the error will be thrown.
A decorator that converts a property to a getter that finds an element with
the selector in the Light or Shadow DOM of your element using the
querySelector method.
@element('my-element', {renderer})
class MyElement extends HTMLElement {
@query('#target') private target: HTMLSpanElement;
protected [render](): TemplateResult {
return html`
<div class="wrapper">
<span id="target"></span>
</div>
`;
}
}a selector of the desired element.
a set of decorator options
A decorator that converts a property to a getter that finds all elements
with the selector in the Light or Shadow DOM of your element using the
querySelectorAll method.
@element('my-element', {renderer})
class MyElement extends HTMLElement {
@queryAll('.target') private targets: HTMLCollectionOf<HTMLSpanElement>;
protected [render](): TemplateResult {
return html`
<div class="wrapper">
<span class="target"></span>
<span class="target"></span>
<span class="target"></span>
</div>
`;
}
}a selector of the desired set of elements.
a set of decorator options
Generated using TypeDoc
This module provides tools to define web components in a declarative way.
How it works
By default, web components are too low-level to define them directly. They require too much boilerplate to create and support. This module provides special decorators that allow setting main parts of web components in the most declarative way possible. These decorators combined, create a component system that works together and is easy to interact with.
There are the following decorators that makes the system work:
Element Lifecycle
Each custom element marked with an @element decorator has the following lifecycle (including standard JS class and custom element lifecycle).
A rendering system is able to wait until multiple properties are set synchronously; only then the single rendering will be performed. However, be careful with the asynchronous setting: it may cause re-rendering on each assignment.
document.createElementmethod, this hook is separate.connectedCallbackis fired. Can be invoked multiple times for the single element.disconnectedCallbackwill be invoked directly. Can be invoked multiple times for the single element.