@forter/element

A collection of small Web Component mixins to add commonly required functionality without the bloat

• No dependencies - just mixin and go
• Plain JavaScript - no build tools required, compatible by default, debug in the browser with standard dev tools
• No magic - straight forward to understand
• Small & efficient - low overhead to keep your components lean
• Include only what you need - take it or leave it
• Cross browser - works on all modern browsers and IE9 with polyfills

Table of Contents

• Install
• Usage
• Browser support
• Mixins
• Examples
• License

👨‍🏭 Install

Install using npm:

npm install --save @forter/element

👩‍💻 Usage

FcElement

<x-app></x-app>

<script>
  class App extends FcElement {
    static get properties() {
      return {
        name: { type: String, value: 'app', reflectToAttribute: true, }
      };
    }

    static get styles() {
      return [`
         :host {
            display: flex;
            flex-direction: column;
            max-width: 1280px;
            margin: 0 auto;
         }
      `];
    }

    render() {
      return `
        ${this.name} 
        <button class="button">Push!</button>
        <button class="button">Play!</button>
      `;
    }
  }

  customElements.define('x-app', App);
</script>

Implement a static getter for properties, returning an object with the property name as the key, and the value an object containing:

|Key|Type|Default|Required| |:--:|:--:|:--:|:--:| |type|{String\|Number\|Boolean\|Array\|Object}|String|No| |value|{String\|Number\|Boolean\|Array\|Object\|null}|undefined|No| |reflectToAttribute|{true\|false}|false|No|

type

The type of the property. Used when converting a property to an attribute, and vice-versa.

For boolean properties, true is converted to an empty attribute, while false removes the attribute. The presence of an attribute sets the property to true.

For array and object properties, the property is JSON stringified (JSON.stringify) when converting to an attribute, and JSON parsed (JSON.parse) when converting to a property.

value

The default value of the property if the property has not been initialised from an attribute, or the property was not set before the element was added to the DOM. If an attribute with a name matching the property name (converted to kebab-case) is present on the element this will always override the default.

reflectToAttribute

Whether the property should be reflected to an attribute with the same name. Camel cased property names (e.g. siteUsername) are converted to kebab cased attribute names (e.g. site-username) automatically.

🧙‍♂️ Mixins

ShadowMixin

Adds a shadow DOM to your component. Takes a string returned from a render() method to set up the shadow DOM, and adds ShadyCSS support if the polyfill is included for browsers that don't natively support shadow DOM. Also adds some convenience accessors for querying shadow DOM elements.

PropertiesMixin

Lets you specify your component's properties upfront, their types, whether their value should be reflected in an attribute, and an observer function to run when the property changes.

EventsMixin

Let's you add declarative event binding in your templates. Also adds some convenience methods for manual event binding and firing.

A convenience FcElement that includes ShadowMixin, PropertiesMixin, and EventsMixin:

class FcElement extends 
    EventsMixin(
      PropertiesMixin(
        ShadowMixin(HTMLElement))); 

👨‍🎤 Browser support

Works with no polyfills or build step for browsers that support ES2015, Shadow DOM v1, Custom Elements v1 and HTML Templates. This is currently the latest versions of Chrome and Safari.

Works with other browsers down to IE11 when using the web components polyfills and a transpilation step (e.g. Babel) as needed.

👨‍🎨 Examples

Coming soon - an example using lit-html.

Coming soon - an example that works on all browsers down to IE9.

Inspired by compost

👨‍💼 License

Apache License © Forter