Awesome

<em>µ</em>ce

windflower

<sup>Social Media Photo by Dawid Zawiła on Unsplash</sup>

µhtml based Custom Elements.

📣 Community Announcement

Please ask questions in the dedicated discussions repository, to help the community around this project grow ♥

API Overview

<em>µ</em>ce exports render, html, and svg, from <em>µ</em>html, plus its own way to define components.

In version 1.2, it exports also a plain-tag named css, useful to trigger CSS minifiers.

Check out the test page or this code pen playground.

// list of all exports
import {define, render, html, svg, css} from 'uce';

define('my-component', {

  // if specified, it can extend built-ins too.
  // by default it's 'element', as HTMLElement
  extends: 'div',

  // if specified, it injects once per class definition
  // a global <style> element in the document <head>, but
  // *not* in the shadowRoot. You can render style just fine
  // within the render, if shadow DOM is desired.
  // For the one-off global case, this method will be invoked with
  // a selector like `div[is="my-component"]` or `some-component`
  style: selector => css`${selector} {
    font-weight: bold;
  }`,

  // if specified, it's like the constructor but
  // it's granted to be invoked *only once* on bootstrap
  // and *always* before connected/attributeChanged/props
  init() {
    // µhtml is provided automatically via this.html
    // it will populate the shadow root, even if closed
    // or simply the node, if no attachShadow is defined
    this.html`<h1>Hello 👋 µce</h1>`;
    // a default props access example
    // <my-ce name="ag" />
    console.log(this.props.name); // "ag"
  },

  // if there is a render method, and no `init`,
  // this method will be invoked automatically on bootstrap.
  // element.render(), if present, is also invoked automatically
  // when `props` are defined as accessors, and one of these is
  // set during some outer component render()
  render() {
    this.html`<h1>Hello again!</h1>`;
  },

  // by default, props resolves all attributes by name
  // const {prop} = this.props; will be an alias for
  // this.getAttribute('prop') operation,
  // but it can simulate what React props do,
  // meaning that if it's defined as object,
  // all properties will trigger automatically
  // a render() call, if there is a render,
  // and properties are set as accessor, so that
  // the syntax to trigger these is .prop=${value}
  // as opposite of the default prop=${value}
  // which is observable, but it can hold only strings.
  // props: {prop: value} will make this.prop work.
  // If you don't want any of this machinery around props
  // you can opt out by defining it as null.
  // Bear in mind, the way to pass props as accessors,
  // is by prefixing the attribute via `.`, that is:
  // this.html`<my-comp .prop=${value}/>`;
  props: null,

  // if present, all names will be automatically bound to the element
  // right before initialization (el.method = el.method.bind(el))
  // this allows usage of methods instead of `this` for inner components
  bound: ['method'],

  // if specified, it renders within its Shadow DOM
  // compatible with both open and closed modes
  attachShadow: {mode: 'closed'},

  // if specified, observe the list of attributes
  observedAttributes: ['test'],

  // if specified, will be notified per each
  // observed attribute change
  attributeChanged(name, oldValue, newValue){},

  // if specified, will be invoked when the node
  // is either appended live, or removed
  connected() {},
  disconnected() {},

  // events are automatically attached, as long
  // as they start with the `on` prefix
  // the context is *always* the component,
  // you'll never need to bind a method here
  onClick(event) {
    console.log(this); // always the current Custom Element
  },

  // if specified with `on` prefix and `Options` suffix,
  // allows adding the listener with a proper third argument
  onClickOptions: {once: true}, // or true, or default false

  // any other method, property, or getter/setter will be
  // properly configured in the defined class prototype
  get test() { return Math.random(); },

  set test(value) { console.log(value); },

  sharedData: [1, 2, 3],

  method() {
    return this.test;
  }

});

F.A.Q.

<details> <summary><strong>Which polyfill should I use?</strong></summary> <div>

The @ungap/custom-elements is the recommended polyfill to grant every Custom Elements V1 feature is available in every browser.

