web component

An extra minimal parent class for web components.

This extends the native HTMLElement, adding some methods for events.

See a live demonstration

• install
• tl;dr
• Example
  • Create a component
  • Add the component to the DOM
  • Listen for events
  • Emit a namespaced event from the instance
  • Emit a plain string (not namespaced) event
• API
  • ESM
  • Common JS
• methods
  • emit(name:string, opts:{ bubbles?, cancelable?, detail? }):boolean
  • dispatch (type, opts)
  • event (name:string):string
• 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's return value to create a web component

Example

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') {
    constructor () {
        super()
    }

    connectedCallback () {
        this.innerHTML = `<div>
            hello again
        </div>`
    }
}

customElements.define(AnotherElement.NAME, AnotherElement)

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'
})

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`

Emit a plain string (not namespaced) event

Don't namespace the event name, just emit 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`

API

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

ESM

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'

Develop

Start a localhost server:

npm start

Test

npm test

See also

• Custom events in Web Components