substrate-system/web-component

Minimal parent web component to inherit from

web component

A minimal parent class for web components.

This extends the native HTMLElement, and adds some methods to help with events.

See a live demonstration

Contents

• install
• tl;dr
• Examples
  • Create a component
  • Add the component to the DOM
  • Listen for events
  • Wildcard Event Listeners
    • Namespaced wildcard: Component.event('*')
    • Global wildcard: '*'
  • Hide undefined elements
  • Emit a namespaced event from the instance
  • Listen for a namespaced event
  • Emit a plain string (not namespaced) event
  • Listen for all namespaced events from a component
  • Listen for all events (global wildcard)
• Modules
  • ESM
  • Common JS
• methods
  • emit(name:string, opts:{ bubbles?, cancelable?, detail? }):boolean
  • dispatch (type, opts)
    • dispatch example
  • event (name:string):string
    • event example
  • qs
  • qsa
  • element.qs & element.qsa
    • example
• Misc
  • /util
    • qs
    • qsa
    • isRegistered(name:string)
    • define(name:string, element:CustomElementConstructor)
• Develop
• Test
• See also

install

npm i -S @substrate-system/web-component

tl;dr

• use .emit to emit a namepsaced event
• use .dispatch to emit a non-namespaced event
• use .event(name) to get the namespaced event type
• extend the factory function to create a web component
• Listen for all event with the '*' event name.

Examples

Create a component

Use the factory function to create a new web component.

import { WebComponent } from '@substrate-system/web-component'

class AnotherElement extends WebComponent.create('another-element') {
    connectedCallback () {
        this.innerHTML = `<div>
            hello again
        </div>`
    }
}

// call custom customElements.define with the right tag name
AnotherElement.define()

The new component will have a property NAME on the class that is equal to the name you passed in. The component name should be kebab case.

Add the component to the DOM

document.body.innerHTML += '<another-element></another-element>'

Listen for events

Use a helper method, WebComponent.event(name:string), to get a namespaced event name.

// find the instance
const el = document.querySelector('my-element')

// listen for namespaced events
el?.addEventListener(MyElement.event('hello'), ev => {
    console.log(ev.detail)  // => 'some data'
})

// listen for non-namespaced events
el?.addEventListener('hello', ev => {
    console.log(ev.detail)  // => 'some data again'
})

Wildcard Event Listeners

The component supports two types of wildcard event listeners.

Namespaced wildcard: Component.event('*')

Listen to all events emitted through the component's .emit() method (events in the component's namespace):

const el = document.querySelector('my-element')

const listener = (ev) => {
    console.log('Namespaced event:', ev.type)
}

// Add listener for all 'my-element:*' events
el.addEventListener(MyElement.event('*'), listener)

// These will trigger the listener
el.emit('click')    // Fires with type 'my-element:click'
el.emit('change')   // Fires with type 'my-element:change'

// This will NOT trigger the listener (not namespaced)
el.dispatch('hello')

// Remove the wildcard listener
el.removeEventListener(MyElement.event('*'), listener)

Global wildcard: '*'

Listen to all events dispatched through the element:

const el = document.querySelector('my-element')

const listener = (ev) => {
    console.log('Any event:', ev.type)
}

// Add listener for ALL events
el.addEventListener('*', listener)

// ALL of these trigger the listener
el.emit('custom')                      // my-element:custom
el.dispatch('hello')                   // hello
el.dispatchEvent(new Event('click'))   // click

// Remove the global wildcard listener
el.removeEventListener('*', listener)

Hide undefined elements

Tip

Use the CSS :defined pseudo-class to hide elements until they have been defined in JS, to prevent a FOUCE.

my-element:not(:defined) {
  visibility: hidden;
}

Caution

JS must exist on the device for the custom elements to be defined. A better option might be to set a single class when everything is defined.

Emit a namespaced event from the instance

// find the instance
const el = document.querySelector('my-element')

// dispatch an event
el?.emit('hello', { detail: 'some data' })  // => `my-element:hello`

Listen for a namespaced event

Use the static method .event to get a namespaced event name.

class ExampleComponent extends WebComponent {
    tag = 'example-component'
    // ...
}

const ev = ExampleComponent.event('click')
// => 'example-component:click'

Emit a plain string (not namespaced) event

The dispatch method wont namespace the event name. It just emits the literal string.

const el = document.querySelector('my-element')

// dispatch an event as plain string, not namespaced
el?.dispatch('hello', { detail: 'some data again' })  // => `hello`

Listen for all namespaced events from a component

Use the pattern Component.event('*') to listen to all events emitted by a specific component with its namespace.

const el = document.querySelector('my-element')

// Listen to all namespaced events from this component
el?.addEventListener(MyElement.event('*'), ev => {
    console.log('Caught namespaced event:', ev.type)
    // Will catch 'my-element:click', 'my-element:change', etc.
})

