CustomElement.js

"use strict";

/**
 * @module CustomElement
 */

/**
 * Create a DOM Event without worrying about browser compatibility
 *
 * @param  {string} eventName The name of the event to create
 * @param {*} [detail] The optional details to attach to the event
 * @return {Event} A valid Event instance that can be dispatched on a DOM node
 * @example
 * var event = CustomElement.makeEvent('change', { name: this._secretInput.value })
 * this.dispatchEvent(event)
 */
exports.makeEvent = makeMakeEvent();

var makeClass = makeMakeClass();

function noOp() {}

/**
 * Register a custom element using some straightforward and convenient configuration
 *
 * @param {Object} config
 * @param {string} config.tagName The name of the tag for which to create a custom element. Must contain at least one `-` and must not have already been defined.
 * @param {Object<string, Object>} config.properties Getters and setters for properties on the custom element that can be accessed and set with `Html.Attributes.property`. These should map a property name onto a `get` function that returns a value and a `set` function that applies a value from the only argument.
 * @param {Object<string, function>} config.methods Functions that can be invoked by the custom element from anywhere. These methods are automatically bound to `this`.
 * @param {function} config.initialize Method invoked during setup that can be used to initialize internal state. This function is called whenever a new instance of the element is created.
 * @param {function} config.onConnect Method invoked whenever the element is inserted into the DOM.
 * @param {function} config.onDisconnect Method invoked whenever the element is removed from the DOM.
 * @param {function} config.onAttributeChange Method invoked whenever an observed attribute changes. Takes 3 arguments: the name of the attribute, the old value, and the new value.
 * @param {string[]} config.observedAttributes List of attributes that are watched such that onAttributeChange will be invoked when they change.
 * @example
 * CustomElements.create({
 *   // This is where you specify the tag for your custom element. You would
 *   // use this custom element with `Html.node "my-custom-tag"`.
 *   tagName: 'my-cool-button',
 *
 *   // Initialize any local variables for the element or do whatever else you
 *   // might do in a class constructor. Takes no arguments.
 *   // NOTE: the element is NOT in the DOM at this point.
 *   initialize: function() {
 *     this._hello = 'world'
 *     this._button = document.createElement('button')
 *   },
 *
 *   // Let the custom element runtime know that you want to be notified of
 *   // changes to the `hello` attribute
 *   observedAttributes: ['hello'],
 *
 *   // Do any updating when an attribute changes on the element. Note the
 *   // difference between attributes and properties of an element (see:
 *   // https://javascript.info/dom-attributes-and-properties). This is a
 *   // proxy for `attributeChangedCallback` (see:
 *   // https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_custom_elements#Using_the_lifecycle_callbacks).
 *   // Takes the name of the attribute that changed, the previous string value,
 *   // and the new string value.
 *   onAttributeChange: function(name, previous, next) {
 *     if (name === 'hello') this._hello = next
 *   },
 *
 *   // Do any setup work after the element has been inserted into the DOM.
 *   // Takes no arguments. This is a proxy for `connectedCallback` (see:
 *   // https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_custom_elements#Using_the_lifecycle_callbacks)
 *   onConnect: function() {
 *     document.addEventListener('click', this._onDocClick)
 *     this._button.addEventListener('click', this._onButtonClick)
 *     this.appendChild(this._button)
 *   },
 *
 *   // Do any teardown work after the element has been removed from the DOM.
 *   // Takes no arguments. This is a proxy for `disconnectedCallback` (see:
 *   // https://developer.mozilla.org/en-US/docs/Web/Web_Components/Using_custom_elements#Using_the_lifecycle_callbacks)
 *   onDisconnect: function() {
 *     document.removeEventListener('click', this._onDocClick)
 *   },
 *
 *   // Set up properties. These allow you to expose data to Elm's virtual DOM.
 *   // You can use any value that can be encoded as a `Json.Encode.Value`.
 *   // You'll often want to implement updates to some visual detail of your element
 *   // from within the setter of a property that controls it. Handlers will be
 *   // automatically bound to the correct value of `@`, so you don't need to worry
 *   // about method context.
 *   properties: {
 *     hello: {
 *       get: function() {
 *        return this._hello
 *       },
 *       set: function(value) {
 *         this._hello = value
 *         this._button.textContent = value
 *       }
 *     }
 *   },
 *
 *   // Set up methods that you can call from anywhere else in the configuration.
 *   // Methods will be automatically bound to the correct value of `@`, so you
 *   // don't need to worry about method context.
 *   methods: {
 *     _onDocClick: function() {
 *       alert('document clicked')
 *     },
 *     _onButtonClick: function() {
 *       alert('clicked on ' + this._hello + ' button')
 *     }
 *   }
 * })
 */
