Component usage

Let's get real !

Using a regular component

Any regular HTML element can be coerced into becoming a component. All the element needs to do is target us to which component it whishes to be via the o-component special attribute (called a directive), or which part of a component it should be via the o-part directive. More on o-part later.

As an example, consider the registered components below:

import { createApp } from '@boyojs/boyo-core';

createApp()
    .component('example1', () => {/* ... */})
    .component('example2', () => {/* ... */})
    .component('my-minimal-component', () => console.log('I am a component, whoot whoot!'))
    .mount('#app');

and the following DOM structure:

<main id="app">
    <section o-component="example1">
        <article o-component="example2">...</article>
        <article o-component="example2">...</article>
    </section>

    <aside o-component="my-minimal-component">...</aside>
</main>

Once .mount('#app') is called, Boyo will know to crawl all the #app child elements (including itself) for any declared o-component or o-part attributes.

Once elements with the o-component directive are found, the value of the directive will be used as the component name to target in the registered components list. If no component is found for a given value, an error will be thrown. If a registered component is found it's mounting process will be initiated, thus, turning the element into a "Boyo enhanced element", aka, a component.

Looking at the examples above, once the o-component="my-minimal-component" element is encountered in the DOM, the registered .component('my-minimal-component', ...) component definition will be retrieved, then invoked, then mounted, and finally the result of which will be printing 'I am a component, whoot whoot!' to the browser console.

Using an autonomous custom element

Creating and using autonomous custom elements with Boyo is trivial. All the element needs is to be present in the DOM with the correct node name.

Consider the registered custom elements below:

import { createApp } from '@boyojs/boyo-core';

createApp()
    .customElement('example1', () => {/* ... */})
    .customElement('example2', () => {/* ... */})
    .customElement('my-minimal-component', () => console.log('I am a component, whoot whoot!'))
    .mount('#app');

and the following DOM structure:

<main id="app">
    <o-example1>
        <o-example2>...</o-example2>
        <o-example2>...</o-example2>
    </o-example1>

    <o-my-minimal-component>...</o-my-minimal-component>
</main>

Once .mount('#app') is called, Boyo will know to define the registered components onto the window's CustomElementRegistry via window.customElements.define, kick starting the custom elements connection process.

Customizing the Shadow DOM

By default, custom elements are created with an open shadow DOM.

This can be customized:

import { createApp } from '@boyojs/boyo-core';

createApp()
    /**
     * No shadow DOM at all.
     * `attachShadow: true` would be the same as
     * `{ mode: 'open' }` which is the default.
     */
    .customElement('example1', {
        attachShadow: false,
        component() {
            //
        },
    })
    /**
     * A closed shadow DOM which delegates focus.
     */
    .customElement('example2', {
        attachShadow: { mode: 'closed', delegatesFocus: true },
        component() {
            //
        },
    })
    .mount('#app');

Using an extended built-in custom element

Creating and using extended built-in custom elements with Boyo is very similar to creating and using autonomous custom elements. Extended built-in custom elements however requires to specify which built-in element is to be extended.

Consider the registered custom elements below:

import { createApp } from '@boyojs/boyo-core';

createApp()
    .customElement('example1', {
        class: HTMLDivElement,
        extends: 'div',
        component() {
            //
        },
    })
    .customElement('example2', {
        class: HTMLSpanElement,
        extends: 'span',
        component() {
            //
        },
    })
    .customElement('my-minimal-component', {
        class: HTMLDialogElement,
        extends: 'dialog',
        component() {
            console.log('I am a component, whoot whoot!');
        },
    })
    .mount('#app');

and the following DOM structure:

<main id="app">
    <div is="o-example1">
        <span is="o-example2">...</span>
        <span is="o-example2">...</span>
    </div>

    <dialog is="o-my-minimal-component">...</dialog>
</main>

Once .mount('#app') is called, the same process as for autonomous custom elements will be kick started.

Customizing the Shadow DOM

The attachment of shadow DOM onto extended built-in custom elements works in the same exact way as for autonomous custom elements, and offers the same customizations.