// This will trigger the wildcard listener
el?.emit('click', { detail: 'clicked' })
el?.emit('change', { detail: 'changed' })

Listen for all events (global wildcard)

Use the literal string '*' to listen to all events dispatched through the element, including both namespaced and non-namespaced events, as well as native DOM events.

const el = document.querySelector('my-element')

// Listen to ALL events on this element
el?.addEventListener('*', ev => {
    console.log('Caught any event:', ev.type)
    // Will catch everything: 'my-element:click', 'hello', 'click', etc.
})

// All of these trigger the global wildcard listener
el?.emit('custom')           // Triggers with type 'my-element:custom'
el?.dispatch('hello')        // Triggers with type 'hello'
el?.dispatchEvent(new Event('click'))  // Triggers with type 'click'

Modules

ESM

This exposes ESM and common JS via package.json exports field.

const { WebComponent } = import '@substrate-system/web-component'

Common JS

const { WebCompponent } = require('@substrate-system/web-component')

methods

emit(name:string, opts:{ bubbles?, cancelable?, detail? }):boolean

This will emit a CustomEvent, namespaced according to a convention.

The return value is the same as the native .dispatchEvent method,

returns true if either event's cancelable attribute value is false or its preventDefault() method was not invoked, and false otherwise.

Because the event is namespaced, we can use event bubbling while minimizing event name collisions.

The naming convention is to take the NAME property of the class, and append a string :event-name.

So emit('test') dispatches an event like my-element:test.

class MyElement {
    NAME = 'my-element'  // <-- for event namespace
    // ...
}

// ... then use the element in markup ...

const el = document.querySelector('my-element')

// 'my-element:test' event
el.addEventListener(MyElement.event('test'), ev => {
    console.log(ev.detail)  // => 'some data'
})

// ... in the future ...

el.emit('test', 'some data')  // dispatch `my-element:test` event

See also, Custom events in Web Components

---

dispatch (type, opts)

Create and emit an event, no namespacing. The return value is the same as the native .dispatchEvent method,

returns true if either event's cancelable attribute value is false or its preventDefault() method was not invoked, and false otherwise.

That is, it returns true if it was not preventDetaulted.

dispatch (type:string, opts:Partial<{
    bubbles,
    cancelable,
    detail
}>):boolean

dispatch example

const el = document.querySelector('my-element')
el.dispatch('change')  // => 'change' event

---

event (name:string):string

Return the namespaced event name.

event example

MyElement.event('change')  // => 'my-element:change'

You can also use '*' as the event name to create a wildcard listener pattern:

MyElement.event('*')  // => 'my-element:*'

This is used with addEventListener to listen to all namespaced events from a component.

---

qs

A convenient shortcut to element.querySelector.

qs (selector:string):HTMLElement|null

qsa

Shortcut to document.querySelectorAll

qsa (selector:string):ReturnType<typeof document.querySelectorAll>

element.qs & element.qsa

A shortcut to element.querySelector & element.querySelectorAll.

example

const myElement = document.querySelector('my-element')
debug('the namespaced event...', MyElement.event('aaa'))

// query inside the element 
const buttons = myElement?.qsa('button')

---

Misc

Some Notes

Attributes (strings, numbers, booleans) tend to reflect, properties don’t.

That means,

• Attributes typically reflect to properties — when you set count="5" in HTML, the element's .count property mirrors that value (often converting the string to a number).
• Properties typically DON'T reflect back to attributes — when you set element.count = 10 in JavaScript, it usually doesn't update the HTML attribute to count="10"

See The killer feature of Web Components.

---

/util

Various functions.

qs

A convenient shortcut to document.querySelector.

import { qs } from 'substrate-system/web-component/qs'

qsa

A shortcut to document.querySelectorAll.

import { qsa } from 'substrate-system/web-component/qsa'

isRegistered(name:string)

Check if an element name has been used already.

function isRegistered (elName:string):boolean

import { isRegistered } from '@substrate-system/web-component/util'

example

import { isRegistered } from '@substrate-system/web-component/util'

if (!isRegistered('example-component')) {
    customElements.define('example-component', ExampleComponent)
}

define(name:string, element:CustomElementConstructor)

Add a component to the custom element registry.

This uses isRegistered, so it will not throw if the name has been taken already.

import { define } from '@substrate-system/web-component/util'

function define (name:string, element:CustomElementConstructor) {

---

Develop

Start a localhost server:

npm start

---

Test

npm test

---

See also

• Custom events in Web Components
• Web Component lifecycle methods
• How to detect when attributes change on a Web Component
• Handling asychronous rendering in Web Components
• Accessible Icon Buttons
• Inclusively Hidden