exports.create = function create(config) {
  if (customElements.get(config.tagName)) {
    throw Error(
      "Custom element with tag name " + config.tagName + " already exists.",
    );
  }

  var observedAttributes = config.observedAttributes || [];
  var methods = config.methods || {};
  var properties = config.properties || {};
  var initialize = config.initialize || noOp;
  var onConnect = config.onConnect || noOp;
  var onDisconnect = config.onDisconnect || noOp;
  var onAttributeChange = config.onAttributeChange || noOp;

  var Class = makeClass();

  for (var key in methods) {
    if (!methods.hasOwnProperty(key)) continue;
    Class.prototype[key] = methods[key];
  }

  Object.defineProperties(Class.prototype, properties);

  Class.prototype.connectedCallback = onConnect;
  Class.prototype.disconnectedCallback = onDisconnect;
  Class.prototype.attributeChangedCallback = onAttributeChange;
  if (Array.isArray(observedAttributes)) {
    Object.defineProperty(Class, "observedAttributes", {
      get: function () {
        return observedAttributes;
      },
    });
  }

  Class.displayName = "<" + config.tagName + "> custom element";
  customElements.define(config.tagName, Class);
};

/**
 * Attempt to make an ES6 class using the Function constructor rather than
 * ordinary class syntax. The string we pass to the Function constructor is
 * static so there is no script injection risk. It allows us to catch
 * syntax errors at runtime for older browsers that don't support class and
 * fall back to an ES5 constructor function.
 */
function makeMakeClass() {
  try {
    return new Function(
      [
        "return class extends HTMLElement {",
        "  constructor() {",
        "    super()",
        "    for (var key in this) {",
        "      var value = this[key]",
        "      if (typeof value !== 'function') continue",
        "      this[key] = value.bind(this)",
        "    }",
        "  }",
        "}",
      ].join("\n"),
    );
  } catch (e) {
    return function () {
      function Class() {
        // This is the best we can do to trick modern browsers into thinking this
        // is a real, legitimate class constructor and not a plane old JS function.
        var _this = HTMLElement.call(this) || this;
        for (var key in _this) {
          var value = _this[key];
          if (typeof value !== "function") continue;
          _this[key] = value.bind(_this);
        }
        return _this;
      }
      Class.prototype = Object.create(HTMLElement.prototype);
      Class.prototype.constructor = Class;
      return Class;
    };
  }
}

/**
 * Return a function for making an event based on what the browser supports.
 * IE11 doesn't support Event constructor, and uses the old Java-style
 * methods instead
 */
function makeMakeEvent() {
  try {
    // if calling Event with new works, do it that way
    var testEvent = new CustomEvent("myEvent", { detail: 1 });
    return function makeEventNewStyle(type, detail) {
      return new CustomEvent(type, { detail: detail });
    };
  } catch (_error) {
    // if calling CustomEvent with new throws an error, do it the old way
    return function makeEventOldStyle(type, detail) {
      var event = document.createEvent("CustomEvent");
      event.initCustomEvent(type, false, false, detail);
      return event;
    };
  }
}