Overview

Quick guide

Wafer components extend the Wafer class (which itself extends HTMLElement), and are defined by a template string, a props object, and an events object.

Template

The template of a Wafer component is a simple static string which will get parsed to DOM elements and attached to the Shadow DOM:

class MyExample extends Wafer {
  // will be attached to the Shadow DOM
  static get template() {
    return `
      <span id="count"></span>
      <button id="dec">-</button>
      <button id="inc">+</button>
    `;
  }
}

Read more about Wafer templates including how to render to the Light DOM instead of the Shadow DOM.

Props

Properties of a Wafer component are expressed as a static object describing the property type, attribute relationship and initial value, keyed by the property name:

class MyExample extends Wafer {
  static get template() {
    return `
      <span id="count"></span>
      <button id="dec">-</button>
      <button id="inc">+</button>
    `;
  }

  static get props() {
    return {
      count: {
        // optional type (used for attribute serialisation)
        type: Number,
        // optionally reflect the property value to the attribute value
        reflect: true,
        // optionally define an initial property value
        initial: 10,
      },
    };
  }
}

Updates to properties on an instance of a Wafer component will trigger updates to be made to the template based on property targets. Updates triggered by property changes are batched during the current event loop for efficient re-rendering.

In contrast to many other component libraries, updates to the template are not handled using a templating abstraction. Instead each property can be associated with an array of targets, with each target defined by a standard CSS selector and a series of updates that should be made to matches for that selector in the template:

class MyExample extends Wafer {
  static get template() {
    return `
      <span id="count"></span>
      <button id="dec">-</button>
      <button id="inc">+</button>
    `;
  }

  static get props() {
    return {
      count: {
        type: Number,
        reflect: true,
        initial: 10,
        targets: [
          {
            // this will target all elements matching #count in the template
            // in this case the <span id="count"></span> element
            // ($ indicates matched in the Shadow DOM)
            selector: "$#count",

            // this will update the `textContent` of the matching element(s)
            // to the value of `count`
            text: true,

            // this will set a `total` property on the matching element(s)
            // to the value of `count`
            property: "total",

            // this will set a `total` attribute on the matching element(s)
            // to the value of `count`
            attribute: "total",
          },
        ],
      },
    };
  }
}

Read more about Wafer properties, including how to initialise property values with attributes, how to use computed values for updates, how to indicate related properties, how to indicate a property change should not trigger an update and how to perform more complex DOM manipulations.

Events

Similarly to properties, events are bound to a Wafer component using CSS selectors and the event name:

class MyExample extends Wafer {
  static get template() {
    return `
      <span id="count"></span>
      <button id="dec">-</button>
      <button id="inc">+</button>
    `;
  }

  static get props() {
    /* ... */
  }

  get events() {
    // by default, events are automatically bound to the component itself
    return {
      "$#dec": {
        click: () => this.count--,
      },
      "$#inc": {
        click: () => this.count++,
      },
    };
  }
}

Read more about Wafer events, including how to bind to other elements, and how to pass other options to the event handlers.