README.md

web component

An extra minimal parent class for web components.

This extends the native HTMLElement, adding some methods to help with 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
  • Modules
  • Common JS
• methods
  • emit(name:string, opts:{ bubbles?, cancelable?, detail? }):boolean
  • dispatch (type, opts)
  • event (name:string):string
  • qs
  • qsa
• Misc
  • isRegistered
• 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)

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

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

Modules

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'

qs

A convenient shortcut to element.querySelector.

qs (selector:string):HTMLElement|null

qsa

Shortcut to element.querySelectorAll

qsa (selector:string):ReturnType<typeof document.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

isRegistered

Check if an element name has been used already.

function isRegistered (elName:string):boolean

example

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

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

---

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