cce - create custom elemen (working title)

A base class for creating Web Components more conveniently. Built on signals lit-html providing helpers for event handling.

[!WARNING] This is still in its infancies and exploration phase. Also the name will definitely change. You may look around, you could even use it - I personally use it to build a couple of side projects, but I can't provide any support in its current state.

Features

• Fine grained render updates using signals
• Thin convnience wrapper around native life-cycle hook
  • mount() instead of connectedCallback()
  • on instead of addEventListener() and manually cleaning up.
• Highly efficient element re-use during rerenders thanks to lit-html
• Setup of context providers and consumers without orchestration using string keys
  • or more memory efficient using the usual createContext route.
  • using the context community standard for interop.
• No synthetic events, no v-dom, all web.
• Lightweight (<7.8kb gzip, signals, context, rendering and all)

API Overview

1class MyCustomElement extends CustomElement {
2    // Props are reactive and available in the render() method via `this.someProp()`
3    // they can be updated using setAttribute or ``<element>.someProp = newValue`
4    // and can be bound in render:
5    //      html`<my-element .someProp=${someValue}></my-element>`
6    static props = {
7        simplePropDefault: "default value",
8        // can be a function that serves as a serialiser/transformer
9        someOtherProp: (value = "also default") => value.toUpperCase(),
10        // meaning, this works too:
11        counter: Number
12    }
13
14    // For private state, simply use a private field. Public would also work,
15    // but you'll most likely want a prop then.
16    #somePrivateState = signal()
17
18    // style is expected to be a CSSStylesheet instance. Create one using 
19    // the builtin `css` template literal, or construct your own.
20    static style = css`
21        div {
22            background: black;
23            color: white;
24        }
25    `
26
27    // A more convenient alias for constructor() { super() }
28    // In one of the next minor versions setup can be async...
29    setup() { 
30        effect(() => console.log("somOtherProp was changed!", this.someOtherProp()))
31
32        setTimeout(() => {
33            // ... but this pattern is convenient enough most of the time.
34            this.someOtherProp("new value")
35        }, 500)
36    }
37
38    mount() {
39        this.on('some-event', (e) => {
40            // this event handler will automatically be removed on unmount
41            // also events are stopped from propagating.
42            // You can still use this.addEventListener when this doesn't suite
43            // your needs.
44            // NOTE: `this.on` is only allowed to be called here at the moment.
45        })
46
47        return () => {
48            // this will be called on unmount
49        }
50    }
51
52    // Render gets passed `this`, so you can destructure props etc and make
53    // it easier to re-use views.
54    render({counter}) {
55        // the html tagged template literal is coming straight from lit-html
56        return html`
57            <div>
58                Value of someNumberProp: ${this.someNumberProp()}
59                <button @click=${() => this.counter(this.counter() + 1)}>
60                    ${counter()}
61                </button>
62
63                <button @click=${() => {
64                    // Shorthand for dispatching events that *bubble up* and 
65                    // can be caught by shadow dom.
66                    // this.dispatchEvent() works like usual, in case `on` does
67                    // not suit your needs.
68                    this.dispatch('simple-event')
69                    this.dispatch('custom-event', payload)
70                }}>
71                    dispatch!
72                </button>
73
74                <!-- shadow dom! -->
75                <slot></slot>
76            </div>
77        `
78    }
79}
80
81// Don't forget to define it!
82customElements.define("my-element", MyCustomElement);