However, if no builtin extend is used, but legacy needs to be supported, including @webreflection/custom-elements-no-builtin on top of the page should patch IE 11 and other legacy browsers.

</div> </details> <details> <summary><strong>How to avoid bundling µce per each component?</strong></summary> <div>

This module reserves, in the Custom Elements Registry a uce-lib class, which only purpose is to provide all exports as static getters.

// whenever uce library is loaded
customElements
  .whenDefined('uce-lib')
  .then(({define, render, html, svg} = customElements.get('uce-lib')) => {
    // that's it: ready to go 🎉
    define('my-component', {
      init() {
        console.log('this is awesome!');
      }
    });
  }
);

<strong>Using a helper</strong>

"There's a module for that", it's called once-defined:

import when from 'once-defined';

when('uce-lib').then(({define, render, html, svg}) => {
  // define your Custom Element
});

</div> </details> <details> <summary><strong>Without classes, how does one define private properties?</strong></summary> <div>

Private properties can be created via a WeakMap, which is indeed how Babel transforms these anyway.

const privates = new WeakMap;
define('ce-with-privates', {
  init() {
    // define these once
    privates.set(this, {test: 1, other: '2'});
  },
  method() {
    // and use it anywhere you need them
    const {test, other} = privates.get(this);
    console.log(test, other);
  }
});

</div> </details> <details> <summary><strong>Without classes, how does one extend other components?</strong></summary> <div>

There are at least two ways to extend an uce component:

define via uce your base component, and use extends: "base-comp-name" to extend it (built-ins supported!)
use one or more mixin through object literals

Object literals have indeed been used as mixin for a very long time, and the pattern with uce would be very similar.

The only warning is that Object.assign, as well as object {...spread}, lose getters and setters in the process, so that if you want to extend more complex components, you should consider using assignProperties, or a similar helper.

import $ from 'assign-properties';
const mixin = (...components) => $({}, ...components);

// a component literal definition
const NamedElement = {
  get name () { return this.tagName; }
};

// a generic NamedElement mixin
const FirstComponent = mixin(NamedElement, {
  method() {
    console.log(this.name);
  }
});

// define it via the FirstComponent mixin
define('first-component', FirstComponent);

// define it via mixin
define('first-component', mixin(FirstComponent, {
  otherThing() {}
}));

</div> </details> <details> <summary><strong>How different is <em>µce</em> from others?</strong></summary> <div>

I have written a gist that compares uce vs lit-element, so that most obvious differences are highlighted, but basically uce provides pretty much everything other libraries provide and vice-versa, and choosing one or another should be driven by personal taste and style, as long as most relevant differences are clear.

That is: uce is neither superior nor inferior to others, it tries to be as simple and concise as possible, and it has great pontentials when used via uce-template too.

</div> </details> <details> <summary><strong>What happened between 1.2 and 1.5?</strong></summary> <div>

A wrong npm publish happened, as 1.5.0 has been pushed for no reason between 0.5 an 0.6, so that latest was picking up actually an older version of the library.

My apologies.

</div> </details> <details> <summary><strong>What's new in v1.2?</strong></summary> <div>

So far, the only missing utility for non Shadow DOM cases, is a way to define once a generic style associated with a component, which is why the special style: (selector) => css property has been added, so that any component can automatically define any specific style, using the selector to confine inner nodes directives.

The css export is a plain template literal tag, which is completely optional, but it might help minifiers, or rollup plugins, to minify that code too.

// note: the css import is optional
import {define, css} from 'uce';

define('very-important', {
  style: sel => css`
    ${sel} {
      font-weight: bold;
      text-transform: uppercase;
    }
    ${sel}:hover {
      font-size: 2rem;
    }
  `
});

If the element doesn't extend a built-in, the received sel, as selector, will simply be its name, otherwise it'll be the built-in name with its [is="..."] attribute.

Please note the style won't interfere, or be attached anyhow, with the regular element.style or this.style, within a method, which is actually why I've chosen that name, so it's clear it's about the generic class/component style, and not its property.

</div> </details>