`;
}
}
```
## Computed properties
Create a computed property by providing a list other property names as `input`
and a `compute` callback to be invoked when the input changes. The `compute`
callbacks are memoized and are expected to be pure.
If the given function is defined on the constructor, the context (`this`) is
guaranteed to be the constructor when called later.
## Observed properties
Create an observed property by providing an `observe` function. Whenever an
observable change occurs, your function will be called with
`host, value, oldValue`.
If the given function is defined on the constructor, the context (`this`) is
guaranteed to be the constructor when called later.
## Listeners
XElement supports declarative, delegated event handlers via a `listeners`
block. Listeners are added during the `connectedCallback` and are removed during
the `disconnectedCallback` in the element's lifecycle. Listeners defined in
the `listeners` block are added to the render root.
Because it's so common to want to introspect the `event` and call a function on
the `host`, the provided arguments are `host, event`.
If the given function is defined on the constructor, the context (`this`) is
guaranteed to be the constructor when called later.
### Example
```javascript
class MyElement extends XElement {
static get properties() {
return {
clicks: {
type: Number,
readOnly: true,
default: 0,
},
};
}
static get listeners() {
return { click: this.onClick };
}
static onClick(host, event) {
host.internal.clicks += event.detail;
}
static template(html) {
return ({ clicks }) => {
return html`Clicks: ${clicks}`;
}
}
}
```
## Manually adding listeners
If you need more fine-grain control over when listeners are added or removed,
you can use the `listen` and `unlisten` functions.
Because it's so common to want to introspect the `event` and call a function on
the `host`, the provided arguments will always be `host, event`.
If the given function is defined on the constructor, the context (`this`) is
guaranteed to be the constructor when called later.
### Example
```javascript
class MyElement extends XElement {
static get properties() {
return {
clicks: {
type: Number,
readOnly: true,
default: 0,
},
};
}
static onClick(host, event) {
host.internal.clicks += event.detail;
}
connectedCallback() {
super.connectedCallback();
this.listen(this.shadowRoot, 'click', this.constructor.onClick);
}
disconnectedCallback() {
super.disconnectedCallback();
this.unlisten(this.shadowRoot, 'click', this.constructor.onClick);
}
static template(html) {
return ({ clicks }) => {
return html`Clicks: ${clicks}`;
}
}
}
```
## Render Root
By default, XElement will create an open shadow root. However, you can change
this behavior by overriding the `createRenderRoot` method. There are a few
reasons why you might want to do this as shown below.
### No Shadow Root
```javascript
class MyElement extends XElement {
static createRenderRoot(host) {
return host;
}
}
```
### Focus Delegation
```javascript
class MyElement extends XElement {
static createRenderRoot(host) {
return host.attachShadowRoot({ mode: 'open', delegatesFocus: true });
}
}
```
## Lifecycle
### Constructor Analysis
Analysis takes place once per class. This allows all future instances to share
common setup work. Halting errors are thrown here to assist in development.
### Instance Construction
Each instance undergoes one-time setup work in the `constructor` callback.
### Instance Initialization
Each instance is initialized once during the first `connectedCallback`.
### Update
When properties update on an initialized element, the following should occur:
- await a queued microtask (prevents unnecessary, synchronous work)
- compute properties (this is implied and happens lazily)
- reflect properties
- render result
- observe properties
## Recipes
### Observing multiple properties
In certain cases, you may want to observe multiple properties at once. One way
to achieve this is to compute a new object and observe that object.
```javascript
class MyElement extends XElement {
static get properties() {
return {
tag: {
type: String,
default: 'div',
},
text: {
type: String,
default: '',
},
element: {
type: HTMLElement,
internal: true,
input: ['tag'],
compute: tag => document.createElement(tag),
observe: (host, element) => {
const container = host.shadowRoot.getElementById('container');
container.innerHTML = '';
container.append(element);
}
},
update: {
type: Object,
internal: true,
input: ['element', 'text'],
compute: (element, text) => ({ element, text }),
observe: (host, { element, text }) => {
element.textContent = text;
},
},
};
}
static template(html) {
return () => {
return html``;
}
}
}
```
## References
- [WHATWG Custom Elements Spec]
- [lit-html]
[WHATWG Custom Elements Spec]: https://html.spec.whatwg.org/multipage/custom-elements.html
[lit-html]: https://lit-html.polymer-project.org/