wayang-ui v0.3.0

Wayang UI

What is it?

wayang-ui is a small, simple scaffolding for building web components. It comes with three exports; the WebComponent class for building visual elements, the Presenter class used to attach behaviors, and the Mixin class for extending elements. It's built using TypeScript, with minimal dependencies, so minified + gzipped it's about 3kb.

Installation

npm install --save wayang-ui

Creating An Element

import { WebComponent } from 'wayang-ui';

class WayButton extends WebComponent {

    // required properties
    static tag = 'way-button'; 
    static html = '<button></button>';
    static css = 'button { background: red; width:100px; height:100px; }';
    static observed = new Map([
        [ 'counter', 'number' ] // binds element attribute and converts type
    ]);
    
    // user defined property, "counter"
    private counter: number = 0;
    public get counter(): number {
        return this.getAttribute('counter');
    }
    public set counter(count: number) {
        this.setAttribute('counter', count);
        console.log(`Counter was set to ${ count }`)
    }
}

// registers the html tag <way-button>
WayButton.register();

To use this element:

<way-button counter="7"></way-button>

The above would produce a 100px X 100px red button and print "Counter was set to 7" in the console.

Creating A Presenter

import { Presenter } from 'wayang-ui';

class CounterPresenter extends Presenter {
    
    public static id = 'counter-presenter';

    connect(component: WebComponent) {
        component.listen('click', this.onClick);
    }
    disconnect(component: WebComponent) {
        component.unlisten('click', this.onClick);
    }
    onClick() {
        this.counter = this.counter || 0;
        this.counter += 1;
        console.log(`Clicked ${ this.counter } times`);
    }
}

// registers the presenter so it can be used with any component
CounterPresenter.register();

Putting A WebComponent And Presenter Together

<way-button presenter="counter-presenter"> </way-button>

The above html would result in the following: 1) The WayButton class is instantiated. 2) The presenter attribute triggers a request for the counter-presenter presenter. 3) An instance of CounterPresenter is created. 4) CounterPresenter.connect() is called with the instance of WayButton as it's parameter.

If the button is clicked, CounterPresenter.onClick() will be called, incrementing the counter property on the WayButton. The change will trigger two console outputs, one from the element, and one from the presenter.

Creating A Mixin

import { Mixin, WebComponent } from 'wayang-ui';

class GreenButton extends Mixin {
    public static id = 'green-button-mixin';

    // these happen at runtime
    public static connect(component: WebComponent) {
        // connect to the element at runtime
    }
    public static disconnect(component: WebComponent) {
        // disconnect, undo runtime changes
    }

    // these happen once, on script execution
    public static html(html: HTMLTemplateElement): void {
        // add a new button
        html.innerHTML += `<button green-button></button>`;
    };
    public static css(css: HTMLTemplateElement): void {
        // make the button green
        css.innerHTML += `<style id="green-button-mixin-css">[green-button] { background: green; }</style>`;
    };
    public static properties(properties: Map<string, string>): void {
        // define conversion mapping for properties
        properties.set('green-button-text', 'string');
    };
    public static observed(observed: string[]): void {
        // let the component know to watch for change
        observed.push('green-button-text');
    };
    public static converters(converters: Map<string, (value: string) => any>): void {
        // no additional types are required
    };
}

GreenButton.register()

Attaching a Mixin to a Web Component

class WayButton extends WebComponent {
    // other required properties
    public static mixins = [ GreenButton ]; // from the example above
}

WebComponent Class Members

note: Members with an asterisk (*) must be defined by developer creating the component.

Presenter Class Members

note: Members with an asterisk (*) must be defined by developer creating the presenter.

Mixin Class Members

note: Members with an asterisk (*) must be defined by developer creating the mixin.

Cleaner Component Example

import { WebComponent } from 'wayang-ui';
import html from './button.html'
import css from './button.css';
import observed from './button.json';

class WayButton extends WebComponent {
    static tag = 'way-button'; 
    static html = html;
    static css = css;
    static observed = new Map<string, string>(observed);
    // user defined members
}

WayButton.register();

This example works by using various scripts, declarations and build tools that enable static content to be imported like code. You can find the necessary code in wayang-element-template project on my github. The important parts are the rollup.config.js in the root, the declarations in src/declarations and the build / copy scripts in package.json.