npm package: @forter/element
Description: Native HTML without boilerplate to create Forter Components
Author: Forter Developers
Latest version: 2.0.0

<div style="color:black;background-color:cornsilk;border-bottom:4px solid orange;padding:14px 20px">⚠️ Forter Web Components are in development. APIs are subject to change without notice. ⚠️</div>

# `@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](#install)
- [Usage](#usage)
- [Browser support](#browser-support)
- [Mixins](#mixins)
- [Examples](#examples)
- [License](#license)

## 👨‍🏭 Install

Install using [npm](https://npmjs.com):

```sh
npm install --save @forter/element
```

## 👩‍💻 Usage

### FcElement

```html
<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](https://github.com/webcomponents/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`:

```js
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](https://github.com/WebComponents/webcomponentsjs) 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](https://github.com/lamplightdev/compost)

## 👨‍💼 License

[Apache License](https://www.apache.org/licenses/LICENSE-2.0) © [Forter](https://forter.com)